forma-dsl 0.2.2 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "A declarative DSL for 3D modeling and scene composition, reusable components, and live previews.",
   "keywords": [
     "cad",

package/src/core/context.js

@@ -1,3 +1,15 @@
+/**
+ * Where geometry is actually built: a node tree in, solved kernel objects out, memoized by
+ * digest.
+ *
+ * Two things earn this its own module. The cache is keyed on content rather than on object
+ * identity, so an edit that rebuilds the tree from scratch still hits every subtree it did
+ * not change — which is what makes re-solving on a keystroke affordable. And the kernel's
+ * objects are WASM allocations that no garbage collector will free, so something has to own
+ * them and let them go; that is what `dispose` and `collect` are for, and why the caller is
+ * told in `render`'s contract that the context is theirs.
+ */
+
 /** @import { CollectOptions, ContextStats, Kernel, Shape, Solid } from '../index.js' */
 /** @import { GeometryNode } from './node.js' */
 

package/src/core/digest.js

@@ -1,9 +1,11 @@
-// A 128-bit content digest, computed once per node and never recomputed.
-//
-// It must be stable across runs, machines and browsers: two structurally identical trees
-// have to produce the same digest every time, or the evaluation cache silently misses and
-// a rebuilt model recomputes everything. That rules out anything seeded per process, and
-// it rules out Web Crypto, which is async and cannot be called from a constructor.
+/**
+ * A 128-bit content digest, computed once per node and never recomputed.
+ *
+ * It must be stable across runs, machines and browsers: two structurally identical trees have
+ * to produce the same digest every time, or the evaluation cache silently misses and a
+ * rebuilt model recomputes everything. That rules out anything seeded per process, and it
+ * rules out Web Crypto, which is async and cannot be called from a constructor.
+ */
 
 const C1 = 0x239b961b, C2 = 0xab0e9789, C3 = 0x38b34ae5, C4 = 0xa1e38b93;
 

package/src/core/kernel.js

@@ -1,3 +1,12 @@
+/**
+ * Loading the Manifold WASM module, and the global knobs for curve resolution.
+ *
+ * One instance per page or process. Memoized here rather than left to each caller, because
+ * two models evaluating concurrently at startup must not each start an instantiation — and
+ * because the resolution controls below are global to the module, so there is nowhere else
+ * they could honestly live.
+ */
+
 /** @import { Kernel, QualityOptions } from '../index.js' */
 
 import ManifoldModule from 'manifold-3d';

package/src/core/node.js

@@ -1,3 +1,16 @@
+/**
+ * The geometry tree: a description of geometry that has not been built yet.
+ *
+ * A node names an operation and its children, and carries a digest of the whole subtree
+ * beneath it. Nothing here touches the kernel — that separation is the point, and the
+ * evaluation context is the other half of it.
+ *
+ * The digest is what the evaluation cache is keyed on, so everything feeding it has to be
+ * canonical: attributes in sorted order, the operands of a commutative operation ordered
+ * too, and no dependence on locale or on the order a document happened to be written in. A
+ * digest that varies across machines is a cache that silently never hits.
+ */
+
 /** @import { BooleanOp, Dimensionality } from '../index.js' */
 
 import { DigestWriter } from './digest.js';

package/src/export/mesh.js

@@ -1,3 +1,12 @@
+/**
+ * Turning a solved kernel object into vertex arrays a renderer can upload.
+ *
+ * The kernel keeps an indexed mesh with vertices shared between faces, which is what makes it
+ * compact and what makes it wrong to draw directly: a shared vertex has one normal, so every
+ * flat face it touches gets smeared into its neighbours. Expanding the indices back out is
+ * the whole of what this file is for.
+ */
+
 /** @import { IndexedMesh, RenderMesh, Solid } from '../index.js' */
 
 /**

package/src/export/stl.js

@@ -1,3 +1,11 @@
+/**
+ * Binary STL, for handing a solved part to a slicer.
+ *
+ * STL is the least a mesh format can carry — triangles and normals, no units, no colour and
+ * no notion of a part — and it is what every slicer reads. Anything richer belongs in its
+ * own exporter rather than in a dialect of this one.
+ */
+
 /** @import { Solid } from '../index.js' */
 
 import { toRenderMesh } from './mesh.js';

package/src/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Type declarations for forma-dsl.
  *
- * Hand-written rather than generated: the runtime is plain JavaScript, and the shapes worth
+ * Handwritten rather than generated: the runtime is plain JavaScript, and the shapes worth
  * publishing are the ones a caller actually touches. Internals that are exported only
  * because a test or the editor reaches for them are typed loosely on purpose.
  */
@@ -90,8 +90,6 @@ export interface QualityOptions {
 export declare function setQuality(options?: QualityOptions): Promise<void>;
 export declare function resetQuality(): Promise<void>;
 
-// --- values -----------------------------------------------------------------------------
-
 export declare class Vector {
   constructor(components: readonly number[]);
   static of(value: Vector | number | readonly number[] | Record<string, number>, dimensions: number): Vector;
@@ -281,6 +279,15 @@ export interface EvaluatorOptions {
   context?: EvaluationContext | null;
   /** Off lets a document declaring a param with no default still be inspected. */
   requireParams?: boolean;
+  /**
+   * How many blocks may be built before evaluation gives up. Omitted, there is no limit.
+   *
+   * Nesting limits and `range` bound one loop each; only this bounds their product. Pass one
+   * when building a document you did not write.
+   */
+  maxNodes?: number | null;
+  /** Checked at every block, so a build can be abandoned before it finishes. */
+  signal?: AbortSignal | null;
 }
 
 export declare class Evaluator {
@@ -350,8 +357,6 @@ export interface FunctionDefinition {
 export declare const FUNCTIONS: Record<string, FunctionDefinition>;
 export declare const CONSTANTS: Record<string, number>;
 
-// --- export ----------------------------------------------------------------------------------
-
 export interface RenderMesh {
   /** Three vertices per triangle, expanded so hard edges stay hard. */
   positions: Float32Array;
@@ -364,14 +369,27 @@ export interface RenderMesh {
 export declare function toRenderMesh(manifold: Solid): RenderMesh;
 export declare function toBinarySTL(manifold: Solid, header?: string): Uint8Array;
 
-// --- the front door ----------------------------------------------------------------------------
-
 export interface RenderOptions {
   /** Which model to render. Defaults to the first the document declares. */
   model?: string | null;
   params?: Record<string, ParameterValue>;
   /** Reuse a context to keep its cache across renders. The caller still owns it. */
   context?: EvaluationContext | null;
+  /**
+   * How many blocks may be built before evaluation gives up. Omitted, there is no limit.
+   *
+   * Nesting limits and `range` bound one loop each; only this bounds their product, which is
+   * what a document nesting two large loops exceeds. Pass one when rendering a document you
+   * did not write.
+   */
+  maxNodes?: number | null;
+  /**
+   * Abandons the render when it fires, throwing the signal's reason.
+   *
+   * Checked at every block and between parts, so a superseded render stops before spending
+   * kernel time rather than after.
+   */
+  signal?: AbortSignal | null;
 }
 
 export interface RenderedPart extends ScenePart {

package/src/index.js

@@ -1,3 +1,13 @@
+/**
+ * The package's public surface: what a consumer may import, and the two calls that do the
+ * work.
+ *
+ * Everything under `src/` is reachable only through this file, and that is what the rest of
+ * the repository is held to: the editor, the landing page and the MCP server all import
+ * `forma-dsl` rather than its sources. An export one of them needs and this file does not
+ * name therefore fails here, rather than in someone's install.
+ */
+
 /** @import { ParameterDescriptor, RenderOptions, RenderResult, RenderedPart, Solid } from './index.js' */
 
 export { Program, Evaluator } from './lang/evaluate.js';
@@ -27,19 +37,21 @@ import { toRenderMesh } from './export/mesh.js';
  * how much a reused context holds.
  *
  * @param {string} source The document.
- * @param {RenderOptions} [options] Which model, what parameters, and a context to reuse.
+ * @param {RenderOptions} [options] Which model, what parameters, a context to reuse, and the
+ *   budget and signal that bound the build.
  * @returns {Promise<RenderResult>} The parts, with both kernel objects and meshes.
- * @throws {Error} On any syntax, evaluation or geometry failure. A context created here is
+ * @throws {Error} On any syntax, evaluation or geometry failure, on a document that exceeds
+ *   `maxNodes`, or with the signal's reason if the caller aborted. A context created here is
  *   disposed before the error propagates; one the caller supplied is left alone, since the
  *   caller may still want it.
  */
 export async function render(source, options = {}) {
-  const { model = null, params = {}, context = null } = options;
+  const { model = null, params = {}, context = null, maxNodes = null, signal = null } = options;
 
   const started = Date.now();
   const program = Program.parse(source);
   const owned = context ?? await EvaluationContext.create();
-  const evaluator = new Evaluator(program, { params, context: owned });
+  const evaluator = new Evaluator(program, { params, context: owned, maxNodes, signal });
 
   try {
     const scene = await evaluator.model(model);
@@ -47,6 +59,10 @@ export async function render(source, options = {}) {
     /** @type {RenderedPart[]} */
     const parts = [];
     for (const part of scene.parts) {
+      // Between parts as well as inside the evaluator: solving is where the time actually
+      // goes, so a caller that gave up during the first part should not pay for the rest.
+      signal?.throwIfAborted();
+
       // Checked before solving rather than after: a 2D part is going to be refused either
       // way, and there is no reason to spend the kernel call first.
       if (part.node.dim !== 3) {

package/src/lang/ast.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The shapes the parser produces.
+ *
+ * It exists because the AST was previously implicit: the set of `kind` values, and what each
+ * one carries, could only be recovered by reading the parser and the evaluator side by side
+ * and hoping they agreed.
+ *
+ * Declarations rather than JSDoc typedefs, which is what this always was — there is no
+ * runtime content here, so there is nothing for a `.js` file to carry and nothing to build.
+ * Written as types, a discriminant is `kind: 'unary'` rather than a `@property` whose
+ * description the lint obliged someone to invent.
+ */
+
+import type { SourceLocation } from '../index.js';
+
+/** A number, string, boolean or null written directly in the source. */
+export interface LiteralExpression {
+  kind: 'literal';
+  value: number | string | boolean | null;
+  loc?: SourceLocation;
+}
+
+/** A `"..."` string with at least one `${...}` splice in it. */
+export interface TemplateExpression {
+  kind: 'template';
+  /** The literal runs and the spliced expressions, in source order. */
+  parts: Array<{ kind: 'text'; value: string } | { kind: 'expr'; expression: Expression }>;
+  loc: SourceLocation;
+}
+
+/** A `[a, b, c]` list. */
+export interface ArrayExpression {
+  kind: 'array';
+  items: Expression[];
+  loc: SourceLocation;
+}
+
+/** A `{ key = value }` object. */
+export interface ObjectExpression {
+  kind: 'object';
+  entries: Array<{ key: string; value: Expression }>;
+  loc: SourceLocation;
+}
+
+/** A bare name, resolved against the enclosing scopes. */
+export interface IdentifierExpression {
+  kind: 'identifier';
+  name: string;
+  loc: SourceLocation;
+}
+
+/** A `target.property` access. Also covers `.x`/`.y`/`.z` on a list. */
+export interface MemberExpression {
+  kind: 'member';
+  object: Expression;
+  property: string;
+  loc?: SourceLocation;
+}
+
+/** A `target[index]` access. */
+export interface IndexExpression {
+  kind: 'index';
+  object: Expression;
+  index: Expression;
+  loc?: SourceLocation;
+}
+
+/** A prefix `-` or `!`. */
+export interface UnaryExpression {
+  kind: 'unary';
+  op: '-' | '!';
+  operand: Expression;
+  loc: SourceLocation;
+}
+
+/** An infix operator. `&&` and `||` short-circuit; the rest evaluate both sides. */
+export interface BinaryExpression {
+  kind: 'binary';
+  op: string;
+  left: Expression;
+  right: Expression;
+  loc: SourceLocation;
+}
+
+/** A `condition ? consequent : alternate`. */
+export interface ConditionalExpression {
+  kind: 'conditional';
+  condition: Expression;
+  consequent: Expression;
+  alternate: Expression;
+  loc?: SourceLocation;
+}
+
+/** A call to one of the builtin functions. There are no user-defined functions. */
+export interface CallExpression {
+  kind: 'call';
+  /** Must resolve to an identifier naming a builtin. */
+  callee: Expression;
+  args: Array<{ name: string | null; value: Expression }>;
+  loc: SourceLocation;
+}
+
+/** Anything that evaluates to a value. */
+export type Expression =
+  | LiteralExpression | TemplateExpression | ArrayExpression | ObjectExpression
+  | IdentifierExpression | MemberExpression | IndexExpression | UnaryExpression
+  | BinaryExpression | ConditionalExpression | CallExpression;
+
+/** A `name = expression` inside a block body. */
+export interface Attribute {
+  name: string;
+  value: Expression;
+  loc?: SourceLocation;
+}
+
+/** The contents of a `{ ... }`, sorted by what each entry is. */
+export interface Body {
+  attributes: Attribute[];
+  blocks: Array<Block | ForBlock | IfBlock>;
+  params: ParamDeclaration[];
+  locals: LocalDeclaration[];
+}
+
+/** A nested block: a shape, an operation, a part, or a call to a component. */
+export interface Block {
+  kind: 'block';
+  /** Which block, such as `box` or `translate`. */
+  type: string;
+  /**
+   * The labels before the brace, as expressions, so a part built in a loop can name itself
+   * from the loop variable.
+   */
+  labels: Expression[];
+  body: Body;
+  loc: SourceLocation;
+}
+
+/** A `for name in sequence { ... }`, optionally with an index variable. */
+export interface ForBlock {
+  kind: 'for';
+  /** One name binds the value; two bind the index and the value. */
+  names: string[];
+  sequence: Expression;
+  body: Body;
+  loc: SourceLocation;
+}
+
+/** An `if condition { ... } else { ... }`. */
+export interface IfBlock {
+  kind: 'if';
+  condition: Expression;
+  consequent: Body;
+  /** The branch taken otherwise, if there is one. */
+  alternate: Body | null;
+  loc: SourceLocation;
+}
+
+/** A `param name { ... }` or `param name = expression`. */
+export interface ParamDeclaration {
+  kind: 'param';
+  name: string;
+  /** Its metadata; only `default` affects geometry. */
+  attributes: Attribute[];
+  loc: SourceLocation;
+}
+
+/** A `local name = expression`. */
+export interface LocalDeclaration {
+  kind: 'local';
+  name: string;
+  /** Its value, computed once. */
+  value: Expression;
+  loc: SourceLocation;
+}
+
+/** A `component "name" { ... }` or `model "name" { ... }`. */
+export interface NamedDeclaration {
+  kind: 'component' | 'model';
+  /** The declared name, always static. */
+  name: string;
+  body: Body;
+  loc: SourceLocation;
+}
+
+/** Anything that can appear at the top level of a document. */
+export type Declaration = ParamDeclaration | LocalDeclaration | NamedDeclaration;
+
+/** A whole parsed document. */
+export interface Document {
+  kind: 'document';
+  declarations: Declaration[];
+}

package/src/lang/builtins.js

@@ -1,3 +1,13 @@
+/**
+ * The registries: every block the language has, every function it can call, and the reader
+ * that turns a block's attributes into typed values.
+ *
+ * This is the one description of what the language contains. The editor's highlighting, the
+ * landing page's and the docs' code samples, and the MCP server's catalogue all read
+ * `BLOCKS` and `FUNCTIONS` from here rather than restating them — so a block added here is
+ * one they all learn about, and a block they claim without it existing fails their tests.
+ */
+
 /** @import { AttributeReader, BlockDefinition, Dimensionality, FunctionDefinition, SourceLocation } from '../index.js' */
 
 import { GeometryNode } from '../core/node.js';

package/src/lang/evaluate.js

@@ -1,3 +1,17 @@
+/**
+ * The evaluator: a parsed document in, a tree of geometry nodes out.
+ *
+ * Nothing here calls the kernel. Evaluating a model produces {@link GeometryNode}s, which
+ * describe geometry without building any, and solving those is {@link EvaluationContext}'s
+ * job. Keeping the two apart is what makes a live preview affordable — a description is
+ * cheap to rebuild on every keystroke, and a solid is not.
+ *
+ * The three things in this file fail in three different ways, which is why they are three
+ * things: {@link Program} indexes what a document declares, {@link Scope} resolves names
+ * against it, and {@link Evaluator} turns blocks into nodes. Which one raised an error is
+ * most of what tells a reader whether they made a typo or a mistake about meaning.
+ */
+
 /** @import { EvaluationContext, EvaluatorOptions, ParameterDescriptor, ParameterValue, Scene, ScenePart } from '../index.js' */
 /** @import { BinaryExpression, Block, Body, CallExpression, Document, Expression, ForBlock, IfBlock, MemberExpression, NamedDeclaration } from './ast.js' */
 
@@ -180,13 +194,13 @@ export class Evaluator {
    * or unreadable input surfaces before any geometry is built.
    *
    * @param {Program} program The program to evaluate.
-   * @param {EvaluatorOptions} [options] Params, an optional kernel context, and whether
-   *   params must all resolve.
+   * @param {EvaluatorOptions} [options] Params, an optional kernel context, whether params
+   *   must all resolve, and the budget and signal that bound the build.
    * @throws {FormaError} If a param has no default and no supplied value, unless
    *   `requireParams` is off.
    */
   constructor(program, options = {}) {
-    const { params = {}, context = null, requireParams = true } = options;
+    const { params = {}, context = null, requireParams = true, maxNodes = null, signal = null } = options;
 
     /** @type {Program} The program being evaluated. */
     this.program = program;
@@ -199,6 +213,28 @@ export class Evaluator {
     /** @type {number} How deep into component calls evaluation currently is. */
     this.depth = 0;
 
+    /**
+     * How many blocks may be built before evaluation gives up, or null for no limit.
+     *
+     * {@link MAX_DEPTH} stops a component that calls itself, and `range` caps how many values
+     * a single loop produces — but neither bounds their product. Two loops of ten thousand
+     * nested in each other is a hundred million blocks, each one a kernel allocation, and no
+     * amount of waiting finishes it.
+     *
+     * Off by default, because the embedder that controls its own input does not need it and
+     * should not have a ceiling imposed. A host that builds documents it did not write — an
+     * MCP server, a shared editor — should pass one.
+     *
+     * @type {number | null}
+     */
+    this.maxNodes = maxNodes;
+
+    /** @type {AbortSignal | null} Checked at every block, so a caller can give up mid-build. */
+    this.signal = signal;
+
+    /** @type {number} How many blocks have been built so far, counted against the budget. */
+    this.built = 0;
+
     const root = new Scope();
     // Constants and type names are in scope before any param default is read, so a default
     // can use `pi` and a `type = number` attribute resolves.
@@ -431,9 +467,23 @@ export class Evaluator {
    * @param {Block | ForBlock | IfBlock} block The block.
    * @param {Scope} scope The enclosing scope.
    * @returns {Promise<Produced>} What it produced.
-   * @throws {FormaError} On unknown blocks, misplaced labels, or nesting past {@link MAX_DEPTH}.
+   * @throws {FormaError} On unknown blocks, misplaced labels, nesting past {@link MAX_DEPTH},
+   *   or a document that has built more blocks than the budget allows.
+   * @throws {Error} The signal's reason, if the caller has aborted.
    */
   async block(block, scope) {
+    // Both checks go here rather than at the loop, because a block is the one thing every
+    // path builds: a `for`, a component call and a plain shape all arrive through it.
+    this.signal?.throwIfAborted();
+
+    if (this.maxNodes !== null && ++this.built > this.maxNodes) {
+      throw new FormaError(
+        `more than ${this.maxNodes} blocks built — the document asks for more geometry than `
+        + 'this budget allows; narrow a loop, or raise maxNodes if it is genuinely this large',
+        block.loc,
+      );
+    }
+
     if (this.depth > MAX_DEPTH) {
       throw new FormaError(`nesting deeper than ${MAX_DEPTH} blocks — is a component using itself?`, block.loc);
     }

package/src/lang/lexer.js

@@ -1,3 +1,15 @@
+/**
+ * The lexer: source text in, a flat stream of tokens out.
+ *
+ * Strings are the one thing it does not hand on whole. A `"..."` carrying `${...}` is split
+ * here into literal runs and spliced source, because working out where a splice ends means
+ * counting braces — which is a job for something reading characters, not for a parser reading
+ * tokens.
+ *
+ * {@link FormaError} lives here rather than next to the evaluator because this is the first
+ * pass that can fail, and every later one raises the same type.
+ */
+
 /** @import { SourceLocation, Token, TokenType } from '../index.js' */
 
 /**
@@ -31,13 +43,11 @@ const PUNCTUATION = [
   '+', '-', '*', '/', '%', '!', '?', ':',
 ];
 
+/** @typedef {{ kind: 'text', value: string } | { kind: 'expr', source: string, loc: SourceLocation }} Part */
+
 /** Escapes recognised inside a string. `\$` is here so a literal `${` can be written. */
 const ESCAPES = { n: '\n', t: '\t', r: '\r', '"': '"', '\\': '\\', $: '$' };
 
-/**
- * @param {string} c A single character.
- * @returns {boolean} Whether a name may begin with it.
- */
 const isIdentStart = (c) => /[A-Za-z_]/.test(c);
 
 /**
@@ -47,10 +57,6 @@ const isIdentStart = (c) => /[A-Za-z_]/.test(c);
  */
 const isIdentPart = (c) => /[A-Za-z0-9_-]/.test(c);
 
-/**
- * @param {string} c A single character.
- * @returns {boolean} Whether it is a decimal digit.
- */
 const isDigit = (c) => c >= '0' && c <= '9';
 
 /**
@@ -212,7 +218,7 @@ class Lexer {
     const loc = this.here();
     this.advance();
 
-    /** @type {Array<{ kind: 'text', value: string } | { kind: 'expr', source: string, loc: SourceLocation }>} */
+    /** @type {Part[]} */
     const parts = [];
     let text = '';
 

package/src/lang/parser.js

@@ -1,3 +1,16 @@
+/**
+ * The parser: tokens in, a syntax tree out.
+ *
+ * Recursive descent with a precedence table for the infix operators. The grammar is small
+ * enough that a generator would cost more than it saved, and writing it by hand is what lets
+ * every node carry the source position that produced it — which is the whole of how errors
+ * point at something later on.
+ *
+ * It checks shape and nothing else. Whether `cylinder` is a real block, and whether its
+ * attributes mean anything, is the evaluator's question; a document that parses is only
+ * a document spelled like forma.
+ */
+
 /** @import { SourceLocation, Token, TokenType } from '../index.js' */
 /** @import { Attribute, Block, Body, Declaration, Document, Expression, ForBlock, IfBlock, LocalDeclaration, ParamDeclaration } from './ast.js' */
 

package/src/values/transform.js

@@ -1,3 +1,12 @@
+/**
+ * Affine transforms, in the layout the kernel expects.
+ *
+ * A value type: every operation returns a new transform and none mutates the receiver, so a
+ * transform captured by a scope cannot be changed underneath it by a sibling block. That
+ * matters more than it sounds — nesting is how the language composes, and a mutable
+ * transform would make a block's meaning depend on what ran before it.
+ */
+
 /** @import { Dimensionality } from '../index.js' */
 /** @import { VectorLike } from './vector.js' */
 

package/src/lang/ast.js

@@ -1,226 +0,0 @@
-/** @import { SourceLocation } from '../index.js' */
-
-/**
- * The shapes the parser produces, as types only.
- *
- * This module has no runtime content. It exists because the AST was previously implicit:
- * the set of `kind` values, and what each one carries, could only be recovered by reading
- * the parser and the evaluator side by side and hoping they agreed.
- *
- * @module
- */
-
-export {};
-
-/**
- * A number, string, boolean or null written directly in the source.
- *
- * @typedef {object} LiteralExpression
- * @property {'literal'} kind Discriminant.
- * @property {number | string | boolean | null} value The value.
- * @property {SourceLocation} [loc] Where it was written.
- */
-
-/**
- * A `"..."` string with at least one `${...}` splice in it.
- *
- * @typedef {object} TemplateExpression
- * @property {'template'} kind Discriminant.
- * @property {Array<{ kind: 'text', value: string } | { kind: 'expr', expression: Expression }>} parts
- *   The literal runs and the spliced expressions, in source order.
- * @property {SourceLocation} loc Where the string began.
- */
-
-/**
- * A `[a, b, c]` list.
- *
- * @typedef {object} ArrayExpression
- * @property {'array'} kind Discriminant.
- * @property {Expression[]} items The elements.
- * @property {SourceLocation} loc Where the bracket was.
- */
-
-/**
- * A `{ key = value }` object.
- *
- * @typedef {object} ObjectExpression
- * @property {'object'} kind Discriminant.
- * @property {Array<{ key: string, value: Expression }>} entries The entries, in source order.
- * @property {SourceLocation} loc Where the brace was.
- */
-
-/**
- * A bare name, resolved against the enclosing scopes.
- *
- * @typedef {object} IdentifierExpression
- * @property {'identifier'} kind Discriminant.
- * @property {string} name The name.
- * @property {SourceLocation} loc Where the name was.
- */
-
-/**
- * A `target.property` access. Also covers `.x`/`.y`/`.z` on a list.
- *
- * @typedef {object} MemberExpression
- * @property {'member'} kind Discriminant.
- * @property {Expression} object What is being read from.
- * @property {string} property The property name.
- * @property {SourceLocation} [loc] Where the dot was.
- */
-
-/**
- * A `target[index]` access.
- *
- * @typedef {object} IndexExpression
- * @property {'index'} kind Discriminant.
- * @property {Expression} object What is being indexed.
- * @property {Expression} index The index.
- * @property {SourceLocation} [loc] Where the bracket was.
- */
-
-/**
- * A prefix `-` or `!`.
- *
- * @typedef {object} UnaryExpression
- * @property {'unary'} kind Discriminant.
- * @property {'-' | '!'} op The operator.
- * @property {Expression} operand What it applies to.
- * @property {SourceLocation} loc Where the operator was.
- */
-
-/**
- * An infix operator. `&&` and `||` short-circuit; the rest evaluate both sides.
- *
- * @typedef {object} BinaryExpression
- * @property {'binary'} kind Discriminant.
- * @property {string} op The operator.
- * @property {Expression} left The left operand.
- * @property {Expression} right The right operand.
- * @property {SourceLocation} loc Where the operator was.
- */
-
-/**
- * A `condition ? consequent : alternate`.
- *
- * @typedef {object} ConditionalExpression
- * @property {'conditional'} kind Discriminant.
- * @property {Expression} condition What decides.
- * @property {Expression} consequent The value when truthy.
- * @property {Expression} alternate The value when not.
- * @property {SourceLocation} [loc] Where it was written.
- */
-
-/**
- * A call to one of the builtin functions. There are no user-defined functions.
- *
- * @typedef {object} CallExpression
- * @property {'call'} kind Discriminant.
- * @property {Expression} callee Must resolve to an identifier naming a builtin.
- * @property {Array<{ name: string | null, value: Expression }>} args The arguments.
- * @property {SourceLocation} loc Where the parenthesis was.
- */
-
-/**
- * Anything that evaluates to a value.
- *
- * @typedef {LiteralExpression | TemplateExpression | ArrayExpression | ObjectExpression
- *   | IdentifierExpression | MemberExpression | IndexExpression | UnaryExpression
- *   | BinaryExpression | ConditionalExpression | CallExpression} Expression
- */
-
-/**
- * A `name = expression` inside a block body.
- *
- * @typedef {object} Attribute
- * @property {string} name The attribute name.
- * @property {Expression} value The value.
- * @property {SourceLocation} [loc] Where the name was.
- */
-
-/**
- * The contents of a `{ ... }`, sorted by what each entry is.
- *
- * @typedef {object} Body
- * @property {Attribute[]} attributes The `name = value` entries.
- * @property {Array<Block | ForBlock | IfBlock>} blocks The nested blocks, in source order.
- * @property {ParamDeclaration[]} params Params declared in this body.
- * @property {LocalDeclaration[]} locals Locals declared in this body.
- */
-
-/**
- * A nested block: a shape, an operation, a part, or a call to a component.
- *
- * @typedef {object} Block
- * @property {'block'} kind Discriminant.
- * @property {string} type Which block, such as `box` or `translate`.
- * @property {Expression[]} labels The labels before the brace, as expressions, so a part
- *   built in a loop can name itself from the loop variable.
- * @property {Body} body Its attributes and children.
- * @property {SourceLocation} loc Where the block began.
- */
-
-/**
- * A `for name in sequence { ... }`, optionally with an index variable.
- *
- * @typedef {object} ForBlock
- * @property {'for'} kind Discriminant.
- * @property {string[]} names One name binds the value; two bind the index and the value.
- * @property {Expression} sequence What to iterate.
- * @property {Body} body What to emit per iteration.
- * @property {SourceLocation} loc Where the `for` was.
- */
-
-/**
- * An `if condition { ... } else { ... }`.
- *
- * @typedef {object} IfBlock
- * @property {'if'} kind Discriminant.
- * @property {Expression} condition What decides.
- * @property {Body} consequent The branch taken when truthy.
- * @property {Body | null} alternate The branch taken otherwise, if there is one.
- * @property {SourceLocation} loc Where the `if` was.
- */
-
-/**
- * A `param name { ... }` or `param name = expression`.
- *
- * @typedef {object} ParamDeclaration
- * @property {'param'} kind Discriminant.
- * @property {string} name The param name.
- * @property {Attribute[]} attributes Its metadata; only `default` affects geometry.
- * @property {SourceLocation} loc Where the declaration began.
- */
-
-/**
- * A `local name = expression`.
- *
- * @typedef {object} LocalDeclaration
- * @property {'local'} kind Discriminant.
- * @property {string} name The local's name.
- * @property {Expression} value Its value, computed once.
- * @property {SourceLocation} loc Where the declaration began.
- */
-
-/**
- * A `component "name" { ... }` or `model "name" { ... }`.
- *
- * @typedef {object} NamedDeclaration
- * @property {'component' | 'model'} kind Which of the two.
- * @property {string} name The declared name, always static.
- * @property {Body} body Its contents.
- * @property {SourceLocation} loc Where the declaration began.
- */
-
-/**
- * Anything that can appear at the top level of a document.
- *
- * @typedef {ParamDeclaration | LocalDeclaration | NamedDeclaration} Declaration
- */
-
-/**
- * A whole parsed document.
- *
- * @typedef {object} Document
- * @property {'document'} kind Discriminant.
- * @property {Declaration[]} declarations The top-level blocks, in source order.
- */