forma-dsl-mcp 0.1.4

package/src/reference/language/syntax.md

@@ -0,0 +1,210 @@
+# Syntax
+
+The lexical rules, the grammar, and the one whitespace rule that is easy to trip over.
+
+---
+
+## Comments
+
+Three forms, all ignored:
+
+```hcl
+// a line comment
+#  also a line comment
+/* a block comment,
+   which may span lines */
+```
+
+A block comment that is never closed is an error: `unterminated block comment`. Block
+comments do not nest.
+
+---
+
+## Numbers
+
+Decimal, with an optional fraction and an optional exponent.
+
+```hcl
+12        0.5       .5        1e3       2.5e-3
+```
+
+There is no hexadecimal, no separator, and no unit suffix. A leading `-` is the unary minus
+operator, not part of the literal.
+
+`2e` and `2em` are **not** numbers with exponents — the lexer backs out of a bare `e` and
+lets it start an identifier, so `2e` lexes as the number `2` followed by the name `e`.
+
+---
+
+## Strings
+
+Double quotes only. A string may not contain a literal newline.
+
+```hcl
+"plain"
+"with a ${var.count * 2} value spliced in"
+"a tab\there, a quote\", a literal \${ not a splice"
+```
+
+**Escapes.** Exactly six: `\n`, `\t`, `\r`, `\"`, `\\` and `\$`. Anything else is an error —
+`unknown escape \q`. `\$` exists so a literal `${` can be written.
+
+**Interpolation.** `${ ... }` splices in any expression. Braces inside the splice are
+counted, so an object literal does not end it early. See
+[Expressions → Interpolation](expressions.md#string-interpolation) for how each value type is
+rendered.
+
+---
+
+## Identifiers
+
+An identifier starts with a letter or `_` and continues with letters, digits, `_` **or `-`**.
+
+```hcl
+height   wall_thickness   _private   min-width   part2
+```
+
+> **Hyphens are part of a name.** `a-b` is one identifier, not `a` minus `b`. Write
+> subtraction with spaces: `a - b`. This is the single most common surprise in the lexer —
+> `local gap = outer-inner` fails with `unknown name "outer-inner"`.
+
+### Keywords
+
+These eleven names introduce a construct and cannot be used as a block type:
+
+```
+param   local   component   model   for   if   else   in   true   false   null
+```
+
+They can still be used as attribute names and as identifiers in expressions where the
+grammar is unambiguous, but avoid it.
+
+### Type names
+
+`number`, `string`, `bool`, `vector`, `list` and `angle` are ordinary identifiers bound to
+themselves, so `type = number` in a [`param`](../reference/param.md) block needs no quoting
+and no keyword.
+
+---
+
+## Blocks, attributes and labels
+
+A body contains attributes and nested blocks, in any order and in any mix.
+
+```hcl
+block_type "label" {
+  attribute = expression
+  nested_block { ... }
+}
+```
+
+- **An attribute** is `name = expression`. Setting the same attribute twice in one block is
+  an error.
+- **A nested block** is an identifier that is *not* followed by `=`, then optional labels,
+  then a braced body.
+- **A label** is a string or an identifier written between the block type and the brace.
+
+Labels come in two flavours:
+
+| Where | Form | Notes |
+| --- | --- | --- |
+| `component "name"`, `model "name"` | Static | The name must be a plain string or identifier. `${ }` is rejected: `a label cannot contain ${ }` |
+| `part "name"` | An expression | Evaluated at build time, so a part in a loop can name itself: `part "leg_${i}"` |
+
+Blocks that take no label reject one — `"box" does not take a label`. Two blocks accept a
+label and quietly ignore it: [`align`](../reference/align.md) and
+[component calls](../reference/component.md).
+
+---
+
+## The newline rule
+
+**Outside brackets, a line break ends an expression.** This is what lets attributes be
+written one per line with no separators:
+
+```hcl
+rect {
+  size   = [62, 13]     // ends here
+  center = true         // a separate attribute
+}
+```
+
+Without the rule, `size = [62, 13]` followed by `-4` on the next line would parse as a
+subtraction rather than as the start of something new.
+
+Inside `(...)`, `[...]` or a call's argument list, the rule is suspended and an expression may
+span as many lines as it likes:
+
+```hcl
+polygon {
+  points = [
+    [0, 0], [26, 0],
+    [24, 6], [0, 74],
+  ]
+}
+
+local total = (
+  var.wall * 2
+  + var.gap
+)
+```
+
+To continue an expression across lines at the top level, put the break **inside** brackets,
+or end the line with an operator so the parser is still mid-expression:
+
+```hcl
+local a = base +          // fine: the line ends mid-expression
+          extra
+
+local b = base
+          + extra         // NOT a continuation: `local b = base`, then a parse error
+```
+
+Trailing commas are allowed in lists, objects and argument lists.
+
+---
+
+## Grammar
+
+An informal EBNF of the whole language. `IDENT`, `NUMBER` and `STRING` are the lexical forms
+above.
+
+```ebnf
+document    = { declaration } ;
+
+declaration = param | local | component | model ;
+param       = "param" label ( "=" expression | body ) ;
+local       = "local" label "=" expression ;
+component   = "component" label body ;
+model       = "model" label body ;
+
+body        = "{" { entry } "}" ;
+entry       = param | local | for | if | attribute | block ;
+attribute   = IDENT "=" expression ;
+block       = IDENT { label } body ;
+label       = IDENT | STRING ;
+
+for         = "for" IDENT [ "," IDENT ] "in" expression body ;
+if          = "if" expression body [ "else" ( if | body ) ] ;
+
+expression  = conditional ;
+conditional = binary [ "?" expression ":" expression ] ;
+binary      = unary { binop unary } ;          (* precedence climbing *)
+unary       = [ "-" | "!" ] unary | postfix ;
+postfix     = primary { "." IDENT | "[" expression "]" | arguments } ;
+arguments   = "(" [ expression { "," expression } [ "," ] ] ")" ;
+primary     = NUMBER | STRING | "true" | "false" | "null"
+            | IDENT | "(" expression ")" | array | object ;
+array       = "[" [ expression { "," expression } [ "," ] ] "]" ;
+object      = "{" { IDENT ( "=" | ":" ) expression [ "," ] } "}" ;
+
+binop       = "||" | "&&" | "==" | "!=" | "<" | "<=" | ">" | ">="
+            | "+" | "-" | "*" | "/" | "%" ;
+```
+
+Two things the grammar cannot express:
+
+- A `param` written in braced form may contain attributes only. Nested blocks inside it are
+  an error: `a param block holds attributes, not nested blocks`.
+- Whether `IDENT` begins an attribute or a block is decided by one token of lookahead: `=`
+  means attribute, anything else means block.

package/src/reference/reference/align.md

@@ -0,0 +1,189 @@
+# `align`
+
+Moves geometry so a measured feature of its bounding box lands where you say.
+
+```hcl
+align {
+  x = "center"
+  y = "center"
+  extrude { height = 20  rounded_rect { size = [62, 13]  radius = 6.5 } }
+}
+```
+
+`align` is the only block that **measures**. Every other operation builds its node from its
+attributes alone; this one has to solve its child first, because where the geometry actually
+is cannot be read off the tree.
+
+---
+
+## Reference
+
+### `align { ... }`
+
+Unions its children, measures the bounding box of the result, and translates it.
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `x` | `"min"` `"center"` `"max"` or a number | untouched | What to do along X |
+| `y` | same | untouched | Along Y |
+| `z` | same | untouched | Along Z. 3D children only |
+
+An axis that is not given is left alone.
+
+#### What each value means
+
+| Value | Effect |
+| --- | --- |
+| `"min"` | The **lowest** face on that axis moves to 0 |
+| `"center"` | The **centre** of the bounding box moves to 0 |
+| `"max"` | The **highest** face moves to 0 |
+| a number *n* | The **lowest** face moves to *n* |
+
+Note the asymmetry: the keywords place a named feature at the origin, while a number places
+the *minimum* face at that coordinate. `z = 5` means "sit this on a surface at height 5".
+
+#### Returns
+
+The children, unioned and translated. Dimensionality passes through — a 2D child accepts
+`x` and `y` only.
+
+#### Caveats
+
+- **`align` needs a kernel context.** It is the one block that cannot be evaluated without
+  one: `align needs a kernel context — render the model rather than building it`. Building a
+  node tree with a bare `Evaluator` and no context will fail on it.
+- **It costs a kernel round-trip.** The child has to be solved before the alignment can be
+  computed, so the subtree is evaluated at build time rather than lazily. The digest cache
+  means it is solved only once, but an `align` around something expensive is not free.
+- It measures the **bounding box**, not the geometry. For anything that is not
+  axis-aligned, the box is larger than the shape.
+- Children are unioned first, so several blocks inside one `align` move together.
+- A label — `align "name" { }` — is accepted and silently ignored.
+
+---
+
+## Usage
+
+### Centring something that was not built centred
+
+The common case. Many profiles are easier to write from a corner, and then need centring:
+
+```hcl
+align {
+  x = "center"
+  y = "center"
+  extrude {
+    height = 20
+    rounded_rect { size = [62, 13]  radius = 6.5 }   // built in the positive quadrant
+  }
+}
+```
+
+Most shapes take a `center = true` attribute, which is cheaper — it changes how the shape is
+built rather than measuring it afterwards. Reach for `align` when the thing being centred is
+a **composition** rather than a single shape, and there is no one attribute to set.
+
+### Sitting something on a surface
+
+`z = n` puts the bottom face at *n*:
+
+```hcl
+align { z = 0  imported_or_composed_thing { } }      // stand it on the build plate
+align { z = 12  pin { } }                            // sit it on top of a 12 mm plate
+```
+
+This is how to stack parts without knowing their heights:
+
+```hcl
+model "stack" {
+  part "base" { align { z = 0   base { } } }
+  part "mid"  { align { z = 10  mid { } } }
+  part "top"  { align { z = 26  top { } } }
+}
+```
+
+### Aligning faces
+
+`"max"` and `"min"` put a face on the origin, which is what you want for flush edges:
+
+```hcl
+align { x = "max"  bracket { } }     // right-hand face on the YZ plane
+```
+
+### Mixing axes
+
+Each axis is independent, and an axis you do not mention is untouched:
+
+```hcl
+align {
+  x = "center"      // centred left-to-right
+  z = 0             // standing on the plate
+                    // y is left exactly where it was
+  composed_thing { }
+}
+```
+
+---
+
+## `align` versus `center` versus `translate`
+
+| Approach | When |
+| --- | --- |
+| `center = true` on the shape | A single primitive. Free — it changes how the shape is built |
+| `translate` by a known amount | You already know the dimensions, usually because they are params |
+| `align` | The extent is **computed** — a hull, a composition, an offset outline — and writing the arithmetic would mean duplicating it |
+
+A model that knows its own dimensions should use them:
+
+```hcl
+param width = 62
+
+// ✓ no measurement needed
+translate { offset = [-var.width / 2, 0, 0]  extrude { height = 20  rect { size = [var.width, 13] } } }
+
+// also fine, and does not need to know the width
+align { x = "center"  extrude { height = 20  rect { size = [var.width, 13] } } }
+```
+
+The second reads better and survives a change to how the profile is built; the first avoids a
+kernel round-trip. For anything small, prefer clarity.
+
+---
+
+## Troubleshooting
+
+### `align needs a kernel context — render the model rather than building it`
+
+An `Evaluator` was constructed without a `context`, and the document contains an `align`.
+[`render`](../api/render.md) always supplies one, so this only comes up when driving the
+evaluator directly:
+
+```js
+const evaluator = new Evaluator(program);                      // ✗ no context
+const evaluator = new Evaluator(program, { context });         // ✓
+```
+
+[`describeParameters`](../api/describe-parameters.md) does not evaluate geometry, so it is
+unaffected.
+
+### `align: "x" must be "min", "center", "max" or a number`
+
+The value is a string that is not one of the three keywords — `"middle"` and `"centre"` are
+the usual culprits. The spelling is `"center"`.
+
+### `align needs at least one shape inside it`
+
+The body produced nothing — an `if` that took no branch, or a `for` over an empty list.
+
+### `align: unknown attribute "z"` on a 2D shape
+
+A cross-section has no Z. Align it before extruding using `x` and `y`, or after extruding
+using all three.
+
+### My model got slower after adding `align`
+
+Each `align` solves its child at evaluation time. Around a cheap shape that is nothing;
+around a hull of a hundred spheres it is the whole cost of the model, paid before anything
+else starts. Align the small thing, or translate by a known amount instead.

package/src/reference/reference/booleans.md

@@ -0,0 +1,231 @@
+# Booleans
+
+The three constructive solid geometry operations. Each takes its children as a **list**
+rather than unioning them first, which is what makes `difference` meaningful.
+
+All three work in 2D and 3D, but every child must be the same dimensionality:
+`"union" cannot mix 2D and 3D shapes`.
+
+---
+
+## `union`
+
+Everything added together.
+
+```hcl
+union {
+  box { size = [40, 20, 10] }
+  translate { offset = [0, 0, 10]  cylinder { radius = 8  height = 6 } }
+}
+```
+
+#### Attributes
+
+None.
+
+#### Caveats
+
+- **Usually unnecessary.** Sibling blocks are already implicitly unioned, so
+  `part "p" { a  b }` and `part "p" { union { a  b } }` are the same. Write `union`
+  explicitly when it makes the grouping clearer — typically as one operand of a
+  `difference`.
+- The order of the children does not affect the result, and does not affect the digest
+  either: union members are sorted by subtree size before hashing, so two unions written in a
+  different order share a cache entry.
+- Empty children are dropped. A union of nothing is empty geometry rather than an error.
+
+---
+
+## `difference`
+
+The first child, with every later child cut out of it.
+
+```hcl
+difference {
+  cylinder { radius = 40  height = 8 }        // the body
+
+  translate { offset = [0, 0, -1]             // everything after it is removed
+    cylinder { radius = 12  height = 10 } }
+
+  for i in range(0, 6) {
+    rotate { z = i * 60
+      translate { offset = [30, 0, -1]  cylinder { radius = 3  height = 10 } } }
+  }
+}
+```
+
+#### Attributes
+
+None.
+
+#### Caveats
+
+- **Order matters, and only here.** The first child is the body; every later one is a cutter.
+  This is the one boolean whose children are never reordered, for exactly that reason.
+- A `for` loop inside a difference contributes one cutter per iteration, which is the normal
+  way to make an array of holes.
+- Subtracting everything leaves empty geometry rather than an error. A part that ends up
+  empty renders as nothing.
+
+---
+
+## `intersection`
+
+Only what every child shares.
+
+```hcl
+intersection {
+  bottle_void { }
+  translate { offset = [0, 0, -1]  cylinder { radius = 40  height = 100 } }
+}
+```
+
+#### Attributes
+
+None.
+
+#### Caveats
+
+- With one child, it is that child. With none, it is an error —
+  `"intersection" needs at least one shape inside it`.
+- Order does not affect the result.
+
+---
+
+## Usage
+
+### Hollowing a shell
+
+A solid minus a slightly smaller copy of itself. Naming both as components keeps the two
+profiles beside each other and lets the digest cache solve each once even when several parts
+need them:
+
+```hcl
+component "bottle_solid" { revolve { polygon { points = silhouette } } }
+component "bottle_void"  { revolve { polygon { points = cavity } } }
+
+model "bottle" {
+  part "bottle" {
+    difference {
+      bottle_solid { }
+      bottle_void { }
+    }
+  }
+
+  part "water" {
+    intersection {                       // the same void, reused for free
+      bottle_void { }
+      translate { offset = [0, 0, -1]  cylinder { radius = 40  height = 130 } }
+    }
+  }
+}
+```
+
+### Arrays of holes
+
+A loop inside a `difference` is the standard bolt pattern:
+
+```hcl
+difference {
+  extrude { height = 8  circle { radius = 40 } }
+
+  for i in range(0, var.bolts) {
+    rotate {
+      z = i * 360 / var.bolts
+      translate { offset = [31, 0, -1]  cylinder { radius = 3  height = 10 } }
+    }
+  }
+}
+```
+
+### Trimming to a region
+
+`intersection` with a large primitive is how a shape is cropped:
+
+```hcl
+intersection {
+  complicated_thing { }
+  translate { offset = [-50, -50, 0]  box { size = [100, 100, 12] } }  // keep 0 ≤ z ≤ 12
+}
+```
+
+For a single flat cut, [`trim`](refinement.md#trim) is cheaper — it cuts with a half-space
+and needs no second solid.
+
+### Grouping so a transform applies to several shapes
+
+Every operation *except* these three unions its children first, so this already works:
+
+```hcl
+translate {
+  offset = [0, 0, 10]
+  box { size = [4, 4, 4] }
+  sphere { radius = 3 }       // both move together
+}
+```
+
+Inside a `difference`, though, each child is separate — so to subtract two shapes *as one
+body*, group them explicitly:
+
+```hcl
+difference {
+  plate { }
+  union {                      // one cutter made of two shapes
+    cylinder { radius = 4  height = 20 }
+    translate { offset = [0, 0, 6]  cylinder { radius = 7  height = 20 } }
+  }
+}
+```
+
+Here the `union` is not decorative: without it the two cylinders would be two separate
+cutters, which happens to give the same result for a difference — but not for an
+`intersection`, where it changes the answer entirely.
+
+---
+
+## Troubleshooting
+
+### `"difference" needs at least one shape inside it`
+
+The body is empty, or everything in it was produced by an `if` that took no branch or a `for`
+over an empty list.
+
+### `"union" cannot mix 2D and 3D shapes`
+
+One child is a cross-section and another is a solid. Usually a profile that was meant to be
+extruded:
+
+```hcl
+union {
+  box { size = [10, 10, 10] }
+  circle { radius = 3 }                          // ✗ still 2D
+  extrude { height = 10  circle { radius = 3 } } // ✓
+}
+```
+
+### My difference removed nothing
+
+The cutter is not where you think, or does not overlap the body. Check by rendering the
+cutter as its own [`part`](part.md) with an opacity, which shows exactly where it sits:
+
+```hcl
+part "cutter" { color = "#ff6b7f"  opacity = 0.4  the_cutter { } }
+```
+
+### The result has stray faces where two solids meet
+
+Coincident surfaces. Overlap unioned solids slightly, and overshoot cutters past both faces
+they pass through.
+
+### My difference is slow
+
+Each cutter is a boolean. A hundred of them in one `difference` is a hundred kernel
+operations; unioning the cutters first is often faster, because the union of many small
+disjoint solids is cheap and the subtraction then happens once:
+
+```hcl
+difference {
+  body { }
+  union { for i in range(0, 100) { ... } }
+}
+```