forma-dsl-mcp 0.1.4

package/src/reference/language/expressions.md

@@ -0,0 +1,206 @@
+# Expressions
+
+Expressions appear on the right of every attribute, in `for` sequences, in `if` conditions,
+in `part` labels and inside `${ }` splices. The language is dynamically typed: values carry
+their type, and a mismatch is reported where it is used.
+
+---
+
+## Values
+
+| Type | Literals | Notes |
+| --- | --- | --- |
+| **number** | `12`, `0.5`, `1e3` | Double precision. Infinities and NaN cannot be written and are rejected where a block reads a number |
+| **string** | `"text"`, `"a ${b} c"` | Double quotes only; see [Syntax → Strings](syntax.md#strings) |
+| **bool** | `true`, `false` | |
+| **list** | `[1, 2, 3]`, `[[0,0], [1,0]]` | Heterogeneous and nestable. A list of numbers is what every block means by a *vector* |
+| **object** | `{ w = 3, h = 4 }`, `{ w: 3 }` | `=` and `:` are interchangeable. Read with `.key` |
+| **null** | `null` | Falsy; renders as the empty string in interpolation |
+
+There is no separate vector type in the language — a vector is a list of numbers, and blocks
+say how many components they want. Where a block wants a vector, a **single number is
+accepted as shorthand for every component**, so `scale { factor = 2 }` and
+`scale { factor = [2, 2, 2] }` are the same.
+
+---
+
+## Operators
+
+Listed loosest-binding first. Everything in one row has equal precedence and associates left
+to right.
+
+| Precedence | Operators | Notes |
+| --- | --- | --- |
+| 1 (loosest) | `cond ? a : b` | Right-associative |
+| 2 | `\|\|` | Short-circuits; always yields a bool |
+| 3 | `&&` | Short-circuits; always yields a bool |
+| 4 | `==` `!=` | Structural equality |
+| 5 | `<` `<=` `>` `>=` | Both sides must be the same type |
+| 6 | `+` `-` | |
+| 7 | `*` `/` `%` | |
+| 8 | `-x` `!x` | Prefix |
+| 9 (tightest) | `a.b` `a[i]` `f(x)` | Postfix |
+
+### Arithmetic
+
+`+`, `-`, `*` and `/` are overloaded so that vector maths reads the way it is meant to.
+
+```hcl
+2 + 3                  // 5
+[10, 20] + [1, 2]      // [11, 22]     componentwise
+[10, 20] - [1, 2]      // [9, 18]      componentwise
+[10, 20] * 2           // [20, 40]     scalar broadcast
+2 * [10, 20]           // [20, 40]     either order
+[10, 20] * [2, 3]      // [20, 60]     componentwise
+[10, 20] / 2           // [5, 10]      scalar only
+10 % 3                 // 1
+```
+
+What each accepts:
+
+| Operator | Number ∘ number | List ∘ list | List ∘ number | Number ∘ list | Anything with a string |
+| --- | --- | --- | --- | --- | --- |
+| `+` | sum | componentwise | ✗ | ✗ | concatenation |
+| `-` | difference | componentwise | ✗ | ✗ | ✗ |
+| `*` | product | componentwise | broadcast | broadcast | ✗ |
+| `/` | quotient | ✗ | broadcast | ✗ | ✗ |
+| `%` | remainder | ✗ | ✗ | ✗ | ✗ |
+
+Two lists of different lengths cannot be combined:
+`cannot combine vectors of length 2 and 3`.
+
+**Division and modulo by zero are errors**, not `Infinity` or `NaN` — a NaN would otherwise
+travel all the way into the kernel and surface as a degenerate vertex a long way from its
+cause.
+
+### Concatenation
+
+`+` concatenates when either side is a string. The other side is rendered by the same rules
+as [interpolation](#string-interpolation):
+
+```hcl
+"part_" + 3            // "part_3"
+"size " + [1, 2]       // "size [1, 2]"
+```
+
+### Comparison and equality
+
+`==` and `!=` compare structurally, so two lists with the same numbers are equal:
+
+```hcl
+[1, 2] == [1, 2]       // true
+1 == "1"               // false — different types are never equal
+```
+
+`<`, `<=`, `>` and `>=` require both sides to be the same type, and compare numbers
+numerically and strings lexicographically. Mixing them is an error:
+`cannot compare a number with a string`.
+
+### Logic
+
+`&&` and `||` short-circuit, so the right side is not evaluated when the left decides the
+answer — `count > 0 && list[0] > 1` is safe on an empty list. Both always return a bool, even
+when given non-bool operands: `1 || false` is `true`, not `1`.
+
+`!x` negates the [truthiness](#truthiness) of any value. Unary `-` requires a number:
+`cannot negate a non-number`.
+
+### Conditional
+
+```hcl
+color = i % 2 == 0 ? "#3f7fbf" : "#bf6b3f"
+```
+
+Binds looser than everything else, so the condition needs no parentheses. It is
+right-associative, so `a ? b : c ? d : e` chains as `a ? b : (c ? d : e)`.
+
+---
+
+## Truthiness
+
+Conditions — in `? :`, `&&`, `||`, `!` and [`if`](control-flow.md#if) — accept any value.
+
+| Falsy | Truthy |
+| --- | --- |
+| `false` | `true` |
+| `0` | any other number |
+| `""` | any non-empty string |
+| `[]` | any non-empty list |
+| `null` | any object, including `{}` |
+
+Empty strings and empty lists being falsy is what makes `if var.label { ... }` and
+`if var.sizes { ... }` read the way they are written.
+
+---
+
+## Member access and indexing
+
+```hcl
+local size = [40, 30, 12]
+size.x        // 40
+size.y        // 30
+size.z        // 12
+size[0]       // 40
+
+local opts = { wall = 2, gap = 0.4 }
+opts.wall     // 2
+opts["wall"]  // 2
+```
+
+`.x`, `.y` and `.z` on a **list** are sugar for indices 0, 1 and 2 — they are not a vector
+type. They are read on a list of any length, so `[1, 2].z` yields nothing rather than
+raising; the failure surfaces later, wherever that nothing is used.
+
+On an **object**, a missing key is an error: `no attribute "wdith"`. Reading a property of
+`null` is too: `cannot read "x" of nothing`.
+
+Indexing past the end of a list is *not* an error; it yields undefined, which then usually
+fails where it is used. Indexing something that is neither a list, a string nor an object is
+an error: `cannot index this value`.
+
+---
+
+## Function calls
+
+```hcl
+max(sizes)             // variadic, flattens its arguments
+pow(2, 10)
+sin(30)                // 0.5 — every angle is in degrees
+```
+
+Functions take **positional arguments only**. Named arguments are an error:
+`pow: functions take positional arguments`. A fixed-arity function checks its count:
+`len takes 1 argument(s), got 2`.
+
+There are no user-defined functions. To name a piece of geometry, declare a
+[`component`](../reference/component.md); to name a value, declare a
+[`local`](../reference/local.md).
+
+See the [function reference](../reference/functions.md) for all thirty of them.
+
+---
+
+## String interpolation
+
+`${ ... }` splices any expression into a string.
+
+```hcl
+part "leg_${i}" { ... }
+color = "#${hex}"
+description = "wall ${var.wall}mm, ${len(sizes)} slots"
+```
+
+How each value renders:
+
+| Value | Rendered as |
+| --- | --- |
+| number | `3`, `0.5` — JavaScript's default number formatting |
+| string | itself |
+| bool | `true` / `false` |
+| list | `[1, 2, 3]` — elements joined by `, ` inside brackets, recursively |
+| `null` | the empty string |
+| object | `{w: 3, h: 4}` — each entry rendered by these same rules. Interpolating one is usually a mistake, but it at least names which object |
+
+A splice must contain exactly one expression; anything left over is an error:
+`trailing input in ${ }`. Errors raised inside a splice are reported at the position of the
+string that contains it, since the splice has no line of its own.

package/src/reference/language/overview.md

@@ -0,0 +1,156 @@
+# Document structure
+
+A forma document is a flat list of top-level blocks. Only four kinds may appear there:
+[`param`](../reference/param.md), [`local`](../reference/local.md),
+[`component`](../reference/component.md) and [`model`](../reference/model.md). Anything else
+at the top level is an error.
+
+```hcl
+param wall = 2                       // an input
+local sizes = [10, 20, 30]           // a computed value
+
+component "plate" {                  // a reusable block
+  param size = [20, 20]
+  extrude { height = wall  rect { size = size  center = true } }
+}
+
+model "stack" {                      // something to render
+  for i, s in sizes {
+    translate { offset = [0, 0, i * wall]  plate { size = [s, s] } }
+  }
+}
+```
+
+Order does not matter between declarations of different kinds — a `model` may use a
+`component` declared below it. Order does matter among `local`s, which are evaluated top to
+bottom. See [Scope and names](scope.md).
+
+---
+
+## The pipeline
+
+```
+source ──▶ lexer ──▶ parser ──▶ evaluator ──▶ geometry nodes ──▶ Manifold (WASM) ──▶ mesh
+                                    │                │
+                                params          digest cache
+```
+
+Each stage has a distinct job, and knowing which stage raised an error tells you what kind of
+mistake it was.
+
+1. **Lexer** turns characters into tokens. It rejects unknown characters, unterminated
+   strings and unterminated block comments.
+2. **Parser** turns tokens into an abstract syntax tree. It rejects anything that is not
+   grammatical — a missing brace, a keyword used as a block type, a `param` block containing
+   nested blocks.
+3. **Evaluator** resolves params and locals, then walks the models. It rejects unknown names,
+   bad operands, unknown blocks, unknown attributes and dimensionality mismatches. Its output
+   is a tree of [geometry nodes](../api/geometry-node.md) — it never calls the kernel itself.
+4. **Kernel** solves the node tree into concrete solids, memoized by node digest in an
+   [`EvaluationContext`](../api/evaluation-context.md).
+
+The separation between steps 3 and 4 is what makes editing cheap. The evaluator is pure and
+fast; the kernel is where the time goes, and it is asked only about subtrees whose content
+actually changed.
+
+The one exception is [`align`](../reference/align.md), which has to measure its child before
+it can decide where to put it. It is the only block that reaches into the kernel during
+evaluation, and the only one that fails when there is no kernel context.
+
+---
+
+## Nesting is composition
+
+There is no separate 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 first operand
+  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 on them, so a transform applied to two shapes
+moves both together:
+
+```hcl
+translate {
+  offset = [0, 0, 10]
+  box { size = [4, 4, 4] }       // these two are unioned first,
+  sphere { radius = 3 }          // then the union is moved
+}
+```
+
+[`difference`](../reference/booleans.md#difference) is the operation where order matters: the
+first child is the body and every later child is cut out of it. `union` and `intersection`
+receive their children as a list too, but the result does not depend on the order.
+
+An operation with no children is an error; a shape with children is an error.
+
+---
+
+## Dimensionality
+
+Every piece of geometry is either 2D or 3D, and the language tracks which.
+
+- **2D shapes** — `rect`, `rounded_rect`, `circle`, `ellipse`, `regular_polygon`, `stadium`,
+  `polygon` — produce cross-sections.
+- **3D shapes** — `box`, `sphere`, `cylinder`, `cone`, `torus` — produce solids.
+- **Operations** either fix what they accept (`extrude` takes 2D, `refine` takes 3D) or pass
+  their children's dimensionality through (`translate`, `rotate`, `hull`, the booleans).
+
+Three rules follow, and each has its own error message:
+
+| Rule | Error when broken |
+| --- | --- |
+| The 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` |
+
+To get from 2D to 3D use [`extrude`](../reference/conversions.md#extrude) or
+[`revolve`](../reference/conversions.md#revolve); to go back use
+[`project`](../reference/conversions.md#project) or
+[`slice`](../reference/conversions.md#slice).
+
+---
+
+## Units and orientation
+
+- **Lengths are unitless.** Every consumer treats them as millimetres — STL has no unit
+  either — but nothing in the language enforces that.
+- **Angles are always in degrees.** Everywhere: `rotate { z = 90 }`, `revolve { angle = 180 }`,
+  `sin(30)`, `param a { type = angle }`. There is no radian form in the language. The
+  JavaScript [`Angle`](../api/values.md#angle) class stores radians internally, and that is
+  the only place radians appear.
+- **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 from
+  `[0, 0]` upwards produces a solid standing on the XY plane.
+- **3D rotations apply X, then Y, then Z**, matching OpenSCAD, so a model ported from there
+  lands in the same orientation.
+
+---
+
+## Identity is content
+
+The evaluator does not produce a call graph — it produces a tree of immutable nodes, each
+carrying a 128-bit digest of its own content and its children's digests. Two structurally
+identical subtrees have the same digest and therefore *are* the same node.
+
+That has consequences worth designing around:
+
+- A component used twenty times is evaluated once. Eight spheres in a loop cost one sphere
+  and eight transforms.
+- Two shapes written with their attributes in a different order still share a cache entry —
+  object keys are sorted before they are digested.
+- The members of a `union` are sorted by subtree size, so two unions written in a different
+  order also share a digest. `difference` is never reordered, because its first child means
+  something different from the rest.
+- Nested transforms collapse into a single matrix, so a deep stack of `translate` blocks is
+  one kernel call rather than one per level.
+- The digest is computed from the IEEE bits of every number, never from a runtime-seeded
+  hash, so it is the same in every browser and every run.
+
+See [`GeometryNode`](../api/geometry-node.md) for the node types themselves, and
+[`EvaluationContext`](../api/evaluation-context.md) for the cache built on top of them.

package/src/reference/language/scope.md

@@ -0,0 +1,184 @@
+# Scope and names
+
+Every name in a document resolves through a chain of scopes. This page says exactly what is
+in each one, and in what order they are built — which is what determines whether a
+declaration may refer to another.
+
+---
+
+## The root scope
+
+Built once, before any geometry, in this order:
+
+1. **Constants** — `pi` and `e`.
+2. **Type names** — `number`, `string`, `bool`, `vector`, `list`, `angle`, each bound to
+   itself as a string, so `type = number` in a param block resolves with no quoting.
+3. **Params**, in source order. Each is bound under its bare name as it is resolved, so a
+   later param's default may refer to an earlier one.
+4. **`var`** — an object holding every resolved param.
+5. **Locals**, in source order. Each is bound as it is resolved, so a later local may refer
+   to an earlier one.
+
+The order has two consequences worth knowing:
+
+```hcl
+param a = 3
+param b = a * 2        // ✓ an earlier param, by its bare name
+param c = var.a * 2    // ✗ unknown name "var" — var does not exist yet
+
+local d = var.a + 1    // ✓ locals are built after var
+local e = f            // ✗ unknown name "f" — a later local
+local f = 2
+```
+
+---
+
+## `var.` versus the bare name
+
+Every param is reachable two ways: bare, and under `var`.
+
+```hcl
+param wall = 2
+
+model "m" {
+  box { size = [wall, var.wall, 1] }   // the same value, twice
+}
+```
+
+They differ when something shadows the bare name. `var` holds **params only** — never
+locals, never component params, never loop variables — so `var.NAME` is the unambiguous way
+to reach an input:
+
+```hcl
+param a = 1
+local a = 2            // shadows the bare name
+
+model "m" {
+  box { size = [a, var.a, 1] }   // [2, 1, 1]
+}
+```
+
+Reading a local through `var` fails, because it is not there: `no attribute "a"`.
+
+Prefer `var.` in models for anything that came from a param. It is the convention the
+editor's examples follow, and it makes an input visually distinct from a local at the point
+of use.
+
+---
+
+## Body scopes
+
+Every block body — a `model`, a `component`, a builtin block, a `for` iteration, an `if`
+branch — evaluates in a fresh scope nested inside its parent.
+
+**Locals declared in a body are visible to the whole body**, not only to what follows them,
+because every local in a body is resolved before any of its blocks are built:
+
+```hcl
+model "m" {
+  box { size = [s, 1, 1] }   // ✓ s is already bound
+  local s = 4
+}
+```
+
+That is the opposite of the top-level rule, where locals are strictly ordered. Within one
+body, ordering between locals still applies — a body local may not refer to a later body
+local.
+
+---
+
+## Component isolation
+
+A [`component`](../reference/component.md) body gets a fresh scope rooted at the **document
+root**, not at the call site. A name that happens to exist where the component is used does
+not leak into it.
+
+```hcl
+local g = 7
+
+component "c" {
+  param s = 1
+  box { size = [s, g, 1] }     // ✓ its own param, and a document local
+}
+
+model "m" {
+  local q = 5
+  c { }                        // c cannot see q
+}
+```
+
+Inside a component body, these are in scope:
+
+- its own `param`s, bound from the attributes at the call site
+- everything in the root scope — constants, type names, document params (bare and via `var.`)
+  and document locals
+- its own body locals
+
+Nothing from the caller. Values travel in through params and no other way.
+
+---
+
+## Model params
+
+A `model` may declare its own `param` blocks. They behave like locals with a declaration
+syntax, not like document params:
+
+- Each **must** have a default — `model "m": param "s" needs a default`.
+- They are **not** settable from outside. `render(source, { params: { s: 9 } })` sets
+  document params only; a model param keeps its default.
+- They are bound in the model's scope under the bare name, and are not added to `var`.
+
+```hcl
+model "bracket" {
+  param thickness { default = 4 }    // a fixed constant for this model
+  box { size = [20, 20, thickness] }
+}
+```
+
+For an input the caller can change, declare the param at the top level instead.
+
+---
+
+## Loop variables
+
+[`for`](control-flow.md#for) binds one or two names in a child scope, live for one iteration:
+
+```hcl
+for size in sizes { ... }          // size is the value
+for i, size in sizes { ... }       // i is the index, size the value
+```
+
+The names shadow anything of the same name in an enclosing scope, and are gone after the
+loop.
+
+---
+
+## Shadowing summary
+
+Innermost wins. From outermost to innermost:
+
+```
+constants and type names
+  └─ params (bare)  ·  var  ·  locals
+       └─ model scope: model params, model body locals
+            └─ block body locals
+                 └─ for-loop variables
+```
+
+A `component` body cuts the chain: it starts again from the root scope regardless of where
+it was called.
+
+---
+
+## What cannot be shadowed
+
+- **Builtin block names.** Declaring `component "box"` is an error:
+  `component "box" shadows a builtin block`. Components and builtins share one namespace so
+  a call site reads the same either way.
+- **Builtin function names.** There are no user-defined functions, so nothing can shadow
+  them.
+- **Duplicate declarations** of the same kind are errors: `param "a" is declared twice`,
+  `component "c" is declared twice`, `model "m" is declared twice`. Locals are the exception:
+  a second `local a` is accepted and silently replaces the first everywhere, including in
+  code written above it. Nothing warns about it, so treat it as a mistake to avoid rather
+  than a feature.