forma-dsl-mcp 0.3.8 → 0.4.0

package/src/reference/cli.md

@@ -0,0 +1,199 @@
+# Command line
+
+[`forma-dsl-cli`](https://www.npmjs.com/package/forma-dsl-cli) solves a document and writes a
+binary STL, with no browser and no build step. It is what puts a `.forma` file in a Makefile,
+a CI job or a release pipeline.
+
+```bash
+npm install -g forma-dsl-cli
+forma render riser.forma -p height=32 -o build/riser.stl
+```
+
+Or, without installing it, `npx forma-dsl-cli render riser.forma -o riser.stl`.
+
+It knows nothing about the language itself. Every answer comes from `forma-dsl` - the same
+package the editor and the MCP server import - so a block added to the language is one it
+renders without being told, and an error it reports is the evaluator's own, with the
+evaluator's own position.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `forma render <file>` | solve a document and write a binary STL |
+| `forma params <file>` | list the parameters the document declares |
+| `forma models <file>` | list the models the document declares |
+
+A `<file>` of `-` reads the document from stdin. `params` and `models` take `--json`.
+
+A document, and an `-o`/`--out` that names one, must resolve inside the directory the command
+is run in: a path that leaves it - by `..`, an absolute path, or a symlink pointing out of the
+tree - is refused with exit code 2.
+
+### `render`
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `-o, --out <file>` | `<file>.stl` | where to write. `-` is stdout |
+| `-m, --model <name>` | the first declared | which [model](reference/model.md) to build |
+| `--part <name>` | see below | one [part](reference/part.md) by name |
+| `-p, --param <name=val>` | each param's own default | a value for one declared [param](reference/param.md). Repeatable |
+| `--params <file>` | - | a JSON object of values by name. `-p` wins over it |
+| `--segments <n>` | the kernel's own | a fixed segment count for every curve |
+| `--min-angle <deg>` | the kernel's own | smallest angle between adjacent segments of a curve |
+| `--min-edge <n>` | the kernel's own | smallest length a curve segment may be shortened to |
+| `--max-nodes <n>` | no limit | refuse a document that would build more blocks than this |
+| `-q, --quiet` | off | do not print the summary |
+
+The three resolution options are [`setQuality`](api/kernel.md) under another name, and are
+global to the kernel exactly as they are there. `--max-nodes` is
+[`render`](api/render.md)'s own budget.
+
+Without `--part`, a model with one part exports that part, and a model with several exports
+them **unioned**. STL has no notion of a part, and a slicer reading two overlapping shells
+makes a mess of them.
+
+---
+
+## Passing parameters
+
+Three ways, and they compose.
+
+**One at a time, on the command line.** A value is JSON where it parses as JSON, and the
+string as written otherwise - so there is no second layer of quoting to get wrong:
+
+```bash
+forma render part.forma -p count=6 -p center=true -p size=[10,20] -p label=M6
+```
+
+| Written | Arrives as |
+| --- | --- |
+| `-p count=6` | the number `6` |
+| `-p center=true` | the boolean `true` |
+| `-p size=[10,20]` | the list `[10, 20]` |
+| `-p label=M6` | the string `"M6"` |
+
+**From a file.** `--params` takes a JSON object of values by name - the thing you commit and
+diff, rather than assemble in a shell loop:
+
+```json
+{
+  "height": 36,
+  "label": "M6",
+  "center": true
+}
+```
+
+```bash
+forma render riser.forma --params params.json -o riser.stl
+```
+
+It has to be a JSON **object**. An array or a bare number parses but names nothing, and is
+refused with exit code 2 rather than quietly contributing nothing. Like every other path, it
+must resolve inside the directory the command runs in.
+
+**Both.** `-p` wins over `--params`, which is what a build matrix wants: the values every
+variant shares live in the file, and the one that varies goes on the line.
+
+```bash
+for h in 8 20 40; do
+  forma render riser.forma --params shared.json -p "height=$h" -o "build/riser-$h.stl"
+done
+```
+
+And the document will tell you what it takes, so the first `params.json` need not be written
+by hand:
+
+```bash
+forma params riser.forma --json | jq 'map({(.name): .default}) | add' > params.json
+```
+
+```json
+{
+  "height": 20,
+  "label": "A",
+  "center": false
+}
+```
+
+---
+
+## In a pipeline
+
+Only what was asked for goes to stdout - the STL under `-o -`, and the listings. The summary
+and every diagnostic go to stderr, so a pipe stays clean:
+
+```bash
+forma render riser.forma --segments 64 -o - > riser.stl
+```
+
+Exit codes are the three a script needs to tell apart:
+
+| Code | What happened |
+| --- | --- |
+| `0` | it worked |
+| `1` | the document did not build - a syntax error, an unknown name, a degenerate solid |
+| `2` | the invocation was wrong - an unknown flag, a missing file, a part that does not exist |
+
+The summary names the cache hits, because that is the number explaining why the second render
+of the same document in a loop is faster, and it is otherwise invisible:
+
+```
+build/riser.stl - 252 triangles · model "riser", part "body" · 6 nodes, 6 solved, 0 cached · 9 ms
+```
+
+---
+
+## Failures
+
+A failure is reported where an editor and a CI annotation can both find it: the position as a
+`file:line:column:` prefix, then the lines around it with a caret under the column.
+
+```
+riser.forma:7:7: rounded_rect: unknown attribute "corner_radius" - rounded_rect reads "center", "radius", "segments", "size"
+5 |     extrude {
+6 |       height = var.height
+7 |       rounded_rect { size = [40, 20]  corner_radius = 4 }
+  |       ^
+8 |     }
+9 |   }
+```
+
+The position comes from the error itself - see [Errors](errors.md) for what each stage raises
+and what it means.
+
+---
+
+## What a document declares
+
+`params --json` is the document describing itself, which is what lets a script build every
+variant without being told what the variants are:
+
+```bash
+forma params riser.forma --json
+```
+
+```json
+[
+  {
+    "name": "height",
+    "type": "number",
+    "default": 20,
+    "required": false,
+    "min": 8,
+    "max": 40
+  }
+]
+```
+
+`required` is true for a param declared with no default, which is one that has to be supplied
+before the document will build at all.
+
+---
+
+## Units
+
+Lengths are unitless in forma, and STL has no unit either. Every consumer treats them as
+millimetres.

package/src/reference/errors.md

@@ -25,7 +25,7 @@ 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 |
+| `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 |
@@ -42,7 +42,7 @@ Raised while turning tokens into a tree. Always a grammar mistake.
 | `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 `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 |
@@ -93,7 +93,7 @@ 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 |
+| `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 |
@@ -115,7 +115,7 @@ 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
+Use the earlier param's bare name instead - see
 [the root scope](language/scope.md#the-root-scope).
 
 ---
@@ -135,11 +135,11 @@ Raised while building geometry.
 
 | Message | Cause |
 | --- | --- |
-| `unknown block "bloop" — the blocks are …` | Not a builtin and not a declared component. The message lists every block there is, this document's own components first |
+| `unknown block "bloop" - the blocks are …` | Not a builtin and not a declared component. The message lists every block there is, this document's own components first |
 | `"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" — box reads …` | Every block rejects attributes it did not read, so a typo fails loudly, and names what it would have read |
+| `box: unknown attribute "colour" - box reads …` | Every block rejects attributes it did not read, so a typo fails loudly, and names what it would have read |
 | `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 |
@@ -149,7 +149,7 @@ Raised while building geometry.
 | `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" — box reads "center", "size"`
+### `box: unknown attribute "colour" - box reads "center", "size"`
 
 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.
@@ -158,8 +158,8 @@ anything through.
 
 Both this and `unknown block` carry the alternatives, because the reader is often a program
 with no copy of this manual: an error that says only what is wrong leaves it guessing at
-spellings. A block that branches on which of two spellings it was given — `radius` against
-`diameter` — reads only one of them, so the list is what that call would accept rather than
+spellings. A block that branches on which of two spellings it was given - `radius` against
+`diameter` - reads only one of them, so the list is what that call would accept rather than
 always the whole set.
 
 ---
@@ -170,7 +170,7 @@ always the whole set.
 | --- | --- |
 | `"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 |
+| `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
@@ -186,7 +186,7 @@ See [Dimensionality](language/overview.md#dimensionality) for the three rules, a
 | `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 |
+| `nesting deeper than 64 blocks - is a component using itself?` | Direct or mutual recursion. Rewrite as a `for` loop |
 
 ---
 
@@ -200,7 +200,7 @@ See [Dimensionality](language/overview.md#dimensionality) for the three rules, a
 | `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
+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.
 
 ---
@@ -217,7 +217,7 @@ dropped. If a part is missing from a render, check it is written directly in the
 
 | 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 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"` |
 
@@ -239,7 +239,7 @@ Raised by the JavaScript API rather than by a document.
 
 ## Silent behaviours
 
-Not errors, and each is deliberate — but each has surprised someone. A parameter reaching the
+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 |

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

@@ -1,7 +1,7 @@
 # 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
+a value. Neither is an expression - for a value that depends on a condition, use
 [`cond ? a : b`](expressions.md#conditional).
 
 ---
@@ -38,7 +38,7 @@ difference {
 | **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 |
+| **Result** | The concatenation of what every iteration produced - geometry, and any `part`s |
 
 #### Caveats
 
@@ -47,7 +47,7 @@ difference {
   [`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
+- 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`.

package/src/reference/language/expressions.md

@@ -17,7 +17,7 @@ their type, and a mismatch is reported where it is used.
 | **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
+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.
@@ -69,7 +69,7 @@ What each accepts:
 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
+**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.
 
@@ -89,7 +89,7 @@ as [interpolation](#string-interpolation):
 
 ```hcl
 [1, 2] == [1, 2]       // true
-1 == "1"               // false — different types are never equal
+1 == "1"               // false - different types are never equal
 ```
 
 `<`, `<=`, `>` and `>=` require both sides to be the same type, and compare numbers
@@ -99,7 +99,7 @@ numerically and strings lexicographically. Mixing them is an error:
 ### 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
+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:
@@ -118,7 +118,7 @@ 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.
+Conditions - in `? :`, `&&`, `||`, `!` and [`if`](control-flow.md#if) - accept any value.
 
 | Falsy | Truthy |
 | --- | --- |
@@ -147,7 +147,7 @@ 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
+`.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.
 
@@ -165,7 +165,7 @@ an error: `cannot index this value`.
 ```hcl
 max(sizes)             // variadic, flattens its arguments
 pow(2, 10)
-sin(30)                // 0.5 — every angle is in degrees
+sin(30)                // 0.5 - every angle is in degrees
 ```
 
 Functions take **positional arguments only**. Named arguments are an error:
@@ -194,12 +194,12 @@ How each value renders:
 
 | Value | Rendered as |
 | --- | --- |
-| number | `3`, `0.5` — JavaScript's default number formatting |
+| number | `3`, `0.5` - JavaScript's default number formatting |
 | string | itself |
 | bool | `true` / `false` |
-| list | `[1, 2, 3]` — elements joined by `, ` inside brackets, recursively |
+| 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 |
+| 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

package/src/reference/language/overview.md

@@ -21,7 +21,7 @@ model "stack" {                      // something to render
 }
 ```
 
-Order does not matter between declarations of different kinds — a `model` may use a
+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).
 
@@ -41,11 +41,11 @@ 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
+   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.
+   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).
 
@@ -95,9 +95,9 @@ An operation with no children is an error; a shape with children is an error.
 
 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.
+- **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).
 
@@ -107,7 +107,7 @@ Three rules follow, and each has its own error message:
 | --- | --- |
 | 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` |
+| 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
@@ -118,8 +118,8 @@ To get from 2D to 3D use [`extrude`](../reference/conversions.md#extrude) or
 
 ## Units and orientation
 
-- **Lengths are unitless.** Every consumer treats them as millimetres — STL has no unit
-  either — but nothing in the language enforces that.
+- **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
@@ -134,7 +134,7 @@ To get from 2D to 3D use [`extrude`](../reference/conversions.md#extrude) or
 
 ## Identity is content
 
-The evaluator does not produce a call graph — it produces a tree of immutable nodes, each
+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.
 
@@ -142,7 +142,7 @@ 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 —
+- 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

package/src/reference/language/scope.md

@@ -1,7 +1,7 @@
 # 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
+in each one, and in what order they are built - which is what determines whether a
 declaration may refer to another.
 
 ---
@@ -10,12 +10,12 @@ declaration may refer to another.
 
 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
+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.
+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.
 
@@ -24,10 +24,10 @@ 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
+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 e = f            // ✗ unknown name "f" - a later local
 local f = 2
 ```
 
@@ -45,8 +45,8 @@ model "m" {
 }
 ```
 
-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
+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
@@ -68,8 +68,8 @@ 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.
+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:
@@ -82,7 +82,7 @@ model "m" {
 ```
 
 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
+body, ordering between locals still applies - a body local may not refer to a later body
 local.
 
 ---
@@ -110,7 +110,7 @@ model "m" {
 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.`)
+- everything in the root scope - constants, type names, document params (bare and via `var.`)
   and document locals
 - its own body locals
 
@@ -123,7 +123,7 @@ Nothing from the caller. Values travel in through params and no other way.
 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`.
+- 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`.

package/src/reference/language/syntax.md

@@ -31,7 +31,7 @@ Decimal, with an optional fraction and an optional exponent.
 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
+`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`.
 
 ---
@@ -46,7 +46,7 @@ Double quotes only. A string may not contain a literal newline.
 "a tab\there, a quote\", a literal \${ not a splice"
 ```
 
-**Escapes.** Exactly six: `\n`, `\t`, `\r`, `\"`, `\\` and `\$`. Anything else is an error —
+**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
@@ -65,7 +65,7 @@ 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 —
+> 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
@@ -111,7 +111,7 @@ Labels come in two flavours:
 | `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
+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).