forma-dsl-mcp 0.1.4

package/src/reference/api/values.md

@@ -0,0 +1,223 @@
+# Values
+
+Three small immutable classes the evaluator works in: [`Vector`](#vector),
+[`Angle`](#angle) and [`Transform`](#transform). Documents never see them directly — a
+document writes lists and bare numbers — but they are exported for anyone building geometry
+through the [`GeometryNode`](geometry-node.md) API.
+
+```js
+import { Vector, Angle, Transform } from 'forma-dsl';
+```
+
+All three are frozen on construction. Every method returns a new value.
+
+---
+
+## `Vector`
+
+A 2D or 3D vector. One class covers both, because every operation is componentwise and a
+separate 3D class would be the same code with one more letter.
+
+### Construction
+
+| | |
+| --- | --- |
+| `new Vector([x, y])` | From components |
+| `Vector.of(value, dimensions)` | From anything vector-like |
+| `Vector.zero(dimensions)` | The origin |
+
+`Vector.of` accepts a `Vector`, a **number** — broadcast to every component — an array, or an
+`{x, y, z}` object whose missing keys read as zero. This is what makes
+`scale { factor = 2 }` work the same as `factor = [2, 2, 2]`.
+
+### Properties
+
+| Property | Description |
+| --- | --- |
+| `components` | The components, frozen |
+| `size` | How many there are |
+| `x`, `y`, `z` | The first, second and third. `z` is `undefined` in 2D |
+| `magnitude` | Length |
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `plus(other)` `minus(other)` | Componentwise |
+| `times(other)` `dividedBy(other)` | Componentwise; a number scales every component |
+| `negated()` | The other way round |
+| `dot(other)` | Dot product |
+| `cross(other)` | Cross product. 3D only |
+| `normalized()` | Scaled to unit length |
+| `toArray()` | A copy, safe to keep |
+
+#### Caveats
+
+- **A zero vector normalises to itself**, not to NaN, so a degenerate normal cannot quietly
+  poison a transform downstream.
+- `Vector.of` throws if the size does not match what was asked for.
+
+---
+
+## `Angle`
+
+An angle, stored in radians and read in whichever unit the caller wants.
+
+The kernel takes degrees and JavaScript's trigonometry takes radians, so a bare number would
+be ambiguous at exactly the call sites where getting it wrong produces a model that is subtly
+wrong rather than an error.
+
+**Every angle the language reads or writes is in degrees.** Radians appear only here.
+
+### Construction
+
+| | |
+| --- | --- |
+| `Angle.degrees(v)` | From degrees |
+| `Angle.radians(v)` | From radians |
+| `Angle.turns(v)` | From full turns, so `0.25` is a right angle |
+| `Angle.of(v)` | From an `Angle`, or a **number read as degrees** |
+| `new Angle(radians)` | Rarely the unit at hand; prefer the factories |
+
+### Properties and methods
+
+| | Description |
+| --- | --- |
+| `radians` | The angle in radians |
+| `degrees` | The angle in degrees |
+| `sin` `cos` `tan` | Trigonometry, as properties |
+| `plus(other)` `minus(other)` | Other may be an `Angle` or a number of degrees |
+| `times(factor)` | A plain multiplier, not an angle |
+
+The unit names appear twice — `Angle.degrees(90)` builds one, `angle.degrees` reads one back.
+They are different namespaces and do not collide.
+
+---
+
+## `Transform`
+
+An affine transform, held column-major at the size the kernel wants: 3×3 for 2D and 4×4 for
+3D.
+
+Column-major throughout, because that is what Manifold reads. Storing row-major and
+transposing at the boundary would put a silent transpose in the one place a wrong model still
+renders.
+
+### Construction
+
+| | |
+| --- | --- |
+| `Transform.identity(dim)` | Changes nothing |
+| `Transform.translation(offset, dim)` | Moves |
+| `Transform.scaling(factor, dim)` | Scales about the origin |
+| `Transform.rotation2D(angle)` | Rotates about the origin. A bare number is degrees |
+| `Transform.rotation3D(angles)` | Degrees about X, Y and Z |
+| `Transform.rotation(angles, dim)` | Dispatches to whichever of the two fits |
+| `Transform.mirroring(normal, dim)` | Reflects in the plane through the origin |
+
+### Properties and methods
+
+| | Description |
+| --- | --- |
+| `dim` | 2 or 3 |
+| `m` | The matrix, column-major and frozen |
+| `order` | Side length — one more than `dim` |
+| `at(row, col)` | One entry, read out of column-major storage |
+| `concat(other)` | `this ∘ other` — **`other` runs first** |
+| `toArray()` | A copy, safe to keep |
+
+#### Caveats
+
+- **3D rotation applies X, then Y, then Z**, matching OpenSCAD, so a model ported from there
+  lands in the same orientation.
+- **`concat` applies its argument first.** That order matches how blocks nest: the transform
+  closest to the shape is applied to it first.
+- `mirroring` normalises the normal, so its length does not change the result.
+- Every transform is about the **origin**. To act about some other point, translate there,
+  act, and translate back.
+
+---
+
+## Usage
+
+### Composing a placement
+
+```js
+import { Transform, GeometryNode } from 'forma-dsl';
+
+// Rotate, then move — the argument to concat runs first.
+const placement = Transform.translation([30, 0, 0], 3)
+  .concat(Transform.rotation3D([0, 0, 45]));
+
+const placed = GeometryNode.transformed(shape, placement);
+```
+
+Reading it as blocks, that is:
+
+```hcl
+translate { offset = [30, 0, 0]  rotate { z = 45  shape { } } }
+```
+
+### Rotating about a point
+
+```js
+const about = (point, rotation) => Transform.translation(point, 3)
+  .concat(rotation)
+  .concat(Transform.translation(new Vector(point).negated().toArray(), 3));
+
+const spun = GeometryNode.transformed(shape, about([20, 20, 0], Transform.rotation3D([0, 0, 30])));
+```
+
+### Working in degrees
+
+```js
+import { Angle } from 'forma-dsl';
+
+const a = Angle.degrees(30);
+a.sin;         // 0.5
+a.radians;     // 0.5235987755982988
+a.plus(60).degrees;   // 90 — a bare number is read as degrees
+```
+
+### Vector arithmetic
+
+```js
+import { Vector } from 'forma-dsl';
+
+const size = new Vector([40, 30, 12]);
+const wall = 2;
+
+const inner = size.minus(new Vector([wall * 2, wall * 2, 0]));
+inner.toArray();      // [36, 26, 12]
+
+Vector.of(3, 3).toArray();          // [3, 3, 3] — a scalar broadcasts
+Vector.of({ x: 1, z: 5 }, 3).toArray();  // [1, 0, 5] — missing keys are zero
+```
+
+---
+
+## Troubleshooting
+
+### `expected 3 components, got 2`
+
+`Vector.of` was asked for a dimensionality the value does not have. In a document this
+surfaces more helpfully as `translate: "offset" must be a number or an array of 3 numbers`.
+
+### `cannot read an angle from string`
+
+`Angle.of` takes an `Angle` or a number. A string is not coerced — that would let `"90deg"`
+silently become `NaN`.
+
+### My composed transform is applied in the wrong order
+
+`concat` runs its **argument** first. `a.concat(b)` means "do `b`, then `a`", matching how
+the equivalent nested blocks read.
+
+### My rotation moved the shape instead of turning it
+
+Every transform is about the origin. Centre the geometry, rotate, then translate.
+
+### Non-uniform scaling made my circle an ellipse
+
+Expected — that is how [`ellipse`](../reference/shapes-2d.md#ellipse) is built internally, and
+it is the cheapest route to an ellipsoid from a sphere.

package/src/reference/errors.md

@@ -0,0 +1,253 @@
+# Errors
+
+Every error the language raises, grouped by the stage that raises it. Knowing the stage
+narrows the cause: a lexer error is a typo, an evaluator error is a mistake about meaning.
+
+All of them carry a source position where one is known, appended to the message and available
+as `error.loc`:
+
+```js
+try {
+  await render(source, { context });
+} catch (error) {
+  error.loc?.line;     // undefined when the error has no position
+}
+```
+
+Most are a [`FormaError`](api/low-level.md#formaerror). A few come from the kernel or from
+`render` itself and are plain `Error`s, so test `error.loc` rather than the class.
+
+---
+
+## Lexer
+
+Raised while turning characters into tokens. Always a typo.
+
+| Message | Cause |
+| --- | --- |
+| `unexpected character "…"` | A character that cannot begin a token — a smart quote, a stray backtick, a non-ASCII dash |
+| `unterminated string` | A `"` with no closing `"`, or a literal newline inside one |
+| `unterminated block comment` | A `/*` with no `*/`. Block comments do not nest |
+| `unknown escape \q` | Only `\n` `\t` `\r` `\"` `\\` `\$` exist |
+| `unterminated ${ } in string` | A splice with no closing brace |
+
+---
+
+## Parser
+
+Raised while turning tokens into a tree. Always a grammar mistake.
+
+| Message | Cause |
+| --- | --- |
+| `expected a block, found "…"` | Something at the top level that is not a block |
+| `unknown top-level block "shape"` | Only `param`, `local`, `component` and `model` may appear at the top level |
+| `expected an attribute or block, found "…"` | Inside a body, an entry that does not start with a name |
+| `expected {, found "…"` | A `param` with no `=` and no body — write `param s { }`. Also a `component` or `model` with no body |
+| `expected =, found "…"` | A `local` with no value |
+| `expected ident, found "…"` | A keyword where a name was required |
+| `"for" cannot be used as a block type` | One of the eleven [keywords](language/syntax.md#keywords) used as a block name |
+| `a param block holds attributes, not nested blocks` | Usually a missing `=`: `param h { default 20 }` |
+| `a label cannot contain ${ }` | `component` and `model` names must be static. [`part`](reference/part.md) labels may be expressions |
+| `expected = or : in an object` | An object literal entry with no separator |
+| `unexpected "…"` | A token that cannot begin an expression |
+| `trailing input in ${ }` | A splice holding more than one expression |
+
+### `expected {, found "box"`
+
+The most common parser error, and the least obvious. A component param needs `=` or a body,
+even an empty one:
+
+```hcl
+component "c" {
+  param s          // ✗ the parser is looking for `=` or `{`
+  box { size = [s, s, s] }
+}
+
+component "c" {
+  param s { }      // ✓ declared, and required at the call site
+  box { size = [s, s, s] }
+}
+```
+
+---
+
+## Declarations
+
+Raised when the parsed document is indexed.
+
+| Message | Cause |
+| --- | --- |
+| `param "a" is declared twice` | Two top-level params share a name |
+| `component "c" is declared twice` | Two components share a name |
+| `model "m" is declared twice` | Two models share a name |
+| `component "box" shadows a builtin block` | Components and builtins share one namespace |
+
+Locals are the exception: a duplicate `local` is accepted and silently replaces the first.
+
+---
+
+## Names and expressions
+
+Raised while evaluating.
+
+| Message | Cause |
+| --- | --- |
+| `unknown name "x"` | Nothing in scope binds it. See [Scope](language/scope.md) |
+| `no attribute "x"` | A missing key on an object — including `var.x` for something that is not a param |
+| `cannot read "x" of nothing` | A property read on `null` |
+| `cannot index this value` | Indexing something that is not a list, string or object |
+| `cannot negate a non-number` | Unary `-` on a string, list or bool |
+| `cannot apply + to a list and a number` | Operands the operator does not accept. See the [operator table](language/expressions.md#arithmetic) |
+| `cannot compare a number with a string` | `<` `<=` `>` `>=` require both sides to be the same type |
+| `cannot combine vectors of length 2 and 3` | Componentwise arithmetic on lists of different lengths |
+| `division by zero` · `modulo by zero` | Errors rather than `Infinity` or `NaN`, so a degenerate value cannot reach the kernel |
+| `unknown function "clamp"` | No such builtin, and there are no user-defined functions |
+| `len takes 1 argument(s), got 2` | Wrong argument count for a fixed-arity function |
+| `pow: functions take positional arguments` | Named arguments are not supported |
+| `range: step cannot be 0` | A zero step would never terminate |
+| `range: more than 100000 values` | A guard against a live editor allocating until the tab dies |
+
+### `unknown name "outer-inner"`
+
+Hyphens are part of an identifier, so `outer-inner` is one name. Put spaces around the
+operator: `outer - inner`. See [Identifiers](language/syntax.md#identifiers).
+
+### `unknown name "var"`
+
+A param default referred to `var`, which is assembled only after every param has resolved.
+Use the earlier param's bare name instead — see
+[the root scope](language/scope.md#the-root-scope).
+
+---
+
+## Params
+
+| Message | Cause |
+| --- | --- |
+| `param "h" has no default and no value was supplied` | A required param with no value. Pass one, or give it a default |
+| `model "m": param "s" needs a default` | Model params cannot be set from outside, so a default is the only way they get a value |
+
+---
+
+## Blocks
+
+Raised while building geometry.
+
+| Message | Cause |
+| --- | --- |
+| `unknown block "bloop"` | Not a builtin and not a declared component. Check the spelling against the [block list](README.md#shapes) |
+| `"box" does not take a label` | Only [`part`](reference/part.md) takes a meaningful label |
+| `"box" is a shape and cannot contain other blocks` | A shape is a leaf. Usually a missing `}` swallowed the next block |
+| `"translate" needs at least one shape inside it` | An operation with nothing to act on |
+| `box: unknown attribute "colour"` | Every block rejects attributes it did not read, so a typo fails loudly |
+| `attribute "size" is set twice` | The same attribute written twice in one block |
+| `box: "size" must be a number or an array of 3 numbers` | Wrong shape of value |
+| `circle: "radius" must be a finite number` | A `NaN` or `Infinity` reached the block |
+| `regular_polygon: "sides" must be at least 3` | |
+| `polygon: "points" must be an array of at least 3 points` | |
+| `circle: give either "radius" or "diameter", not both` | They mean the same thing |
+| `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` | One end radius on its own is ambiguous |
+| `offset: "join" must be one of "Square", "Round", "Miter"` | An enum attribute with an unrecognised value |
+
+### `box: unknown attribute "colour"`
+
+Worth dwelling on, because it is the error that saves the most time. A misspelled attribute
+would otherwise be silent, and the model would render subtly wrong with nothing to point at.
+The one exception is a [`param`](reference/param.md) block, which is metadata and passes
+anything through.
+
+---
+
+## Dimensionality
+
+| Message | Cause |
+| --- | --- |
+| `"union" cannot mix 2D and 3D shapes` | Children of different dimensionality in one block |
+| `"extrude" takes 2D geometry, got 3D` | A block that fixes what it takes got the other thing |
+| `part "body" is 2D — extrude or revolve it before rendering` | A cross-section reached the renderer |
+| `cannot combine 2D and 3D geometry in a union` | The same mistake, from the [node API](api/geometry-node.md) rather than a document |
+
+See [Dimensionality](language/overview.md#dimensionality) for the three rules, and
+[2D ↔ 3D](reference/conversions.md) for the way across.
+
+---
+
+## Components
+
+| Message | Cause |
+| --- | --- |
+| `c: "s" has no default and was not given` | A required component param the call site did not pass |
+| `c: unknown param "t"` | Components have no pass-through: every value must be declared |
+| `component "c" produced no geometry` | An empty body, a loop over an empty list, or an `if` that took no branch |
+| `a component cannot declare parts` | Scene structure belongs in the model |
+| `nesting deeper than 64 blocks — is a component using itself?` | Direct or mutual recursion. Rewrite as a `for` loop |
+
+---
+
+## Parts and scenes
+
+| Message | Cause |
+| --- | --- |
+| `a part cannot contain another part` | Parts are a flat list |
+| `a part needs at least one shape inside it` | Put the `if` around the part, not inside it |
+| `model "m" produced no geometry` | Nothing was produced. Often a `for` over an empty range |
+| `the document declares no model` | Add a `model` block |
+| `no model named "x"` | `render(source, { model })` named one that does not exist |
+
+A [`part`](reference/part.md) nested inside an operation raises **nothing** — it is silently
+dropped. If a part is missing from a render, check it is written directly in the model.
+
+---
+
+## Control flow
+
+| Message | Cause |
+| --- | --- |
+| `for: expected a list to iterate` | The sequence is not a list. Strings are not iterable here |
+
+---
+
+## `align`
+
+| Message | Cause |
+| --- | --- |
+| `align needs a kernel context — render the model rather than building it` | An `Evaluator` built with no context. [`render`](api/render.md) always supplies one |
+| `align needs at least one shape inside it` | Nothing to measure |
+| `align: "x" must be "min", "center", "max" or a number` | The spelling is `"center"` |
+
+---
+
+## Runtime
+
+Raised by the JavaScript API rather than by a document.
+
+| Message | Cause |
+| --- | --- |
+| `EvaluationContext has been disposed` | A solid or a render used a context after `dispose()` |
+| `EvaluationContext used before create() resolved` | The constructor was called directly. Use `EvaluationContext.create()` |
+| `bad dimensionality 4` | `new GeometryNode` with something other than 2 or 3 |
+| `expected 3 components, got 2` | `Vector.of` asked for a size the value does not have |
+| `cannot read an angle from string` | `Angle.of` takes an `Angle` or a number |
+
+---
+
+## Silent behaviours
+
+Not errors, and each is deliberate — but each has surprised someone. A parameter reaching the
+end of its range should not break a model, so these degenerate quietly:
+
+| What | Result |
+| --- | --- |
+| `extrude { height = 0 }` | Empty geometry |
+| `revolve { angle = 0 }` | Empty geometry |
+| A `difference` that removes everything | Empty geometry |
+| A negative `offset` larger than the shape | Empty geometry |
+| `range` running backwards for its step | An empty list |
+| A label on `align` or a component call | Ignored |
+| A supplied param the document does not declare | Ignored |
+| `min`, `max`, `step`, `options` on a param | Advisory; never enforced |
+| A duplicate `local` | Replaces the first, everywhere |
+| A `part` inside an operation | Dropped from the scene |
+| An index past the end of a list | Nothing, which fails later where it is used |
+
+If a model renders but is not what you meant, this table is the place to start.

package/src/reference/language/control-flow.md

@@ -0,0 +1,160 @@
+# Control flow
+
+Two constructs, both of which appear where a block appears and produce geometry rather than
+a value. Neither is an expression — for a value that depends on a condition, use
+[`cond ? a : b`](expressions.md#conditional).
+
+---
+
+## `for`
+
+Repeats a body once per item in a list.
+
+```hcl
+for i in range(0, 6) { ... }        // one name: the value
+for i, item in list { ... }          // two names: the index, then the value
+```
+
+Everything every iteration produces is collected and handed to the enclosing block, so a
+loop inside an operation contributes several children to it:
+
+```hcl
+difference {
+  extrude { height = 20  rounded_rect { size = [62, 13]  radius = 6.5  center = true } }
+
+  for i, size in sizes {            // each iteration adds one more thing to subtract
+    translate {
+      offset = [(i - (len(sizes) - 1) / 2) * 8, 0, 2.5]
+      extrude { height = 20  regular_polygon { sides = 6  width_across_flats = size } }
+    }
+  }
+}
+```
+
+### Reference
+
+| | |
+| --- | --- |
+| **Sequence** | Any expression that evaluates to a list. Iterating anything else is an error: `for: expected a list to iterate` |
+| **Names** | One name binds the value. Two names bind the index and then the value |
+| **Scope** | Each iteration gets a fresh child scope holding just those names |
+| **Result** | The concatenation of what every iteration produced — geometry, and any `part`s |
+
+#### Caveats
+
+- A loop over an empty list produces nothing. If that is all a model contains, the model
+  fails with `model "m" produced no geometry`. Guard the empty case with
+  [`if`](#if) when a parameter can legitimately reach zero.
+- `range(a, b)` **excludes** `b`, and produces an empty list rather than looping forever when
+  the range runs backwards. See [`range`](../reference/functions.md#range).
+- Iterating a string does not work — strings are not lists here. Use
+  [`len`](../reference/functions.md#len) and index into it if you need the characters.
+- There is no `break`, no `continue` and no accumulator. A loop that needs to skip items
+  should filter the list it iterates, or wrap its body in an `if`.
+
+### Building parts in a loop
+
+A [`part`](../reference/part.md) inside a loop needs a distinct name, and the loop variable
+is how it gets one:
+
+```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] } }
+    }
+  }
+}
+```
+
+Part labels are expressions, so `"tray_${i}"` is evaluated once per iteration. Two parts with
+the same name are not rejected, but the viewer will show two entries called the same thing.
+
+### Radial arrays
+
+The common pattern for anything on a bolt circle:
+
+```hcl
+for i in range(0, var.bolts) {
+  rotate {
+    z = i * 360 / var.bolts
+    translate { offset = [var.plate_r - 9, 0, -1]  cylinder { radius = 3  height = 10 } }
+  }
+}
+```
+
+---
+
+## `if`
+
+Includes a body only when a condition holds.
+
+```hcl
+if var.reinforced {
+  box { size = [40, 40, 4] }
+}
+```
+
+With an alternative, and chained:
+
+```hcl
+if var.style == "round" {
+  cylinder { radius = 10  height = 4 }
+} else if var.style == "hex" {
+  extrude { height = 4  regular_polygon { sides = 6  radius = 10 } }
+} else {
+  box { size = [20, 20, 4]  center = true }
+}
+```
+
+### Reference
+
+| | |
+| --- | --- |
+| **Condition** | Any expression. Judged by [truthiness](expressions.md#truthiness), so `if var.name { }` is true for a non-empty string |
+| **Branches** | `else` takes a body; `else if` chains, nested rather than flattened |
+| **Scope** | Each branch is its own body scope |
+| **Result** | What the taken branch produced, or nothing when no branch is taken |
+
+#### Caveats
+
+- A condition is an ordinary expression, so both branches are *parsed* but only the taken one
+  is evaluated. An error inside the untaken branch will not be reported.
+- An `if` that takes no branch contributes nothing. Inside an operation that requires
+  children, that can turn into `"translate" needs at least one shape inside it`.
+- There is no `if` for attributes. Use the conditional operator:
+  `color = var.hot ? "#e2593c" : "#3f7fbf"`.
+
+### Making a part optional
+
+Put the `if` **outside** the `part`, not inside it. A part with no geometry is an error
+(`a part needs at least one shape inside it`), so guarding the contents is not enough:
+
+```hcl
+// ✓ the part exists only when it is wanted
+if var.show_label {
+  part "label" { color = "#f4f1e4"  ... }
+}
+
+// ✗ fails with "a part needs at least one shape inside it" when show_label is false
+part "label" {
+  if var.show_label { ... }
+}
+```
+
+### Choosing between shapes
+
+Because `if` produces geometry, it composes inside any operation:
+
+```hcl
+difference {
+  box { size = [40, 40, 10] }
+
+  if var.through {
+    translate { offset = [20, 20, -1]  cylinder { radius = 4  height = 12 } }
+  } else {
+    translate { offset = [20, 20, 4]   cylinder { radius = 4  height = 7 } }
+  }
+}
+```