forgecad 0.7.0 → 0.8.0

package/dist/docs-raw/generated/concepts.md

@@ -1,27 +1,25 @@
 # API by Concept
 
-> **Auto-generated** from `@concept` tags in `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Every public API function belongs to one of 16 fundamental concepts. This document groups them by concept rather than by module, making it easy to see the full set of operations for each idea.
 
 ## Concepts
 
-- **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(20 functions)*
+- **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(50 functions)*
 - **[C2: Boolean Combination](#c2-boolean-combination)** — Combine same-dimension geometry using CSG set operations. *(6 functions)*
 - **[C3: Rigid Transform](#c3-rigid-transform)** — Reposition or reorient geometry without changing its shape. *(3 functions)*
-- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(10 functions)*
+- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(12 functions)*
 - **[C5: Topology Query](#c5-topology-query)** — Select or inspect named faces and edges on a shape. *(3 functions)*
 - **[C6: Edge Feature](#c6-edge-feature)** — Modify edges of a solid — fillets, chamfers, draft, offset. *(7 functions)*
 - **[C7: Pattern Replication](#c7-pattern-replication)** — Duplicate geometry in regular arrangements (linear, circular, mirror). *(6 functions)*
-- **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(7 functions)*
-- **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(0 functions)*
+- **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(17 functions)*
+- **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(6 functions)*
 - **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(4 functions)*
-- **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(6 functions)*
+- **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(7 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(5 functions)*
-- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(6 functions)*
+- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(26 functions)*
 - **[C15: Import & Composition](#c15-import-composition)** — Bring external geometry or other ForgeCAD modules into the current script. *(1 functions)*
-- **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(0 functions)*
+- **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(4 functions)*
 
 ---
 
@@ -29,41 +27,280 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 
 Create geometry from parameters — no input geometry required.
 
-#### `circle2d()` — Create a 2D circle centered at the origin.
+#### `sdf.sphere()` — Create an SDF sphere centered at the origin.
 
-**Details**
+```ts
+sdf.sphere(radius: number): SdfShape
+```
 
-Omit `segments` for a smooth (auto-tessellated) circle. Pass an integer to get a regular polygon approximation — e.g. `6` for a hexagon, `8` for an octagon.
+#### `sdf.box()` — Create an SDF box centered at the origin with given full dimensions (not half-extents).
+
+```ts
+sdf.box(x: number, y: number, z: number): SdfShape
+```
+
+#### `sdf.cylinder()` — Create an SDF cylinder centered at the origin, axis along Z.
+
+```ts
+sdf.cylinder(height: number, radius: number): SdfShape
+```
+
+#### `sdf.torus()` — Create an SDF torus centered at the origin, lying in the XY plane.
+
+```ts
+sdf.torus(majorRadius: number, minorRadius: number): SdfShape
+```
+
+#### `sdf.capsule()` — Create an SDF capsule centered at the origin, axis along Z.
+
+```ts
+sdf.capsule(height: number, radius: number): SdfShape
+```
+
+#### `sdf.cone()` — Create an SDF cone with base at z=0 and tip at z=height.
+
+```ts
+sdf.cone(height: number, radius: number): SdfShape
+```
+
+#### `sdf.smoothUnion()` — Smooth union — blends shapes together with a smooth transition radius.
+
+```ts
+sdf.smoothUnion(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
+```
+
+#### `sdf.smoothDifference()` — Smooth difference — smoothly subtracts b from a.
+
+```ts
+sdf.smoothDifference(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
+```
+
+#### `sdf.smoothIntersection()` — Smooth intersection — smoothly intersects a and b.
+
+```ts
+sdf.smoothIntersection(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
+```
+
+#### `sdf.morph()` — Morph between two SDF shapes. t=0 → a, t=1 → b.
+
+```ts
+sdf.morph(a: SdfShape, b: SdfShape, t: number): SdfShape
+```
+
+#### `sdf.blend()` — Spatially blend between two SDF patterns. The blend function receives (x, y, z) and returns 0..1: 0 = fully pattern `a`, 1 = fully pattern `b`.
+
+```ts
+sdf.blend(a: SdfShape, b: SdfShape, fn: (x: number, y: number, z: number) => number, options?: BlendOptions): SdfShape
+```
+
+**`BlendOptions`**
+- `constants?: Record<string, number>` — Optional named constants accessible in the blend function.
+
+#### `sdf.gyroid()` — Gyroid TPMS lattice — the most common lattice for additive manufacturing.
+
+```ts
+sdf.gyroid(options: TpmsOptions): SdfShape
+```
+
+`TpmsOptions`: `{ cellSize: number, thickness: number }`
+
+#### `sdf.schwarzP()` — Schwarz-P TPMS lattice — isotropic pore structure.
+
+```ts
+sdf.schwarzP(options: TpmsOptions): SdfShape
+```
+
+#### `sdf.diamond()` — Diamond TPMS lattice — stiffest TPMS structure.
+
+```ts
+sdf.diamond(options: TpmsOptions): SdfShape
+```
+
+#### `sdf.lidinoid()` — Lidinoid TPMS lattice — visually distinct from gyroid, popular in research and art.
+
+```ts
+sdf.lidinoid(options: TpmsOptions): SdfShape
+```
+
+#### `sdf.noise()` — 3D Simplex noise field — produces organic, natural-looking displacements.
+
+```ts
+sdf.noise(options?: NoiseOptions): SdfShape
+```
+
+**`NoiseOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `scale?` | `number` | Spatial frequency — smaller = larger features. Default: 0.1 |
+| `amplitude?` | `number` | Peak displacement amplitude. Default: 1 |
+| `octaves?` | `number` | fBm octaves (1 = plain simplex, higher = more detail). Default: 1 |
+| `seed?` | `number` | Seed for deterministic variation. Default: 0 |
+
+#### `sdf.voronoi()` — 3D Voronoi pattern — organic cellular structures like bone, coral, or soap bubbles.
+
+```ts
+sdf.voronoi(options?: VoronoiOptions): SdfShape
+```
+
+**`VoronoiOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cellSize?` | `number` | Size of each Voronoi cell in world units. Default: 10 |
+| `wallThickness?` | `number` | Wall thickness between cells. Default: 1 |
+| `seed?` | `number` | Seed for deterministic variation. Default: 0 |
+| `suppressionThreshold?` | `number` | Projection weight for membrane suppression (0..1). Controls how much of the surface-normal distance component is removed from Voronoi cell distances. 0 = no projection (classic 3D voronoi with membranes). 1 = full tangent-plane projection (pure 2D pattern on surface). Default: 0.85. Only active when voronoi is intersected with another shape. |
+
+#### `sdf.honeycomb()` — Honeycomb (hexagonal) lattice pattern. Intersect with your shape to apply.
+
+```ts
+sdf.honeycomb(options?: HoneycombOptions): SdfShape
+```
+
+**`HoneycombOptions`**
+- `cellSize?: number` — Size of each hex cell. Default: 8
+- `wallThickness?: number` — Wall thickness. Default: 1
+
+#### `sdf.waves()` — Sinusoidal wave ridges — parallel ridges along an axis.
+
+```ts
+sdf.waves(options?: WavesOptions): SdfShape
+```
+
+**`WavesOptions`**
+- `wavelength?: number` — Distance between wave peaks. Default: 10
+- `amplitude?: number` — Height of waves. Default: 1
+- `axis?: "x" | "y" | "z"` — Axis along which waves propagate: 'x', 'y', or 'z'. Default: 'x'
+
+#### `sdf.knurl()` — Knurl pattern — crossed helical grooves for grips and handles.
+
+```ts
+sdf.knurl(options?: KnurlOptions): SdfShape
+```
+
+**`KnurlOptions`**
+- `pitch?: number` — Distance between knurl ridges. Default: 3
+- `depth?: number` — Depth of knurl grooves. Default: 0.5
+- `angle?: number` — Helix angle in degrees. Default: 30
+
+#### `sdf.perforated()` — Perforated plate pattern — regular array of cylindrical holes.
+
+```ts
+sdf.perforated(options?: PerforatedOptions): SdfShape
+```
+
+**`PerforatedOptions`**
+- `radius?: number` — Hole radius. Default: 3
+- `spacing?: number` — Center-to-center spacing. Default: 8
+
+#### `sdf.scales()` — Fish/dragon scale pattern — overlapping circular scales in hex-packed rows.
+
+```ts
+sdf.scales(options?: ScalesOptions): SdfShape
+```
+
+**`ScalesOptions`**
+- `size?: number` — Scale diameter. Default: 5
+- `depth?: number` — How much scales protrude. Default: 0.8
+
+#### `sdf.brick()` — Brick/stone wall pattern — running bond with mortar grooves.
+
+```ts
+sdf.brick(options?: BrickOptions): SdfShape
+```
+
+**`BrickOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `width?` | `number` | Brick width. Default: 10 |
+| `height?` | `number` | Brick height. Default: 5 |
+| `depth?` | `number` | Mortar groove depth. Default: 0.5 |
+| `mortar?` | `number` | Mortar gap width. Default: 1 |
+
+#### `sdf.weave()` — Grid lattice pattern — two families of infinite slabs crossing at 90°.
+
+```ts
+sdf.weave(options?: WeaveOptions): SdfShape
+```
+
+**`WeaveOptions`**
+- `spacing?: number` — Thread center-to-center spacing (for intersection patterns). Default: 5
+- `threadRadius?: number` — Thread half-width. Default: 1
+
+#### `sdf.basketWeave()` — Basket weave surface pattern — threads with over-under crossings in UV space. Returns a SurfacePattern for use with `.surfaceDisplace()`.
+
+```ts
+sdf.basketWeave(options?: BasketWeaveOptions): SurfacePattern
+```
+
+**`BasketWeaveOptions`**
+- `spacing?: number` — Spacing between threads in mm (both directions). Default: 3
+- `threadWidth?: number` — Thread width in mm. Default: 1.5
+- `depth?: number` — Thread protrusion depth in mm. Default: 0.8
+
+#### `sdf.twist()` — Twist an SDF shape around the Z axis.
+
+```ts
+sdf.twist(shape: SdfShape, degreesPerUnit: number): SdfShape
+```
+
+#### `sdf.bend()` — Bend an SDF shape around the Z axis.
+
+```ts
+sdf.bend(shape: SdfShape, radius: number): SdfShape
+```
+
+#### `sdf.repeat()` — Repeat an SDF shape in space.
+
+```ts
+sdf.repeat(shape: SdfShape, spacing: Vec3, count?: Vec3): SdfShape
+```
+
+#### `sdf.SurfacePattern()` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
+
+```ts
+sdf.SurfacePattern: typeof SurfacePattern
+```
 
-**Example**
+#### `sdf.fromFunction()` — Create an SDF shape from an arbitrary distance function. You must provide bounds since the function is opaque.
+
+```ts
+sdf.fromFunction(fn: (x: number, y: number, z: number) => number, bounds: { min: Vec3; max: Vec3; }, constants?: Record<string, number>): SdfShape
+```
+
+#### `circle2d()` — Create a 2D circle centered at the origin.
+
+Omit `segments` for a smooth (auto-tessellated) circle. Pass an integer to get a regular polygon approximation — e.g. `6` for a hexagon, `8` for an octagon.
 
 ```ts
 circle2d(25).extrude(10);          // smooth cylinder
 circle2d(25, 6).extrude(10);       // hexagonal prism
 ```
 
-`circle2d(radius: number, segments?: number): Sketch`
+```ts
+circle2d(radius: number, segments?: number): Sketch
+```
 
 #### `ellipse()` — Create a 2D ellipse centered at the origin.
 
-**Example**
-
 ```ts
 ellipse(30, 15).extrude(5);
 ellipse(30, 15, 32).extrude(5); // lower-resolution approximation
 ```
 
-`ellipse(rx: number, ry: number, segments?: number): Sketch`
+```ts
+ellipse(rx: number, ry: number, segments?: number): Sketch
+```
 
 #### `loadFont()` — Pre-load and cache a font for use with `text2d()`.
 
-**Details**
-
 Fonts are cached by their source string (or `cacheKey` for `ArrayBuffer` sources), so repeated calls with the same path are free. Pre-loading is useful when you call `text2d()` many times with the same font — it avoids repeated disk reads.
 
-Built-in font names that work everywhere (browser + CLI): - `'sans-serif'` or `'inter'` — bundled Inter Regular
+Built-in font names that work everywhere (browser + CLI):
 
-**Example**
+- `'sans-serif'` or `'inter'` — bundled Inter Regular
 
 ```ts
 const font = loadFont('/path/to/Arial Bold.ttf');
@@ -71,32 +308,28 @@ text2d('Title', { size: 12, font }).extrude(1.5);
 text2d('Subtitle', { size: 8, font }).extrude(1);
 ```
 
-`loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font`
+```ts
+loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype.Font
+```
 
 #### `ngon()` — Create a regular polygon inscribed in a circle of the given radius.
 
-**Details**
-
 `radius` is the center-to-vertex (circumradius) distance. Use `sides` of `3` for a triangle, `6` for a hexagon, etc. The first vertex is at the top (−90° from +X).
 
-**Example**
-
 ```ts
 ngon(6, 20).extrude(10); // hexagonal prism, circumradius 20
 ```
 
-`ngon(sides: number, radius: number): Sketch`
+```ts
+ngon(sides: number, radius: number): Sketch
+```
 
 #### `path()` — Create a new `PathBuilder` for tracing a 2D outline point by point.
 
-**Details**
-
 `PathBuilder` is a fluent API for constructing 2D profiles using a mix of line segments, arcs, bezier curves, and splines. Always start with `.moveTo(x, y)` to set the starting point. Call `.close()` to get a filled `Sketch`, or `.stroke(width)` to thicken an open polyline into a solid profile.
 
 Edge labels can be assigned with `.label('name')` after any segment — they propagate through extrusion, revolve, loft, and sweep into named faces on the resulting `Shape`.
 
-**Example**
-
 ```ts
 // Closed triangle
 const triangle = path().moveTo(0, 0).lineH(50).lineV(30).close();
@@ -113,21 +346,21 @@ const slot = path()
   .close();
 ```
 
-`path(): PathBuilder`
+```ts
+path(): PathBuilder
+```
 
 #### `polygon()` — Create a 2D polygon from an array of `[x, y]` points or `Point2D` objects.
 
-**Details**
-
 Winding order is normalized automatically — clockwise (CW) input is silently reversed to CCW before being passed to the geometry kernel.
 
-**Example**
-
 ```ts
 polygon([[0, 0], [50, 0], [25, 40]]).extrude(5); // triangle
 ```
 
-`polygon(points: ([ number, number ] | Point2D)[]): Sketch`
+```ts
+polygon(points: ([ number, number ] | Point2D)[]): Sketch
+```
 
 #### `polygonVertices()` — Compute the vertex positions of a regular polygon.
 
@@ -145,7 +378,9 @@ const v3 = [center.x + r, center.y];
 const [v1, v2, v3] = polygonVertices(3, r);
 ```
 
-`polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]`
+```ts
+polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
+```
 
 **`PolygonVerticesOptions`**
 - `startDeg?: number` — Angle of the first vertex in degrees (default: 90 = top).
@@ -156,57 +391,55 @@ const [v1, v2, v3] = polygonVertices(3, r);
 
 #### `rect()` — Create a 2D rectangle centered at the origin.
 
-**Example**
-
 ```ts
 rect(40, 20).extrude(5);
 ```
 
-`rect(width: number, height: number): Sketch`
+```ts
+rect(width: number, height: number): Sketch
+```
 
 #### `arcSlot()` — Create an arc-shaped slot (banana / annular sector) centered at the origin.
 
-**Details**
-
 The slot is symmetric about the +X axis. The two ends are closed with semicircular caps. `pitchRadius` is the distance from the origin to the centerline of the slot, and `thickness` is the radial width of the slot.
 
-**Example**
-
 ```ts
 arcSlot(135, 74, 40).extrude(5); // pitch R135, 74° sweep, 40mm wide
 ```
 
-`arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch`
+```ts
+arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
+```
 
 #### `roundedRect()` — Create a 2D rectangle with rounded corners, centered at the origin.
 
-**Details**
-
 The corner radius is automatically clamped to `min(width/2, height/2)` so it can never exceed the shape dimensions.
 
-**Example**
-
 ```ts
 roundedRect(60, 30, 5).extrude(3);
 ```
 
-`roundedRect(width: number, height: number, radius: number): Sketch`
+```ts
+roundedRect(width: number, height: number, radius: number): Sketch
+```
 
 #### `slot()` — Create a slot (oblong / stadium shape) — a rectangle with semicircular ends, centered at the origin.
 
-**Example**
-
 ```ts
 slot(40, 10).extrude(3); // 40mm long, 10mm wide slot
 ```
 
-`slot(length: number, width: number): Sketch`
+```ts
+slot(length: number, width: number): Sketch
+```
 
 #### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
 A closed spline (default) returns a filled profile. An open spline requires a strokeWidth option to produce a solid sketch. Use tension (0..1, default 0.5) to control curve tightness.
 
-`spline2d(points: Vec2[], options?: Spline2DOptions): Sketch`
+```ts
+spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
+```
 
 **`Spline2DOptions`**
 
@@ -220,30 +453,28 @@ A closed spline (default) returns a filled profile. An open spline requires a st
 
 #### `star()` — Create a star shape with alternating outer and inner radii.
 
-**Example**
-
 ```ts
 star(5, 30, 12).extrude(4); // five-pointed star
 ```
 
-`star(points: number, outerR: number, innerR: number): Sketch`
+```ts
+star(points: number, outerR: number, innerR: number): Sketch
+```
 
 #### `stroke()` — Create a stroked polyline sketch from an array of 2D points.
 
-`stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"): Sketch`
+```ts
+stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"): Sketch
+```
 
 #### `text2d()` — Build a filled 2D Sketch from a text string.
 
-**Details**
-
 The Sketch origin is at the left end of the text baseline by default. Use `align` and `baseline` options to adjust placement. Text is rendered using the bundled Inter font by default, or any TTF/OTF/WOFF font you provide.
 
 Alignment reference table:
 
 | `align` | `baseline` | Origin | |------------|--------------|-------------------------------------| | `'left'` | `'baseline'` | Bottom-left of first char (default) | | `'center'` | `'center'` | Dead center of text block | | `'right'` | `'top'` | Top-right corner |
 
-**Example**
-
 ```ts
 // Extruded nameplate
 text2d('FORGE CAD', { size: 8 }).extrude(1.2);
@@ -263,7 +494,9 @@ const font = loadFont('/path/to/Arial Bold.ttf');
 text2d('Title', { size: 12, font }).extrude(1.5);
 ```
 
-`text2d(content: string, options?: TextOptions): Sketch`
+```ts
+text2d(content: string, options?: TextOptions): Sketch
+```
 
 **`TextOptions`**
 
@@ -273,43 +506,49 @@ text2d('Title', { size: 12, font }).extrude(1.5);
 | `letterSpacing?` | `number` | Extra space between characters in model units. Negative values tighten the tracking. |
 | `align?` | `"left" | "center" | "right"` | Horizontal alignment relative to x = 0. - `'left'` — left edge at x = 0 (default) - `'center'` — centred on x = 0 - `'right'` — right edge at x = 0 |
 | `baseline?` | `"baseline" | "center" | "top"` | Vertical alignment relative to y = 0. - `'baseline'` — y = 0 is the text baseline (bottom of capital letters) - `'center'` — y = 0 is the vertical midpoint of the cap height - `'top'` — y = 0 is the top of capital letters |
-| `font?` | `string | opentype$1.Font` | Font to use for text rendering. - `'sans-serif'` or `'inter'` — bundled Inter font (works everywhere, including browser) - **file path** — path to a TTF, OTF, or WOFF font file (CLI/Node only) - **Font object** — a previously loaded opentype.js Font (from `loadFont()`) - **omitted** — uses the bundled Inter font (same as `'sans-serif'`) text2d('Hello World', { size: 10 }) // default Inter text2d('Custom Font', { size: 10, font: '/path/to/font.ttf' }) |
+| `font?` | `string | opentype.Font` | Font to use for text rendering. - `'sans-serif'` or `'inter'` — bundled Inter font (works everywhere, including browser) - **file path** — path to a TTF, OTF, or WOFF font file (CLI/Node only) - **Font object** — a previously loaded opentype.js Font (from `loadFont()`) - **omitted** — uses the bundled Inter font (same as `'sans-serif'`) text2d('Hello World', { size: 10 }) // default Inter text2d('Custom Font', { size: 10, font: '/path/to/font.ttf' }) |
 | `flattenTolerance?` | `number` | Bezier flattening tolerance in model units. Smaller = more polygon segments = smoother curves. |
 
 #### `textWidth()` — Measure the rendered advance width of a string without creating any geometry.
 
-**Details**
-
 Uses the same font metrics as `text2d()`. Useful for computing layout dimensions before building the actual sketch — e.g. sizing a plate to fit a label.
 
-**Example**
-
 ```ts
 const w = textWidth('SERIAL: 001', { size: 6 });
 const plate = box(w + 10, 12, 2);
 ```
 
-`textWidth(content: string, options?: Pick<TextOptions, "size" | "letterSpacing" | "font">): number`
+```ts
+textWidth(content: string, options?: Pick<TextOptions, "size" | "letterSpacing" | "font">): number
+```
 
 #### `box()` — Create a rectangular box. Centered on XY, base at Z=0.
 
 For named faces, build from a labeled sketch: `rect(x, y).labelEdges('s', 'e', 'n', 'w').extrude(z, { labels: { start: 'bottom', end: 'top' } })`.
 
-`box$1(x: number, y: number, z: number): Shape`
+```ts
+box(x: number, y: number, z: number): Shape
+```
 
 #### `cylinder()` — Create a cylinder or cone with named faces and edges. Centered on XY, base at Z=0.
 
 When radiusTop differs from radius, creates a tapered cone. Use the segments parameter to create regular prisms (e.g. 6 for a hexagonal prism). Returns a Shape with faces: top, bottom, side; and edges: top-rim, bottom-rim.
 
-`cylinder$1(height: number, radius: number, radiusTop?: number, segments?: number): Shape`
+```ts
+cylinder(height: number, radius: number, radiusTop?: number, segments?: number): Shape
+```
 
 #### `sphere()` — Create a sphere centered at the origin. Use segments for lower-poly approximations.
 
-`sphere$1(radius: number, segments?: number): Shape`
+```ts
+sphere(radius: number, segments?: number): Shape
+```
 
 #### `torus()` — Create a torus (donut shape) lying in the XY plane. Centered on all axes (origin is the ring center).
 
-`torus$1(majorRadius: number, minorRadius: number, segments?: number): Shape`
+```ts
+torus(majorRadius: number, minorRadius: number, segments?: number): Shape
+```
 
 ---
 
@@ -319,63 +558,63 @@ Combine same-dimension geometry using CSG set operations.
 
 #### `difference2d()` — Subtract one or more 2D sketches from a base sketch.
 
-**Details**
-
 The first sketch is the base; all subsequent sketches are subtracted from it. Accepts individual sketches or arrays: `difference2d(base, c1, c2)` or `difference2d([base, c1, c2])`. Uses Manifold's batch operation — faster than chaining `.subtract()` one by one.
 
-**Example**
-
 ```ts
 const donut = difference2d(circle2d(50), circle2d(30));
 ```
 
-`difference2d(...inputs: SketchOperandInput[]): Sketch`
+```ts
+difference2d(...inputs: SketchOperandInput[]): Sketch
+```
 
 #### `intersection2d()` — Keep only the area where all input sketches overlap (intersection boolean).
 
-**Details**
-
 Accepts individual sketches or arrays: `intersection2d(a, b)` or `intersection2d([a, b, c])`. Uses Manifold's batch operation — faster than chaining `.intersect()` one by one.
 
-**Example**
-
 ```ts
 const lens = intersection2d(circle2d(30).translate(-10, 0), circle2d(30).translate(10, 0));
 ```
 
-`intersection2d(...inputs: SketchOperandInput[]): Sketch`
+```ts
+intersection2d(...inputs: SketchOperandInput[]): Sketch
+```
 
 #### `union2d()` — Combine 2D sketches into a single profile using an additive boolean union.
 
-**Details**
-
 Accepts individual sketches or arrays: `union2d(a, b, c)` or `union2d([a, b, c])`. Uses Manifold's batch operation — faster than chaining `.add()` one by one when combining many sketches.
 
-**Example**
-
 ```ts
 const cross = union2d(rect(60, 10), rect(10, 60));
 ```
 
-`union2d(...inputs: SketchOperandInput[]): Sketch`
+```ts
+union2d(...inputs: SketchOperandInput[]): Sketch
+```
 
 #### `union()` — Combine shapes into a single solid (additive boolean).
 
 Accepts individual shapes, or an array of shapes. The first operand's color is preserved in the result.
 
-`union(...inputs: ShapeOperandInput[]): Shape`
+```ts
+union(...inputs: ShapeOperandInput[]): Shape
+```
 
 #### `difference()` — Subtract shapes from a base shape (subtractive boolean).
 
 The first shape is the base; all subsequent shapes are subtracted from it. Accepts individual shapes, or an array of shapes.
 
-`difference(...inputs: ShapeOperandInput[]): Shape`
+```ts
+difference(...inputs: ShapeOperandInput[]): Shape
+```
 
 #### `intersection()` — Keep only the overlapping volume of the input shapes (intersection boolean).
 
 Requires at least two shapes. Accepts individual shapes, or an array.
 
-`intersection(...inputs: ShapeOperandInput[]): Shape`
+```ts
+intersection(...inputs: ShapeOperandInput[]): Shape
+```
 
 ---
 
@@ -387,17 +626,23 @@ Reposition or reorient geometry without changing its shape.
 
 Use for clarity when the unit of an angle value would otherwise be ambiguous — e.g. `param("Angle", degrees(45))`.
 
-`degrees(deg: number): number`
+```ts
+degrees(deg: number): number
+```
 
 #### `radians()` — Convert radians to degrees.
 
 ForgeCAD's public API uses degrees throughout. Use this when you have a radian value (e.g. from `Math.atan2`) that you want to express in degrees.
 
-`radians(rad: number): number`
+```ts
+radians(rad: number): number
+```
 
 #### `composeChain()` — Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
 
-`composeChain(...steps: TransformInput[]): Transform`
+```ts
+composeChain(...steps: TransformInput[]): Transform
+```
 
 ---
 
@@ -405,11 +650,77 @@ ForgeCAD's public API uses degrees throughout. Use this when you have a radian v
 
 Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
 
+#### `nurbs3d()` — Create a NURBS curve from control points.
+
+With default options, creates a cubic non-rational B-spline with uniform clamped knots. Set `weights` for rational curves (exact circles, conics). Set `degree` for linear (1), quadratic (2), cubic (3), or higher-order curves.
+
+```js
+// Simple cubic B-spline through control points
+const curve = nurbs3d([[0,0,0], [10,5,0], [20,-5,10], [30,0,5]]);
+const tube = sweep(circle(2), curve);
+```
+
+```js
+// Rational quadratic — exact circular arc
+const arc = nurbs3d(
+  [[10,0,0], [10,10,0], [0,10,0]],
+  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
+);
+```
+
+```ts
+nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
+```
+
+**`NurbsCurve3DOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
+| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
+| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
+| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
+
+#### `nurbsSurface()` — Create a NURBS surface from a grid of control points.
+
+The control grid is indexed as `controlGrid[u][v]` — each row is a curve in the V direction, and columns trace curves in the U direction.
+
+With default options, creates a bicubic non-rational B-spline surface with uniform clamped knots.
+
+```js
+// Simple 4×4 control grid — a gently curved surface
+const grid = [
+  [[0,0,0], [10,0,2], [20,0,2], [30,0,0]],
+  [[0,10,1], [10,10,5], [20,10,5], [30,10,1]],
+  [[0,20,1], [10,20,5], [20,20,5], [30,20,1]],
+  [[0,30,0], [10,30,2], [20,30,2], [30,30,0]],
+];
+const surface = nurbsSurface(grid, { thickness: 2 });
+```
+
+```ts
+nurbsSurface(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape
+```
+
+**`NurbsSurfaceOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degreeU?` | `number` | Degree in U direction (default 3). |
+| `degreeV?` | `number` | Degree in V direction (default 3). |
+| `weights?` | `number[][]` | Weights grid — same dimensions as controlGrid (default: all 1.0). |
+| `knotsU?` | `number[]` | Knot vector in U direction (default: uniform clamped). |
+| `knotsV?` | `number[]` | Knot vector in V direction (default: uniform clamped). |
+| `thickness?` | `number` | Sheet thickness — if > 0, thickens the surface into a solid (default 0 = surface only). |
+| `resolution?` | `number` | Tessellation resolution — points per direction (default 32). |
+
 #### `connectEdges()` — Create a transition surface or solid bridge between two edge segments.
 
 Tangents can be inferred from neighboring geometry or supplied explicitly through `options`. This is useful for loft-like blends where you want a direct connection between two edge spans.
 
-`connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape`
+```ts
+connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
+```
 
 **`EdgeSegment`**
 
@@ -435,7 +746,7 @@ Tangents can be inferred from neighboring geometry or supplied explicitly throug
 |--------|------|-------------|
 | `profile?` | `Sketch` | Cross-section profile to sweep along the transition curve. If omitted, a circular profile with `radius` is used. |
 | `radius?` | `number` | Radius of circular cross-section (used when `profile` is omitted). Default: 5% of chord length. |
-| `up?` | `Vec3$6` | Preferred up vector for the sweep frame. Default: auto-detected. |
+| `up?` | `Vec3` | Preferred up vector for the sweep frame. Default: auto-detected. |
 | `edgeLength?` | `number` | Edge length for level-set meshing. Smaller = finer. |
 | `boundsPadding?` | `number` | Extra bounds padding for level-set meshing. |
 | `width`, `height` | | — |
@@ -448,8 +759,8 @@ Tangents can be inferred from neighboring geometry or supplied explicitly throug
 | `endB?` | `EdgeEnd` | Which end of edge B to connect. Default: 'start'. |
 | `tangentModeA?` | `TangentMode` | Tangent mode for edge A. Default: 'along'. |
 | `tangentModeB?` | `TangentMode` | Tangent mode for edge B. Default: 'along'. |
-| `tangentA?` | `Vec3$6` | Explicit tangent for edge A. |
-| `tangentB?` | `Vec3$6` | Explicit tangent for edge B. |
+| `tangentA?` | `Vec3` | Explicit tangent for edge A. |
+| `tangentB?` | `Vec3` | Explicit tangent for edge B. |
 | `flipA?` | `boolean` | Flip tangent A. |
 | `flipB?` | `boolean` | Flip tangent B. |
 
@@ -457,15 +768,17 @@ Tangents can be inferred from neighboring geometry or supplied explicitly throug
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
 
-`hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D`
+```ts
+hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
+```
 
 **`QuinticHermiteCurveEndpoint`**
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `point` | `Vec3$4` | Position |
-| `tangent` | `Vec3$4` | Tangent direction (will be normalized internally) |
-| `curvature?` | `Vec3$4` | Second derivative / curvature vector. Default [0, 0, 0]. |
+| `point` | `Vec3` | Position |
+| `tangent` | `Vec3` | Tangent direction (will be normalized internally) |
+| `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
 | `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
 
 #### `loft()` — Loft between multiple sketches along Z stations.
@@ -474,7 +787,9 @@ Profiles can differ in topology and vertex count: interpolation is done on signe
 
 Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
 
-`loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape`
+```ts
+loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
+```
 
 **`LoftOptions`**
 - `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
@@ -490,7 +805,9 @@ Internally uses variableSweep infrastructure with SDF interpolation.
 
 Performance note: uses level-set meshing, heavier than simple loft().
 
-`loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$3[], tValues: number[], options?: LoftAlongSpineOptions): Shape`
+```ts
+loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3[], tValues: number[], options?: LoftAlongSpineOptions): Shape
+```
 
 **`LoftAlongSpineOptions`**
 
@@ -499,13 +816,15 @@ Performance note: uses level-set meshing, heavier than simple loft().
 | `samples?` | `number` | Number of samples when spine is a Curve3D. Default 48. |
 | `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
-| `up?` | `Vec3$3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
+| `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
 #### `spline3d()` — Create a reusable 3D spline curve object (Catmull-Rom).
 
 The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
 
-`spline3d(points: Vec3$3[], options?: Spline3DOptions): Curve3D`
+```ts
+spline3d(points: Vec3[], options?: Spline3DOptions): Curve3D
+```
 
 **`Spline3DOptions`**
 - `closed?: boolean` — Closed loop (default false).
@@ -513,7 +832,12 @@ The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() f
 
 #### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
 
-The four curves form the boundary of a quadrilateral patch: - bottom: u=0..1 at v=0 (from corner00 to corner10) - top: u=0..1 at v=1 (from corner01 to corner11) - left: v=0..1 at u=0 (from corner00 to corner01) - right: v=0..1 at u=1 (from corner10 to corner11)
+The four curves form the boundary of a quadrilateral patch:
+
+- bottom: u=0..1 at v=0 (from corner00 to corner10)
+- top: u=0..1 at v=1 (from corner01 to corner11)
+- left: v=0..1 at u=0 (from corner00 to corner01)
+- right: v=0..1 at u=1 (from corner10 to corner11)
 
 The interior is filled using bilinear Coons patch interpolation: P(u,v) = Lc(u,v) + Ld(u,v) - B(u,v)
 
@@ -521,19 +845,19 @@ The result is a thin solid created by offsetting the surface mesh along its norm
 
 Note: curves should meet at corners. Small gaps are tolerated.
 
-`surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape`
+```ts
+surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
+```
 
 **`SurfacePatchOptions`**
 - `resolution?: number` — Number of samples along each direction. Default 24.
 - `thickness?: number` — Thickness of the generated solid. Default 0.5.
 
-#### `sweep()` — Sweep a 2D profile along a 3D path to create a solid.
-
-Path can be a Curve3D from spline3d() or an array of [x,y,z] points (polyline). The profile is interpreted in the local frame normal plane. Compatible sweeps can export through the OCCT exact route using the canonical path representation.
+#### `sweep()`
 
-Performance note: sweep uses level-set meshing internally. Prefer direct primitives/extrude/revolve when they can express the same shape.
-
-`sweep(profile: Sketch, path: Curve3D | Vec3$3[], options?: SweepOptions): Shape`
+```ts
+sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape
+```
 
 **`SweepOptions`**
 
@@ -542,7 +866,7 @@ Performance note: sweep uses level-set meshing internally. Prefer direct primiti
 | `samples?` | `number` | Number of samples when path is a Curve3D. Default 48. |
 | `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
-| `up?` | `Vec3$3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
+| `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
 #### `variableSweep()` — Sweep a variable cross-section along a 3D spine curve.
 
@@ -552,7 +876,9 @@ Each section specifies a t parameter (0 = start, 1 = end of spine) and a 2D prof
 
 Performance note: like sweep(), this uses level-set meshing internally.
 
-`variableSweep(spine: Curve3D | Vec3$3[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape`
+```ts
+variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
+```
 
 **`VariableSweepSection`**
 - `t: number` — Parameter along the spine (0 = start, 1 = end).
@@ -565,7 +891,7 @@ Performance note: like sweep(), this uses level-set meshing internally.
 | `samples?` | `number` | Number of samples when spine is a Curve3D. Default 48. |
 | `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
-| `up?` | `Vec3$3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
+| `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
 #### `transitionCurve()` — Create a smooth transition curve between two edges.
 
@@ -574,11 +900,11 @@ Returns a `HermiteCurve3D` that starts at `edgeA.point` tangent to `edgeA.tangen
 The curve maintains G1 continuity (matching tangent direction) at both endpoints. Weight parameters control the shape of the transition.
 
 ```js
-// Connect two edges with a balanced transition
-const curve = transitionCurve(
-  { point: [0, 0, 0], tangent: [1, 0, 0] },
-  { point: [10, 5, 0], tangent: [1, 0, 0] },
-);
+```js
+
+// Connect two edges with a balanced transition const curve = transitionCurve( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 0], tangent: [1, 0, 0] }, );
+
+```
 
 // Weighted: curve hugs edge A longer
 const weighted = transitionCurve(
@@ -588,24 +914,25 @@ const weighted = transitionCurve(
 );
 ```
 
-`transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D`
+```ts
+transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
+```
 
 **`TransitionEdge`**
-- `point: Vec3$6` — Connection point on the edge. Can be any point along the edge where the transition should connect.
-- `tangent: Vec3$6` — Tangent direction at the connection point. This is the direction the curve should initially follow when leaving this edge. For a straight edge, this is typically the edge direction pointing "outward" (away from the body of the edge, toward the other edge).
-- `normal?: Vec3$6` — Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector.
+- `point: Vec3` — Connection point on the edge. Can be any point along the edge where the transition should connect.
+- `tangent: Vec3` — Tangent direction at the connection point. This is the direction the curve should initially follow when leaving this edge. For a straight edge, this is typically the edge direction pointing "outward" (away from the body of the edge, toward the other edge).
+- `normal?: Vec3` — Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector.
 
 #### `transitionSurface()` — Create a solid transition surface between two edges by sweeping a profile along a Hermite transition curve.
 
 This produces a watertight solid that smoothly connects the two edges. Works with both Manifold and OCCT backends.
 
 ```js
-// Circular tube connecting two edges
-const tube = transitionSurface(
-  { point: [0, 0, 0], tangent: [1, 0, 0] },
-  { point: [10, 5, 3], tangent: [0, 1, 0] },
-  { radius: 0.5 },
-);
+```js
+
+// Circular tube connecting two edges const tube = transitionSurface( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 3], tangent: [0, 1, 0] }, { radius: 0.5 }, );
+
+```
 
 // Custom profile with weights
 const custom = transitionSurface(
@@ -615,7 +942,9 @@ const custom = transitionSurface(
 );
 ```
 
-`transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape`
+```ts
+transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+```
 
 ---
 
@@ -625,14 +954,10 @@ Select or inspect named faces and edges on a shape.
 
 #### `coalesceEdges()` — Merge collinear edge segments into longer logical edges.
 
-**Details**
-
 Tessellation often splits one geometric edge into multiple short segments. `coalesceEdges` groups adjacent collinear segments and merges each group into a single `EdgeSegment` spanning the full extent. This is usually needed before passing edges to `fillet()` or `chamfer()` on non-primitive shapes.
 
 The `tolerance` controls the maximum perpendicular distance from collinearity before two segments are considered non-collinear. Default: `0.01`.
 
-**Example**
-
 ```ts
 const topEdges = selectEdges(part, { atZ: 20 });
 for (const edge of coalesceEdges(topEdges)) {
@@ -640,7 +965,9 @@ for (const edge of coalesceEdges(topEdges)) {
 }
 ```
 
-`coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]`
+```ts
+coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
+```
 
 **`EdgeSegment`**
 
@@ -657,19 +984,17 @@ for (const edge of coalesceEdges(topEdges)) {
 
 #### `selectEdge()` — Select the single best-matching edge from a shape.
 
-**Details**
-
 When `near` is specified, returns the edge whose midpoint is closest to that point. Otherwise returns the first matching edge in mesh order. Throws if no edges match the query — useful as a guard when you expect exactly one result.
 
-**Example**
-
 ```ts
 // Chamfer one specific edge near a known point
 const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
 result = chamfer(result, 1.5, bottomEdge);
 ```
 
-`selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment`
+```ts
+selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment
+```
 
 **`EdgeQuery`**
 
@@ -693,14 +1018,10 @@ result = chamfer(result, 1.5, bottomEdge);
 
 #### `selectEdges()` — Select all edges from a shape that match the given query.
 
-**Details**
-
 Extracts sharp edges from the mesh (dihedral angle > 1°), applies all filters in the query, and returns the matching `EdgeSegment[]`. When `near` is specified the results are sorted closest-first.
 
 Works on any shape — primitives, booleans, shells, and imported meshes. Use this when tracked topology is unavailable (e.g. after a difference or on imported geometry). For simpler cases, pass an `EdgeQuery` directly to `fillet()` or `chamfer()` instead of calling `selectEdges` separately.
 
-**Example**
-
 ```ts
 // Fillet all top edges of a box
 const topEdges = selectEdges(part, { atZ: 20, perpendicular: [0, 0, 1] });
@@ -710,7 +1031,9 @@ for (const edge of coalesceEdges(topEdges)) {
 }
 ```
 
-`selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]`
+```ts
+selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+```
 
 ---
 
@@ -720,14 +1043,10 @@ Modify edges of a solid — fillets, chamfers, draft, offset.
 
 #### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
 
-**Details**
-
 Produces a 45° bevel at the specified `size` (distance from edge). Works on both straight and curved edges. Supports OCCT and Manifold backends.
 
 The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
-**Example**
-
 ```ts
 // Chamfer all edges
 chamfer(myShape, 1)
@@ -736,18 +1055,16 @@ chamfer(myShape, 1)
 chamfer(myShape, 2, { parallel: [0, 0, 1] })
 ```
 
-`chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape`
+```ts
+chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
+```
 
 #### `draft()` — Apply a draft angle (taper) to vertical faces for mold extraction.
 
-**Details**
-
 Adds a taper angle to the vertical faces of a solid so that it can be extracted from a mold. The neutral plane is the Z position where the draft angle is zero — faces above and below are tapered symmetrically. Typical values for injection molding are 1–5°.
 
 Requires the OCCT backend. Throws on Manifold.
 
-**Example**
-
 ```ts
 // Add 3° draft to a box for injection molding
 draft(myBox, 3)
@@ -756,19 +1073,21 @@ draft(myBox, 3)
 draft(myShape, 2, [0, 0, 1], 10)
 ```
 
-`draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape`
+```ts
+draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
+```
 
 #### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
 
-**Details**
-
 Works on both straight and curved edges. Supports OCCT and Manifold backends. When using OCCT, all edges are filleted in a single kernel operation for best quality. When using Manifold, edges are filleted sequentially.
 
-The `edges` parameter is flexible: - Omit to fillet **all** sharp edges - Pass an `EdgeQuery` for an inline filter (most common) - Pass an `EdgeSegment` or `EdgeSegment[]` from `selectEdges()` for pre-selected edges
+The `edges` parameter is flexible:
 
-Throws if no edges match the selection, or if `radius` is not a positive finite number.
+- Omit to fillet **all** sharp edges
+- Pass an `EdgeQuery` for an inline filter (most common)
+- Pass an `EdgeSegment` or `EdgeSegment[]` from `selectEdges()` for pre-selected edges
 
-**Example**
+Throws if no edges match the selection, or if `radius` is not a positive finite number.
 
 ```ts
 // Fillet all edges
@@ -782,18 +1101,16 @@ const edges = selectEdges(myShape, { parallel: [0, 0, 1] })
 fillet(myShape, 3, edges)
 ```
 
-`fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape`
+```ts
+fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
+```
 
 #### `offsetSolid()` — Uniformly offset all surfaces of a solid inward or outward.
 
-**Details**
-
 Unlike `shell()`, which hollows a solid by removing one face, `offsetSolid()` produces a new solid whose every surface is shifted by `thickness`. Positive values grow the shape outward; negative values shrink it inward.
 
 Requires the OCCT backend. Throws on Manifold.
 
-**Example**
-
 ```ts
 // Grow a box outward by 1mm on all sides
 offsetSolid(myBox, 1)
@@ -802,22 +1119,22 @@ offsetSolid(myBox, 1)
 offsetSolid(myShape, -0.5)
 ```
 
-`offsetSolid(shape: Shape, thickness: number): Shape`
+```ts
+offsetSolid(shape: Shape, thickness: number): Shape
+```
 
 #### `chamfer2d()` — Bevel a named vertical edge of a shape with a 45° chamfer.
 
-**Details**
-
 Compiler-owned chamfer for tracked vertical edges. Requires a compile-plan-covered target. Supported subset and quadrant semantics are the same as `fillet2d()` — see that function for details.
 
-**Example**
-
 ```ts
 const b = rectangle(0, 0, 50, 50).extrude(20);
 const chamfered = chamfer2d(b.toShape(), b.edge('vert-br'), 3, [-1, -1]);
 ```
 
-`chamfer2d(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape`
+```ts
+chamfer2d(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape
+```
 
 **`EdgeRef`**
 - `query?: EdgeQueryRef` — Compiler-owned edge query when available.
@@ -825,36 +1142,38 @@ const chamfered = chamfer2d(b.toShape(), b.edge('vert-br'), 3, [-1, -1]);
 
 #### `fillet2d()` — Round a named vertical edge of a shape with a circular fillet.
 
-**Details**
-
 Compiler-owned fillet for tracked vertical edges. Requires a compile-plan-covered target (shapes from `box()`, `rectangle().extrude()`, or rigid transforms of those).
 
-**Supported edges:** - Tracked vertical edges from `box()` or `rectangle().extrude()` - Rigid transforms between tracked source and target - Untouched sibling tracked vertical edges after earlier `fillet2d`/`chamfer2d`
+**Supported edges:**
+
+- Tracked vertical edges from `box()` or `rectangle().extrude()`
+- Rigid transforms between tracked source and target
+- Untouched sibling tracked vertical edges after earlier `fillet2d`/`chamfer2d`
 
 **Not supported:** edges after shell, hole, cut, trim, difference, intersection, generic sketch extrudes, or tapered extrudes. Use `fillet()` with an `EdgeQuery` for those cases.
 
 Canonical quadrants: `vert-bl → [1,-1]`, `vert-br → [-1,-1]`, `vert-tr → [-1,1]`, `vert-tl → [1,1]`
 
-**Example**
-
 ```ts
 const b = rectangle(0, 0, 50, 50).extrude(20);
 const filleted = fillet2d(b.toShape(), b.edge('vert-br'), 5, [-1, -1]);
 ```
 
-`fillet2d(shape: Shape, edge: EdgeRef, radius: number, quadrant?: [ number, number ], segments?: number): Shape`
+```ts
+fillet2d(shape: Shape, edge: EdgeRef, radius: number, quadrant?: [ number, number ], segments?: number): Shape
+```
 
 #### `filletCorners()` — Create a polygon from points with specific corners rounded to arc fillets.
 
-**Details**
-
 Each corner spec identifies a vertex by its index in the `points` array and the desired fillet `radius`. Both convex and concave corners are supported.
 
-Constraints: - Collinear corners cannot be filleted (throws an error) - Two neighboring fillets whose tangent lengths overlap the same edge will throw - Radius must be positive and small enough to fit within the adjacent edge lengths
+Constraints:
 
-Use `offset(-r).offset(+r)` instead if you want to round **all** convex corners uniformly. Use `filletCorners` when you need selective or mixed sharp/rounded profiles.
+- Collinear corners cannot be filleted (throws an error)
+- Two neighboring fillets whose tangent lengths overlap the same edge will throw
+- Radius must be positive and small enough to fit within the adjacent edge lengths
 
-**Example**
+Use `offset(-r).offset(+r)` instead if you want to round **all** convex corners uniformly. Use `filletCorners` when you need selective or mixed sharp/rounded profiles.
 
 ```ts
 const roof = filletCorners(roofPoints, [
@@ -864,7 +1183,9 @@ const roof = filletCorners(roofPoints, [
 ]);
 ```
 
-`filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch`
+```ts
+filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
+```
 
 `FilletCornerSpec`: `{ index: number, radius: number, segments?: number }`
 
@@ -891,7 +1212,9 @@ for (const {x, y} of circularLayout(12, r)) {
 }
 ```
 
-`circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]`
+```ts
+circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
+```
 
 **`CircularLayoutOptions`**
 - `startDeg?: number` — Angle of the first element in degrees (default: 0 = +X axis).
@@ -902,13 +1225,12 @@ for (const {x, y} of circularLayout(12, r)) {
 
 #### `circularPattern()` — Repeat a shape in a circular pattern around an axis and union the copies.
 
-**Details**
-
 Distributes `count` copies evenly around the rotation axis (360° / count per step). All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy — post-merge face identity via owner-scoped canonical queries still works for pattern descendants.
 
-Two calling conventions: - **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)` - **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
+Two calling conventions:
 
-**Example**
+- **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)`
+- **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
 
 ```ts
 // 8 holes evenly spaced around origin
@@ -918,7 +1240,9 @@ circularPattern(cylinder(12, 4).translate(30, 0, -1), 8)
 circularPattern(myFeature, 4, { axis: [1, 0, 0], origin: [0, 0, 50] })
 ```
 
-`circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape`
+```ts
+circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
+```
 
 **`CircularPatternOptions`**
 - `centerX?: number` — Center X of the rotation (default: 0). Used when axis is Z (legacy mode).
@@ -926,41 +1250,41 @@ circularPattern(myFeature, 4, { axis: [1, 0, 0], origin: [0, 0, 50] })
 
 #### `circularPattern2d()` — Repeat a 2D sketch in a circular pattern around a center point and union the copies.
 
-`circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch`
+```ts
+circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
+```
 
 #### `linearPattern()` — Repeat a shape in a linear pattern along a direction vector and union the copies.
 
-**Details**
-
 Creates `count` copies of `shape`, each offset by `(dx*i, dy*i, dz*i)` from the original. All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy so face identity via owner-scoped canonical queries still works post-merge.
 
-**Example**
-
 ```ts
 // 5 cylinders, 20mm apart along X
 linearPattern(cylinder(10, 3), 5, 20, 0)
 ```
 
-`linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape`
+```ts
+linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
+```
 
 #### `linearPattern2d()` — Repeat a 2D sketch in a linear pattern and union the copies.
 
-`linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch`
+```ts
+linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+```
 
 #### `mirrorCopy()` — Mirror a shape across a plane and union the mirror with the original.
 
-**Details**
-
 The mirror plane passes through the origin and is defined by its normal vector. The mirrored copy is unioned with the original to produce a single symmetric Shape.
 
-**Example**
-
 ```ts
 // Mirror across the YZ plane (X=0)
 mirrorCopy(box(50, 30, 10), [1, 0, 0])
 ```
 
-`mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape`
+```ts
+mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+```
 
 ---
 
@@ -968,14 +1292,72 @@ mirrorCopy(box(50, 30, 10), [1, 0, 0])
 
 Define geometry by relationships and let a solver find positions.
 
+#### `Constraint.makeParallel()` — Constrain two lines to be parallel.
+
+```ts
+Constraint.makeParallel(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.enforceAngle()` — Constrain the signed angle from line `a` to line `b`.
+
+```ts
+Constraint.enforceAngle(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg, angleDeg: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.horizontal()` — Constrain a line to be horizontal.
+
+```ts
+Constraint.horizontal(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.vertical()` — Constrain a line to be vertical.
+
+```ts
+Constraint.vertical(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.equalLength()` — Constrain two lines to have equal length.
+
+```ts
+Constraint.equalLength(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.distance()` — Constrain the distance between two points.
+
+```ts
+Constraint.distance(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg, value: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.fix()` — Fix a point at a specific coordinate.
+
+```ts
+Constraint.fix(builder: ConstrainedSketchBuilder, pt: PointArg, x: number, y: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.coincident()` — Constrain two points to occupy the same location.
+
+```ts
+Constraint.coincident(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.perpendicular()` — Constrain two lines to be perpendicular.
+
+```ts
+Constraint.perpendicular(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.length()` — Constrain the length of a line.
+
+```ts
+Constraint.length(builder: ConstrainedSketchBuilder, line: LineArg, value: number): ConstrainedSketchBuilder
+```
+
 #### `addPolygon()` — Add a general polygon concept to the builder.
 
 Creates n vertices and n sides (CCW: `sides[i]` from `vertices[i]` → `vertices[(i+1) % n]`). Applies a `ccw` constraint to enforce winding. All dimensional constraints (lengths, angles, position) are left to the caller.
 
 Use `sk.addPolygon()` as the shorthand builder method.
 
-**Example**
-
 ```ts
 const sk = constrainedSketch();
 const tri = sk.addPolygon({ points: [[0,0],[100,0],[50,80]] });
@@ -984,7 +1366,9 @@ sk.length(tri.side(0), 100);
 return sk.solve().extrude(5);
 ```
 
-`addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon`
+```ts
+addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon
+```
 
 **`PolygonOptions`**
 - `addLoop?: boolean` — Whether to register a closed loop for sketch generation. Default: true.
@@ -1001,8 +1385,6 @@ Creates 4 vertices (CCW: bl→br→tr→tl), 4 sides, 4 structural constraints (
 
 Use `sk.rect()` as the shorthand builder method.
 
-**Example**
-
 ```ts
 const sk = constrainedSketch();
 const r = sk.rect({ x: 0, y: 0, width: 100, height: 50 });
@@ -1011,7 +1393,9 @@ sk.length(r.bottom, 120);  // override initial width
 return sk.solve().extrude(10);
 ```
 
-`addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect`
+```ts
+addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect
+```
 
 **`RectOptions`**
 
@@ -1041,8 +1425,6 @@ Vertices are placed at `(cx + r·cos(startAngle + i·2π/n), cy + r·sin(...))`.
 
 Use `sk.regularPolygon()` as the shorthand builder method.
 
-**Example**
-
 ```ts
 const sk = constrainedSketch();
 const hex = sk.regularPolygon({ sides: 6, radius: 25 });
@@ -1051,7 +1433,9 @@ sk.length(hex.side(0), 30);  // all sides change (equal constraint)
 return sk.solve().extrude(5);
 ```
 
-`addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon`
+```ts
+addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon
+```
 
 **`RegularPolygonOptions`**
 
@@ -1070,8 +1454,6 @@ return sk.solve().extrude(5);
 
 #### `circle()` — Create an analytic 2D circle for measurement, construction, and extrusion.
 
-**Example**
-
 ```ts
 const c = circle(0, 0, 25);
 c.diameter; c.circumference; c.area;
@@ -1085,15 +1467,18 @@ cyl.face('side');  // FaceRef (curved)
 Circle2D.fromDiameter(point(0, 0), 50);
 ```
 
-`circle(cx: number, cy: number, radius: number): Circle2D`
+```ts
+circle(cx: number, cy: number, radius: number): Circle2D
+```
 
 #### `constrainedSketch()` — Create a parametric 2D sketch driven by geometric constraints and a nonlinear solver.
 
 **Workflow**
 
-1. Create a builder with `constrainedSketch()`. 2. Add geometry — points, lines, circles, arcs — using the builder methods. 3. Add constraints (`horizontal`, `length`, `fix`, etc.) to drive the geometry. 4. Call `.solve()` to run the solver and get a `ConstraintSketch` (which extends `Sketch`).
-
-**Example**
+1. Create a builder with `constrainedSketch()`.
+2. Add geometry — points, lines, circles, arcs — using the builder methods.
+3. Add constraints (`horizontal`, `length`, `fix`, etc.) to drive the geometry.
+4. Call `.solve()` to run the solver and get a `ConstraintSketch` (which extends `Sketch`).
 
 ```ts
 const sk = constrainedSketch();
@@ -1117,15 +1502,15 @@ result.inspect();               // human-readable summary
 result.withUpdatedConstraint('cst-5', 120); // update a dimension without rebuilding
 ```
 
-`constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder`
+```ts
+constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder
+```
 
 **`ConstrainedSketchOptions`**
 - `strict?: boolean` — When true, adding a constraint that cannot be satisfied throws instead of silently discarding it.
 
 #### `line()` — Create an analytic 2D line segment between two points.
 
-**Example**
-
 ```ts
 const l = line(0, 0, 50, 0);
 l.length; l.midpoint; l.angle; l.direction;
@@ -1137,12 +1522,12 @@ Line2D.fromPointAndAngle(point(0, 0), 45, 100);
 Line2D.fromPointAndDirection(point(0, 0), [1, 1], 50);
 ```
 
-`line(x1: number, y1: number, x2: number, y2: number): Line2D`
+```ts
+line(x1: number, y1: number, x2: number, y2: number): Line2D
+```
 
 #### `point()` — Create an analytic 2D point for measurement and construction geometry.
 
-**Example**
-
 ```ts
 const p = point(10, 20);
 p.distanceTo(point(30, 40));  // Euclidean distance
@@ -1151,15 +1536,52 @@ p.translate(5, 5);           // new shifted point
 p.toTuple();                 // [10, 20]
 ```
 
-`point(x: number, y: number): Point2D`
+```ts
+point(x: number, y: number): Point2D
+```
 
 ---
 
-## C9: Spatial Placement
+## C9: Spatial Placement
+
+Position geometry relative to other geometry using semantic anchors.
+
+
+#### `Points.distance()` — Euclidean distance between two 3D points.
+
+```ts
+Points.readonly distance: typeof distance
+```
+
+#### `Points.midpoint()` — Center point between two 3D points.
+
+```ts
+Points.readonly midpoint: typeof midpoint
+```
+
+#### `Points.lerp()` — Linearly interpolate between two 3D points. t=0 returns a, t=1 returns b.
+
+```ts
+Points.readonly lerp: typeof lerp
+```
+
+#### `Points.direction()` — Unit direction vector from a to b. Throws if a and b are the same point.
+
+```ts
+Points.readonly direction: typeof direction
+```
+
+#### `Points.offset()` — Move a point along a direction vector by a given amount.
+
+```ts
+Points.readonly offset: typeof offset
+```
 
-Position geometry relative to other geometry using semantic anchors.
+#### `Points.polar()` — Compute a 2D point at distance and angle (degrees) from an optional origin.
 
-*No free functions — see class methods (Shape, Sketch, ConstrainedSketchBuilder).*
+```ts
+Points.readonly polar: typeof polar
+```
 
 ---
 
@@ -1169,7 +1591,7 @@ Compose parts with joints for kinematic simulation.
 
 #### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
-**Details**
+**Use this from iteration 1 for any model with moving parts.** Hinges, sliders, gears, articulated fingers, doors — all start with `assembly()`, not with manual rotation math. Don't build a static "extended pose" first and refactor to an assembly later: joint sliders, animations, sweeps, collision detection, and robot export all flow from the kinematic graph.
 
 An assembly models a mechanism as a directed graph of parts connected by joints. Parts are the nodes; joints are directed edges from parent to child. The graph must be a forest (no cycles). Root parts (those with no incoming joint) are anchored to world space.
 
@@ -1179,8 +1601,6 @@ The higher-level `connect()` API uses declared **connectors** to compute joint f
 
 For multi-file assemblies, a file that returns an `Assembly` is importable via `require()` and yields an `ImportedAssembly`. Use `mergeInto()` to flatten a sub-assembly into a parent assembly.
 
-**Example**
-
 ```ts
 const mech = assembly("Arm")
   .addPart("base", box(80, 80, 20, true), {
@@ -1196,15 +1616,17 @@ const mech = assembly("Arm")
 return mech; // auto-solved at defaults, renders all parts
 ```
 
-`assembly(name?: string): Assembly`
+```ts
+assembly(name?: string): Assembly
+```
 
 #### `bomToCsv()` — Convert an array of BOM rows into a CSV string.
 
-**Details**
-
 Produces a CSV with columns: `part`, `qty`, `material`, `process`, `tolerance`, `notes`. String values are quoted and internal double-quotes are escaped. Prefer calling `solvedAssembly.bomCsv()` directly — this function is exposed for custom BOM processing.
 
-`bomToCsv(rows: BomRow[]): string`
+```ts
+bomToCsv(rows: BomRow[]): string
+```
 
 **`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
 
@@ -1212,12 +1634,8 @@ Produces a CSV with columns: `part`, `qty`, `material`, `process`, `tolerance`,
 
 #### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
 
-**Details**
-
 This is a convenience wrapper for single-shape, single-joint use cases. It calls `param()` to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
 
-**Example**
-
 ```ts
 const arm = joint("Shoulder", armShape, [0, 0, 20], {
   axis: [0, 1, 0],
@@ -1226,14 +1644,14 @@ const arm = joint("Shoulder", armShape, [0, 0, 20], {
 return arm;
 ```
 
-`joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape`
+```ts
+joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
+```
 
 `RevoluteJointOpts`: `{ min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
 
 #### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
 
-**Details**
-
 Defines joints (revolute or prismatic), optional gear/rack couplings, and named animations. The viewport resolves transforms through the joint chain at display time — the script geometry is computed only once at rest pose.
 
 **Critical:** Solve the assembly at **rest pose** (all animated joints = 0). The viewport applies `jointsView` transforms on top of the returned scene. If geometry is already solved at non-zero angles, animation will double-rotate everything.
@@ -1280,8 +1698,6 @@ keyframes: [
 
 Mixing explicit `at` and omitted `at` in the same animation is not allowed.
 
-**Example**
-
 ```js
 jointsView({
   joints: [{
@@ -1300,7 +1716,9 @@ jointsView({
 });
 ```
 
-`jointsView(options?: JointsViewOptions): void`
+```ts
+jointsView(options?: JointsViewOptions): void
+```
 
 **`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
 
@@ -1323,112 +1741,140 @@ jointsView({
 
 Declare user-facing controls that drive model geometry.
 
-#### `boolParam()` — Declare a boolean parameter that renders as a checkbox in the UI.
+#### `Param.number()` — Declare a numeric parameter that renders as a slider in the UI.
 
-**Details**
+Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
 
-Internally stored as `0`/`1`. When overriding from CLI or `require()`, pass `1` for true and `0` for false. The `name` string is the override key.
+Default range rules when options are omitted:
+
+- `min` defaults to `0`
+- `max` defaults to `defaultValue * 4`
+- `step` is auto-calculated: `1` for integer params, `0.1` for ranges ≤ 100, `1` for larger ranges
 
-**Example**
+The `unit` option is cosmetic only — no conversion is performed. Use `integer: true` for counts, sides, quantities (rounds to whole numbers; step defaults to `1`).
 
 ```ts
-const showHoles = boolParam("Show Holes", true);
-if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
-return plate;
+const width = Param.number("Width", 50);
+const angle = Param.number("Angle", 45, { min: 0, max: 180, unit: "°" });
+const sides = Param.number("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-Override via import:
+**Parameter overrides** — key must match `name` exactly:
 
 ```ts
-const pan = require("./pan.forge.js", { "Show Lid": 0 });
+// Via require()
+const bracket = require("./bracket.forge.js", { Width: 80 });
+
+// Via CLI
+// forgecad run model.forge.js --param "Wall Thickness=3"
 ```
 
-`boolParam(name: string, defaultValue: boolean): boolean`
+Also available as the shorthand alias `param()`.
 
-#### `choiceParam()` — Declare a choice parameter that renders as a dropdown in the UI.
+```ts
+Param.number(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
+```
 
-**Details**
+#### `Param.string()` — Declare a string parameter that renders as a text input in the UI.
 
-`defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `choiceParam` over `param` when a slider would hide intent — named choices like `"wok"` are self-describing.
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
 
-Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
+```ts
+const label = Param.string("Label", "Hello World");
+const name  = Param.string("Name", "Part-001", { maxLength: 20 });
+```
 
-**Example**
+Override via import:
 
 ```ts
-const panStyle = choiceParam("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
-if (panStyle === "wok") return buildWok();
+const tag = require("./tag.forge.js", { Label: "Custom Text" });
 ```
 
-Override via import:
+Only available as `Param.string()` — no standalone alias.
 
 ```ts
-const pan = require("./pan.forge.js", { "Pan Style": "wok" });
+Param.string(name: string, defaultValue: string, opts?: { maxLength?: number; }): string
 ```
 
-Override via CLI:
+#### `Param.bool()` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-```bash
-forgecad run model.forge.js --param "Pan Style=wok"
+Internally stored as `0`/`1`. When overriding from CLI or `require()`, pass `1` for true and `0` for false. The `name` string is the override key.
+
+```ts
+const showHoles = Param.bool("Show Holes", true);
+if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
+return plate;
 ```
 
-`choiceParam(name: string, defaultValue: string, choices: string[]): string`
+Override via import:
 
-#### `listParam()` — Declare a list parameter — an array of struct items with per-field UI controls.
+```ts
+const pan = require("./pan.forge.js", { "Show Lid": 0 });
+```
 
-**Details**
+Also available as the shorthand alias `boolParam()`.
 
-Each item in the list is a struct whose fields each render as their own control (slider, checkbox, or dropdown). The user can add/remove rows up to `minItems`/`maxItems` bounds.
+```ts
+Param.bool(name: string, defaultValue: boolean): boolean
+```
 
-Field types: - Boolean fields (`boolean: true` in field defs) return as `boolean` - Choice fields (`choices: [...]` in field defs) return as `string` - All other fields return as `number`
+#### `Param.choice()` — Declare a choice parameter that renders as a dropdown in the UI.
 
-`listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]`
+`defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `Param.choice` over `Param.number` when a slider would hide intent — named choices like `"wok"` are self-describing.
 
-`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
+Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
 
-#### `param()` — Declare a numeric parameter that renders as a slider in the UI.
+```ts
+const panStyle = Param.choice("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
+if (panStyle === "wok") return buildWok();
+```
 
-**Details**
+Override via import:
 
-Each `param()` call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+```ts
+const pan = require("./pan.forge.js", { "Pan Style": "wok" });
+```
 
-Default range rules when options are omitted: - `min` defaults to `0` - `max` defaults to `defaultValue * 4` - `step` is auto-calculated: `1` for integer params, `0.1` for ranges ≤ 100, `1` for larger ranges
+Override via CLI:
 
-The `unit` option is cosmetic only — no conversion is performed. Use `integer: true` for counts, sides, quantities (rounds to whole numbers; step defaults to `1`).
+```bash
+forgecad run model.forge.js --param "Pan Style=wok"
+```
 
-**Example**
+Also available as the shorthand alias `choiceParam()`.
 
 ```ts
-const width = param("Width", 50);
-const angle = param("Angle", 45, { min: 0, max: 180, unit: "°" });
-const sides = param("Sides", 6, { min: 3, max: 12, integer: true });
+Param.choice(name: string, defaultValue: string, choices: string[]): string
 ```
 
-**Parameter overrides** — key must match `name` exactly:
+#### `Param.list()` — Declare a list parameter — an array of struct items with per-field UI controls.
 
-```ts
-// Via require()
-const bracket = require("./bracket.forge.js", { Width: 80 });
+Each item in the list is a struct whose fields each render as their own control (slider, checkbox, or dropdown). The user can add/remove rows up to `minItems`/`maxItems` bounds.
 
-// Via CLI
-// forgecad run model.forge.js --param "Wall Thickness=3"
+Field types:
+
+- Boolean fields (`boolean: true` in field defs) return as `boolean`
+- Choice fields (`choices: [...]` in field defs) return as `string`
+- All other fields return as `number`
+
+```ts
+Param.list<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
 ```
 
-`param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number`
+`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
 
 #### `dim()` — Add a dimension annotation between two points.
 
-**Details**
-
 Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
 
 Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or `Point2D` objects (Z is treated as 0 for 2D inputs).
 
 **Ownership Rules (Report Pages)**
 
-- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts. - `component: "Part Name"` — route dimension to another named returned object. - Multiple owners: dimension is shared and appears on the assembly overview page. - No ownership set: report export infers ownership via endpoint-in-bbox.
-
-**Example**
+- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
+- `component: "Part Name"` — route dimension to another named returned object.
+- Multiple owners: dimension is shared and appears on the assembly overview page.
+- No ownership set: report export infers ownership via endpoint-in-bbox.
 
 ```ts
 dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
@@ -1438,25 +1884,25 @@ dim([0, 0, 0], [100, 0, 0], { component: "Base", color: "#00AAFF" });
 
 `component` (string or string[] — report ownership), `currentComponent` (boolean)
 
-`dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void`
+```ts
+dim(from: PointArg, to: PointArg, opts?: DimOpts): void
+```
 
 `DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
 
 #### `dimLine()` — Add a dimension annotation along a `Line2D`.
 
-**Details**
-
 Convenience wrapper around { points from a constrained-sketch `Line2D` entity. All `opts` are forwarded unchanged.
 
-**Example**
-
 ```ts
 const a = point(0, 0);
 const b = point(100, 0);
 dimLine(line(a, b), { label: "Span", offset: -8 });
 ```
 
-`dimLine(l: Line2D, opts?: DimOpts): void`
+```ts
+dimLine(l: Line2D, opts?: DimOpts): void
+```
 
 ---
 
@@ -1468,15 +1914,21 @@ Extract 2D geometry from a 3D solid (section, projection).
 
 The result is returned in the face's local 2D coordinate system, making it convenient for offsets, pocket profiles, or follow-up sketch operations driven by an existing face.
 
-`faceProfile(shape: Shape, face: FaceSelector): Sketch`
+```ts
+faceProfile(shape: Shape, face: FaceSelector): Sketch
+```
 
 #### `intersectWithPlane()` — Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
 
-`intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch`
+```ts
+intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch
+```
 
 #### `projectToPlane()` — Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
 
-`projectToPlane(shape: Shape, plane: PlaneSpec): Sketch`
+```ts
+projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
+```
 
 ---
 
@@ -1486,13 +1938,11 @@ Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF).
 
 #### `bom()` — Register a Bill of Materials entry for report export.
 
-**Details**
-
 BOM entries are accumulated during script execution and exported alongside the model in report views. Rows are grouped by normalized `description + unit`. Pass an explicit `key` to force multiple descriptions to collapse into a single line item.
 
-- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts). - `unit` defaults to `"pieces"` when omitted or empty. - The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
-
-**Example**
+- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts).
+- `unit` defaults to `"pieces"` when omitted or empty.
+- The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
 
 ```ts
 const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
@@ -1501,27 +1951,54 @@ const boltCount = param("Bolt Count", 16, { min: 0, max: 200, integer: true });
 bom(tubeLen, "iron tube 30 x 20", { unit: "mm" });
 bom(boltCount, "M4 bolt, 16 mm length");
 bom(4, "rubber foot", { key: "foot-rubber" }); // explicit aggregation key
+
+// Structured metadata for richer reports:
+bom(tubeLen, "rectangular steel tube", {
+  unit: "mm",
+  material: "steel",
+  section: [30, 20],
+  wall: 3,
+});
 ```
 
-`bom(quantity: number, description: string, opts?: BomOpts): void`
+```ts
+bom(quantity: number, description: string, opts?: BomOpts): void
+```
 
 **`BomOpts`**
-- `unit?: string` — Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces"
-- `key?: string` — Optional explicit grouping key used during report aggregation.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `unit?` | `string` | Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" |
+| `key?` | `string` | Optional explicit grouping key used during report aggregation. |
+| `material?` | `string` | Material name, e.g. "steel", "birch plywood", "nylon" |
+| `dimensions?` | `number[]` | Overall dimensions `[width, height]` or `[width, height, thickness]` in the entry's unit |
+| `section?` | `number[]` | Cross-section dimensions `[w, h]` for tubes and profiles |
+| `wall?` | `number` | Wall thickness for hollow sections (mm) |
+| `diameter?` | `number` | Diameter for round stock, bolts, dowels (mm) |
+| `length?` | `number` | Length for fasteners (mm) |
+| `process?` | `string` | Manufacturing process, e.g. "laser cut", "CNC", "welded" |
+| `notes?` | `string` | Free-form notes |
+| `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
 #### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
 
-**Details**
+Call `robotExport()` alongside your assembly definition. The CLI commands `forgecad export sdf` and `forgecad export urdf` pick up the declaration and produce a robot package with:
 
-Call `robotExport()` alongside your assembly definition. The CLI commands `forgecad export sdf` and `forgecad export urdf` pick up the declaration and produce a robot package with: - Mesh-based inertia tensors (full 6-component, not bounding-box approximations) - Separate collision meshes (convex hull by default — ~50–80% smaller) - Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
+- Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
+- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
 
 **Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
 | Mode | Description | Default | |------|-------------|---------| | `'convex'` | Convex hull (separate `_collision.stl`) | Yes | | `'box'` | AABB primitive — fastest physics | | | `'visual'` | Same mesh as visual — exact but slow | | | `'none'` | No collision geometry | |
 
-**Unit conventions:** - Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s. - Prismatic distances are in mm in Forge; exported in meters. - `massKg` is preferred; `densityKgM3` is used when mass is unknown. - Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
+**Unit conventions:**
 
-**Example**
+- Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
+- Prismatic distances are in mm in Forge; exported in meters.
+- `massKg` is preferred; `densityKgM3` is used when mass is unknown.
+- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```ts
 const rover = assembly("Scout")
@@ -1557,7 +2034,9 @@ forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
 forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
 ```
 
-`robotExport(options: RobotExportOptions): CollectedRobotExport`
+```ts
+robotExport(options: RobotExportOptions): CollectedRobotExport
+```
 
 **`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world?: RobotWorldOptions`
 
@@ -1589,15 +2068,16 @@ forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
 
 #### `sheetMetal()` — Create a parametric sheet metal part with flanges, bend allowances, and flat-pattern unfolding.
 
-**Details**
-
 `sheetMetal()` keeps one semantic model and derives both a folded 3D solid and an accurate flat pattern from it. The K-factor bend allowance is applied during unfolding. This is a strict v1 subset — it does not infer sheet metal from arbitrary solids.
 
-**Recommended authoring order:** 1. Define the base panel + thickness + bend parameters. 2. Chain `.flange()` calls for each edge. Validate with `.folded()` and `.flatPattern()` before adding cutouts. 3. Add panel cutouts, then flange cutouts one region at a time. 4. Validate after each new cutout region.
+**Recommended authoring order:**
 
-**v1 limitations:** one base panel, up to four 90° edge flanges, constant thickness, explicit K-factor, rectangular corner reliefs, planar cutouts only. No hems, jogs, lofted bends, non-90° flanges, or bend-region cutouts.
+1. Define the base panel + thickness + bend parameters.
+2. Chain `.flange()` calls for each edge. Validate with `.folded()` and `.flatPattern()` before adding cutouts.
+3. Add panel cutouts, then flange cutouts one region at a time.
+4. Validate after each new cutout region.
 
-**Example**
+**v1 limitations:** one base panel, up to four 90° edge flanges, constant thickness, explicit K-factor, rectangular corner reliefs, planar cutouts only. No hems, jogs, lofted bends, non-90° flanges, or bend-region cutouts.
 
 ```ts
 const cover = sheetMetal({
@@ -1618,7 +2098,9 @@ const folded = cover.folded();
 const flat   = cover.flatPattern();
 ```
 
-`sheetMetal(options: SheetMetalOptions): SheetMetalPart`
+```ts
+sheetMetal(options: SheetMetalOptions): SheetMetalPart
+```
 
 **`SheetMetalOptions`**
 
@@ -1634,20 +2116,18 @@ const flat   = cover.flatPattern();
 
 #### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
-**Details**
-
 For regular sketches, each polygon loop becomes a closed `LWPOLYLINE`. For constrained sketches, exports raw `LINE`, `CIRCLE`, and `ARC` entities from the constraint edge geometry, which preserves internal/shared edges that `toPolygons()` would merge away.
 
 The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
 
-**Example**
-
 ```ts
 const s = rect(100, 60);
 const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-`sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string`
+```ts
+sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
+```
 
 **`SketchDxfOptions`**
 - `layer?: string` — DXF layer name. Default: "0"
@@ -1655,20 +2135,18 @@ const dxf = sketchToDxf(s, { layer: 'cut' });
 
 #### `sketchToSvg()` — Export a 2D sketch as an SVG string.
 
-**Details**
-
 For regular sketches, exports filled polygon regions. For constrained sketches, exports raw edge geometry (LINE, ARC, CIRCLE) which preserves internal/shared edges that `toPolygons()` would merge away.
 
 The SVG uses the sketch's native coordinate system (Y-up) with a CSS transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
 
-**Example**
-
 ```ts
 const s = rect(100, 60);
 const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
 ```
 
-`sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string`
+```ts
+sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
+```
 
 **`SketchSvgOptions`**
 
@@ -1686,9 +2164,121 @@ const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
 
 Control viewport appearance and debugging aids.
 
-#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
+#### `verify.that()` — Custom predicate check.
+
+```ts
+verify.that(label: string, check: () => boolean, message?: string): void
+```
+
+#### `verify.equal()` — Check that two numbers are approximately equal (within tolerance).
+
+```ts
+verify.equal(label: string, actual: number, expected: number, tolerance?: number, message?: string): void
+```
 
-**Details**
+#### `verify.notEqual()` — Check that two numbers are NOT equal (differ by more than tolerance).
+
+```ts
+verify.notEqual(label: string, actual: number, unexpected: number, tolerance?: number, message?: string): void
+```
+
+#### `verify.greaterThan()` — Check that actual > min.
+
+```ts
+verify.greaterThan(label: string, actual: number, min: number, message?: string): void
+```
+
+#### `verify.lessThan()` — Check that actual < max.
+
+```ts
+verify.lessThan(label: string, actual: number, max: number, message?: string): void
+```
+
+#### `verify.inRange()` — Check that min <= actual <= max.
+
+```ts
+verify.inRange(label: string, actual: number, min: number, max: number, message?: string): void
+```
+
+#### `verify.centersCoincide()` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
+
+```ts
+verify.centersCoincide(label: string, a: ShapeLike, b: ShapeLike, tolerance?: number): void
+```
+
+#### `verify.notColliding()` — Check that two shapes do not collide (minGap > 0).
+
+```ts
+verify.notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: number): void
+```
+
+#### `verify.minClearance()` — Check that a minimum clearance gap exists between two shapes.
+
+```ts
+verify.minClearance(label: string, a: ShapeLike, b: ShapeLike, minGap: number, searchLength?: number): void
+```
+
+#### `verify.parallel()` — Check that two face normals are parallel (within toleranceDeg degrees).
+
+```ts
+verify.parallel(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+#### `verify.perpendicular()` — Check that two face normals are perpendicular (within toleranceDeg degrees).
+
+```ts
+verify.perpendicular(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+#### `verify.coplanar()` — Check that a face is coplanar with (same plane as) another face, meaning they are parallel AND their centers lie on the same plane.
+
+```ts
+verify.coplanar(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number, toleranceMm?: number): void
+```
+
+#### `verify.faceAt()` — Check that a face center lies at a specific position (within toleranceMm).
+
+```ts
+verify.faceAt(label: string, face: FaceRefLike, expectedPos: [ number
+```
+
+#### `verify.sameDirection()` — Check that two face normals point in the same direction (not antiparallel). Stricter than parallel — both |angle| AND sign must match.
+
+```ts
+verify.sameDirection(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+#### `verify.isEmpty()` — Check that a shape is empty.
+
+```ts
+verify.isEmpty(label: string, shape: ShapeLike, message?: string): void
+```
+
+#### `verify.notEmpty()` — Check that a shape is NOT empty.
+
+```ts
+verify.notEmpty(label: string, shape: ShapeLike, message?: string): void
+```
+
+#### `verify.volumeApprox()` — Check that a shape's volume is approximately equal to expected (mm³).
+
+```ts
+verify.volumeApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
+```
+
+#### `verify.areaApprox()` — Check that a shape's surface area is approximately equal to expected (mm²).
+
+```ts
+verify.areaApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
+```
+
+#### `verify.boundingBoxSize()` — Check that a shape's bounding box has approximately the given size.
+
+```ts
+verify.boundingBoxSize(label: string, shape: ShapeLike, expectedSize: [ number
+```
+
+#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
 
 Offsets are resolved from the returned object tree, not a flat list. In `radial` mode each node follows its parent branch direction, then fans locally from the immediate parent center — nested assemblies peel apart level by level. In fixed-axis or fixed-vector modes, the branch follows that axis/vector but nested descendants fan out perpendicular by default.
 
@@ -1696,8 +2286,6 @@ Multiple calls merge — later values override earlier ones on a per-key basis.
 
 For programmatic explode applied before returning (without the slider), use `lib.explode()` instead.
 
-**Example**
-
 ```js
 explodeView({
   amountScale: 1.2,
@@ -1707,7 +2295,9 @@ explodeView({
 });
 ```
 
-`explodeView(options?: ExplodeViewOptions): void`
+```ts
+explodeView(options?: ExplodeViewOptions): void
+```
 
 **`ExplodeViewOptions`**
 
@@ -1728,15 +2318,42 @@ explodeView({
 
 #### `cutPlane()`
 
-`cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void`
+```ts
+cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void
+```
 
 **`CutPlaneOptions`**
 - `offset?: number` — Optional offset along the plane normal (primarily for object-form overload).
 - `exclude?: CutPlaneExcludeInput` — Object names to keep uncut for this plane.
 
-#### `scene()` — Configure the scene environment for the current script execution.
+#### `mock()` — Register a mock (context) object for visualization and collision checking.
+
+Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via `require()`. This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
+
+The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
+
+Mock objects participate in `forgecad run` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
+
+In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.
+
+```ts
+// bracket.forge.js
+const wall = mock(box(100, 200, 10).translate(0, 0, -5), "wall");
+const bolt = mock(cylinder(3, 15).translate(10, 15, 0), "bolt");
+
+const bracket = box(20, 30, 5);
+verify.notColliding("bracket vs wall", bracket, wall);
+
+return bracket;
+// When imported: only bracket is exported
+// When run directly: bracket + wall + bolt all visible
+```
 
-**Details**
+```ts
+mock<T extends Shape>(shape: T, name?: string): T
+```
+
+#### `scene()` — Configure the scene environment for the current script execution.
 
 Controls camera position, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
 
@@ -1748,8 +2365,6 @@ Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewp
 
 All numeric values accept `param()` expressions.
 
-**Example**
-
 ```js
 scene({
   background: { top: '#000814', bottom: '#001d3d' },
@@ -1771,7 +2386,9 @@ scene({
 });
 ```
 
-`scene(options: SceneOptions): void`
+```ts
+scene(options: SceneOptions): void
+```
 
 **`SceneOptions`**
 
@@ -1840,18 +2457,16 @@ scene({
 
 Shows each user-authored label name in the viewport for visual debugging. Returns the shape unchanged for chaining: `return showLabels(myShape)`.
 
-`showLabels(shape: Shape): Shape`
+```ts
+showLabels(shape: Shape): Shape
+```
 
 #### `viewConfig()` — Configure viewport helper visuals for the current script execution.
 
-**Details**
-
 Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when `jointsView` is active. Multiple calls merge — later values override earlier ones per key.
 
 This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
 
-**Example**
-
 ```js
 viewConfig({
   jointOverlay: {
@@ -1863,7 +2478,9 @@ viewConfig({
 });
 ```
 
-`viewConfig(options?: ViewConfigOptions): void`
+```ts
+viewConfig(options?: ViewConfigOptions): void
+```
 
 `ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
 
@@ -1871,16 +2488,12 @@ viewConfig({
 
 #### `spec()` — Create a named, reusable bundle of verification checks.
 
-**Details**
-
 A spec groups related `verify.*` calls under a collapsible header in the Checks panel. This makes large check suites scannable. Specs can be applied to multiple shapes and can check relationships between parts.
 
 Specs can be defined in separate `.forge.js` files and imported via `require()` to share them across models.
 
 `spec.check()` returns a `SpecResult` — you can inspect it programmatically or ignore the return value and let the Checks panel show results.
 
-**Example**
-
 ```ts
 const printable = spec("Fits printer bed", (shape) => {
   verify.notEmpty("Has geometry", shape);
@@ -1903,7 +2516,9 @@ fitSpec.check(bracket, standoff);
 
 **Spec-first workflow:** Write specs before building geometry. Checks go from red to green as you build — effectively TDD for CAD.
 
-`spec(name: string, checkFn: (...args: any[]) => void): Spec`
+```ts
+spec(name: string, checkFn: (...args: any[]) => void): Spec
+```
 
 **`Spec`**
 - `name: string` — The display name of this spec
@@ -1920,11 +2535,19 @@ Unlike union(), colors and individual identities are preserved. Children can be
 
 **Local coordinate pattern:** Build child parts at the origin (local coordinates), then group and translate once to place the whole assembly. This eliminates the error-prone pattern of manually adding parent offsets to every sub-part.
 
-// BAD — every sub-part repeats the parent's global offset const unitX = 0, unitY = -18, unitZ = 70; const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ); const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4); const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+```js
+// BAD — every sub-part repeats the parent's global offset
+const unitX = 0, unitY = -18, unitZ = 70;
+const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ);
+const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+```
 
 // GOOD — build at origin, group, translate once const body = roundedBox(100, 20, 32, 4); const panel = box(98, 2, 18).translate(0, -12, 4); const louver = box(88, 2, 6).translate(0, -14, -11); const indoorUnit = group( { name: 'Body', shape: body }, { name: 'Panel', shape: panel }, { name: 'Louver', shape: louver }, ).translate(0, -18, 70);
 
-`group(...items: GroupInput[]): ShapeGroup`
+```ts
+group(...items: GroupInput[]): ShapeGroup
+```
 
 ---
 
@@ -1932,6 +2555,46 @@ Unlike union(), colors and individual identities are preserved. Children can be
 
 Pre-built parametric parts accessible via `lib.*`.
 
-*No free functions — see class methods (Shape, Sketch, ConstrainedSketchBuilder).*
+#### `Wood.board()` — Create a wood board with metadata for manufacturing.
+
+The board is a box(width, height, thickness) centered on XY, base at Z=0. Width along X, height along Y, thickness along Z (0 to thickness).
+
+```ts
+Wood.readonly board: (width: number, height: number, thickness: number, opts?: WoodBoardOptions) => WoodBoard
+```
+
+**`WoodBoardOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `species?` | `string` | Wood species, e.g. "birch", "oak", "plywood". Default: "wood" |
+| `material?` | `string` | Material description for BOM, e.g. "birch plywood". Default: species value |
+| `grain?` | `string` | Grain direction: "long" (along width) or "cross" (along height). Default: "long" |
+| `color?` | `string` | Color hex string for visualization. Default: "#d2b48c" (tan/wood) |
+| `autoBom?` | `boolean` | If false, skip automatic BOM registration. Default: true |
+
+#### `Wood.dado()` — Cut a dado (channel) across the face of a host board for a guest board to sit in.
+
+Mutates `host.shape` by subtracting a rectangular channel.
+
+```ts
+Wood.readonly dado: typeof dado
+```
+
+#### `Wood.rabbet()` — Cut a rabbet (L-shaped step) along an edge of a board.
+
+Mutates `board.shape` by subtracting a step from the specified edge.
+
+```ts
+Wood.readonly rabbet: typeof rabbet
+```
+
+#### `Wood.mortiseAndTenon()` — Cut a mortise in one board and shape a tenon on another.
+
+Mutates both boards — subtracts the mortise pocket and removes shoulder material to form the tenon.
+
+```ts
+Wood.readonly mortiseAndTenon: typeof mortiseAndTenon
+```
 
 ---