forma-dsl-mcp 0.1.4

package/src/reference/api/kernel.md

@@ -0,0 +1,182 @@
+# Kernel
+
+Loading the Manifold WebAssembly module, and tuning how finely it approximates curves.
+
+```js
+import { loadKernel, setQuality, resetQuality } from 'forma-dsl';
+```
+
+Most callers never touch these. [`EvaluationContext.create()`](evaluation-context.md#evaluationcontextcreate)
+loads the kernel for you, and `segments` on a shape handles resolution locally. Reach for
+this page when bundling needs help finding the `.wasm`, or when a draft pass and a final pass
+want different quality.
+
+---
+
+## `loadKernel`
+
+### `loadKernel(options?)`
+
+Loads and sets up the Manifold module, once per page or process.
+
+| | |
+| --- | --- |
+| **`options.locateFile`** | `() => string` — returns the URL of the `.wasm` file |
+| **Returns** | `Promise<Kernel>` — the `manifold-3d` toplevel module |
+
+#### Caveats
+
+- **Memoized on the promise, not the result.** Two models evaluating concurrently at startup
+  share one instantiation rather than each starting their own.
+- **Only the first call's options take effect.** Later calls get the memoized promise, so
+  `locateFile` has to be right the first time.
+- A rejected load is *not* memoized — a WASM fetch that lost the network can be retried
+  rather than being permanently broken for the page.
+
+### Bundlers and `locateFile`
+
+A bundler that fingerprints assets renames `manifold.wasm`, and the module cannot then find
+it by its own relative path. Point at the built URL:
+
+```js
+import wasmUrl from 'manifold-3d/manifold.wasm?url';
+import { loadKernel } from 'forma-dsl';
+
+await loadKernel({ locateFile: () => wasmUrl });
+```
+
+Do this **before** the first `EvaluationContext.create()`, or the default path is what gets
+memoized.
+
+In Node, nothing is needed — the module resolves the file itself.
+
+---
+
+## `setQuality`
+
+### `setQuality(options?)`
+
+Sets the resolution used for curved surfaces, globally.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `minAngle` | `number` | Smallest angle, in degrees, between adjacent segments of a curve |
+| `minEdgeLength` | `number` | Smallest length a curve segment may be shortened to |
+| `segments` | `number` | A fixed segment count, overriding both limits above |
+
+Returns `Promise<void>`, resolving once the kernel is loaded and configured. Each option is
+left alone when omitted.
+
+#### Caveats
+
+- **These are global to the kernel, not per model.** A viewer that renders a draft and then a
+  final pass has to set them around each evaluation, not once at load.
+- **Quality settings are not part of a node's digest.** The cache is keyed on content, so a
+  solid built at draft quality will be *reused* at final quality unless the cache is cleared.
+  See [Usage](#a-draft-pass-and-a-final-pass).
+- A shape's own `segments` attribute overrides all of this for that shape. Prefer it whenever
+  a specific facet count matters — a hole that must clear a printed bolt should not depend on
+  a global.
+
+## `resetQuality`
+
+### `resetQuality()`
+
+Restores the kernel's own defaults. Returns `Promise<void>`.
+
+---
+
+## Usage
+
+### A draft pass and a final pass
+
+Because quality is global and digests do not include it, the cache has to be dropped between
+passes — otherwise the final render happily reuses the draft's geometry:
+
+```js
+import { setQuality, EvaluationContext, render } from 'forma-dsl';
+
+// Draft: fast, coarse.
+await setQuality({ segments: 16 });
+let context = await EvaluationContext.create();
+const draft = await render(source, { params, context });
+draw(draft.parts);
+context.dispose();
+
+// Final: a fresh context, so nothing coarse survives.
+await setQuality({ minAngle: 1, minEdgeLength: 0.2 });
+context = await EvaluationContext.create();
+const final = await render(source, { params, context });
+draw(final.parts);
+```
+
+If instead you want one context throughout, put the resolution in the document so it *is*
+part of the digest:
+
+```hcl
+param facets { type = number  default = 32  min = 8  max = 160  step = 8 }
+
+model "m" {
+  cylinder { radius = 10  height = 20  segments = var.facets }
+}
+```
+
+That is the better answer for an editor: changing `facets` changes the content, so the cache
+does the right thing automatically.
+
+### Global quality for an export
+
+A one-off high-quality export, then back to normal:
+
+```js
+await setQuality({ minEdgeLength: 0.1 });
+try {
+  const context = await EvaluationContext.create();
+  const result = await render(source, { params, context });
+  await writeFile('final.stl', toBinarySTL(result.parts[0].concrete));
+  context.dispose();
+} finally {
+  await resetQuality();
+}
+```
+
+### Reaching the kernel directly
+
+`context.wasm` is the loaded module, and every Manifold API is on it:
+
+```js
+const context = await EvaluationContext.create();
+const { Manifold, CrossSection } = context.wasm;
+```
+
+Anything you construct this way is **yours** to delete — the context only owns what it built
+itself.
+
+---
+
+## Troubleshooting
+
+### The page 404s on `manifold.wasm`
+
+The bundler renamed it. Pass `locateFile`, before the first context is created:
+
+```js
+import wasmUrl from 'manifold-3d/manifold.wasm?url';
+await loadKernel({ locateFile: () => wasmUrl });
+```
+
+### `locateFile` is being ignored
+
+The kernel was already loaded — the promise is memoized, so only the first call's options
+count. Move the `loadKernel` call earlier, before anything creates a context.
+
+### `setQuality` had no effect on an existing model
+
+The geometry was already cached. Quality is not part of the digest, so the cached solid is
+returned unchanged. Use a fresh context, or put the segment count in the document where it
+becomes part of the content.
+
+### Curves are too coarse in one place only
+
+Set `segments` on that shape rather than moving the global. It is per-shape, it is part of the
+digest, and it is visible to whoever reads the model.

package/src/reference/api/low-level.md

@@ -0,0 +1,239 @@
+# Compiler stages
+
+The pipeline, stage by stage, plus the registries the evaluator reads. These are exported so
+that editors, linters and tools can reach into the compiler without re-implementing it — the
+[editor](../../../editor) uses them for syntax
+highlighting and inline diagnostics.
+
+```js
+import {
+  tokenize, parse, Program, Evaluator, FormaError,
+  BLOCKS, FUNCTIONS, CONSTANTS,
+} from 'forma-dsl';
+```
+
+For ordinary use, [`render`](render.md) and
+[`describeParameters`](describe-parameters.md) are the front door.
+
+---
+
+## `tokenize`
+
+### `tokenize(source)`
+
+Turns source into tokens. Returns `Token[]`, ending with an `eof`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type` | `'ident' \| 'number' \| 'string' \| 'punct' \| 'eof'` | |
+| `value` | `any` | A string for `ident` and `punct`, a number for `number`, the parsed runs and splices for `string`, `null` for `eof` |
+| `loc` | `SourceLocation` | `{ line, column, offset }` |
+| `nlBefore` | `boolean` | Whether a line break preceded this token |
+
+`nlBefore` is what the parser uses to know an attribute has ended. See
+[the newline rule](../language/syntax.md#the-newline-rule).
+
+---
+
+## `parse`
+
+### `parse(source)`
+
+Turns source into an abstract syntax tree. Returns a `FormaDocument`.
+
+The AST's shape is an implementation detail of the evaluator and is typed loosely on purpose.
+Use [`Program`](#program) to get at declarations in a stable form.
+
+---
+
+## `Program`
+
+### `Program.parse(source)` · `new Program(document)`
+
+A parsed document, indexed by what each declaration is for. Constructing one is what catches
+duplicate names and a component that shadows a builtin.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `params` | `Map<string, unknown>` | Declared params, in source order |
+| `locals` | `unknown[]` | Declared locals, in source order |
+| `components` | `Map<string, unknown>` | Declared components |
+| `models` | `Map<string, unknown>` | Declared models |
+
+### `program.parameterDescriptors(evaluator?)`
+
+The declared params as [`ParameterDescriptor`](describe-parameters.md#returns)s. Without an
+evaluator, every field but the name comes back `undefined` —
+[`describeParameters`](describe-parameters.md) is this with one supplied.
+
+#### Listing a document's models without rendering
+
+```js
+import { Program } from 'forma-dsl';
+
+const program = Program.parse(source);
+[...program.models.keys()];      // ['printable', 'assembly']
+```
+
+---
+
+## `Evaluator`
+
+### `new Evaluator(program, options?)`
+
+Turns a program into geometry nodes. Resolving params and locals happens during
+**construction**, so every error about a missing or unreadable input surfaces before any
+geometry is built.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `params` | `Record<string, ParameterValue>` | Values for the document's params |
+| `context` | [`EvaluationContext`](evaluation-context.md) `\| null` | Needed only by [`align`](../reference/align.md), which measures its child |
+| `requireParams` | `boolean`, default `true` | Off lets a document declaring a required param still be inspected |
+
+| Member | Description |
+| --- | --- |
+| `program` | The program being evaluated |
+| `context` | The kernel context, if any |
+| `root` | The document-level [scope](../language/scope.md#the-root-scope) |
+| `expression(node, scope)` | Evaluates one expression |
+| `model(name?)` | Builds one model into a `Scene`. Defaults to the first declared |
+
+A `Scene` is `{ name, parts, node }`, where `parts` carry `GeometryNode`s and `node` is
+everything unioned.
+
+#### Caveats
+
+- **The evaluator does not call the kernel** — except for `align`. Its output is a node tree;
+  solving it is [`EvaluationContext`](evaluation-context.md)'s job.
+- Without a `context`, a document containing `align` fails with
+  `align needs a kernel context — render the model rather than building it`.
+- `requireParams: false` is for inspection only. A param with no value is simply absent from
+  scope, so evaluating geometry that reads it will fail.
+
+#### Building a node tree without solving it
+
+```js
+import { Program, Evaluator } from 'forma-dsl';
+
+const program = Program.parse(source);
+const scene = await new Evaluator(program, { params: { height: 20 } }).model();
+
+scene.node.digest;       // identity of the whole model
+scene.node.subtreeSize;  // how many nodes it took
+```
+
+Useful for diffing two documents, or for caching geometry identity without loading WASM at
+all.
+
+---
+
+## `FormaError`
+
+Every error the language raises. Extends `Error`.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `'FormaError'` | |
+| `loc` | `SourceLocation \| null` | Where it was raised, when known |
+
+The position is appended to the message as well as kept on the error, so a caller that only
+prints `error.message` still tells the reader where to look.
+
+```js
+try {
+  await render(source, { context });
+} catch (error) {
+  if (error.loc) {
+    markProblem(error.loc.line, error.loc.column, error.message);
+  } else {
+    showBanner(error.message);
+  }
+}
+```
+
+Not every failure is a `FormaError` — a few come from the kernel, and `render` raises a plain
+`Error` for a 2D part. Check `error.loc` rather than the class when all you need is a
+position. See [Errors](../errors.md) for the full catalogue.
+
+---
+
+## Registries
+
+### `BLOCKS`
+
+Every block the language understands, by name, as `Record<string, BlockDefinition>`.
+
+| Field | Description |
+| --- | --- |
+| `dim` | Output dimensionality, where it is fixed regardless of the children |
+| `leaf` | True for a shape, which takes no children |
+| `takes` | What the children must be; `'same'` passes their dimensionality through |
+| `combine` | `'list'` receives every child; anything else receives them unioned |
+| `build(args, children?)` | Produces the node |
+
+**[`part`](../reference/part.md) and [`align`](../reference/align.md) are not in it** — the
+evaluator handles both itself, because neither is an ordinary geometry operation.
+
+```js
+import { BLOCKS } from 'forma-dsl';
+
+Object.keys(BLOCKS).length;                            // the builtin blocks
+Object.keys(BLOCKS).filter((k) => BLOCKS[k].leaf);     // just the shapes
+```
+
+### `FUNCTIONS`
+
+Every builtin function, as `Record<string, FunctionDefinition>` with `arity` — `null` for
+variadic — and `call(args)`.
+
+### `CONSTANTS`
+
+`{ pi, e }`.
+
+#### Driving an editor from the registries
+
+Keeping completion and highlighting honest means reading the registries rather than a
+hand-kept list:
+
+```js
+import { BLOCKS, FUNCTIONS, CONSTANTS } from 'forma-dsl';
+
+const completions = [
+  ...Object.keys(BLOCKS).map((name) => ({ label: name, type: 'class' })),
+  ...Object.keys(FUNCTIONS).map((name) => ({ label: name, type: 'function' })),
+  ...Object.keys(CONSTANTS).map((name) => ({ label: name, type: 'constant' })),
+];
+```
+
+The docs site does the same thing for its syntax highlighting, which is why a new block
+cannot be added without the documentation's code samples learning about it.
+
+---
+
+## Troubleshooting
+
+### `align needs a kernel context — render the model rather than building it`
+
+Pass a context, or avoid `align` in documents you intend to evaluate without one:
+
+```js
+new Evaluator(program, { context: await EvaluationContext.create() });
+```
+
+### `param "x" has no default and no value was supplied`
+
+Thrown from the `Evaluator` **constructor**, not from `model()`. Pass `requireParams: false`
+to inspect such a document without values.
+
+### My hand-driven evaluation returns nodes, not solids
+
+That is the design. Pass each `part.node` to
+[`context.evaluate`](evaluation-context.md#contextevaluatenode), or use
+[`render`](render.md), which does both.
+
+### `part` and `align` are missing from `BLOCKS`
+
+Neither is an ordinary block: a `part` is a piece of the scene rather than an operand, and
+`align` has to measure its child. Both are handled directly by the evaluator. Add them to any
+list you build from `BLOCKS` for an editor.

package/src/reference/api/render.md

@@ -0,0 +1,217 @@
+# `render`
+
+Compiles a document and evaluates one model into renderable parts.
+
+```js
+import { render } from 'forma-dsl';
+
+const result = await render(source, { params: { height: 20 } });
+```
+
+---
+
+## Reference
+
+### `render(source, options?)`
+
+Parses `source`, resolves its params, evaluates one model into a geometry tree, and solves
+every part into a concrete solid and a mesh.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `source` | `string` | The document |
+| `options.model` | `string \| null` | Which model to build. Defaults to the **first** the document declares |
+| `options.params` | `Record<string, ParameterValue>` | Values for the document's top-level params. Anything not declared is ignored |
+| `options.context` | [`EvaluationContext`](evaluation-context.md) `\| null` | A context to reuse. One is created if you do not pass one |
+
+#### Returns
+
+A `Promise<RenderResult>`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The model's name |
+| `parts` | `RenderedPart[]` | One per [`part`](../reference/part.md) — see below |
+| `program` | [`Program`](low-level.md#program) | The parsed document, for inspecting params |
+| `context` | `EvaluationContext` | The context that owns every solid in `parts` |
+| `stats` | `RenderStats` | `nodes`, `evaluated`, `cacheHits`, `milliseconds` |
+
+Each `RenderedPart`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | From the part's label |
+| `color` | `string` | From the part's `color` attribute |
+| `opacity` | `number` | From the part's `opacity` attribute |
+| `node` | [`GeometryNode`](geometry-node.md) | The part's tree. This is what `collect` wants |
+| `concrete` | `Solid` | The solved Manifold object, **owned by the context** |
+| `mesh` | `RenderMesh` | `positions`, `normals`, `triangleCount`, `vertexCount` |
+
+#### Caveats
+
+- **The caller owns `result.context` and must dispose it.** WebAssembly objects are not
+  garbage-collected; nothing is freed until you say so.
+- **Never call `delete()` on `part.concrete` yourself.** It belongs to the context, which
+  may still have it cached under its digest.
+- If `render` throws and it created the context itself, that context is disposed before the
+  error propagates. A context you supplied is left alone, since you may still want it.
+- Params are resolved before any geometry is built, so a missing required param fails
+  immediately rather than halfway through a model.
+- `options.params` sets **top-level** params only. A param declared inside a `model` is a
+  constant — see [model params](../reference/model.md#model-params).
+
+---
+
+## Usage
+
+### Rendering once
+
+```js
+import { render, toBinarySTL } from 'forma-dsl';
+import { writeFile } from 'node:fs/promises';
+
+const result = await render(source);
+
+await writeFile('part.stl', toBinarySTL(result.parts[0].concrete));
+
+result.context.dispose();
+```
+
+A single render can afford to let `render` create the context and dispose it immediately
+afterwards. Anything more than that should reuse one.
+
+### Rendering many variants
+
+Reusing a context is the whole point of the digest cache: only the subtrees whose content
+actually changed are re-evaluated.
+
+```js
+import { render, toBinarySTL, EvaluationContext } from 'forma-dsl';
+import { writeFile } from 'node:fs/promises';
+
+const context = await EvaluationContext.create();
+
+for (const height of [10, 20, 30]) {
+  const result = await render(source, { params: { height }, context });
+  await writeFile(`part-${height}.stl`, toBinarySTL(result.parts[0].concrete));
+
+  // Free what this tree can no longer reach, so a long run stays bounded.
+  context.collect(result.parts.map((part) => part.node));
+}
+
+context.dispose();
+```
+
+The `collect` call is what keeps memory flat across a long run. Without it the context
+accumulates every intermediate solid from every variant.
+
+### Driving a live editor
+
+The same pattern, with one context for the life of the page:
+
+```js
+const context = await EvaluationContext.create();
+let current = null;
+
+async function rerender(source, params) {
+  try {
+    const result = await render(source, { params, context });
+    draw(result.parts);
+    current = result;
+    context.collect(result.parts.map((part) => part.node));
+    return result.stats;
+  } catch (error) {
+    showProblem(error.message, error.loc);   // FormaError carries a position
+    return null;
+  }
+}
+```
+
+Typing a digit into a dimension re-solves that wall and nothing else — `stats.cacheHits`
+against `stats.evaluated` shows how much was skipped.
+
+### Choosing a model
+
+```js
+await render(source);                          // the first model declared
+await render(source, { model: 'assembly' });   // by name
+```
+
+To list what a document offers:
+
+```js
+const { program } = await render(source);
+[...program.models.keys()];    // ['printable', 'assembly']
+```
+
+Or without rendering: `Program.parse(source).models.keys()`.
+
+### Exporting each part separately
+
+```js
+const result = await render(source);
+
+for (const part of result.parts) {
+  await writeFile(`${part.name}.stl`, toBinarySTL(part.concrete, part.name));
+}
+
+result.context.dispose();
+```
+
+### Reading the statistics
+
+```js
+const { stats } = await render(source, { context });
+
+stats.nodes;        // nodes in the tree — a measure of the document's size
+stats.evaluated;    // kernel calls actually made, across the context's life
+stats.cacheHits;    // how many were avoided
+stats.milliseconds; // wall clock for this render
+```
+
+`evaluated` and `cacheHits` are running totals on the **context**, not per render, so compare
+them across calls rather than reading one in isolation.
+
+---
+
+## Troubleshooting
+
+### `EvaluationContext has been disposed`
+
+Something held on to a result after disposing the context that owns it. `part.concrete` and
+`part.mesh` are only valid while the context is alive — copy the mesh arrays out first if you
+need them later.
+
+### Memory grows across renders
+
+Add the `collect` call. A reused context caches every solid it has ever built, by design;
+`collect(roots)` frees what the current tree can no longer reach.
+
+```js
+context.collect(result.parts.map((part) => part.node));
+```
+
+### `part "body" is 2D — extrude or revolve it before rendering`
+
+The model produced a cross-section. See [2D ↔ 3D](../reference/conversions.md).
+
+### `align needs a kernel context — render the model rather than building it`
+
+Only happens when driving [`Evaluator`](low-level.md#evaluator) directly without a context.
+`render` always supplies one.
+
+### The error has no line number
+
+Most do — `FormaError` carries a `loc` with `line`, `column` and `offset`, and appends it to
+the message. A few errors are raised before any position is known (`the document declares no
+model`) or inside a value helper that has none (`no attribute "a"`).
+
+```js
+try {
+  await render(source);
+} catch (error) {
+  error.loc?.line;   // undefined when the error has no position
+}
+```