forma-dsl-mcp 0.1.4

package/src/reference/reference/functions.md

@@ -0,0 +1,314 @@
+# Functions
+
+Thirty builtin functions, callable in any [expression](../language/expressions.md). They take
+**positional arguments only** — named arguments are an error — and there are no user-defined
+functions: to name a value declare a [`local`](local.md), and to name geometry declare a
+[`component`](component.md).
+
+**Every angle is in degrees**, in both directions: `sin` takes degrees, `atan` returns them.
+
+| | |
+| --- | --- |
+| [Arithmetic](#arithmetic) | `abs` `floor` `ceil` `round` `sqrt` `sign` `pow` `log` `exp` |
+| [Trigonometry](#trigonometry) | `sin` `cos` `tan` `asin` `acos` `atan` `atan2` |
+| [Aggregates](#aggregates) | `min` `max` `sum` |
+| [Lists](#lists) | `len` `concat` `reverse` `contains` `join` `range` |
+| [Conversion](#conversion) | `str` `num` |
+| [Constants](#constants) | `pi` `e` |
+
+---
+
+## Arithmetic
+
+| Function | Arity | Description |
+| --- | --- | --- |
+| `abs(x)` | 1 | Magnitude, discarding the sign |
+| `floor(x)` | 1 | Rounds towards −∞ |
+| `ceil(x)` | 1 | Rounds towards +∞ |
+| `round(x)` | 1 | Rounds to the nearest integer, halves upwards |
+| `sqrt(x)` | 1 | Square root. Negative input gives NaN, which fails where it is used |
+| `sign(x)` | 1 | `-1`, `0` or `1` |
+| `pow(x, y)` | 2 | `x` raised to `y` |
+| `log(x)` | 1 | Natural logarithm |
+| `exp(x)` | 1 | `e` raised to `x` |
+
+```hcl
+local rows = ceil(len(items) / 4)
+local step = pow(2, var.doublings)
+```
+
+---
+
+## Trigonometry
+
+| Function | Arity | Takes | Returns |
+| --- | --- | --- | --- |
+| `sin(a)` | 1 | degrees | ratio |
+| `cos(a)` | 1 | degrees | ratio |
+| `tan(a)` | 1 | degrees | ratio |
+| `asin(v)` | 1 | ratio | degrees |
+| `acos(v)` | 1 | ratio | degrees |
+| `atan(v)` | 1 | ratio | degrees |
+| `atan2(y, x)` | 2 | two lengths | degrees, in the correct quadrant |
+
+Degrees throughout is deliberate: every angle a model writes is in degrees, and a stray
+radian conversion is invisible until the part is printed.
+
+```hcl
+// A point on a bolt circle
+local angle = i * 360 / var.bolts
+local point = [var.r * cos(angle), var.r * sin(angle)]
+
+// The angle of a slope
+local rake = atan2(var.rise, var.run)
+```
+
+Note the argument order of `atan2`: **y first**, then x.
+
+---
+
+## Aggregates
+
+| Function | Arity | Description |
+| --- | --- | --- |
+| `min(...)` | variadic | The smallest value |
+| `max(...)` | variadic | The largest value |
+| `sum(...)` | variadic | Everything added together; `0` for no arguments |
+
+All three **flatten their arguments**, so a list and a spread of numbers both work:
+
+```hcl
+min(3, 7, 2)           // 2
+min([3, 7, 2])         // 2
+max(sizes)             // the largest entry
+sum(thicknesses)       // total stack height
+```
+
+This is how a value gets clamped, since the language has no `clamp`:
+
+```hcl
+local bolts = max(3, min(16, var.bolts))
+```
+
+#### Caveats
+
+- `min()` and `max()` with no arguments return `Infinity` and `-Infinity`, which fail with
+  `must be a finite number` wherever a block reads them. Guard an empty list.
+
+---
+
+## Lists
+
+### `len`
+
+`len(value)` → number
+
+The length of a list or a string. Anything else gives `0` — it does not raise.
+
+```hcl
+len([1, 2, 3])      // 3
+len("abcd")         // 4
+len(42)             // 0
+```
+
+### `concat`
+
+`concat(...)` → list
+
+Joins lists and values into one flat list.
+
+```hcl
+concat([1, 2], [3])        // [1, 2, 3]
+concat(sizes, [10, 12])    // sizes with two more entries
+```
+
+Flattens one level, like the aggregates.
+
+### `reverse`
+
+`reverse(list)` → list
+
+A reversed copy. The original is untouched.
+
+```hcl
+reverse([1, 2, 3])          // [3, 2, 1]
+concat(profile, reverse(profile))
+```
+
+### `contains`
+
+`contains(list, value)` → bool
+
+Whether the list holds the value. Comparison is by identity for numbers and strings, so it
+does not match nested lists structurally.
+
+```hcl
+contains(["a", "b"], var.mode)
+```
+
+### `join`
+
+`join(separator, list)` → string
+
+Joins a list into a string. **The separator comes first.**
+
+```hcl
+join("-", ["M3", "x", "12"])      // "M3-x-12"
+join(", ", sizes)
+```
+
+### `range`
+
+`range(end)` · `range(start, end)` · `range(start, end, step)` → list
+
+A list of numbers. The end is **excluded**.
+
+```hcl
+range(4)              // [0, 1, 2, 3]
+range(2, 6)           // [2, 3, 4, 5]
+range(0, 10, 2.5)     // [0, 2.5, 5, 7.5]
+range(5, 0, -1)       // [5, 4, 3, 2, 1]
+range(0, -5)          // []  — backwards with a positive step is empty, not infinite
+```
+
+This is what drives most [`for`](../language/control-flow.md#for) loops.
+
+#### Caveats
+
+- **The end is excluded**, so `range(0, var.bolts)` gives exactly `bolts` values.
+- A `step` of `0` is an error: `range: step cannot be 0`.
+- A range running the wrong way for its step is **empty** rather than infinite, which is what
+  a loop written around a parameter needs when the parameter crosses zero.
+- More than 100,000 values is an error: `range: more than 100000 values`. The guard exists
+  because in a live editor `range(0, 1e9)` is a state the document passes through while the
+  number is being typed.
+- Floating-point accumulation applies. `range(0, 1, 0.1)` may not end where you expect;
+  prefer integer counts and multiply: `for i in range(0, 10) { local t = i / 10 ... }`.
+
+---
+
+## Conversion
+
+| Function | Arity | Description |
+| --- | --- | --- |
+| `str(v)` | 1 | The value as a string |
+| `num(v)` | 1 | The value as a number; non-numeric text gives NaN |
+
+```hcl
+part "slot_${str(i)}" { ... }     // though "${i}" already does this
+local n = num(var.text_input)
+```
+
+String interpolation already converts, so `str` is mostly useful when building a string with
+`+`.
+
+---
+
+## Constants
+
+| Name | Value |
+| --- | --- |
+| `pi` | 3.141592653589793 |
+| `e` | 2.718281828459045 |
+
+They are ordinary names in the root scope, so they can be shadowed by a param or a local —
+avoid doing so.
+
+```hcl
+local circumference = 2 * pi * var.radius
+```
+
+Since every angle in the language is in degrees, `pi` comes up less than it would elsewhere —
+mostly in arc lengths and areas rather than in rotations.
+
+---
+
+## Usage
+
+### Clamping a parameter
+
+`min`/`max` bounds are advisory in a [`param`](param.md) block. Enforce them where it matters:
+
+```hcl
+param bolts { type = number  default = 6  min = 3  max = 16  step = 1 }
+
+local bolts = max(3, min(16, round(var.bolts)))
+```
+
+### Laying out an array from a list
+
+`len` gives the count, and the index does the rest:
+
+```hcl
+local sizes = [1.5, 2, 2.5, 3, 4, 5, 6]
+
+for i, size in sizes {
+  translate {
+    offset = [(i - (len(sizes) - 1) / 2) * var.spacing, 0, 0]   // centred on the origin
+    ...
+  }
+}
+```
+
+### Polar coordinates
+
+```hcl
+for i in range(0, var.count) {
+  local a = i * 360 / var.count
+  translate {
+    offset = [var.r * cos(a), var.r * sin(a), 0]
+    cylinder { radius = 2  height = 10 }
+  }
+}
+```
+
+Equivalent to rotating a translated copy, and sometimes easier to read when each item also
+needs its own orientation.
+
+### Building a label
+
+```hcl
+param sizes = [3, 4, 5]
+
+model "m" {
+  part "set_${join("_", var.sizes)}" { ... }     // "set_3_4_5"
+}
+```
+
+---
+
+## Troubleshooting
+
+### `len takes 1 argument(s), got 2`
+
+A fixed-arity function got the wrong count. The variadic ones — `min`, `max`, `sum`,
+`concat`, `range` — accept any number; the rest do not.
+
+### `pow: functions take positional arguments`
+
+Named arguments are not supported: `pow(2, 10)`, never `pow(x = 2, y = 10)`.
+
+### `unknown function "clamp"`
+
+There is no `clamp`, no `abs` on lists, no `map` and no `filter`. Compose what you need from
+`min`/`max`, and use a [`for`](../language/control-flow.md#for) loop where you would reach for
+`map`.
+
+### `range: step cannot be 0`
+
+A step of zero would never terminate. If the step is computed, guard it.
+
+### `range: more than 100000 values`
+
+Usually a range whose end is a mistyped parameter. The limit is a guard against a live editor
+allocating until the tab dies.
+
+### `... must be a finite number`
+
+Something upstream produced `NaN` or `Infinity` — `sqrt` of a negative, `min()` of nothing,
+`num("abc")`. The error names the block and attribute that read it, not where it was
+produced, so work backwards from there.
+
+### My `join` produced the arguments the wrong way round
+
+The separator is first: `join(", ", list)`.

package/src/reference/reference/local.md

@@ -0,0 +1,197 @@
+# `local`
+
+A named value, computed once and reused.
+
+```hcl
+local sizes = [1.5, 2, 2.5, 3, 4, 5, 6]
+local radius = var.diameter / 2
+```
+
+---
+
+## Reference
+
+### `local NAME = expression`
+
+Binds a name to the result of an expression. Locals hold values, never geometry — to name a
+piece of geometry, declare a [`component`](component.md).
+
+#### Parameters
+
+| | |
+| --- | --- |
+| `NAME` | A plain identifier or a quoted string. It may not contain `${ }` |
+| `expression` | Any [expression](../language/expressions.md). Evaluated once, when the local is declared |
+
+#### Returns
+
+Nothing. A local binds a name; it produces no geometry.
+
+#### Caveats
+
+- **Locals are ordered at the top level.** A local may refer to params, to constants and to
+  locals declared *above* it — never below. `local a = b` before `local b = 2` fails with
+  `unknown name "b"`.
+- **Locals inside a body are not ordered.** Every local in one block body is resolved before
+  any of that body's blocks are built, so a block may use a local declared after it. See
+  [Scope → Body scopes](../language/scope.md#body-scopes).
+- **Locals are not in `var`.** `var` holds params only. A local named the same as a param
+  shadows the bare name but leaves `var.NAME` pointing at the param.
+- **A duplicate local is not an error.** A second `local a` silently replaces the first
+  everywhere, including in code written above it. Nothing warns, so treat it as a mistake to
+  avoid.
+- A local is evaluated once, not per use. It cannot depend on a loop variable declared
+  elsewhere, because it is not inside that loop.
+
+---
+
+## Usage
+
+### Naming a derived dimension
+
+The main use: give a computed number a name so the model reads in the vocabulary of the
+thing being modelled rather than in arithmetic.
+
+```hcl
+param diameter      = 72
+param neck_diameter = 28
+param wall          = 1.6
+
+local r       = var.diameter / 2
+local nr      = var.neck_diameter / 2
+local neck_or = nr + var.wall              // outer radius of the neck
+
+model "bottle" {
+  cylinder { radius = neck_or  height = 18 }
+}
+```
+
+Each local may use the ones above it, so a chain of derived measurements stays readable.
+
+### Holding a table of values
+
+A list local is the usual way to drive a `for` loop over irregular data:
+
+```hcl
+local sizes = [1.5, 2, 2.5, 3, 4, 5, 6]
+
+model "hex_key_holder" {
+  for i, size in sizes {
+    translate {
+      offset = [(i - (len(sizes) - 1) / 2) * 8, 0, 0]
+      extrude { height = 20  regular_polygon { sides = 6  width_across_flats = size } }
+    }
+  }
+}
+```
+
+A list of lists works the same way and is how a profile is written:
+
+```hcl
+local profile = [
+  [0, 0], [26, 0], [24, 6], [16, 26], [0, 74],
+]
+
+model "vase" { revolve { polygon { points = profile } } }
+```
+
+### Grouping related settings
+
+An object local keeps a set of numbers that belong together from spreading out:
+
+```hcl
+local fit = { clearance = 0.3, wall = 1.6, chamfer = 0.6 }
+
+model "m" {
+  cylinder { radius = 10 + fit.clearance  height = 4 }
+}
+```
+
+### Locals inside a block
+
+A local declared inside a body is scoped to that body, which keeps a working value out of
+the document's namespace:
+
+```hcl
+param width = 120
+param wall  = 4
+
+model "frame" {
+  part "rail" {
+    local span = var.width - var.wall * 2   // only meaningful here
+    box { size = [span, 10, 4] }
+  }
+}
+```
+
+---
+
+## `local` versus `param` versus `component`
+
+| Use | When |
+| --- | --- |
+| [`param`](param.md) | The value is an **input** — someone outside the document should be able to change it |
+| `local` | The value is **derived** from params or is a fixed table, and should never be a control |
+| [`component`](component.md) | You are naming **geometry**, not a value |
+
+A common shape is a handful of params and a run of locals that turn them into the dimensions
+the geometry actually uses:
+
+```hcl
+param body_height = 170
+param wall        = 1.6
+
+local h   = var.body_height
+local top = h + 18
+local cavity_top = top + 2      // runs past the opening so the neck is not capped
+```
+
+---
+
+## Troubleshooting
+
+### `unknown name "b"`
+
+A top-level local referred to something declared below it. Move the declaration up — locals
+are resolved strictly in source order:
+
+```hcl
+local a = b * 2     // ✗ b does not exist yet
+local b = 2
+
+local b = 2         // ✓
+local a = b * 2
+```
+
+Inside a block body the rule is relaxed, so this only bites at the top level.
+
+### `unknown name "outer-inner"`
+
+Hyphens are part of an identifier, so `outer-inner` is one name rather than a subtraction.
+Put spaces around the operator:
+
+```hcl
+local gap = outer - inner
+```
+
+### `no attribute "a"` when reading `var.a`
+
+`var` holds params only. A local is reached by its bare name:
+
+```hcl
+local a = 2
+box { size = [a, 1, 1] }        // ✓
+box { size = [var.a, 1, 1] }    // ✗ no attribute "a"
+```
+
+### My local is not picking up the loop variable
+
+A local is evaluated where it is written, once. It cannot see a loop variable from a loop it
+is not inside. Move the local inside the loop body, or compute the value inline:
+
+```hcl
+for i in range(0, 6) {
+  local angle = i * 60        // ✓ inside the loop, re-evaluated each iteration
+  rotate { z = angle  ... }
+}
+```

package/src/reference/reference/model.md

@@ -0,0 +1,213 @@
+# `model`
+
+Something to render. A document may declare several; [`render`](../api/render.md) builds one
+of them.
+
+```hcl
+model "hex_key_holder" {
+  part "body" {
+    color = "#6f7d8c"
+    extrude { height = 20  rounded_rect { size = [62, 13]  radius = 6.5  center = true } }
+  }
+}
+```
+
+---
+
+## Reference
+
+### `model "NAME" { ... }`
+
+Declares a renderable scene. The body is geometry, optionally organised into
+[`part`](part.md)s.
+
+#### Body
+
+| Entry | Meaning |
+| --- | --- |
+| [`part "name" { ... }`](part.md) | A separately coloured piece of the scene |
+| geometry blocks | Rendered as one default part named after the model |
+| `param NAME { default = expr }` | A constant for this model. Must have a default; not settable from outside |
+| `local NAME = expr` | A working value, scoped to the model |
+| `for` / `if` | Ordinary control flow, which may produce parts as well as geometry |
+
+#### Returns
+
+A scene: a list of parts, each with a name, a colour, an opacity and a geometry node.
+
+#### Caveats
+
+- **Every part must be 3D.** A 2D part is rejected before it is solved:
+  `part "body" is 2D — extrude or revolve it before rendering`.
+- **A model must produce something.** An empty body, or one whose only loop ran zero times,
+  fails with `model "m" produced no geometry`.
+- **Declaring the same model twice is an error**: `model "m" is declared twice`.
+- **Model params are not inputs.** They must have defaults and cannot be set by the caller.
+  See [Model params](#model-params).
+- A document with no model at all fails at render time with `the document declares no model`.
+
+---
+
+## Usage
+
+### Choosing which model renders
+
+With no name, the **first** model in the document is built:
+
+```js
+await render(source);                      // the first model
+await render(source, { model: 'exploded' }); // by name
+```
+
+Naming one that does not exist fails with `no model named "exploded"`. In the editor, the
+first model is the one shown.
+
+Several models in one document is the idiomatic way to keep variants of the same object
+together — a printable part and the assembly it belongs to, say:
+
+```hcl
+component "bracket" { ... }
+component "pin"     { ... }
+
+model "printable" {                 // what goes to the slicer
+  part "bracket" { bracket { } }
+}
+
+model "assembly" {                  // what it looks like assembled
+  part "bracket" { color = "#6f7d8c"  bracket { } }
+  part "pin"     { color = "#c8842f"  translate { offset = [0, 0, 12]  pin { } } }
+}
+```
+
+### Parts, and geometry without them
+
+Geometry written straight into a model — outside any `part` — becomes **one default part
+named after the model**, coloured `#b8c4d0`:
+
+```hcl
+model "riser" {
+  box { size = [40, 20, 10] }       // → one part called "riser"
+}
+```
+
+Mixing the two is allowed. The loose geometry still collapses into a single part, which is
+listed after the declared ones:
+
+```hcl
+model "m" {
+  box { size = [10, 10, 10] }       // → part "m"
+  part "pin" { cylinder { radius = 2  height = 20 } }
+}
+// parts: "pin", then "m"
+```
+
+Prefer explicit parts once there is more than one piece — they are what the viewer colours
+and lists, and what an exporter can write out separately.
+
+### Model params
+
+A `model` may declare `param` blocks. They are **constants for that model**, not inputs:
+
+```hcl
+model "bracket" {
+  param thickness { default = 4 }
+  param slots     { default = 3 }
+
+  extrude { height = thickness  rect { size = [20, slots * 10] } }
+}
+```
+
+| | Document `param` | Model `param` |
+| --- | --- | --- |
+| Default required | No — may be required instead | **Yes**: `model "m": param "s" needs a default` |
+| Settable by the caller | Yes, via `render(source, { params })` | No |
+| Appears in `describeParameters` | Yes | No |
+| Readable as `var.NAME` | Yes | No — bare name only |
+
+Use them to give one model's fixed numbers a name without adding a control to the editor.
+For anything the caller should change, declare the param at the top level.
+
+### Building parts in a loop
+
+`for` and `if` may produce parts, not just geometry, so a scene can be generated:
+
+```hcl
+model "stacked_trays" {
+  for i in range(0, var.rows) {
+    part "tray_${i}" {
+      color = i % 2 == 0 ? "#3f7fbf" : "#bf6b3f"
+      translate { offset = [0, 0, i * 13]  tray { size = [40, 30, 12]  wall = 2 } }
+    }
+  }
+}
+```
+
+An optional part goes behind an `if` **around** the part, never inside it — a part with no
+geometry is an error:
+
+```hcl
+if var.show_label {
+  part "label" { color = "#f4f1e4"  ... }
+}
+```
+
+### Exploded views
+
+A param that displaces one part is the cheapest way to make an assembly inspectable, and
+costs nothing when it is zero:
+
+```hcl
+param lift { type = number  default = 0  min = 0  max = 90 }
+
+model "assembly" {
+  part "body" { body { } }
+  part "cap"  { translate { offset = [0, 0, 170 + var.lift]  cap { } } }
+}
+```
+
+---
+
+## Troubleshooting
+
+### `model "m" produced no geometry`
+
+The body evaluated to nothing. Usual causes:
+
+- an empty body;
+- a `for` over an empty list — `range(0, var.n)` where `n` is `0`;
+- an `if` with no `else` whose condition was false.
+
+Guard the degenerate case so something is always produced, or make the parameter's minimum
+exclude it.
+
+### `part "body" is 2D — extrude or revolve it before rendering`
+
+A part ended up holding a cross-section rather than a solid. 2D shapes cannot be rendered
+directly:
+
+```hcl
+part "body" { circle { radius = 5 } }                          // ✗
+part "body" { extrude { height = 2  circle { radius = 5 } } }  // ✓
+```
+
+See [`extrude`](conversions.md#extrude) and [`revolve`](conversions.md#revolve).
+
+### `the document declares no model`
+
+The document has params, locals and components but nothing to render. Add a `model` block.
+
+### `model "m": param "s" needs a default`
+
+A param declared inside a model has no default. Model params cannot be supplied from
+outside, so a default is the only way they can ever have a value. Either give it one, or move
+the param to the top level where the caller can set it.
+
+### `model "m" is declared twice`
+
+Two models share a name, so `render(source, { model: 'm' })` would be ambiguous. Rename one.
+
+### My `render(source, { params })` value is ignored
+
+The param is probably declared inside the model rather than at the top level. Only top-level
+params are settable. Check with [`describeParameters`](../api/describe-parameters.md) — it
+lists exactly the params a caller can set.