forma-dsl-mcp 0.1.4

package/src/reference/reference/param.md

@@ -0,0 +1,230 @@
+# `param`
+
+A declared input. Params are what the editor turns into controls and what
+[`render`](../api/render.md) accepts values for.
+
+```hcl
+param height { type = number  default = 20  min = 8  max = 40  step = 1 }
+param wall = 2.5
+```
+
+---
+
+## Reference
+
+### `param NAME { ... }`
+
+Declares an input at the top level of a document. Read it as `var.NAME`, or by its bare name.
+
+```hcl
+param bolts {
+  type        = number
+  default     = 6
+  min         = 3
+  max         = 16
+  step        = 1
+  description = "How many holes on the bolt circle"
+}
+```
+
+#### Attributes
+
+Every attribute is optional. **Only `default` affects geometry** — the rest describe the
+control the editor should build, and are returned verbatim by
+[`describeParameters`](../api/describe-parameters.md).
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `default` | any | The value used when the caller supplies none. Without it the param is *required* |
+| `type` | `number` `string` `bool` `vector` `list` `angle` | Which control to build. Written bare, without quotes. Inferred from `default` when omitted |
+| `min` | number | Lower bound of the control |
+| `max` | number | Upper bound of the control |
+| `step` | number | Granularity of the control |
+| `description` | string | Help text |
+| `options` | list | A fixed set of choices, for a dropdown rather than a free field |
+
+Unknown attributes are **not** rejected here — a param block is metadata, and anything in it
+is passed through to the descriptor. This is the one block in the language that does not
+reject attributes it does not understand.
+
+#### Returns
+
+Nothing. A param binds a name; it produces no geometry.
+
+#### Caveats
+
+- **`min`, `max`, `step` and `options` are not enforced.** They shape the editor's control
+  and nothing else. `render(source, { params: { bolts: 9999 } })` succeeds on a param
+  declared `max = 16`. Validate in the model if a bound matters —
+  `local n = min(max(var.bolts, 3), 16)`.
+- A param block may contain **attributes only**. Nested blocks inside it are an error:
+  `a param block holds attributes, not nested blocks`.
+- Declaring the same param twice is an error: `param "a" is declared twice`.
+- A param's `default` may refer to params declared **above** it by their bare name, but not
+  to `var` — `var` is assembled after every param has resolved. See
+  [Scope](../language/scope.md#the-root-scope).
+- A param declared inside a `model` is a different thing: it must have a default and cannot
+  be set from outside. See [`model`](model.md#model-params).
+
+---
+
+### `param NAME = expression`
+
+Shorthand for a param whose only attribute is `default`.
+
+```hcl
+param thickness = 8
+param sizes     = [1.5, 2, 2.5, 3]
+```
+
+Identical to `param thickness { default = 8 }`. Use it when the editor needs no bounds and
+no description.
+
+---
+
+## Usage
+
+### Reading a param
+
+Both spellings work; `var.` is the convention because it marks the value as an input at the
+point of use.
+
+```hcl
+param height = 20
+
+model "m" {
+  extrude { height = var.height  circle { radius = 10 } }
+  //                 ^^^^^^^^^^ or just `height`, same value
+}
+```
+
+`var` holds **params only**. A [`local`](local.md) with the same name shadows the bare name
+but never appears under `var`, which is what makes `var.` unambiguous:
+
+```hcl
+param a = 1
+local a = 2
+
+model "m" { box { size = [a, var.a, 1] } }   // [2, 1, 1]
+```
+
+### Choosing a type
+
+`type` is what the editor reads to decide which control to draw.
+
+```hcl
+param count   { type = number  default = 6  min = 1  max = 20  step = 1 }   // slider
+param label   { type = string  default = "A" }                              // text field
+param hollow  { type = bool    default = true }                             // checkbox
+param size    { type = vector  default = [40, 30, 12] }                     // three fields
+param sweep   { type = angle   default = 45  min = 0  max = 360 }           // degrees
+```
+
+When `type` is omitted it is inferred from the default: a number gives `number`, a boolean
+`bool`, a string `string`, a list `vector`. A param with neither a `type` nor a `default`
+falls back to `number`.
+
+An `angle` param is an ordinary number as far as the language is concerned — every angle in
+forma is in degrees, and the type only tells the editor to label the control that way.
+
+### Declaring a required input
+
+A param with no `default` has no value until one is supplied. Rendering without it fails:
+
+```hcl
+param serial { type = string }
+```
+
+```
+param "serial" has no default and no value was supplied
+```
+
+[`describeParameters`](../api/describe-parameters.md) reports it as `required: true`, so a
+front end can insist on a value before rendering. This is how a document says "there is no
+sensible default for this".
+
+### Deriving one input from another
+
+Params are resolved in source order, so a later default may be written in terms of an
+earlier one:
+
+```hcl
+param diameter = 72
+param wall     = 1.6
+param bore     = diameter / 2 - wall * 4     // ✓ bare names of earlier params
+```
+
+For a value that is always derived and should never be a control, use a
+[`local`](local.md) instead — locals are computed after every param and may use `var.`.
+
+### Offering a fixed set of choices
+
+```hcl
+param finish {
+  type    = string
+  default = "matte"
+  options = ["matte", "gloss", "raw"]
+}
+
+model "m" {
+  part "body" {
+    color = var.finish == "gloss" ? "#e8eef4" : "#8f9ba6"
+    box { size = [20, 20, 20] }
+  }
+}
+```
+
+`options` is carried through to the descriptor for the editor to render as a dropdown.
+Nothing checks that a supplied value is one of them, so branch with a final `else` that is
+safe.
+
+---
+
+## Troubleshooting
+
+### `param "height" has no default and no value was supplied`
+
+The document declares the param with no `default`, and the caller passed no value. Either
+give it a default, or supply one:
+
+```js
+await render(source, { params: { height: 20 } });
+```
+
+[`describeParameters`](../api/describe-parameters.md) works on such a document — it is built
+to be callable before any value exists, so a front end can discover what to ask for.
+
+### `param "a" is declared twice`
+
+Two top-level `param` blocks share a name. Unlike locals, params are rejected rather than
+overwritten, because a duplicated input would make the editor's control ambiguous.
+
+### `a param block holds attributes, not nested blocks`
+
+Something inside the braces was parsed as a block rather than an attribute — usually a
+missing `=`:
+
+```hcl
+param height { default 20 }     // ✗ parsed as a block named `default`
+param height { default = 20 }   // ✓
+```
+
+### `unknown name "var"`
+
+A param default referred to `var`. `var` is assembled only after every param has been
+resolved, so it does not exist yet:
+
+```hcl
+param a = 3
+param b = var.a * 2     // ✗ unknown name "var"
+param b = a * 2         // ✓ earlier params are in scope by their bare name
+```
+
+### The editor ignores my `min` and `max`
+
+They are advisory. The control respects them, but a value supplied through the JavaScript
+API does not, and the geometry never sees them. Clamp in the model if it matters:
+
+```hcl
+local bolts = max(3, min(16, var.bolts))
+```

package/src/reference/reference/part.md

@@ -0,0 +1,229 @@
+# `part`
+
+A separately coloured piece of the rendered scene.
+
+```hcl
+model "assembly" {
+  part "frame" { color = "#6f7d8c"  box { size = [40, 40, 4] } }
+  part "pin"   { color = "#c8842f"  translate { offset = [0, 0, 4]  cylinder { radius = 3  height = 10 } } }
+}
+```
+
+---
+
+## Reference
+
+### `part "NAME" { ... }`
+
+Groups geometry into one named, coloured piece of the scene. Parts are solved independently
+and drawn in their own colour.
+
+A part is **not an operand**. It does not contribute geometry to the block around it, and an
+enclosing `translate` will not move it — which is why a part belongs directly in a
+[`model`](model.md), or inside a `for` or `if` in one.
+
+#### Label
+
+Optional, and an **expression** rather than a fixed string, so a part built in a loop can
+name itself:
+
+```hcl
+part "tray_${i}" { ... }
+```
+
+Without a label, the part is named `part_<line>` after the line it was written on.
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `color` | string | `"#b8c4d0"` | Any CSS colour the viewer understands. Usually `#rrggbb` |
+| `opacity` | number | `1` | `0` is invisible, `1` is opaque. Useful for showing contents through a shell |
+
+#### Returns
+
+Nothing, to the enclosing block. The part travels separately and lands in the scene.
+
+#### Caveats
+
+- **A part cannot contain another part**: `a part cannot contain another part`. Parts are a
+  flat list, not a tree.
+- **A part nested inside an operation is silently dropped.** `translate { part "p" { … } }`
+  discards the part with no error, because an operation collects geometry from its children
+  and a part contributes none. Declare parts directly in the model. See
+  [Troubleshooting](#a-part-inside-an-operation-disappears).
+- **A part cannot be empty**: `a part needs at least one shape inside it`. To make a part
+  conditional, put the [`if`](../language/control-flow.md#if) around it, not inside it.
+- **A part cannot come out of a [`component`](component.md)**:
+  `a component cannot declare parts`. Call the component inside a part instead.
+- **Every part must be 3D** by the time it renders:
+  `part "body" is 2D — extrude or revolve it before rendering`.
+- Several blocks inside a part are implicitly unioned, exactly as anywhere else.
+- Nothing rejects two parts with the same name; the viewer will simply list two entries
+  called the same thing.
+
+---
+
+## Usage
+
+### Colouring an assembly
+
+The common case. Each physical piece gets a part, and the colours make the render readable:
+
+```hcl
+model "water_bottle" {
+  part "bottle" { color = "#8fd3e8"  bottle_shell { } }
+  part "cap"    { color = "#e2593c"  translate { offset = [0, 0, 170]  cap { } } }
+  part "label"  { color = "#f4f1e4"  label_band { } }
+}
+```
+
+### Showing what is inside
+
+`opacity` makes a shell see-through without changing the geometry:
+
+```hcl
+model "assembly" {
+  part "case" {
+    color   = "#8fa8bd"
+    opacity = 0.35            // the board below shows through
+    case_shell { }
+  }
+
+  part "board" { color = "#2f7d4f"  translate { offset = [0, 0, 3]  board { } } }
+}
+```
+
+Opacity is a display property. It does not affect the solid, the digest, or an exported STL.
+
+### Parts in a loop
+
+A part label is an expression, so the loop variable can name each one:
+
+```hcl
+model "stack" {
+  for i in range(0, var.rows) {
+    part "tray_${i}" {
+      color = i % 2 == 0 ? "#3f7fbf" : "#bf6b3f"
+      translate { offset = [0, 0, i * 13]  tray { } }
+    }
+  }
+}
+```
+
+### Making a part optional
+
+Put the condition **outside** the part:
+
+```hcl
+// ✓
+if var.show_label {
+  part "label" { color = "#f4f1e4"  label_band { } }
+}
+
+// ✗ — when show_label is false this is an empty part, which is an error
+part "label" {
+  if var.show_label { label_band { } }
+}
+```
+
+### One part, several pieces of geometry
+
+Everything in a part is unioned, so a part may hold as many blocks as it needs:
+
+```hcl
+part "bottle" {
+  color = "#8fd3e8"
+
+  difference {                       // the shell…
+    bottle_solid { }
+    bottle_void { }
+  }
+
+  for i in range(0, 3) {             // …plus the thread ridges, same part
+    translate { offset = [0, 0, 174 + i * 4.5]  torus { radius = 15.6  tube_radius = 1.1 } }
+  }
+}
+```
+
+---
+
+## How parts reach the renderer
+
+[`render`](../api/render.md) returns one entry per part:
+
+```js
+const result = await render(source);
+
+for (const part of result.parts) {
+  part.name;      // "bottle"
+  part.color;     // "#8fd3e8"
+  part.opacity;   // 1
+  part.node;      // the GeometryNode — what context.collect() wants
+  part.concrete;  // the solved Manifold solid, owned by the context
+  part.mesh;      // positions and normals, ready to upload
+}
+```
+
+Parts are solved independently, so two parts that share a subtree still solve it once — the
+digest cache is keyed on content, not on which part asked.
+
+To export one part, pass its `concrete` to [`toBinarySTL`](../api/export.md#tobinarystl).
+
+---
+
+## Troubleshooting
+
+### `a part needs at least one shape inside it`
+
+The part's body produced nothing — usually an `if` inside it that took no branch, or a `for`
+over an empty list. Move the condition outside the part.
+
+### `a part cannot contain another part`
+
+Parts are flat. To group several coloured pieces, declare them as siblings in the model. If
+the grouping matters for positioning, apply the same `translate` inside each one, or hoist
+the shared placement into a [`component`](component.md).
+
+### `a component cannot declare parts`
+
+Geometry comes out of a component; scene structure does not. Invert it:
+
+```hcl
+component "shell" { ... }                    // geometry only
+model "m" { part "shell" { shell { } } }     // the part lives here
+```
+
+### `part "body" is 2D — extrude or revolve it before rendering`
+
+The part holds a cross-section. Extrude or revolve it first — see
+[2D ↔ 3D](conversions.md).
+
+### A part inside an operation disappears
+
+A part is not an operand, so an operation collects no geometry from it. What happens next
+depends on whether the operation had anything else to work with:
+
+```hcl
+// ✗ fails: "translate" needs at least one shape inside it
+translate { offset = [0, 0, 10]  part "p" { box { size = [1, 1, 1] } } }
+
+// ✗ worse — renders, but part "p" is silently gone from the scene
+translate {
+  offset = [0, 0, 10]
+  box { size = [1, 1, 1] }
+  part "p" { sphere { radius = 1 } }
+}
+
+// ✓ the transform belongs inside the part
+part "p" { translate { offset = [0, 0, 10]  box { size = [1, 1, 1] } } }
+```
+
+Nothing warns about the second case. If a part you declared is missing from the render,
+check that it is written directly in the [`model`](model.md) — or inside a `for` or `if` in
+one — and not nested inside a transform or a boolean.
+
+### Two parts have the same name
+
+Nothing rejects it. Part names come from an expression, so a loop that computes the same
+label twice produces duplicates — include the loop index: `part "leg_${i}"`.