forma-dsl

forma-dsl

A declarative DSL for 3D modeling and scene composition, reusable components, and live previews. This is the monorepo: the library, the command line and the MCP server that consume it, the editor, and the reference manual.

The site · Try the editor · Read the reference

npx forma-dsl-cli render riser.forma -p height=32 -o riser.stl

The live demo types each document out and solves it as it goes, then re-solves as a parameter moves - in the browser, with the same kernel.

param height { type = number  default = 20  min = 8  max = 40 }

model "riser" {
  part "body" {
    color = "#6f7d8c"
    difference {
      extrude {
        height = var.height
        rounded_rect { size = [40, 20]  radius = 4  center = true }
      }
      translate { offset = [0, 0, 3]  cylinder { radius = 5  height = var.height } }
    }
  }
}

Workspaces

Package	Published	What it is
packages/forma-dsl	forma-dsl	The language, its evaluator and the geometry kernel binding. One runtime dependency
packages/forma-dsl-cli	forma-dsl-cli	The forma command: solve a document to STL in a build, with no browser. One runtime dependency, the library
packages/forma-dsl-mcp	forma-dsl-mcp	An MCP server over stdio: it knows the language, solves what it writes, and produces .forma files
apps/landing	no	The landing page: a live WebGL hero, a demo that types the language and solves it, and the privacy and terms sheets
apps/editor	no	The browser editor: CodeMirror, three.js, Vite
apps/docs	no	The reference manual, and the builder that renders it

How the pieces are kept honest

Every workspace here depends on the published entry point, not on the library's sources: the editor imports forma-dsl, never ../../packages/forma-dsl/src. An export one of them needs and the package does not have therefore fails in this repository rather than in someone's install.

The same rule governs what each workspace may claim about the language. None of them restates the vocabulary - each reads it from the library's own registries, and a test holds them to it:

• Syntax highlighting is generated, not transcribed. The editor's (language.js), the landing page's (highlight.js) and the manual's (build.mjs) all colour from BLOCKS and FUNCTIONS, so a block added to the language is highlighted without anyone updating a list.
• Every example on the site renders. The editor's four documents (examples.test.js) and the landing page's demos (demos.test.js) are solved by tests, so nothing shown being typed is a document the library can no longer build.
• The MCP server's catalogue cannot drift. It merges the registries into its own prose at load time and exposes any disagreement as catalogueDrift, which catalogue.test.js asserts is empty. Its worked examples are rendered at both ends of every parameter's range.
• The editor's completion offers the whole language. It is built from BLOCKS, FUNCTIONS, CONSTANTS and TYPE_NAMES, and completion.test.js asserts that no name in a registry is missing from what the editor offers - so a block added to the language is suggested without anyone updating a list.
• The manual has no dead cross-references. npm run build resolves all 237 internal links and fails rather than publishing a broken one.

Working on it

Node 22.13 or newer - the floor the published packages declare.

npm ci
npm run check   # lint, typecheck, tests, build, package contents: the whole gate, same as CI

Command	What it does
npm run dev	the landing page, with hot reload
npm run dev:editor	the editor
npm run mcp	the MCP server, on stdio
npm run cli	the forma command, from the source tree
npm test	every workspace's tests
npm run test:coverage	the same, against the thresholds CI enforces
npm run build	the whole site into dist/

CONTRIBUTING.md has the house style, the stability policy and how a release is cut. CHANGELOG.md records what changed in each one.

Found something exploitable? SECURITY.md says where to send it - please not a public issue. PRIVACY.md covers the published packages: neither makes a network request, and the MCP server writes only inside the directories your client declares.

License

MIT - see LICENSE.