forma-dsl-mcp 0.1.4

package/src/reference/api/evaluation-context.md

@@ -0,0 +1,221 @@
+# `EvaluationContext`
+
+Evaluates a geometry tree against the Manifold kernel, memoized by node digest. It is both
+the cache that makes editing cheap and the owner of every WebAssembly object produced.
+
+```js
+import { EvaluationContext } from 'forma-dsl';
+
+const context = await EvaluationContext.create();
+// … render with it …
+context.dispose();
+```
+
+---
+
+## Reference
+
+### `EvaluationContext.create()`
+
+The only way to build a context, because the kernel loads asynchronously.
+
+Returns `Promise<EvaluationContext>`, with the WASM module ready.
+
+### `context.evaluate(node)`
+
+Solves a [`GeometryNode`](geometry-node.md) and returns the kernel object for it, memoized by
+the node's digest.
+
+| | |
+| --- | --- |
+| **Parameter** | `node: GeometryNode` |
+| **Returns** | `Promise<Solid \| Shape>` — a `Manifold` for a 3D node, a `CrossSection` for a 2D one |
+| **Throws** | If the context has been disposed |
+
+Concurrent requests for the same node share one evaluation, so a shape used twice in a tree
+walked concurrently is built once rather than twice with one copy leaked.
+
+### `context.collect(roots, options?)`
+
+Frees every cached object the given roots can no longer reach.
+
+| | |
+| --- | --- |
+| **`roots`** | `readonly GeometryNode[]` — the trees still in use |
+| **`options.keep`** | `number`, default `512`. How many unreachable entries to keep as a most-recently-used tail |
+| **Returns** | `number` — how many objects were freed |
+
+The retained tail matters more than it looks: editing churns the tree, so the entries that
+just fell out of it are the ones most likely to come straight back — on an undo, or on the
+next character of a number being typed.
+
+### `context.dispose()`
+
+Frees every WASM object the context has produced. The context cannot be used again;
+evaluations still in flight free their own results as they land. Disposing twice is harmless.
+
+### Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `wasm` | `Kernel` | The loaded module. Throws if read before `create()` resolved |
+| `size` | `number` | How many objects the cache holds |
+| `disposed` | `boolean` | Whether `dispose()` has run |
+| `stats` | `{ evaluated, hits, freed }` | Running totals for the context's whole life |
+
+---
+
+## Why a context exists
+
+WebAssembly objects are not garbage-collected. Something has to own them, and something has
+to decide when they are no longer needed — that is this class.
+
+It is also the cache. Nothing is freed as evaluation proceeds, because an intermediate result
+is also a cache entry and a later node may still need it. The two ways out are `collect`,
+which frees what the current tree can no longer reach, and `dispose`, which frees the lot.
+
+**A context is meant to outlive a single render.** Reusing one across renders is what makes
+the digest cache worth having: a re-render after an edit re-evaluates only the subtrees whose
+content actually changed.
+
+---
+
+## Usage
+
+### One context per session
+
+```js
+const context = await EvaluationContext.create();
+
+try {
+  for (const params of variants) {
+    const result = await render(source, { params, context });
+    await write(result);
+    context.collect(result.parts.map((part) => part.node));
+  }
+} finally {
+  context.dispose();
+}
+```
+
+The `try`/`finally` matters: a throw halfway through a batch would otherwise leak every solid
+built so far.
+
+### In a browser, for the life of the page
+
+The editor keeps one context forever and collects after each render:
+
+```js
+const context = await EvaluationContext.create();
+
+async function rerender(source, params) {
+  const result = await render(source, { params, context });
+  draw(result.parts);
+  context.collect(result.parts.map((part) => part.node));
+}
+```
+
+There is no `dispose` here, and that is correct — the page unloading frees the whole heap.
+
+### Tuning what is kept
+
+The default tail of 512 entries suits an editor. A batch job that renders a thousand
+unrelated variants has no use for it:
+
+```js
+context.collect(roots, { keep: 0 });     // free everything unreachable
+```
+
+A renderer showing a draft and then a final pass of the *same* model might raise it, so the
+draft's subtrees survive into the final render.
+
+### Watching the cache work
+
+```js
+const before = { ...context.stats };
+await render(source, { params: { height: 21 }, context });
+
+const evaluated = context.stats.evaluated - before.evaluated;
+const hits = context.stats.hits - before.hits;
+console.log(`${evaluated} solved, ${hits} reused`);
+```
+
+On a document where one dimension changed, `evaluated` should be a handful and `hits` most of
+the tree. If `evaluated` is the whole document every time, something is defeating the cache —
+see [Troubleshooting](#every-render-re-evaluates-everything).
+
+### Evaluating a node directly
+
+`render` is the front door, but the context takes any node:
+
+```js
+import { GeometryNode, EvaluationContext } from 'forma-dsl';
+
+const context = await EvaluationContext.create();
+
+const box = GeometryNode.shape(3, 'box', { size: [10, 10, 10], center: false });
+const solid = await context.evaluate(box);
+
+solid.volume();          // 1000
+context.dispose();
+```
+
+---
+
+## Ownership rules
+
+1. **Everything a context returns belongs to the context.** Never call `delete()` on a
+   `Solid`, a `Shape` or anything hanging off `part.concrete`.
+2. **A result is valid only while its context is alive.** After `dispose()`, every object it
+   produced is gone. Copy out what you need first — `toRenderMesh` and `toBinarySTL` both
+   produce plain typed arrays that outlive the context.
+3. **`render` does not dispose a context you supplied.** It disposes only one it created
+   itself, and only on failure.
+
+---
+
+## Troubleshooting
+
+### `EvaluationContext has been disposed`
+
+An `evaluate` or a `render` used a context after `dispose()`. Usually an async render that
+was still in flight when a page or a test tore the context down — await it first.
+
+### `EvaluationContext used before create() resolved`
+
+The constructor was called directly. Use the factory:
+
+```js
+new EvaluationContext();              // ✗ no kernel
+await EvaluationContext.create();     // ✓
+```
+
+### Memory grows without bound
+
+Add a `collect` after each render, passing the roots that are still in use:
+
+```js
+context.collect(result.parts.map((part) => part.node));
+```
+
+Without it, every intermediate solid from every render is retained — which is the correct
+default, because the context cannot know whether you still hold a reference.
+
+### `collect` freed nothing
+
+It returns `0` when the number of unreachable entries is at or below `keep` — the default 512
+tail. That is expected on a small document. Pass `{ keep: 0 }` to see whether anything is
+genuinely unreachable.
+
+### Every render re-evaluates everything
+
+Either a fresh context is being created per render — check that the same one is passed back
+in — or the document's content genuinely changes on every render. A param that feeds a
+dimension changes the digest of everything downstream of it, which is correct; a param that
+feeds only one wall should not.
+
+### Solids behave oddly after an error
+
+If `render` threw on a context it created, that context was disposed before the error
+propagated, and anything you captured from an earlier successful render on it is now freed.
+Supply your own context when you need results to survive a failure.

package/src/reference/api/export.md

@@ -0,0 +1,185 @@
+# Export
+
+Turning a solved solid into buffers a renderer can upload, or a file a slicer can read.
+
+```js
+import { toRenderMesh, toBinarySTL } from 'forma-dsl';
+```
+
+Both take a `Solid` — the `concrete` field of a
+[rendered part](render.md#returns) — and both return plain typed arrays that **outlive the
+context**, so they are what to copy out before disposing.
+
+---
+
+## `toRenderMesh`
+
+### `toRenderMesh(solid)`
+
+Converts a solid into flat arrays for a renderer.
+
+| | |
+| --- | --- |
+| **Parameter** | `solid: Solid` |
+| **Returns** | `RenderMesh` |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `positions` | `Float32Array` | Three vertices per triangle, expanded — `triangleCount * 9` floats |
+| `normals` | `Float32Array` | One face normal, repeated for all three corners |
+| `triangleCount` | `number` | Triangles |
+| `vertexCount` | `number` | Vertices **before** expansion, as the kernel counted them |
+
+#### Why vertices are expanded
+
+The kernel returns indexed triangles sharing vertices, which is what a viewer wants for
+upload size. But a shared vertex across a hard edge gets one averaged normal and is
+smooth-shaded, so a cube reads as a sphere-ish blob. Normals are therefore computed per face
+and the vertices expanded, which is what keeps the edge hard.
+
+The cost is that `positions.length / 3` is `triangleCount * 3` rather than `vertexCount`. Use
+`vertexCount` only as a measure of the underlying mesh.
+
+#### Caveats
+
+- A degenerate triangle keeps a zero normal rather than dividing by zero and poisoning the
+  buffer with NaN.
+- [`render`](render.md) already calls this for every part — `part.mesh` is the result. Call
+  it yourself only for a solid you built directly.
+
+---
+
+## `toBinarySTL`
+
+### `toBinarySTL(solid, header?)`
+
+Encodes a solid as binary STL.
+
+| | |
+| --- | --- |
+| **`solid`** | `Solid` |
+| **`header`** | `string`, default `'forma-dsl'`. Free text for the 80-byte header, truncated to fit |
+| **Returns** | `Uint8Array` — the file |
+
+Binary rather than ASCII: a model of any size is several times smaller and every slicer reads
+it.
+
+#### Caveats
+
+- **STL has no units.** Every consumer treats the numbers as millimetres, which is what the
+  language's lengths are usually meant to be, but nothing records that.
+- **STL has no colour and no parts.** A [`part`](../reference/part.md)'s colour and opacity do
+  not survive. Export each part to its own file if they need to stay distinct.
+- The header is truncated to 79 bytes so it cannot run into the triangle count that follows.
+- Float32 throughout, as the format requires. A model with features far from the origin loses
+  precision.
+
+---
+
+## Usage
+
+### Exporting one part
+
+```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();
+```
+
+### Exporting every part separately
+
+Colours do not survive STL, so one file per part is how an assembly stays an assembly:
+
+```js
+const result = await render(source);
+
+for (const part of result.parts) {
+  await writeFile(`${part.name}.stl`, toBinarySTL(part.concrete, `${result.name}/${part.name}`));
+}
+
+result.context.dispose();
+```
+
+The header is a reasonable place to record where the file came from.
+
+### Downloading from a browser
+
+```js
+const stl = toBinarySTL(part.concrete, part.name);
+const url = URL.createObjectURL(new Blob([stl], { type: 'model/stl' }));
+
+const a = document.createElement('a');
+a.href = url;
+a.download = `${part.name}.stl`;
+a.click();
+
+URL.revokeObjectURL(url);
+```
+
+### Uploading to a renderer
+
+`render` has already produced the mesh, so three.js needs no conversion:
+
+```js
+import { BufferGeometry, BufferAttribute, Mesh, MeshStandardMaterial } from 'three';
+
+function toThree(part) {
+  const geometry = new BufferGeometry();
+  geometry.setAttribute('position', new BufferAttribute(part.mesh.positions, 3));
+  geometry.setAttribute('normal', new BufferAttribute(part.mesh.normals, 3));
+
+  return new Mesh(geometry, new MeshStandardMaterial({
+    color: part.color,
+    transparent: part.opacity < 1,
+    opacity: part.opacity,
+  }));
+}
+```
+
+### Keeping geometry past the context
+
+Typed arrays are plain memory, so they survive disposal — unlike `part.concrete`:
+
+```js
+const result = await render(source);
+const saved = result.parts.map((part) => ({
+  name: part.name,
+  color: part.color,
+  stl: toBinarySTL(part.concrete),     // copied out…
+}));
+result.context.dispose();              // …so this is safe
+```
+
+---
+
+## Troubleshooting
+
+### `EvaluationContext has been disposed`
+
+The solid was freed before it was encoded. Export first, dispose after — or copy the arrays
+out, which is what the example above does.
+
+### The STL is empty, or has zero triangles
+
+The part solved to empty geometry. Usual causes: a `difference` that removed everything, an
+`extrude` whose height reached `0`, a `revolve` whose angle reached `0`. All of these are
+silent by design, so a parameter at the end of its range does not break a model.
+
+### My part came in at the wrong scale
+
+STL carries no units. The slicer is assuming millimetres; if the model was written in
+centimetres, scale it in the document.
+
+### Colours are missing from the exported file
+
+STL has none. Export parts separately and colour them in the slicer, or use the render mesh
+directly if you control the viewer.
+
+### Hard edges look smooth in my renderer
+
+The mesh is already expanded with per-face normals, so this is the renderer recomputing
+them. Upload `mesh.normals` as given and do not call anything like
+`computeVertexNormals()`.

package/src/reference/api/geometry-node.md

@@ -0,0 +1,215 @@
+# `GeometryNode`
+
+The immutable, content-addressed intermediate representation. The evaluator produces these;
+the kernel consumes them.
+
+```js
+import { GeometryNode } from 'forma-dsl';
+
+const box = GeometryNode.shape(3, 'box', { size: [10, 10, 10], center: true });
+box.digest;       // '3f2a…' — 32 hex characters
+box.subtreeSize;  // 1
+```
+
+---
+
+## Why it exists
+
+The evaluator never calls the kernel. It produces a tree of nodes, each carrying a 128-bit
+digest of its own content and its children's digests, computed once in the constructor and
+never from a live walk of the subtree.
+
+**Identity is digest identity.** Two structurally identical subtrees *are* the same node, so
+a component used twenty times is evaluated once. That is the whole basis of the cache in
+[`EvaluationContext`](evaluation-context.md), and the reason typing a digit into a dimension
+re-solves one wall rather than the document.
+
+The digest is computed from the IEEE bits of every number rather than from a hash seeded per
+process, so it is identical in every browser and every run.
+
+---
+
+## Reference
+
+### Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `dim` | `2 \| 3` | Whether this node is a cross-section or a solid |
+| `kind` | `string` | What the node does — `shape3d`, `boolean`, `transform`, `extrude`, … |
+| `props` | `Record<string, unknown>` | The node's own parameters |
+| `children` | `readonly GeometryNode[]` | The operands |
+| `digest` | `string` | 128-bit content digest, 32 lowercase hex characters |
+| `subtreeSize` | `number` | How many nodes this subtree holds, counting itself |
+| `isEmpty` | `boolean` | Whether it stands for no geometry at all |
+
+Nodes are frozen. Every factory returns a new node rather than mutating one.
+
+### Factories
+
+Prefer these to the constructor — they apply the algebraic simplifications that keep the tree
+small.
+
+| Factory | Description |
+| --- | --- |
+| `GeometryNode.empty(dim)` | A node standing for no geometry |
+| `GeometryNode.shape(dim, shape, params)` | A leaf primitive — `'box'`, `'circle'`, `'cylinder'`, … |
+| `GeometryNode.union(children)` | Everything added together |
+| `GeometryNode.difference(children)` | The first child with the rest removed |
+| `GeometryNode.intersection(children)` | Only what every child shares |
+| `GeometryNode.boolean(op, children)` | The three above, by name |
+| `GeometryNode.transformed(child, transform)` | A [`Transform`](values.md#transform) applied |
+| `GeometryNode.unary(kind, child, props?, dim?)` | Any single-child operation |
+
+### Simplifications
+
+The factories are not thin wrappers. Each collapses cases that would otherwise cost a kernel
+call and a cache entry:
+
+| Written | Becomes |
+| --- | --- |
+| A boolean with one surviving child | That child |
+| A boolean with empty children | The empties dropped |
+| A boolean with nothing left | `empty` |
+| A union of several children | The children **sorted by subtree size**, so order does not change the digest |
+| A transform of a transform | One node with the matrices multiplied |
+| Any unary operation on `empty` | `empty` |
+
+`difference` is never reordered: its first child is the body and the rest are cutters.
+
+### Caveats
+
+- **`dim` must be 2 or 3.** Anything else throws `bad dimensionality`.
+- **Booleans cannot mix dimensionality**: `cannot combine 2D and 3D geometry in a union`.
+- `GeometryNode.unary` defaults its result dimensionality to the child's, which is wrong for
+  the operations that change it — pass `dim` explicitly for anything extrude-like.
+- Two nodes with the same digest are interchangeable. Nothing stops you building the same
+  node twice; the cache will treat both as one.
+
+---
+
+## Usage
+
+### Walking a tree
+
+```js
+function* walk(node, seen = new Set()) {
+  if (seen.has(node.digest)) return;   // a shared subtree is visited once
+  seen.add(node.digest);
+  yield node;
+  for (const child of node.children) yield* walk(child, seen);
+}
+
+const result = await render(source);
+const kinds = new Map();
+
+for (const node of walk(result.parts[0].node)) {
+  kinds.set(node.kind, (kinds.get(node.kind) ?? 0) + 1);
+}
+```
+
+Deduplicating on `digest` is what makes the walk reflect what the kernel will actually do —
+the tree is a DAG, not a tree, once sharing is taken into account.
+
+### Measuring how much a model shares
+
+```js
+const { parts } = await render(source);
+const root = parts[0].node;
+
+const unique = new Set();
+for (const node of walk(root)) unique.add(node.digest);
+
+console.log(`${root.subtreeSize} nodes written, ${unique.size} distinct`);
+```
+
+A large gap is the digest cache doing its job — eight spheres in a loop are one sphere node
+and eight transforms.
+
+### Building geometry without the language
+
+The node API is public, so a program can emit geometry directly:
+
+```js
+import { GeometryNode, Transform, EvaluationContext, toBinarySTL } from 'forma-dsl';
+
+const context = await EvaluationContext.create();
+
+const pin = GeometryNode.shape(3, 'cylinder', {
+  height: 20, bottomRadius: 3, topRadius: 3, segments: 32, center: false,
+});
+
+const ring = GeometryNode.union(
+  Array.from({ length: 6 }, (_, i) => GeometryNode.transformed(
+    pin,
+    Transform.rotation3D([0, 0, i * 60]).concat(Transform.translation([30, 0, 0], 3)),
+  )),
+);
+
+const solid = await context.evaluate(ring);
+await writeFile('ring.stl', toBinarySTL(solid));
+context.dispose();
+```
+
+Note that `pin` is one node used six times — the kernel builds one cylinder.
+
+### Checking whether an edit changed anything
+
+```js
+const before = (await render(source, { context })).parts[0].node.digest;
+const after = (await render(edited, { context })).parts[0].node.digest;
+
+if (before === after) console.log('the edit did not change the geometry');
+```
+
+Reformatting, renaming a local, or reordering the members of a union all leave the digest
+untouched.
+
+---
+
+## Node kinds
+
+What the evaluator emits, and what [`EvaluationContext`](evaluation-context.md) knows how to
+solve:
+
+| Kind | Children | Notes |
+| --- | --- | --- |
+| `empty` | 0 | No geometry |
+| `shape2d` | 0 | `props.shape` is `rect`, `circle` or `polygon` |
+| `shape3d` | 0 | `props.shape` is `box`, `sphere`, `cylinder`, `hull` or `mesh` |
+| `boolean` | 2+ | `props.op` is `union`, `difference` or `intersection` |
+| `transform` | 1 | `props.transform` is a [`Transform`](values.md#transform) |
+| `extrude`, `revolve` | 1 | 2D → 3D |
+| `projection` | 1 | 3D → 2D; `props.type` is `full` or `slice` |
+| `offset`, `hull`, `refine`, `simplify`, `smooth`, `trim` | 1 | Refinement |
+
+Higher-level blocks do not have their own kinds. `rounded_rect` is a `rect` inside an
+`offset`; `torus` is a `circle`, a `transform` and a `revolve`; `cone` is a `cylinder`.
+
+---
+
+## Troubleshooting
+
+### `bad dimensionality 4`
+
+The constructor was called with something other than `2` or `3`.
+
+### `cannot combine 2D and 3D geometry in a union`
+
+A boolean was handed a mix. In a document this surfaces earlier and more helpfully as
+`"union" cannot mix 2D and 3D shapes`.
+
+### My hand-built extrude produced a 2D result
+
+`GeometryNode.unary` defaults `dim` to the child's, and an extrude's child is 2D. Pass it:
+
+```js
+GeometryNode.unary('extrude', profile, { height: 10, /* … */ }, 3);
+```
+
+### Two nodes I expected to be equal have different digests
+
+Digests cover **all** props. A `segments` of `0` and a `segments` of `32` are different
+shapes even when they look alike, and a float that differs in the last bit is a different
+number. Digest equality is exact, by design — the alternative is a cache that occasionally
+returns the wrong solid.