forma-dsl-mcp 0.1.4

package/src/guide.js

@@ -0,0 +1,313 @@
+/**
+ * The language, compressed to what someone writing a document has to hold in their head.
+ *
+ * This is deliberately not the reference manual — the manual is bundled too, and
+ * `forma_reference` serves it. This is the page that goes into a model's context before it
+ * writes anything: the rules that are not guessable, the mistakes that are expensive, and
+ * the shape of a working document.
+ */
+
+/** The sections, in reading order. Each is a complete thought on its own. */
+const SECTIONS = {
+  shape: `## The shape of a document
+
+A document is a flat list of four kinds of top-level block. Nothing else may appear there.
+
+| Block | What it is |
+| --- | --- |
+| \`param NAME = expr\` / \`param NAME { ... }\` | An input. Read it as \`var.NAME\` |
+| \`local NAME = expr\` | A named value, computed once |
+| \`component "NAME" { ... }\` | Reusable geometry, called like a builtin block |
+| \`model "NAME" { ... }\` | Something to render. The first one is the default |
+
+\`\`\`hcl
+param height { type = number  default = 20  min = 8  max = 40 }
+local wall = 2.5
+
+component "boss" {
+  param radius = 5
+  cylinder { radius = radius  height = 8 }
+}
+
+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 } }
+    }
+  }
+}
+\`\`\`
+
+Order does not matter between declarations of different kinds — a model may use a component
+declared below it. Order does matter among top-level \`local\`s, which resolve top to bottom.`,
+
+  nesting: `## Nesting is composition
+
+There is no expression language for geometry. **A block's children are its operands**,
+written inside its braces:
+
+\`\`\`hcl
+difference {                             // subtract…
+  box { size = [20, 20, 10] }            // …this is the body
+  cylinder { radius = 5  height = 30 }   // …and this is cut out of it
+}
+\`\`\`
+
+**Several children in a row are implicitly unioned.** Every operation except the three
+booleans unions its children before acting, so a transform around two shapes moves both:
+
+\`\`\`hcl
+translate {
+  offset = [0, 0, 10]
+  box { size = [4, 4, 4] }       // unioned first…
+  sphere { radius = 3 }          // …then the union is moved
+}
+\`\`\`
+
+\`difference\` is the one operation where order matters: the first child is the body, every
+later child is cut out of it. An operation with no children is an error; a shape with
+children is an error.`,
+
+  dimensionality: `## Dimensionality
+
+Every piece of geometry is 2D or 3D, and the language tracks which.
+
+- **2D** — \`rect\` \`rounded_rect\` \`circle\` \`ellipse\` \`regular_polygon\` \`stadium\` \`polygon\`
+- **3D** — \`box\` \`sphere\` \`cylinder\` \`cone\` \`torus\`
+- **Operations** either fix what they take (\`extrude\` takes 2D, \`refine\` takes 3D) or pass
+  their children's dimensionality through (\`translate\` \`rotate\` \`scale\` \`mirror\` \`hull\`
+  \`simplify\` \`align\`, the booleans).
+
+Three rules, each with its own error:
+
+| Rule | Error when broken |
+| --- | --- |
+| Children of one block must all be the same dimensionality | \`"union" cannot mix 2D and 3D shapes\` |
+| A block that fixes what it takes must get it | \`"extrude" takes 2D geometry, got 3D\` |
+| Anything rendered must be 3D | \`part "body" is 2D — extrude or revolve it before rendering\` |
+
+2D → 3D with \`extrude\` or \`revolve\`; 3D → 2D with \`project\` or \`slice\`.`,
+
+  units: `## Units and orientation
+
+- **Lengths are unitless.** Every consumer treats them as millimetres.
+- **Angles are always degrees.** Everywhere — \`rotate { z = 90 }\`, \`revolve { angle = 180 }\`,
+  \`sin(30)\`, \`param a { type = angle }\`. There is no radian form.
+- **Z is up.** \`extrude\` sweeps along +Z. \`revolve\` spins a profile written in the XY plane
+  about the Y axis, mapping the profile's Y to the result's Z — so a profile drawn upwards
+  from \`[0, 0]\` produces a solid standing on the XY plane.
+- **3D rotations apply X, then Y, then Z**, matching OpenSCAD.
+- **Transforms act about the origin.** Centre a shape (\`center = true\`) before rotating it,
+  or it swings away.`,
+
+  syntax: `## Syntax
+
+**Comments** — \`// line\`, \`# line\`, \`/* block */\`. Block comments do not nest.
+
+**Numbers** — \`12\` \`0.5\` \`.5\` \`1e3\` \`2.5e-3\`. No hex, no separators, no unit suffix.
+
+**Strings** — double quotes only, no literal newline. Exactly six escapes: \`\\n\` \`\\t\` \`\\r\`
+\`\\"\` \`\\\\\` \`\\$\`. \`\${ expr }\` splices any expression in.
+
+**Identifiers** start with a letter or \`_\` and continue with letters, digits, \`_\` **or \`-\`**.
+
+> **Hyphens are part of a name.** \`a-b\` is one identifier, not a subtraction. Write
+> \`a - b\` with spaces. This is the single most common surprise: \`local gap = outer-inner\`
+> fails with \`unknown name "outer-inner"\`.
+
+**Keywords**, which cannot be used as a block type:
+\`param local component model for if else in true false null\`.
+
+**Blocks and attributes.** A body holds attributes and nested blocks in any mix. An attribute
+is \`name = expression\`; anything else that is followed by a brace is a nested block. Setting
+the same attribute twice is an error.
+
+**The newline rule.** Outside brackets, **a line break ends an expression** — that is what
+lets attributes be written one per line with no separators. Inside \`(...)\`, \`[...]\` or an
+argument list the rule is suspended, so break there to continue across lines:
+
+\`\`\`hcl
+local total = (
+  var.wall * 2
+  + var.gap
+)
+
+local b = base
+          + extra      // NOT a continuation — this is a parse error
+\`\`\`
+
+Trailing commas are allowed in lists, objects and argument lists.`,
+
+  expressions: `## Expressions
+
+| Type | Literals |
+| --- | --- |
+| number | \`12\` \`0.5\` \`1e3\` |
+| string | \`"text"\` \`"a \${b} c"\` |
+| bool | \`true\` \`false\` |
+| list | \`[1, 2, 3]\` \`[[0,0], [1,0]]\` |
+| object | \`{ w = 3, h = 4 }\` or \`{ w: 3 }\`, read with \`.key\` |
+| null | \`null\` |
+
+There is no vector type: **a vector is a list of numbers**, and a block says how many
+components it wants. Where a block wants a vector, **a single number stands for every
+component** — \`scale { factor = 2 }\` is \`scale { factor = [2, 2, 2] }\`.
+
+**Operators**, loosest first: \`?:\` · \`||\` · \`&&\` · \`== !=\` · \`< <= > >=\` · \`+ -\` ·
+\`* / %\` · prefix \`-x !x\` · postfix \`a.b a[i] f(x)\`.
+
+\`\`\`hcl
+[10, 20] + [1, 2]      // [11, 22]   componentwise
+[10, 20] * 2           // [20, 40]   scalar broadcast, either order
+[10, 20] / 2           // [5, 10]    scalar only
+"part_" + 3            // "part_3"   + concatenates when either side is a string
+\`\`\`
+
+\`+\` and \`-\` on two lists are componentwise and reject a bare number; \`/\` accepts a scalar
+only. Two lists of different lengths cannot be combined. **Division and modulo by zero are
+errors**, not \`Infinity\`.
+
+\`<\` \`<=\` \`>\` \`>=\` need both sides to be the same type. \`==\` compares structurally.
+
+**Truthy / falsy** — falsy is \`false\`, \`0\`, \`""\`, \`[]\`, \`null\`. Everything else is truthy,
+including \`{}\`.
+
+**Members** — \`.x\` \`.y\` \`.z\` read index 0, 1, 2 off a list, so \`size.z\` works on a
+3-vector. \`a[i]\` indexes. \`var.NAME\` reads a param.`,
+
+  scope: `## Scope and names
+
+- **\`var\` holds params only** — never locals. A local with the same name shadows the bare
+  name but \`var.NAME\` still means the param.
+- **Component params are read by their bare name.** There is no \`var.\` for them.
+- **A component body cannot see the call site.** It is evaluated in a fresh scope rooted at
+  the document, so a \`local\` where it is called does not leak in. Document params and other
+  components are in scope.
+- **A param default may use earlier params by their bare name**, but never \`var\` — \`var\` is
+  assembled only after every param has resolved.
+- **Top-level locals are ordered**; locals inside a body are not, so a block may use a local
+  written below it.
+- **Loop variables** are bound per iteration in a fresh child scope.`,
+
+  control: `## Control flow
+
+Both appear where a block appears, and produce geometry rather than a value.
+
+\`\`\`hcl
+for i in range(0, 6) { ... }          // one name: the value
+for i, item in list { ... }           // two names: the index, then the value
+
+if cond { ... } else if other { ... } else { ... }
+\`\`\`
+
+- The sequence must be a **list**. \`range(a, b)\` excludes \`b\` and is empty when it runs
+  backwards, so a loop can never spin forever.
+- There is no \`break\`, no \`continue\` and no accumulator. Filter the list instead.
+- A loop over an empty list produces nothing, which is an error where something was
+  required — guard it with \`if\`.
+- For a *value* that depends on a condition, use \`cond ? a : b\`, not \`if\`.
+
+The radial-array idiom, which is most of what loops are for:
+
+\`\`\`hcl
+for i in range(0, var.bolts) {
+  rotate {
+    z = i * 360 / var.bolts
+    translate { offset = [var.circle_r, 0, -1]  cylinder { radius = 3  height = 12 } }
+  }
+}
+\`\`\``,
+
+  parts: `## Parts and scenes
+
+A \`part\` is a separately coloured piece of the finished scene. It is **not an operand**: it
+contributes no geometry to the block around it.
+
+\`\`\`hcl
+model "assembly" {
+  part "frame" { color = "#6f7d8c"  box { size = [40, 40, 4] } }
+  part "pin"   { color = "#c8842f"  opacity = 0.4
+                 translate { offset = [0, 0, 4]  cylinder { radius = 3  height = 10 } } }
+}
+\`\`\`
+
+- Declare parts **directly in a model**, or inside a \`for\`/\`if\` in one. A part nested inside
+  a transform or a boolean is **silently dropped** — no error, it is just gone.
+- A part cannot contain another part, cannot be empty, and cannot come out of a component.
+- Geometry written outside any part becomes one default part named after the model.
+- The label is an expression: \`part "leg_\${i}"\`.
+- To make a part optional, put the \`if\` **around** it, never inside it.`,
+
+  pitfalls: `## The mistakes that cost the most time
+
+1. **Hyphens bind into names.** \`outer-inner\` is one identifier. Write \`outer - inner\`.
+2. **A misspelled attribute is an error, not a silent no-op** — \`box: unknown attribute
+   "colour"\`. The one exception is a \`param\` block, which passes anything through.
+3. **A part inside a transform disappears** with no warning. Put the transform inside the
+   part.
+4. **Transforms are about the origin.** \`rotate\` a shape built in the positive quadrant and
+   it swings away from where you expected. Use \`center = true\`, or \`align\`.
+5. **A cutter must overshoot.** A \`difference\` whose cutter ends exactly on the body's face
+   leaves a zero-thickness skin. Start it below and run it past.
+6. **\`revolve\` needs a profile at X ≥ 0.** Crossing the axis puts a spike through the middle.
+7. **2D cannot be rendered.** A part holding a \`circle\` fails; extrude it.
+8. **\`param s\` alone is a syntax error.** Write \`param s { }\` for a required param.
+9. **\`min\`/\`max\`/\`step\`/\`options\` on a param are advisory** and never enforced. Clamp in
+   the model if the bound matters: \`local n = max(3, min(16, var.bolts))\`.
+10. **Empty geometry is silent.** \`extrude { height = 0 }\`, a \`difference\` that removes
+    everything and a backwards \`range\` all produce nothing rather than an error — and then
+    fail further out with \`model "m" produced no geometry\`.
+11. **A line break ends an expression** outside brackets. Continue inside \`(...)\` or end the
+    line on an operator.
+12. **\`rotate\` spells its 2D and 3D attributes differently** — \`angle\` in 2D, \`x\`/\`y\`/\`z\`
+    or \`angles\` in 3D.`,
+
+  workflow: `## How to write one of these
+
+1. **Name the inputs first.** Anything a person would want to change is a \`param\` with a
+   \`default\`, a \`min\` and a \`max\`. Anything derived from those is a \`local\`.
+2. **Write the profile, then give it thickness.** Most real parts are a 2D outline extruded
+   or revolved. Modelling in 2D and converting once is shorter and more robust than
+   composing solids.
+3. **Name repeated features as components** — including the *negative* of a feature. A
+   \`component "counterbore"\` subtracted in a loop reads far better than four inlined unions.
+4. **One \`part\` per physical piece**, each with a colour. It is what makes a render legible
+   and what lets a single piece be exported.
+5. **Check it.** Call \`forma_check\` with \`solve: true\` and read the bounding box and the
+   volume back: they are how you know the thing is the size you meant and is not empty.
+   Iterate until it renders, then write it with \`forma_write\`.
+
+Keep every dimension that matters expressed in terms of params, so the document answers
+"what if it were 20 mm taller" without being rewritten.`,
+};
+
+/** The order sections are served in when everything is asked for. */
+const ORDER = [
+  'shape', 'nesting', 'dimensionality', 'units', 'syntax', 'expressions',
+  'scope', 'control', 'parts', 'pitfalls', 'workflow',
+];
+
+/** The names a caller may ask for. */
+export const GUIDE_SECTIONS = ORDER;
+
+/**
+ * The guide, whole or in part.
+ *
+ * @param {string} [section] One of {@link GUIDE_SECTIONS}, or nothing for all of it.
+ * @returns {string} Markdown.
+ * @throws {Error} If the section is not one the guide has.
+ */
+export function guide(section) {
+  if (!section) {
+    return ['# The forma language, in brief', '', ...ORDER.map((name) => SECTIONS[name])].join('\n\n');
+  }
+  if (!SECTIONS[section]) {
+    throw new Error(`no guide section "${section}" — it is one of ${ORDER.join(', ')}`);
+  }
+  return SECTIONS[section];
+}

package/src/reference/README.md

@@ -0,0 +1,153 @@
+# forma Reference
+
+`forma` is a declarative language for describing solids. A document is a list of top-level
+blocks; geometry is written by **nesting blocks**, where a block's children are its operands.
+The evaluator turns a document into a tree of immutable geometry nodes, and the
+[Manifold](https://github.com/elalish/manifold) CSG kernel — compiled to WebAssembly — solves
+that tree into meshes.
+
+```hcl
+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 }
+      }
+    }
+  }
+}
+```
+
+This reference documents every construct in the language and every function the JavaScript
+package exports. For a tour of the project itself — how to run the editor, how to consume the
+library from Node — see the [top-level README](../../../README.md).
+
+---
+
+## Learn the language
+
+Read these in order the first time.
+
+| Page | What it covers |
+| --- | --- |
+| [Document structure](language/overview.md) | The four top-level blocks, the evaluation pipeline, nesting and implicit union, dimensionality |
+| [Syntax](language/syntax.md) | Comments, numbers, strings, identifiers, labels, the rule that a newline ends an attribute |
+| [Expressions](language/expressions.md) | Values, operators, precedence, truthiness, interpolation, member access |
+| [Scope and names](language/scope.md) | What is in scope where, `var.`, shadowing, component isolation |
+| [Control flow](language/control-flow.md) | `for` and `if` / `else if` / `else` |
+
+---
+
+## Declarations
+
+The four blocks that may appear at the top level of a document.
+
+| Declaration | Description |
+| --- | --- |
+| [`param`](reference/param.md) | An input, exposed in the editor as a control and readable as `var.NAME` |
+| [`local`](reference/local.md) | A named value, computed once |
+| [`component`](reference/component.md) | A reusable parameterised block, callable like any builtin |
+| [`model`](reference/model.md) | Something to render. A document may declare several |
+
+---
+
+## Shapes
+
+Leaf blocks. They take attributes and never contain other blocks.
+
+| Block | Dimensionality | Description |
+| --- | --- | --- |
+| [`rect`](reference/shapes-2d.md#rect) | 2D | An axis-aligned rectangle |
+| [`rounded_rect`](reference/shapes-2d.md#rounded_rect) | 2D | A rectangle with true arcs at the corners |
+| [`circle`](reference/shapes-2d.md#circle) | 2D | A circle, from a radius or a diameter |
+| [`ellipse`](reference/shapes-2d.md#ellipse) | 2D | A circle scaled to two exact radii |
+| [`regular_polygon`](reference/shapes-2d.md#regular_polygon) | 2D | An *n*-gon, sized across flats, across corners, or by radius |
+| [`stadium`](reference/shapes-2d.md#stadium) | 2D | A rectangle fully rounded on its short axis |
+| [`polygon`](reference/shapes-2d.md#polygon) | 2D | An explicit outline, or several contours with holes |
+| [`box`](reference/shapes-3d.md#box) | 3D | An axis-aligned cuboid |
+| [`sphere`](reference/shapes-3d.md#sphere) | 3D | A sphere |
+| [`cylinder`](reference/shapes-3d.md#cylinder) | 3D | A cylinder, or a frustum from two radii |
+| [`cone`](reference/shapes-3d.md#cone) | 3D | A cone, or a truncated cone |
+| [`torus`](reference/shapes-3d.md#torus) | 3D | A ring, optionally a partial arc |
+
+2D shapes cannot be rendered on their own — [`extrude`](reference/conversions.md#extrude) or
+[`revolve`](reference/conversions.md#revolve) them first.
+
+---
+
+## Operations
+
+Blocks that take geometry as children and produce new geometry.
+
+| Block | Takes | Description |
+| --- | --- | --- |
+| [`union`](reference/booleans.md#union) | 2D or 3D | Everything added together |
+| [`difference`](reference/booleans.md#difference) | 2D or 3D | The first child, with every later child cut out of it |
+| [`intersection`](reference/booleans.md#intersection) | 2D or 3D | Only what every child shares |
+| [`translate`](reference/transforms.md#translate) | 2D or 3D | Moves geometry |
+| [`rotate`](reference/transforms.md#rotate) | 2D or 3D | Turns geometry about the origin |
+| [`scale`](reference/transforms.md#scale) | 2D or 3D | Scales geometry about the origin |
+| [`mirror`](reference/transforms.md#mirror) | 2D or 3D | Reflects geometry in a plane through the origin |
+| [`extrude`](reference/conversions.md#extrude) | 2D → 3D | Sweeps a profile along Z, with optional twist and taper |
+| [`revolve`](reference/conversions.md#revolve) | 2D → 3D | Turns a profile about the Y axis into a solid of revolution |
+| [`project`](reference/conversions.md#project) | 3D → 2D | The shadow of a solid on the XY plane |
+| [`slice`](reference/conversions.md#slice) | 3D → 2D | The cross-section of a solid at one Z |
+| [`offset`](reference/refinement.md#offset) | 2D | Grows or shrinks an outline |
+| [`hull`](reference/refinement.md#hull) | 2D or 3D | The convex hull of everything inside |
+| [`refine`](reference/refinement.md#refine) | 3D | Subdivides edges longer than a limit |
+| [`simplify`](reference/refinement.md#simplify) | 2D or 3D | Removes vertices within a tolerance |
+| [`smooth`](reference/refinement.md#smooth) | 3D | Rounds edges below a sharpness threshold |
+| [`trim`](reference/refinement.md#trim) | 3D | Cuts a solid with a half-space |
+| [`align`](reference/align.md) | 2D or 3D | Moves geometry so a measured feature of its bounding box lands where you say |
+
+---
+
+## Scene
+
+| Block | Description |
+| --- | --- |
+| [`part`](reference/part.md) | A separately coloured piece of the rendered scene |
+
+---
+
+## Expressions
+
+| Page | What it covers |
+| --- | --- |
+| [Functions](reference/functions.md) | `abs`, `min`, `len`, `range`, `sin`, and the rest of the builtin functions |
+| [Constants](reference/functions.md#constants) | `pi` and `e` |
+| [Operators](language/expressions.md#operators) | Arithmetic, comparison, logic, and what each accepts |
+
+---
+
+## JavaScript API
+
+`src/` is the library; the editor is one consumer of it. Everything below is exported from
+the package root and typed by hand-written declarations.
+
+| API | Description |
+| --- | --- |
+| [`render`](api/render.md) | Compile a document and evaluate one model into renderable parts |
+| [`describeParameters`](api/describe-parameters.md) | Read a document's declared params without rendering |
+| [`EvaluationContext`](api/evaluation-context.md) | The digest cache and the owner of every WASM object |
+| [`GeometryNode`](api/geometry-node.md) | The immutable, content-addressed geometry IR |
+| [`loadKernel`, `setQuality`, `resetQuality`](api/kernel.md) | Loading and tuning the Manifold module |
+| [`toRenderMesh`, `toBinarySTL`](api/export.md) | Turning a solid into buffers or a file |
+| [`Vector`, `Angle`, `Transform`](api/values.md) | The value types the evaluator works in |
+| [`Program`, `Evaluator`, `parse`, `tokenize`, …](api/low-level.md) | The compiler stages, and the block and function registries |
+
+---
+
+## Errors
+
+[Every error message](errors.md), what raises it, and what to change — the language's errors
+in one place, grouped by the stage that raises them.

package/src/reference/api/describe-parameters.md

@@ -0,0 +1,167 @@
+# `describeParameters`
+
+Reads what a document declares as inputs, without rendering anything.
+
+```js
+import { describeParameters } from 'forma-dsl';
+
+const params = describeParameters(source);
+```
+
+---
+
+## Reference
+
+### `describeParameters(source)`
+
+Parses `source` and returns one descriptor per top-level [`param`](../reference/param.md), in
+source order. No geometry is evaluated and no kernel is loaded — this is the call a front end
+makes to build controls before it can have any values to render with.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `source` | `string` | The document |
+
+#### Returns
+
+`ParameterDescriptor[]`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The param's name |
+| `type` | `'number' \| 'string' \| 'bool' \| 'vector' \| 'list' \| 'angle' \| string` | The declared `type`, or one inferred from the default |
+| `default` | `ParameterValue \| undefined` | The evaluated default, if there is one |
+| `required` | `boolean` | `true` when the param declares no default |
+| `min` | `number \| undefined` | Advisory |
+| `max` | `number \| undefined` | Advisory |
+| `step` | `number \| undefined` | Advisory |
+| `description` | `string \| undefined` | Help text |
+| `options` | `ParameterValue[] \| undefined` | A fixed set of choices |
+
+#### Caveats
+
+- **Params are read leniently.** A document that declares a required param must be
+  describable before anyone could have supplied a value for it, so nothing throws about
+  missing values here.
+- **One unreadable attribute does not lose the rest.** If a `min` refers to something that
+  cannot be resolved yet, that field comes back `undefined` and every other descriptor is
+  still returned.
+- **`min`, `max`, `step` and `options` are advisory.** Nothing enforces them, including
+  [`render`](render.md). Clamp in the model if a bound matters.
+- **Model params are not listed.** A `param` inside a `model` is a constant, not an input.
+- It still throws on a **syntax error** — the document has to parse.
+
+#### Type inference
+
+When a param declares no `type`, one is inferred from the default:
+
+| Default | Inferred type |
+| --- | --- |
+| a number | `number` |
+| a boolean | `bool` |
+| a string | `string` |
+| a list | `vector` |
+| nothing | `number` |
+
+---
+
+## Usage
+
+### Building controls
+
+```js
+const descriptors = describeParameters(source);
+
+for (const p of descriptors) {
+  switch (p.type) {
+    case 'number':
+      addSlider(p.name, {
+        value: p.default ?? p.min ?? 0,
+        min: p.min, max: p.max, step: p.step,
+        title: p.description,
+      });
+      break;
+    case 'bool':
+      addCheckbox(p.name, { value: p.default ?? false });
+      break;
+    case 'string':
+      p.options ? addSelect(p.name, p.options) : addTextField(p.name);
+      break;
+    case 'vector':
+      addVectorField(p.name, { value: p.default ?? [0, 0, 0] });
+      break;
+  }
+}
+```
+
+### Collecting values to render with
+
+```js
+const descriptors = describeParameters(source);
+
+const params = Object.fromEntries(
+  descriptors
+    .filter((p) => p.default !== undefined)
+    .map((p) => [p.name, p.default]),
+);
+
+const result = await render(source, { params, context });
+```
+
+### Insisting on required inputs
+
+```js
+const missing = describeParameters(source)
+  .filter((p) => p.required && values[p.name] === undefined)
+  .map((p) => p.name);
+
+if (missing.length) {
+  throw new Error(`Supply a value for: ${missing.join(', ')}`);
+}
+```
+
+This is the whole reason `required` exists: a document can declare that there is no sensible
+default, and a front end can act on that before rendering fails.
+
+### Re-reading after an edit
+
+`describeParameters` is cheap — a parse, no kernel — so calling it on every edit is
+reasonable. Keep any value the user has already set, for a param that still exists with a
+compatible type:
+
+```js
+function reconcile(source, previous) {
+  const next = {};
+  for (const p of describeParameters(source)) {
+    next[p.name] = p.name in previous ? previous[p.name] : p.default;
+  }
+  return next;
+}
+```
+
+---
+
+## Troubleshooting
+
+### A descriptor's `default` is `undefined`
+
+Either the param declares no default — check `required` — or its default could not be
+evaluated. A default that refers to a param declared **below** it cannot resolve; params are
+read in source order.
+
+### `min` and `max` came back `undefined`
+
+The expression could not be evaluated. That is deliberately not fatal: one unreadable
+metadata attribute must not cost the caller every other descriptor.
+
+### My param is not in the list
+
+It is probably declared inside a `model` rather than at the top level. Only top-level params
+are inputs; see [model params](../reference/model.md#model-params).
+
+### The values I pass are ignored
+
+`render` accepts values for declared top-level params only, and silently ignores anything
+else. Compare the keys you pass against `describeParameters(source).map((p) => p.name)`.