forma-dsl-mcp 0.1.4

package/src/reference/reference/shapes-3d.md

@@ -0,0 +1,279 @@
+# 3D shapes
+
+Five leaf blocks producing solids. They take attributes and never contain other blocks.
+
+| Block | Sized by | Centred by default |
+| --- | --- | --- |
+| [`box`](#box) | `size` | no |
+| [`sphere`](#sphere) | `radius` or `diameter` | always |
+| [`cylinder`](#cylinder) | `height` and one or two radii | no |
+| [`cone`](#cone) | `height`, `radius`, `top_radius` | no |
+| [`torus`](#torus) | `radius`, `tube_radius` | always |
+
+Anything these cannot express is usually a 2D profile plus
+[`extrude`](conversions.md#extrude) or [`revolve`](conversions.md#revolve) — that is where
+the real modelling happens.
+
+---
+
+## `box`
+
+An axis-aligned cuboid.
+
+```hcl
+box { size = [40, 20, 10] }
+box { size = [40, 20, 10]  center = true }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | 3-vector | **required** | X, Y and Z extents |
+| `center` | bool | `false` | `true` centres it on the origin; otherwise its minimum corner sits there |
+
+#### Caveats
+
+- A single number is accepted as shorthand for all three, so `size = 10` is a 10 mm cube.
+- There is no rounded box. Round a 2D profile and extrude it —
+  see [Usage](#rounded-boxes).
+
+---
+
+## `sphere`
+
+```hcl
+sphere { radius = 12 }
+sphere { diameter = 24  segments = 64 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `radius` | number | `1` | |
+| `diameter` | number | — | An alternative spelling of the same thing |
+| `segments` | integer | `0` | Segments around the equator; `0` lets the kernel choose |
+
+#### Caveats
+
+- Give `radius` **or** `diameter`, never both.
+- Always centred on the origin.
+
+---
+
+## `cylinder`
+
+A cylinder, or a frustum when the two ends differ.
+
+```hcl
+cylinder { radius = 5  height = 20 }
+cylinder { diameter = 10  height = 20  center = true }
+cylinder { bottom_radius = 12  top_radius = 8  height = 15 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `height` | number | **required** | Along Z |
+| `radius` | number | — | Both ends alike |
+| `diameter` | number | — | An alternative spelling of `radius` |
+| `bottom_radius` | number | — | The end at Z = 0 |
+| `top_radius` | number | — | The end at Z = `height` |
+| `segments` | integer | `0` | Segments around; `0` lets the kernel choose |
+| `center` | bool | `false` | `true` centres it on Z = 0; otherwise it stands on the XY plane |
+
+#### Caveats
+
+- Give **either** `radius`/`diameter`, **or both** `bottom_radius` and `top_radius`. Anything
+  else is `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` —
+  one radius on its own is ambiguous, and there is no default.
+- Unlike every other shape, `radius` has no usable default here: the check runs before the
+  fallback would apply.
+- `center` affects Z only. X and Y are always centred on the axis.
+
+---
+
+## `cone`
+
+A cone, or a truncated cone.
+
+```hcl
+cone { radius = 10  height = 20 }
+cone { radius = 10  top_radius = 4  height = 20 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `height` | number | **required** | Along Z |
+| `radius` | number | `1` | The base, at Z = 0 |
+| `diameter` | number | — | An alternative spelling of `radius` |
+| `top_radius` | number | `0` | `0` gives a point |
+| `segments` | integer | `0` | Segments around |
+| `center` | bool | `false` | As for [`cylinder`](#cylinder) |
+
+#### Caveats
+
+- `cone` and `cylinder` build the same kind of solid; they differ only in which attributes
+  are required and what `top_radius` defaults to. Use whichever reads better — `cone` when
+  the top is a point, `cylinder` when both ends matter.
+
+---
+
+## `torus`
+
+A ring, optionally a partial arc.
+
+```hcl
+torus { radius = 20  tube_radius = 4 }
+torus { radius = 20  tube_radius = 4  angle = 180 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `radius` | number | **required** | Centre of the ring to centre of the tube |
+| `tube_radius` | number | **required** | Radius of the tube itself |
+| `angle` | angle | `360` | How far round to sweep, in degrees |
+| `segments` | integer | `0` | Segments around the ring |
+| `tube_segments` | integer | `0` | Segments around the tube's cross-section |
+
+#### Caveats
+
+- Built as a circle pushed out to `radius` and revolved, which is what a torus is. The outer
+  radius of the result is `radius + tube_radius`.
+- `tube_radius` greater than `radius` produces self-intersecting geometry. The kernel will
+  resolve it into *something*, but not anything you meant.
+- An `angle` of `0` or less yields empty geometry rather than an error, so a parameter
+  sweeping to zero does not break the model.
+- Always centred on the origin, lying in the XY plane.
+
+---
+
+## Usage
+
+### Rounded boxes
+
+There is no rounded-box primitive. Round the 2D profile and extrude it — which also gives
+control over whether the vertical edges or the horizontal ones are rounded:
+
+```hcl
+component "rounded_box" {
+  param size   = [20, 20, 10]
+  param radius = 3
+
+  extrude {
+    height = size.z
+    rounded_rect { size = [size.x, size.y]  radius = radius  center = true }
+  }
+}
+```
+
+For rounding in all three axes, [`smooth`](refinement.md#smooth) or a
+[`hull`](refinement.md#hull) of eight spheres are the usual approaches.
+
+### Through-holes
+
+Make the cutter longer than the thing it cuts, and start it below:
+
+```hcl
+difference {
+  cylinder { radius = 40  height = 8 }
+
+  translate {
+    offset = [0, 0, -1]                     // start below the bottom face
+    cylinder { radius = 12  height = 10 }   // and finish above the top
+  }
+}
+```
+
+A cutter that ends exactly on a face leaves a zero-thickness coincident surface, which is
+slow to resolve and can produce artefacts. One millimetre of overshoot at each end costs
+nothing.
+
+### Bolt circles
+
+```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 } }
+  }
+}
+```
+
+### Rings and fillets from a torus
+
+A torus is the cheapest way to get a circular fillet or a raised thread ridge:
+
+```hcl
+for i in range(0, 3) {
+  translate {
+    offset = [0, 0, 174 + i * 4.5]
+    torus { radius = 15.6  tube_radius = 1.1  segments = 96  tube_segments = 16 }
+  }
+}
+```
+
+### Controlling facet count
+
+`segments` is per shape, and it is worth setting on anything that must fit something else:
+
+```hcl
+param preview { type = bool  default = true }
+local facets = var.preview ? 24 : 128
+
+model "m" {
+  cylinder { radius = 10  height = 20  segments = facets }
+}
+```
+
+Globally, [`setQuality`](../api/kernel.md#setquality) moves the default that `segments = 0`
+resolves to.
+
+---
+
+## Troubleshooting
+
+### `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"`
+
+Either one radius for both ends, or two for a frustum. Giving only `bottom_radius` leaves the
+top undefined:
+
+```hcl
+cylinder { height = 10  bottom_radius = 5 }                    // ✗
+cylinder { height = 10  bottom_radius = 5  top_radius = 5 }    // ✓
+cylinder { height = 10  radius = 5 }                           // ✓ simpler
+```
+
+### `sphere: give either "radius" or "diameter", not both`
+
+Pass one.
+
+### `"box" is a shape and cannot contain other blocks`
+
+A shape is a leaf. Usually a missing `}` on an earlier line has swallowed the next block.
+
+### `box: "size" must be a number or an array of 3 numbers`
+
+`size` needs three components in 3D. A 2-vector is a common slip when converting a profile:
+
+```hcl
+box { size = [40, 20] }       // ✗
+box { size = [40, 20, 10] }   // ✓
+```
+
+### My cylinder is not where I expect
+
+By default a cylinder stands **on** the XY plane, with its base at Z = 0. `center = true`
+puts its middle there instead. The same is true of `box`, whose minimum corner — not its
+centre — sits at the origin by default.
+
+### Two solids that touch exactly render with artefacts
+
+Coincident faces are ambiguous. Overlap them by a small amount when unioning, and overshoot
+by a small amount when subtracting.

package/src/reference/reference/transforms.md

@@ -0,0 +1,246 @@
+# Transforms
+
+Four operations that move geometry without changing its shape. Each works in 2D and 3D, and
+passes its children's dimensionality through.
+
+All four **union their children first**, so a transform applied to several blocks moves them
+together:
+
+```hcl
+translate {
+  offset = [0, 0, 10]
+  box { size = [4, 4, 4] }
+  sphere { radius = 3 }       // both move
+}
+```
+
+Nested transforms collapse into a single matrix before they reach the kernel, so a deep stack
+of `translate` and `rotate` blocks costs one operation rather than one per level.
+
+---
+
+## `translate`
+
+Moves geometry.
+
+```hcl
+translate { offset = [10, 0, 5]  box { size = [4, 4, 4] } }
+translate { offset = [10, 0]     rect { size = [4, 4] } }      // 2D
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `offset` | vector of the child's dimensionality | **required** | How far to move along each axis |
+
+#### Caveats
+
+- `offset` must have as many components as the child has dimensions — 2 for a cross-section,
+  3 for a solid. A mismatch is `translate: "offset" must be a number or an array of 3
+  numbers`.
+- A single number broadcasts to every axis, which is rarely what you want here but is
+  consistent with every other vector attribute.
+
+---
+
+## `rotate`
+
+Turns geometry about the origin. **All angles are in degrees.**
+
+```hcl
+rotate { z = 45  box { size = [20, 4, 4] } }                    // 3D, one axis
+rotate { angles = [0, 90, 45]  box { size = [20, 4, 4] } }      // 3D, all three
+rotate { angle = 30  rect { size = [20, 4] } }                  // 2D
+```
+
+#### Attributes — 3D children
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `angles` | 3-vector | — | Degrees about X, Y and Z at once |
+| `x`, `y`, `z` | number | `0` | Degrees about that axis, named one at a time |
+
+#### Attributes — 2D children
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `angle` | angle | **required** | Degrees, counter-clockwise |
+
+#### Caveats
+
+- **Rotation is about the origin, not about the geometry.** To spin something in place, put
+  it at the origin, rotate, then translate — or build it centred in the first place.
+- In 3D the axes are applied **X, then Y, then Z**, matching OpenSCAD, so a model ported from
+  there lands in the same orientation. Composing rotations in a different order requires
+  separate `rotate` blocks.
+- `angles` and the named axes are alternatives. Using `angle` on a 3D child, or `x`/`y`/`z`
+  on a 2D one, is an unknown attribute.
+
+---
+
+## `scale`
+
+Scales geometry about the origin.
+
+```hcl
+scale { factor = 2  sphere { radius = 5 } }
+scale { factor = [1, 1, 0.5]  sphere { radius = 5 } }    // flattened
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `factor` | vector of the child's dimensionality | **required** | Multiplier per axis. A single number scales every axis alike |
+
+#### Caveats
+
+- Scaling is about the origin, so anything not centred there also moves.
+- A negative factor mirrors as well as scales, and flips the winding. Prefer
+  [`mirror`](#mirror) when reflection is what you mean.
+- A factor of `0` collapses the geometry to nothing.
+- Non-uniform scaling of a curved surface changes its radii — a scaled sphere is an
+  ellipsoid, which is the cheapest way to get one.
+
+---
+
+## `mirror`
+
+Reflects geometry in the plane through the origin with the given normal.
+
+```hcl
+mirror { normal = [1, 0, 0]  bracket { } }      // reflect across the YZ plane
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `normal` | vector of the child's dimensionality | **required** | The normal of the mirror plane. Normalised first, so its length does not matter |
+
+#### Caveats
+
+- The plane always passes through the **origin**. To mirror about some other plane,
+  translate to the origin, mirror, and translate back.
+- In 2D, `normal` describes a line rather than a plane.
+- `mirror` replaces the geometry with its reflection; it does not keep the original. For a
+  symmetric pair, union both:
+
+  ```hcl
+  union {
+    bracket { }
+    mirror { normal = [1, 0, 0]  bracket { } }
+  }
+  ```
+
+---
+
+## Usage
+
+### Rotating in place
+
+The origin is the pivot, so centre first:
+
+```hcl
+// ✗ the box sweeps around the origin
+rotate { z = 30  box { size = [40, 10, 4] } }
+
+// ✓ centred, so it turns on the spot
+rotate { z = 30  box { size = [40, 10, 4]  center = true } }
+
+// ✓ or move it back afterwards
+translate { offset = [20, 5, 0]  rotate { z = 30  box { size = [40, 10, 4]  center = true } } }
+```
+
+### Order of operations
+
+Blocks nest inside-out: the transform closest to the shape is applied first.
+
+```hcl
+translate {          // …then moved 50 along X
+  offset = [50, 0, 0]
+  rotate {           // the box is rotated first…
+    z = 45
+    box { size = [20, 4, 4]  center = true }
+  }
+}
+```
+
+Swapping the two gives a different result — rotating a translated box sweeps it around the
+origin on an arc of radius 50.
+
+### Radial patterns
+
+Rotate a translated copy, once per step:
+
+```hcl
+for i in range(0, 8) {
+  rotate {
+    z = i * 45
+    translate { offset = [30, 0, 0]  cylinder { radius = 3  height = 10 } }
+  }
+}
+```
+
+Because identity is content identity, this costs **one** cylinder and eight transforms — the
+cylinder node is the same node every time round the loop.
+
+### Mirrored pairs
+
+```hcl
+component "hinge_leaf" { ... }
+
+model "hinge" {
+  part "left"  { hinge_leaf { } }
+  part "right" { mirror { normal = [1, 0, 0]  hinge_leaf { } } }
+}
+```
+
+### Ellipsoids and tapers
+
+Non-uniform `scale` is the simplest route to shapes the primitives do not offer:
+
+```hcl
+scale { factor = [1, 0.6, 1]  sphere { radius = 20  segments = 64 } }
+```
+
+---
+
+## Troubleshooting
+
+### `translate: "offset" must be a number or an array of 3 numbers`
+
+The offset has the wrong number of components for its child. 2D children want two, 3D
+children want three — and a 2D shape stays 2D until it is extruded:
+
+```hcl
+translate { offset = [1, 2, 3]  rect { size = [4, 4] } }   // ✗ rect is 2D
+translate { offset = [1, 2]     rect { size = [4, 4] } }   // ✓
+```
+
+### `rotate: unknown attribute "angle"`
+
+`angle` is the 2D spelling. A 3D child takes `x`, `y`, `z` or `angles`:
+
+```hcl
+rotate { angle = 45  box { size = [1, 1, 1] } }    // ✗
+rotate { z = 45      box { size = [1, 1, 1] } }    // ✓
+```
+
+The reverse — `z` on a 2D child — fails the same way.
+
+### `"translate" needs at least one shape inside it`
+
+Transforms need something to act on. Often the body contains only a
+[`part`](part.md), which contributes no geometry to its parent, or an `if` that took no
+branch.
+
+### My rotated part flew off across the scene
+
+Rotation is about the origin. A shape 200 mm out rotates around a 200 mm arc. Centre it,
+rotate, then move it where it belongs.
+
+### My mirrored copy vanished
+
+`mirror` replaces rather than adds. Union the original with the reflection if you want both.

package/src/reference.js

@@ -0,0 +1,160 @@
+/**
+ * The reference manual, bundled and searchable.
+ *
+ * The manual is the language's own documentation, copied into the package by
+ * `scripts/sync-reference.mjs` rather than paraphrased, so an answer from here is the same
+ * answer a person reading the published docs would get. Search is deliberately simple —
+ * substring matching over headings and body text, ranked — because the corpus is 28 pages
+ * and anything cleverer would be a dependency and a source of surprise.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Where the copied manual lives inside the package. */
+const ROOT = fileURLToPath(new URL('./reference/', import.meta.url));
+
+/** How many characters of context a search hit carries. */
+const SNIPPET = 320;
+
+/**
+ * The manual's pages, in reading order rather than directory order.
+ *
+ * Written out because a listing would put `align` before `param`, which is not the order
+ * anyone learns this in. A page on disk that is missing from here is a failure the tests
+ * catch, so the list cannot silently fall behind the manual.
+ *
+ * @type {Array<{ path: string, title: string, about: string }>}
+ */
+export const PAGES = [
+  { path: 'README.md', title: 'Reference index', about: 'Every construct, listed and linked' },
+  { path: 'language/overview.md', title: 'Document structure', about: 'The four top-level blocks, the pipeline, nesting, dimensionality' },
+  { path: 'language/syntax.md', title: 'Syntax', about: 'Comments, numbers, strings, identifiers, labels, the newline rule, the grammar' },
+  { path: 'language/expressions.md', title: 'Expressions', about: 'Values, operators, truthiness, interpolation, member access' },
+  { path: 'language/scope.md', title: 'Scope and names', about: 'What is in scope where, var., shadowing, component isolation' },
+  { path: 'language/control-flow.md', title: 'Control flow', about: 'for and if / else if / else' },
+  { path: 'reference/param.md', title: 'param', about: 'Inputs, their metadata, and what is advisory' },
+  { path: 'reference/local.md', title: 'local', about: 'Named values, ordering, and how they differ from params' },
+  { path: 'reference/component.md', title: 'component', about: 'Reusable parameterised geometry' },
+  { path: 'reference/model.md', title: 'model', about: 'Renderable scenes, model params, several models in one document' },
+  { path: 'reference/shapes-2d.md', title: '2D shapes', about: 'rect, rounded_rect, circle, ellipse, regular_polygon, stadium, polygon' },
+  { path: 'reference/shapes-3d.md', title: '3D shapes', about: 'box, sphere, cylinder, cone, torus' },
+  { path: 'reference/booleans.md', title: 'Booleans', about: 'union, difference, intersection' },
+  { path: 'reference/transforms.md', title: 'Transforms', about: 'translate, rotate, scale, mirror' },
+  { path: 'reference/conversions.md', title: '2D to 3D and back', about: 'extrude, revolve, project, slice' },
+  { path: 'reference/refinement.md', title: 'Refinement', about: 'offset, hull, refine, simplify, smooth, trim' },
+  { path: 'reference/align.md', title: 'align', about: 'Placing geometry by measuring its bounding box' },
+  { path: 'reference/part.md', title: 'part', about: 'Coloured pieces of the rendered scene' },
+  { path: 'reference/functions.md', title: 'Functions', about: 'Every builtin function and constant' },
+  { path: 'errors.md', title: 'Errors', about: 'Every error message, what raises it, and what to change' },
+  { path: 'api/render.md', title: 'render', about: 'JavaScript API: compile a document and evaluate a model' },
+  { path: 'api/describe-parameters.md', title: 'describeParameters', about: 'JavaScript API: read a document’s params without rendering' },
+  { path: 'api/evaluation-context.md', title: 'EvaluationContext', about: 'JavaScript API: the digest cache and WASM ownership' },
+  { path: 'api/geometry-node.md', title: 'GeometryNode', about: 'JavaScript API: the content-addressed geometry IR' },
+  { path: 'api/kernel.md', title: 'Kernel', about: 'JavaScript API: loadKernel, setQuality, resetQuality' },
+  { path: 'api/export.md', title: 'Export', about: 'JavaScript API: toRenderMesh and toBinarySTL' },
+  { path: 'api/values.md', title: 'Values', about: 'JavaScript API: Vector, Angle, Transform' },
+  { path: 'api/low-level.md', title: 'Low-level API', about: 'JavaScript API: Program, Evaluator, parse, tokenize, the registries' },
+];
+
+/** The pages, by path, so a lookup does not scan the list. */
+const BY_PATH = new Map(PAGES.map((page) => [page.path, page]));
+
+/**
+ * Every page on disk, whether or not {@link PAGES} names it.
+ *
+ * Used by the tests to prove the two agree; nothing at runtime reads it.
+ *
+ * @returns {Promise<string[]>} Paths relative to the manual's root, sorted.
+ */
+export async function discoverPages() {
+  /** @type {string[]} */
+  const found = [];
+  const walk = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const child = join(directory, entry.name);
+      if (entry.isDirectory()) await walk(child);
+      else if (entry.name.endsWith('.md')) found.push(relative(ROOT, child));
+    }
+  };
+  await walk(ROOT);
+  return found.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Reads one page.
+ *
+ * @param {string} path The page, as {@link PAGES} spells it.
+ * @returns {Promise<{ path: string, title: string, markdown: string }>} The page.
+ * @throws {Error} If no such page exists.
+ */
+export async function readPage(path) {
+  const normalised = path.replace(/^\.?\//, '');
+  const page = BY_PATH.get(normalised);
+  if (!page) {
+    throw new Error(
+      `no reference page "${path}" — the pages are ${PAGES.map((each) => each.path).join(', ')}`,
+    );
+  }
+  return { path: page.path, title: page.title, markdown: await readFile(join(ROOT, page.path), 'utf8') };
+}
+
+/**
+ * The heading a character offset falls under, so a hit can say where in the page it is.
+ *
+ * @param {string} markdown The page.
+ * @param {number} offset Where the match was found.
+ * @returns {string} The nearest heading above it, or the page's title.
+ */
+function headingAt(markdown, offset) {
+  const before = markdown.slice(0, offset);
+  const headings = before.match(/^#{1,4} .*$/gm);
+  return headings?.length ? headings.at(-1).replace(/^#+ /, '') : '';
+}
+
+/**
+ * Searches the manual.
+ *
+ * Every term must appear somewhere in the page; pages are ranked by how often the terms
+ * occur, with a heading match worth more than a body one.
+ *
+ * @param {string} query What to look for.
+ * @param {number} [limit] How many hits to return.
+ * @returns {Promise<Array<{ path: string, title: string, heading: string, snippet: string }>>}
+ *   The hits, best first.
+ */
+export async function searchReference(query, limit = 6) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return [];
+
+  /** @type {Array<{ score: number, path: string, title: string, heading: string, snippet: string }>} */
+  const hits = [];
+
+  for (const page of PAGES) {
+    const markdown = await readFile(join(ROOT, page.path), 'utf8');
+    const lower = markdown.toLowerCase();
+    if (!terms.every((term) => lower.includes(term))) continue;
+
+    const headings = (lower.match(/^#{1,4} .*$/gm) ?? []);
+    const score = terms.reduce((total, term) => {
+      const body = lower.split(term).length - 1;
+      const named = headings.filter((heading) => heading.includes(term)).length;
+      return total + body + named * 8;
+    }, 0);
+
+    const at = lower.indexOf(terms[0]);
+    const from = Math.max(0, at - SNIPPET / 4);
+    hits.push({
+      score,
+      path: page.path,
+      title: page.title,
+      heading: headingAt(markdown, at),
+      snippet: markdown.slice(from, from + SNIPPET).trim(),
+    });
+  }
+
+  return hits
+    .toSorted((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ score: _score, ...hit }) => hit);
+}