forgecad 0.6.3 → 0.7.0

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

@@ -6,10 +6,10 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 
 ## Concepts
 
-- **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(19 functions)*
-- **[C2: Boolean Combination](#c2-boolean-combination)** — Combine same-dimension geometry using CSG set operations. *(3 functions)*
+- **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(20 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). *(12 functions)*
+- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(10 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)*
@@ -19,7 +19,7 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 - **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(6 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. *(5 functions)*
+- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(6 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)*
 
@@ -29,223 +29,287 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 
 Create geometry from parameters — no input geometry required.
 
-#### `arcBridgeBetweenRects()`
+#### `circle2d()` — Create a 2D circle centered at the origin.
 
-```ts
-arcBridgeBetweenRects(rectA: RectAreaArg, rectB: RectAreaArg, segments?: number): Shape
-```
+**Details**
 
-Build an arc bridge between two rectangular areas.
+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.
 
-#### `circle2d()`
+**Example**
 
 ```ts
-circle2d(radius: number, segments?: number): Sketch
+circle2d(25).extrude(10);          // smooth cylinder
+circle2d(25, 6).extrude(10);       // hexagonal prism
 ```
 
-Create a 2D circle centered at the origin. Use segments for lower-poly approximations.
+`circle2d(radius: number, segments?: number): Sketch`
 
-#### `ellipse()`
+#### `ellipse()` — Create a 2D ellipse centered at the origin.
+
+**Example**
 
 ```ts
-ellipse(rx: number, ry: number, segments?: number): Sketch
+ellipse(30, 15).extrude(5);
+ellipse(30, 15, 32).extrude(5); // lower-resolution approximation
 ```
 
-Create a 2D ellipse centered at the origin with the given X and Y radii.
+`ellipse(rx: number, ry: number, segments?: number): Sketch`
 
-#### `loadFont()`
+#### `loadFont()` — Pre-load and cache a font for use with `text2d()`.
 
-```ts
-loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font
-```
+**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.
 
-Load and cache a font. - A built-in font name: `'sans-serif'` or `'inter'` (works everywhere) - A file path to a TTF/OTF/WOFF file (CLI/Node only) - An ArrayBuffer of font data (works everywhere)
+Built-in font names that work everywhere (browser + CLI): - `'sans-serif'` or `'inter'` — bundled Inter Regular
 
-#### `ngon()`
+**Example**
 
 ```ts
-ngon(sides: number, radius: number): Sketch
+const font = loadFont('/path/to/Arial Bold.ttf');
+text2d('Title', { size: 12, font }).extrude(1.5);
+text2d('Subtitle', { size: 8, font }).extrude(1);
 ```
 
-Create a regular polygon (equilateral triangle, hexagon, etc.) inscribed in a circle of the given radius.
+`loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font`
 
-#### `path()`
+#### `ngon()` — Create a regular polygon inscribed in a circle of the given radius.
 
-```ts
-path(): PathBuilder
-```
+**Details**
 
-Create a path builder for constructing 2D outlines.
+`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).
 
-#### `polar()`
+**Example**
 
 ```ts
-polar(length: number, angleDeg: number, from?: [ number, number ]): [ number, number ]
+ngon(6, 20).extrude(10); // hexagonal prism, circumradius 20
 ```
 
-Compute a point by moving a given distance at a given angle from a start point. Angle is in degrees, measured CCW from the +X axis (standard math convention). Returns `[x, y]`. ```js polar(10, 45)            // [7.07, 7.07] — from origin polar(10, 45, [5, 5])    // [12.07, 12.07] — from (5,5) ```
+`ngon(sides: number, radius: number): Sketch`
 
-#### `polygon()`
+#### `path()` — Create a new `PathBuilder` for tracing a 2D outline point by point.
 
-```ts
-polygon(points: ([ number, number ] | Point2D)[]): Sketch
-```
+**Details**
 
-Create a 2D polygon from an array of [x, y] points or Point2D objects. Winding is normalized to CCW.
+`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.
 
-#### `polygonVertices()`
+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
-polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
+// Closed triangle
+const triangle = path().moveTo(0, 0).lineH(50).lineV(30).close();
+
+// L-shaped bracket as a stroke
+const bracket = path().moveTo(0, 0).lineH(50).lineV(-70).lineAngled(20, 235).stroke(4);
+
+// Labeled edges for downstream face references
+const slot = path()
+  .moveTo(0, 0)
+  .lineTo(30, 0).label('bottom')
+  .lineTo(30, 10)
+  .lineTo(0, 10).label('top')
+  .close();
 ```
 
-Compute the vertex positions of a regular polygon. Default orientation places the first vertex at the top (90 degrees), matching the convention used by `ngon()`. Eliminates manual Math.sqrt(3) for triangles, pentagon vertex math, etc: ```js // Before — manual equilateral triangle const v1 = [center.x - r/2, center.y + r * Math.sqrt(3)/2]; const v2 = [center.x - r/2, center.y - r * Math.sqrt(3)/2]; const v3 = [center.x + r, center.y]; // After — declarative const [v1, v2, v3] = polygonVertices(3, r); ```
+`path(): PathBuilder`
 
-<details><summary><code>PolygonVerticesOptions</code></summary>
+#### `polygon()` — Create a 2D polygon from an array of `[x, y]` points or `Point2D` objects.
 
-```ts
-interface PolygonVerticesOptions {
-  /** Angle of the first vertex in degrees (default: 90 = top). */
-  startDeg?: number;
-  /** Center X coordinate (default: 0). */
-  centerX?: number;
-  /** Center Y coordinate (default: 0). */
-  centerY?: number;
-}
-```
+**Details**
 
-</details>
+Winding order is normalized automatically — clockwise (CW) input is silently reversed to CCW before being passed to the geometry kernel.
 
-<details><summary><code>LayoutPoint</code></summary>
+**Example**
 
 ```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
+polygon([[0, 0], [50, 0], [25, 40]]).extrude(5); // triangle
 ```
 
-</details>
+`polygon(points: ([ number, number ] | Point2D)[]): Sketch`
 
-#### `rect()`
+#### `polygonVertices()` — Compute the vertex positions of a regular polygon.
 
-```ts
-rect(width: number, height: number, center?: boolean): Sketch
-```
+Default orientation places the first vertex at the top (90 degrees), matching the convention used by `ngon()`.
 
-Create a 2D rectangle. When center is true, the origin is at the rectangle center; otherwise at the bottom-left corner.
+Eliminates manual Math.sqrt(3) for triangles, pentagon vertex math, etc:
 
-#### `arcSlot()`
+```js
+// Before — manual equilateral triangle
+const v1 = [center.x - r/2, center.y + r * Math.sqrt(3)/2];
+const v2 = [center.x - r/2, center.y - r * Math.sqrt(3)/2];
+const v3 = [center.x + r, center.y];
 
-```ts
-arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
+// After — declarative
+const [v1, v2, v3] = polygonVertices(3, r);
 ```
 
-Create an arc-shaped slot (banana/annular sector) centered at the origin. The slot is symmetric about the +X axis. ```js arcSlot(135, 74, 40)  // pitch R135, 74° sweep, 40mm wide ```
+`polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]`
 
-#### `routePerimeter()`
+**`PolygonVerticesOptions`**
+- `startDeg?: number` — Angle of the first vertex in degrees (default: 90 = top).
+- `centerX?: number` — Center X coordinate (default: 0).
+- `centerY?: number` — Center Y coordinate (default: 0).
 
-```ts
-routePerimeter(steps: PerimeterStep[]): Sketch
-```
+`LayoutPoint`: `{ x: number, y: number }`
 
-Route a smooth closed perimeter around a sequence of construction circles, connected by tangent fillet arcs. Steps must alternate: circle, fillet, circle, fillet, ... The sequence wraps — the last fillet connects back to the first circle. ```js const outline = routePerimeter([ { center: [0, 0], radius: 45 }, { fillet: 5 }, { center: polar(60, 60), radius: 18 }, { fillet: 17 }, { center: polar(60, 120), radius: 18 }, { fillet: 5 }, ]) ```
+#### `rect()` — Create a 2D rectangle centered at the origin.
 
-#### `roundedRect()`
+**Example**
 
 ```ts
-roundedRect(width: number, height: number, radius: number, center?: boolean): Sketch
+rect(40, 20).extrude(5);
 ```
 
-Create a 2D rectangle with rounded corners. The radius is clamped to fit within the dimensions.
+`rect(width: number, height: number): Sketch`
 
-#### `slot()`
+#### `arcSlot()` — Create an arc-shaped slot (banana / annular sector) centered at the origin.
 
-```ts
-slot(length: number, width: number): Sketch
-```
+**Details**
 
-Create a slot (stadium/discorectangle) — a rectangle with semicircular ends, centered at origin.
+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.
 
-#### `spline2d()`
+**Example**
 
 ```ts
-spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
+arcSlot(135, 74, 40).extrude(5); // pitch R135, 74° sweep, 40mm wide
 ```
 
-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.
+`arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch`
 
-<details><summary><code>Spline2DOptions</code></summary>
+#### `roundedRect()` — Create a 2D rectangle with rounded corners, centered at the origin.
 
-```ts
-interface Spline2DOptions {
-  /** Closed loop (default true). */
-  closed?: boolean;
-  /** Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. */
-  tension?: number;
-  /** Samples per segment (minimum 3). Default 16. */
-  samplesPerSegment?: number;
-  /** For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. */
-  strokeWidth?: number;
-  /** Stroke join for open splines. Default 'Round'. */
-  join?: "Round" | "Square";
-}
-```
+**Details**
 
-</details>
+The corner radius is automatically clamped to `min(width/2, height/2)` so it can never exceed the shape dimensions.
 
-#### `star()`
+**Example**
 
 ```ts
-star(points: number, outerR: number, innerR: number): Sketch
+roundedRect(60, 30, 5).extrude(3);
 ```
 
-Create a star shape with alternating outer and inner radii.
+`roundedRect(width: number, height: number, radius: number): Sketch`
+
+#### `slot()` — Create a slot (oblong / stadium shape) — a rectangle with semicircular ends, centered at the origin.
 
-#### `stroke()`
+**Example**
 
 ```ts
-stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"): Sketch
+slot(40, 10).extrude(3); // 40mm long, 10mm wide slot
 ```
 
-Create a stroked polyline sketch from an array of 2D points.
+`slot(length: number, width: number): Sketch`
+
+#### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
-#### `text2d()`
+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`
+
+**`Spline2DOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `closed?` | `boolean` | Closed loop (default true). |
+| `tension?` | `number` | Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. |
+| `samplesPerSegment?` | `number` | Samples per segment (minimum 3). Default 16. |
+| `strokeWidth?` | `number` | For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. |
+| `join?` | `"Round" | "Square"` | Stroke join for open splines. Default 'Round'. |
+
+#### `star()` — Create a star shape with alternating outer and inner radii.
+
+**Example**
 
 ```ts
-text2d(content: string, options?: TextOptions): Sketch
+star(5, 30, 12).extrude(4); // five-pointed star
 ```
 
-Build a 2-D filled Sketch from a text string. The Sketch origin is at the left end of the text baseline by default (see `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. // Extruded nameplate text2d('FORGE CAD', { size: 8 }).extrude(1.2) // Centered label on the XY plane text2d('V 2.0', { size: 6, align: 'center', baseline: 'center' })
+`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`
+
+#### `text2d()` — Build a filled 2D Sketch from a text string.
 
-<details><summary><code>TextOptions</code></summary>
+**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
-interface TextOptions {
-  /** Cap height of the text in model units. All other dimensions (stroke weight, spacing) scale proportionally. */
-  size?: number;
-  /** Extra space between characters in model units. Negative values tighten the tracking. */
-  letterSpacing?: number;
-  /** Horizontal alignment relative to x = 0. - `'left'`   — left edge at x = 0 (default) - `'center'` — centred on x = 0 - `'right'`  — right edge at x = 0 */
-  align?: "left" | "center" | "right";
-  /** 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 */
-  baseline?: "baseline" | "center" | "top";
-  /** 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$1.Font;
-  /** Bezier flattening tolerance in model units. Smaller = more polygon segments = smoother curves. */
-  flattenTolerance?: number;
-}
+// Extruded nameplate
+text2d('FORGE CAD', { size: 8 }).extrude(1.2);
+
+// Centered label on the XY plane
+text2d('V 2.0', { size: 6, align: 'center', baseline: 'center' });
+
+// Engraved text cut into the top face of a box
+const label = text2d('REV A', { size: 5, align: 'center', baseline: 'center' });
+plate.subtract(label.onFace(plate, 'top', { protrude: -0.5 }).extrude(1));
+
+// Custom TTF font
+text2d('Hello', { size: 10, font: '/path/to/Arial.ttf' }).extrude(1);
+
+// Pre-loaded font for reuse
+const font = loadFont('/path/to/Arial Bold.ttf');
+text2d('Title', { size: 12, font }).extrude(1.5);
 ```
 
-</details>
+`text2d(content: string, options?: TextOptions): Sketch`
+
+**`TextOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `size?` | `number` | Cap height of the text in model units. All other dimensions (stroke weight, spacing) scale proportionally. |
+| `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' }) |
+| `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.
 
-#### `textWidth()`
+**Example**
 
 ```ts
-textWidth(content: string, options?: Pick<TextOptions, "size" | "letterSpacing" | "font">): number
+const w = textWidth('SERIAL: 001', { size: 6 });
+const plate = box(w + 10, 12, 2);
 ```
 
-Returns the rendered width of a string in model units (same options as text2d).
+`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`
+
+#### `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`
+
+#### `sphere()` — Create a sphere centered at the origin. Use segments for lower-poly approximations.
+
+`sphere$1(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`
 
 ---
 
@@ -253,399 +317,305 @@ Returns the rendered width of a string in model units (same options as text2d).
 
 Combine same-dimension geometry using CSG set operations.
 
-#### `difference2d()`
+#### `difference2d()` — Subtract one or more 2D sketches from a base sketch.
 
-```ts
-difference2d(...inputs: SketchOperandInput[]): Sketch
-```
+**Details**
 
-Subtract 2D sketches from a base sketch. The first sketch is the base; all others are subtracted.
+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.
 
-#### `intersection2d()`
+**Example**
 
 ```ts
-intersection2d(...inputs: SketchOperandInput[]): Sketch
+const donut = difference2d(circle2d(50), circle2d(30));
 ```
 
-Keep only the overlapping area of the input sketches (intersection boolean).
+`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.
 
-#### `union2d()`
+**Example**
 
 ```ts
-union2d(...inputs: SketchOperandInput[]): Sketch
+const lens = intersection2d(circle2d(30).translate(-10, 0), circle2d(30).translate(10, 0));
 ```
 
-Combine 2D sketches into a single profile (additive boolean). Accepts individual sketches or arrays.
+`intersection2d(...inputs: SketchOperandInput[]): Sketch`
 
----
+#### `union2d()` — Combine 2D sketches into a single profile using an additive boolean union.
 
-## C3: Rigid Transform
+**Details**
 
-Reposition or reorient geometry without changing its shape.
+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.
 
-#### `degrees()`
+**Example**
 
 ```ts
-degrees(deg: number): number
+const cross = union2d(rect(60, 10), rect(10, 60));
 ```
 
-Convert degrees to degrees (identity — for readability in scripts)
+`union2d(...inputs: SketchOperandInput[]): Sketch`
 
-#### `radians()`
+#### `union()` — Combine shapes into a single solid (additive boolean).
 
-```ts
-radians(rad: number): number
-```
+Accepts individual shapes, or an array of shapes. The first operand's color is preserved in the result.
 
-Convert radians to degrees
+`union(...inputs: ShapeOperandInput[]): Shape`
 
-#### `composeChain()`
+#### `difference()` — Subtract shapes from a base shape (subtractive boolean).
 
-```ts
-composeChain(...steps: TransformInput[]): Transform
-```
+The first shape is the base; all subsequent shapes are subtracted from it. Accepts individual shapes, or an array of shapes.
 
-Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
+`difference(...inputs: ShapeOperandInput[]): Shape`
 
----
+#### `intersection()` — Keep only the overlapping volume of the input shapes (intersection boolean).
 
-## C4: Dimensional Promotion
+Requires at least two shapes. Accepts individual shapes, or an array.
 
-Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
+`intersection(...inputs: ShapeOperandInput[]): Shape`
 
-#### `connectEdges()`
+---
 
-```ts
-connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
-```
+## C3: Rigid Transform
 
-<details><summary><code>EdgeSegment</code></summary>
+Reposition or reorient geometry without changing its shape.
 
-```ts
-interface EdgeSegment {
-  /** Stable index within the extraction (deterministic for a given mesh). */
-  index: number;
-  start: Vec3;
-  end: Vec3;
-  midpoint: Vec3;
-  /** Normalized direction from start → end. */
-  direction: Vec3;
-  length: number;
-  /** Dihedral angle in degrees (0 = coplanar, 180 = knife edge). */
-  dihedralAngle: number;
-  /** true = outside corner (convex), false = inside corner (concave). */
-  convex: boolean;
-  /** Normal of first adjacent face. */
-  normalA: Vec3;
-  /** Normal of second adjacent face (same as normalA for boundary edges). */
-  normalB: Vec3;
-  /** true if this is a boundary (unmatched) edge — unusual for closed solids. */
-  boundary: boolean;
-}
-```
+#### `degrees()` — Identity function that returns degrees unchanged.
 
-</details>
+Use for clarity when the unit of an angle value would otherwise be ambiguous — e.g. `param("Angle", degrees(45))`.
 
-<details><summary><code>TransitionCurveOptions</code></summary>
+`degrees(deg: number): number`
 
-```ts
-interface TransitionCurveOptions {
-  /** Weight for the start edge. Controls tangent magnitude at the start. - 1.0 (default): balanced transition - > 1.0: curve follows start edge longer before turning - < 1.0: curve turns sooner at the start */
-  weightA?: number;
-  /** Weight for the end edge. Controls tangent magnitude at the end. - 1.0 (default): balanced transition - > 1.0: curve follows end edge longer before turning - < 1.0: curve turns sooner at the end */
-  weightB?: number;
-  /** Number of sample points for the output polyline. Default 64. Higher values give smoother curves at the cost of more geometry. */
-  samples?: number;
-}
-```
+#### `radians()` — Convert radians to degrees.
 
-</details>
+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.
 
-<details><summary><code>TransitionSurfaceOptions</code> extends TransitionCurveOptions</summary>
+`radians(rad: number): number`
 
-```ts
-interface TransitionSurfaceOptions extends TransitionCurveOptions {
-  /** Cross-section profile to sweep along the transition curve. If omitted, a circular profile with `radius` is used. */
-  profile?: Sketch;
-  /** Radius of circular cross-section (used when `profile` is omitted). Default: 5% of chord length. */
-  radius?: number;
-  width: number;
-  height: number;
-  /** Preferred up vector for the sweep frame. Default: auto-detected. */
-  up?: Vec3$7;
-  /** Edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Extra bounds padding for level-set meshing. */
-  boundsPadding?: number;
-}
-```
+#### `composeChain()` — Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
 
-</details>
+`composeChain(...steps: TransformInput[]): Transform`
 
-<details><summary><code>ConnectEdgesOptions</code> extends TransitionSurfaceOptions</summary>
+---
 
-```ts
-interface ConnectEdgesOptions extends TransitionSurfaceOptions {
-  /** Which end of edge A to connect. Default: 'start'. */
-  endA?: EdgeEnd;
-  /** Which end of edge B to connect. Default: 'start'. */
-  endB?: EdgeEnd;
-  /** Tangent mode for edge A. Default: 'along'. */
-  tangentModeA?: TangentMode;
-  /** Tangent mode for edge B. Default: 'along'. */
-  tangentModeB?: TangentMode;
-  /** Explicit tangent for edge A. */
-  tangentA?: Vec3$7;
-  /** Explicit tangent for edge B. */
-  tangentB?: Vec3$7;
-  /** Flip tangent A. */
-  flipA?: boolean;
-  /** Flip tangent B. */
-  flipB?: boolean;
-}
-```
+## C4: Dimensional Promotion
 
-</details>
+Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
 
-#### `hermiteTransition()`
+#### `connectEdges()` — Create a transition surface or solid bridge between two edge segments.
 
-```ts
-hermiteTransition(a: EdgeEndpoint, b: EdgeEndpoint): HermiteCurve3D
-```
+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.
 
-Create a Hermite transition curve between two edge endpoints. The curve starts at `a.point` tangent to `a.tangent` and ends at `b.point` tangent to `b.tangent`, with smooth G1-continuous interpolation. Weight controls: - weight = 1.0 (default): balanced transition - weight > 1.0: curve follows this edge's direction longer before turning - weight < 1.0: curve turns sooner, shorter tangent influence
+`connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape`
 
-<details><summary><code>EdgeEndpoint</code></summary>
+**`EdgeSegment`**
 
-```ts
-interface EdgeEndpoint {
-  /** Connection point on the edge */
-  point: Vec3$5;
-  /** Tangent direction along the edge at the connection point */
-  tangent: Vec3$5;
-  /** Surface normal at the connection point (optional, for future G2 support) */
-  normal?: Vec3$5;
-  /** Weight controlling how far the curve follows this edge's tangent. Default 1.0. */
-  weight?: number;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `index` | `number` | Stable index within the extraction (deterministic for a given mesh). |
+| `direction` | `Vec3` | Normalized direction from start → end. |
+| `dihedralAngle` | `number` | Dihedral angle in degrees (0 = coplanar, 180 = knife edge). |
+| `convex` | `boolean` | true = outside corner (convex), false = inside corner (concave). |
+| `normalA` | `Vec3` | Normal of first adjacent face. |
+| `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
+| `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
+| `start`, `end`, `midpoint`, `length` | | — |
 
-</details>
+**`TransitionCurveOptions`**
+- `weightA?: number` — Weight for the start edge. Controls tangent magnitude at the start. - 1.0 (default): balanced transition - > 1.0: curve follows start edge longer before turning - < 1.0: curve turns sooner at the start
+- `weightB?: number` — Weight for the end edge. Controls tangent magnitude at the end. - 1.0 (default): balanced transition - > 1.0: curve follows end edge longer before turning - < 1.0: curve turns sooner at the end
+- `samples?: number` — Number of sample points for the output polyline. Default 64. Higher values give smoother curves at the cost of more geometry.
 
-#### `hermiteTransitionG2()`
+**`TransitionSurfaceOptions`** extends TransitionCurveOptions
 
-```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `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. |
+| `edgeLength?` | `number` | Edge length for level-set meshing. Smaller = finer. |
+| `boundsPadding?` | `number` | Extra bounds padding for level-set meshing. |
+| `width`, `height` | | — |
 
-Create a quintic Hermite transition curve between two edge endpoints (G2 continuity). 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.
+**`ConnectEdgesOptions`** extends TransitionSurfaceOptions
 
-<details><summary><code>QuinticHermiteCurveEndpoint</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `endA?` | `EdgeEnd` | Which end of edge A to connect. Default: 'start'. |
+| `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. |
+| `flipA?` | `boolean` | Flip tangent A. |
+| `flipB?` | `boolean` | Flip tangent B. |
 
-```ts
-interface QuinticHermiteCurveEndpoint {
-  /** Position */
-  point: Vec3$5;
-  /** Tangent direction (will be normalized internally) */
-  tangent: Vec3$5;
-  /** Second derivative / curvature vector. Default [0, 0, 0]. */
-  curvature?: Vec3$5;
-  /** Weight: scales tangent magnitude relative to chord length. Default 1.0. */
-  weight?: number;
-}
-```
+#### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
-</details>
+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.
 
-#### `loft()`
+`hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D`
 
-```ts
-loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
-```
+**`QuinticHermiteCurveEndpoint`**
 
-Loft between multiple sketches along Z stations. Profiles can differ in topology and vertex count: interpolation is done on signed-distance fields and meshed with level-set extraction. Heights must be strictly increasing. Compatible loft stacks can export through the OCCT exact route. Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
+| 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]. |
+| `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
 
-<details><summary><code>LoftOptions</code></summary>
+#### `loft()` — Loft between multiple sketches along Z stations.
 
-```ts
-interface LoftOptions {
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-}
-```
+Profiles can differ in topology and vertex count: interpolation is done on signed-distance fields and meshed with level-set extraction. Heights must be strictly increasing. Compatible loft stacks can export through the OCCT exact route.
 
-</details>
+Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
 
-#### `loftAlongSpine()`
+`loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape`
 
-```ts
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$4[], tValues: number[], options?: LoftAlongSpineOptions): Shape
-```
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
 
-Loft between multiple profiles positioned along an arbitrary 3D spine curve. Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge. The tValues array specifies where each profile sits along the spine (0 = start, 1 = end). Must have the same length as profiles and be in [0, 1]. Internally uses variableSweep infrastructure with SDF interpolation. Performance note: uses level-set meshing, heavier than simple loft().
+#### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
-<details><summary><code>LoftAlongSpineOptions</code></summary>
+Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
 
-```ts
-interface LoftAlongSpineOptions {
-  /** Number of samples when spine is a Curve3D. Default 48. */
-  samples?: number;
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-  /** Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. */
-  up?: Vec3$4;
-}
-```
+The tValues array specifies where each profile sits along the spine (0 = start, 1 = end). Must have the same length as profiles and be in [0, 1].
 
-</details>
+Internally uses variableSweep infrastructure with SDF interpolation.
 
-#### `spline3d()`
+Performance note: uses level-set meshing, heavier than simple loft().
 
-```ts
-spline3d(points: Vec3$4[], options?: Spline3DOptions): Curve3D
-```
+`loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$3[], tValues: number[], options?: LoftAlongSpineOptions): Shape`
 
-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.
+**`LoftAlongSpineOptions`**
 
-<details><summary><code>Spline3DOptions</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `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. |
 
-```ts
-interface Spline3DOptions {
-  /** Closed loop (default false). */
-  closed?: boolean;
-  /** Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. */
-  tension?: number;
-}
-```
+#### `spline3d()` — Create a reusable 3D spline curve object (Catmull-Rom).
 
-</details>
+The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
 
-#### `surfacePatch()`
+`spline3d(points: Vec3$3[], options?: Spline3DOptions): Curve3D`
 
-```ts
-surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
-```
+**`Spline3DOptions`**
+- `closed?: boolean` — Closed loop (default false).
+- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
 
-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 interior is filled using bilinear Coons patch interpolation: P(u,v) = Lc(u,v) + Ld(u,v) - B(u,v) The result is a thin solid created by offsetting the surface mesh along its normals by the specified thickness. Note: curves should meet at corners. Small gaps are tolerated.
+#### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
 
-<details><summary><code>SurfacePatchOptions</code></summary>
+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)
 
-```ts
-interface SurfacePatchOptions {
-  /** Number of samples along each direction. Default 24. */
-  resolution?: number;
-  /** Thickness of the generated solid. Default 0.5. */
-  thickness?: number;
-}
-```
+The interior is filled using bilinear Coons patch interpolation: P(u,v) = Lc(u,v) + Ld(u,v) - B(u,v)
 
-</details>
+The result is a thin solid created by offsetting the surface mesh along its normals by the specified thickness.
 
-#### `sweep()`
+Note: curves should meet at corners. Small gaps are tolerated.
 
-```ts
-sweep(profile: Sketch, path: Curve3D | Vec3$4[], options?: SweepOptions): Shape
-```
+`surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape`
 
-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. Performance note: sweep uses level-set meshing internally. Prefer direct primitives/extrude/revolve when they can express the same shape.
+**`SurfacePatchOptions`**
+- `resolution?: number` — Number of samples along each direction. Default 24.
+- `thickness?: number` — Thickness of the generated solid. Default 0.5.
 
-<details><summary><code>SweepOptions</code></summary>
+#### `sweep()` — Sweep a 2D profile along a 3D path to create a solid.
 
-```ts
-interface SweepOptions {
-  /** Number of samples when path is a Curve3D. Default 48. */
-  samples?: number;
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-  /** Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. */
-  up?: Vec3$4;
-}
-```
+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.
 
-</details>
+Performance note: sweep uses level-set meshing internally. Prefer direct primitives/extrude/revolve when they can express the same shape.
 
-#### `variableSweep()`
+`sweep(profile: Sketch, path: Curve3D | Vec3$3[], options?: SweepOptions): Shape`
 
-```ts
-variableSweep(spine: Curve3D | Vec3$4[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
-```
+**`SweepOptions`**
 
-Sweep a variable cross-section along a 3D spine curve. Unlike sweep(), which uses a single constant profile, variableSweep() interpolates between multiple profiles at different stations along the spine. This enables organic shapes like tapering tubes, bone-like structures, and sculptural forms. Each section specifies a t parameter (0 = start, 1 = end of spine) and a 2D profile sketch. The SDF-based level-set mesher smoothly blends between profiles at intermediate positions. Performance note: like sweep(), this uses level-set meshing internally.
+| Option | Type | Description |
+|--------|------|-------------|
+| `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. |
 
-<details><summary><code>VariableSweepSection</code></summary>
+#### `variableSweep()` — Sweep a variable cross-section along a 3D spine curve.
 
-```ts
-interface VariableSweepSection {
-  /** Parameter along the spine (0 = start, 1 = end). */
-  t: number;
-  /** Cross-section profile at this station. */
-  profile: Sketch;
-}
-```
+Unlike sweep(), which uses a single constant profile, variableSweep() interpolates between multiple profiles at different stations along the spine. This enables organic shapes like tapering tubes, bone-like structures, and sculptural forms.
 
-</details>
+Each section specifies a t parameter (0 = start, 1 = end of spine) and a 2D profile sketch. The SDF-based level-set mesher smoothly blends between profiles at intermediate positions.
 
-<details><summary><code>VariableSweepOptions</code></summary>
+Performance note: like sweep(), this uses level-set meshing internally.
 
-```ts
-interface VariableSweepOptions {
-  /** Number of samples when spine is a Curve3D. Default 48. */
-  samples?: number;
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-  /** Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. */
-  up?: Vec3$4;
-}
-```
+`variableSweep(spine: Curve3D | Vec3$3[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape`
 
-</details>
+**`VariableSweepSection`**
+- `t: number` — Parameter along the spine (0 = start, 1 = end).
+- `profile: Sketch` — Cross-section profile at this station.
 
-#### `transitionCurve()`
+**`VariableSweepOptions`**
 
-```ts
-transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `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. |
 
-Create a smooth transition curve between two edges. Returns a `HermiteCurve3D` that starts at `edgeA.point` tangent to `edgeA.tangent` and ends at `edgeB.point` tangent to `edgeB.tangent`. 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] }, ); // Weighted: curve hugs edge A longer const weighted = transitionCurve( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 0], tangent: [1, 0, 0] }, { weightA: 2.0, weightB: 0.5 }, ); ```
+#### `transitionCurve()` — Create a smooth transition curve between two edges.
 
-<details><summary><code>TransitionEdge</code></summary>
+Returns a `HermiteCurve3D` that starts at `edgeA.point` tangent to `edgeA.tangent` and ends at `edgeB.point` tangent to `edgeB.tangent`.
 
-```ts
-interface TransitionEdge {
-  /** Connection point on the edge. Can be any point along the edge where the transition should connect. */
-  point: Vec3$7;
-  /** 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). */
-  tangent: Vec3$7;
-  /** Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector. */
-  normal?: Vec3$7;
-}
+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] },
+);
+
+// Weighted: curve hugs edge A longer
+const weighted = transitionCurve(
+  { point: [0, 0, 0], tangent: [1, 0, 0] },
+  { point: [10, 5, 0], tangent: [1, 0, 0] },
+  { weightA: 2.0, weightB: 0.5 },
+);
 ```
 
-</details>
+`transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D`
 
-#### `transitionCurveFromPoints()`
+**`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.
 
-```ts
-transitionCurveFromPoints(startPoint: Vec3$7, startTangent: Vec3$7, endPoint: Vec3$7, endTangent: Vec3$7, options?: TransitionCurveOptions): HermiteCurve3D
-```
+#### `transitionSurface()` — Create a solid transition surface between two edges by sweeping a profile along a Hermite transition curve.
 
-Convenience: create a transition curve from raw coordinate data. Useful when you have endpoints and directions as plain arrays without constructing TransitionEdge objects.
+This produces a watertight solid that smoothly connects the two edges. Works with both Manifold and OCCT backends.
 
-#### `transitionSurface()`
+```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 },
+);
 
-```ts
-transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+// Custom profile with weights
+const custom = transitionSurface(
+  { point: [0, 0, 0], tangent: [1, 0, 0] },
+  { point: [10, 5, 3], tangent: [0, 1, 0] },
+  { profile: mySketch, weightA: 1.5, weightB: 0.8 },
+);
 ```
 
-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 }, ); // Custom profile with weights const custom = transitionSurface( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 3], tangent: [0, 1, 0] }, { profile: mySketch, weightA: 1.5, weightB: 0.8 }, ); ```
+`transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape`
 
 ---
 
@@ -653,106 +623,94 @@ Create a solid transition surface between two edges by sweeping a profile along
 
 Select or inspect named faces and edges on a shape.
 
-#### `coalesceEdges()`
+#### `coalesceEdges()` — Merge collinear edge segments into longer logical edges.
 
-```ts
-coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
-```
+**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.
 
-Coalesce collinear edge segments into longer logical edges. Multiple short mesh segments along the same line (e.g. from tessellation) are merged into a single EdgeSegment spanning the full extent. The `tolerance` controls how far endpoints can deviate from collinearity.
+The `tolerance` controls the maximum perpendicular distance from collinearity before two segments are considered non-collinear. Default: `0.01`.
 
-<details><summary><code>EdgeSegment</code></summary>
+**Example**
 
 ```ts
-interface EdgeSegment {
-  /** Stable index within the extraction (deterministic for a given mesh). */
-  index: number;
-  start: Vec3;
-  end: Vec3;
-  midpoint: Vec3;
-  /** Normalized direction from start → end. */
-  direction: Vec3;
-  length: number;
-  /** Dihedral angle in degrees (0 = coplanar, 180 = knife edge). */
-  dihedralAngle: number;
-  /** true = outside corner (convex), false = inside corner (concave). */
-  convex: boolean;
-  /** Normal of first adjacent face. */
-  normalA: Vec3;
-  /** Normal of second adjacent face (same as normalA for boundary edges). */
-  normalB: Vec3;
-  /** true if this is a boundary (unmatched) edge — unusual for closed solids. */
-  boundary: boolean;
+const topEdges = selectEdges(part, { atZ: 20 });
+for (const edge of coalesceEdges(topEdges)) {
+  result = fillet(result, 2, edge);
 }
 ```
 
-</details>
+`coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]`
 
-#### `selectEdge()`
+**`EdgeSegment`**
 
-```ts
-selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `index` | `number` | Stable index within the extraction (deterministic for a given mesh). |
+| `direction` | `Vec3` | Normalized direction from start → end. |
+| `dihedralAngle` | `number` | Dihedral angle in degrees (0 = coplanar, 180 = knife edge). |
+| `convex` | `boolean` | true = outside corner (convex), false = inside corner (concave). |
+| `normalA` | `Vec3` | Normal of first adjacent face. |
+| `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
+| `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
+| `start`, `end`, `midpoint`, `length` | | — |
 
-Select the single best-matching edge from a shape. When `near` is specified, returns the closest matching edge. Otherwise returns the first matching edge (by mesh order). Throws if no edges match.
+#### `selectEdge()` — Select the single best-matching edge from a shape.
 
-<details><summary><code>EdgeQuery</code></summary>
+**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
-interface EdgeQuery {
-  /** Sort by proximity to this point (closest first). */
-  near?: Vec3;
-  /** Filter: edge direction approximately parallel to this vector. */
-  parallel?: Vec3;
-  /** Filter: edge direction approximately perpendicular to this vector. */
-  perpendicular?: Vec3;
-  /** Filter: only convex (outside corner) edges. */
-  convex?: boolean;
-  /** Filter: only concave (inside corner) edges. */
-  concave?: boolean;
-  /** Filter: minimum dihedral angle in degrees. */
-  minAngle?: number;
-  /** Filter: maximum dihedral angle in degrees. */
-  maxAngle?: number;
-  /** Filter: minimum edge length. */
-  minLength?: number;
-  /** Filter: maximum edge length. */
-  maxLength?: number;
-  /** Filter: edge midpoint must be within this bounding region. */
-  within?: BoundingRegion;
-  /** Shorthand: edge midpoint Z ≈ this value (within tolerance). */
-  atZ?: number;
-  /** Tolerance for approximate matches (default: 1.0). */
-  tolerance?: number;
-  /** Angular tolerance in degrees for parallel/perpendicular (default: 10). */
-  angleTolerance?: number;
-}
+// Chamfer one specific edge near a known point
+const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
+result = chamfer(result, 1.5, bottomEdge);
 ```
 
-</details>
+`selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment`
 
-<details><summary><code>BoundingRegion</code></summary>
+**`EdgeQuery`**
 
-```ts
-interface BoundingRegion {
-  xMin?: number;
-  xMax?: number;
-  yMin?: number;
-  yMax?: number;
-  zMin?: number;
-  zMax?: number;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `near?` | `Vec3` | Sort by proximity to this point (closest first). When used with `selectEdge`, picks the closest match. |
+| `parallel?` | `Vec3` | Filter: edge direction approximately parallel to this vector. |
+| `perpendicular?` | `Vec3` | Filter: edge direction approximately perpendicular to this vector. |
+| `convex?` | `boolean` | Filter: only convex (outside corner) edges. |
+| `concave?` | `boolean` | Filter: only concave (inside corner) edges. |
+| `minAngle?` | `number` | Filter: minimum dihedral angle in degrees. |
+| `maxAngle?` | `number` | Filter: maximum dihedral angle in degrees. |
+| `minLength?` | `number` | Filter: minimum edge length. |
+| `maxLength?` | `number` | Filter: maximum edge length. |
+| `within?` | `BoundingRegion` | Filter: edge midpoint must be within this bounding region. |
+| `atZ?` | `number` | Shorthand: edge midpoint Z ≈ this value (within `tolerance`). Equivalent to `within: { zMin: atZ - tol, zMax: atZ + tol }`. |
+| `tolerance?` | `number` | Position tolerance for approximate matches (default: `1.0`). Used by `atZ` and `near`. |
+| `angleTolerance?` | `number` | Angular tolerance in degrees for `parallel`/`perpendicular` filters (default: `10`). |
+
+`BoundingRegion`: `{ xMin?: number, xMax?: number, yMin?: number, yMax?: number, zMin?: number, zMax?: number }`
 
-</details>
+#### `selectEdges()` — Select all edges from a shape that match the given query.
 
-#### `selectEdges()`
+**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
-selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+// Fillet all top edges of a box
+const topEdges = selectEdges(part, { atZ: 20, perpendicular: [0, 0, 1] });
+let result = part;
+for (const edge of coalesceEdges(topEdges)) {
+  result = fillet(result, 2, edge);
+}
 ```
 
-Select all edges from a shape that match the given query. Extracts sharp edges from the mesh (dihedral angle > 1°), applies filters, and returns the matching EdgeSegment array.
+`selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]`
 
 ---
 
@@ -760,100 +718,155 @@ Select all edges from a shape that match the given query. Extracts sharp edges f
 
 Modify edges of a solid — fillets, chamfers, draft, offset.
 
-#### `filletEdgeSegment()`
+#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
 
-```ts
-filletEdgeSegment(shape: Shape, segment: EdgeSegment, radius: number, segments?: number): 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.
 
-Apply a fillet (rounded edge) to a mesh-selected edge. Works on any straight edge of any shape — not limited to tracked box edges. The edge must have been obtained from selectEdge() / selectEdges().
+The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
-<details><summary><code>EdgeSegment</code></summary>
+**Example**
 
 ```ts
-interface EdgeSegment {
-  /** Stable index within the extraction (deterministic for a given mesh). */
-  index: number;
-  start: Vec3;
-  end: Vec3;
-  midpoint: Vec3;
-  /** Normalized direction from start → end. */
-  direction: Vec3;
-  length: number;
-  /** Dihedral angle in degrees (0 = coplanar, 180 = knife edge). */
-  dihedralAngle: number;
-  /** true = outside corner (convex), false = inside corner (concave). */
-  convex: boolean;
-  /** Normal of first adjacent face. */
-  normalA: Vec3;
-  /** Normal of second adjacent face (same as normalA for boundary edges). */
-  normalB: Vec3;
-  /** true if this is a boundary (unmatched) edge — unusual for closed solids. */
-  boundary: boolean;
-}
+// Chamfer all edges
+chamfer(myShape, 1)
+
+// Chamfer only vertical edges
+chamfer(myShape, 2, { parallel: [0, 0, 1] })
 ```
 
-</details>
+`chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape`
 
-#### `chamferEdgeSegment()`
+#### `draft()` — Apply a draft angle (taper) to vertical faces for mold extraction.
 
-```ts
-chamferEdgeSegment(shape: Shape, segment: EdgeSegment, size: number): Shape
-```
+**Details**
 
-Apply a chamfer (beveled edge) to a mesh-selected edge. Works on any straight edge of any shape — not limited to tracked box edges.
+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°.
 
-#### `chamfer()`
+Requires the OCCT backend. Throws on Manifold.
+
+**Example**
 
 ```ts
-chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
+// Add 3° draft to a box for injection molding
+draft(myBox, 3)
+
+// Draft with custom pull direction and neutral plane
+draft(myShape, 2, [0, 0, 1], 10)
 ```
 
-Apply chamfers (beveled edges) to one or more edges of a shape. Works on both straight and curved edges. Supports OCCT and Manifold backends. // Chamfer all edges chamfer(myShape, 1) // Chamfer vertical edges only chamfer(myShape, 2, { parallel: [0, 0, 1] })
+`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.
 
-#### `draft()`
+**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
+
+Throws if no edges match the selection, or if `radius` is not a positive finite number.
+
+**Example**
 
 ```ts
-draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
+// Fillet all edges
+fillet(myShape, 2)
+
+// Fillet only top convex edges
+fillet(myShape, 1.5, { atZ: 20, convex: true })
+
+// Fillet vertical edges selected beforehand
+const edges = selectEdges(myShape, { parallel: [0, 0, 1] })
+fillet(myShape, 3, edges)
 ```
 
-Apply a draft angle (taper) to all faces of a solid for mold extraction. Draft angle is a manufacturing feature that adds taper to the vertical faces of a solid so that it can be extracted from a mold. The neutral plane is where the draft angle is zero — faces above and below are tapered symmetrically. Requires the OCCT backend. Throws on Manifold. // Add 3° draft to a box for injection molding draft(myBox, 3) // Draft with custom pull direction and neutral plane draft(myShape, 2, [0, 0, 1], 10)
+`fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape`
+
+#### `offsetSolid()` — Uniformly offset all surfaces of a solid inward or outward.
+
+**Details**
 
-#### `fillet()`
+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
-fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
+// Grow a box outward by 1mm on all sides
+offsetSolid(myBox, 1)
+
+// Shrink a shape inward by 0.5mm
+offsetSolid(myShape, -0.5)
 ```
 
-Apply fillets (rounded edges) to one or more edges of a shape. 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. - EdgeSegment: a single edge from selectEdge() - EdgeSegment[]: multiple edges from selectEdges() - EdgeQuery: inline query (same options as selectEdges) - undefined: all sharp edges on the shape // Fillet all edges fillet(myShape, 2) // Fillet edges at the top fillet(myShape, 1.5, { atZ: 20, convex: true }) // Fillet specific edges const edges = selectEdges(myShape, { parallel: [0, 0, 1] }) fillet(myShape, 3, edges)
+`offsetSolid(shape: Shape, thickness: number): Shape`
+
+#### `chamfer2d()` — Bevel a named vertical edge of a shape with a 45° chamfer.
 
-#### `offsetSolid()`
+**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
-offsetSolid(shape: Shape, thickness: number): Shape
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const chamfered = chamfer2d(b.toShape(), b.edge('vert-br'), 3, [-1, -1]);
 ```
 
-Uniformly offset all surfaces of a solid inward or outward by a thickness value. Unlike shell(), which hollows a solid, offsetSolid() produces a new solid whose surfaces are all shifted by the given thickness. Positive = outward, negative = inward. Requires the OCCT backend. Throws on Manifold. // Grow a box outward by 1mm on all sides offsetSolid(myBox, 1) // Shrink a shape inward by 0.5mm offsetSolid(myShape, -0.5)
+`chamfer2d(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape`
+
+**`EdgeRef`**
+- `query?: EdgeQueryRef` — Compiler-owned edge query when available.
+- Also: `name: EdgeName`
 
-#### `filletCorners()`
+#### `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`
+
+**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
-filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const filleted = fillet2d(b.toShape(), b.edge('vert-br'), 5, [-1, -1]);
 ```
 
-Create a polygon from points with specified corners rounded to arc fillets. Each corner spec identifies a vertex index and radius.
+`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><summary><code>FilletCornerSpec</code></summary>
+**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
+
+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.
+
+**Example**
 
 ```ts
-interface FilletCornerSpec {
-  index: number;
-  radius: number;
-  segments?: number;
-}
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
 ```
 
-</details>
+`filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch`
+
+`FilletCornerSpec`: `{ index: number, radius: number, segments?: number }`
 
 ---
 
@@ -861,92 +874,93 @@ interface FilletCornerSpec {
 
 Duplicate geometry in regular arrangements (linear, circular, mirror).
 
-#### `circularLayout()`
+#### `circularLayout()` — Compute evenly-spaced positions around a circle.
 
-```ts
-circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
-```
-
-Compute evenly-spaced positions around a circle. Eliminates the most common trig pattern in CAD scripts: ```js // Before — manual trig for (let i = 0; i < 12; i++) { const angle = i * 30 * Math.PI / 180; markers.push(marker.translate(r * Math.cos(angle), r * Math.sin(angle), 0)); } // After — declarative for (const {x, y} of circularLayout(12, r)) { markers.push(marker.translate(x, y, 0)); } ```
+Eliminates the most common trig pattern in CAD scripts:
 
-<details><summary><code>CircularLayoutOptions</code></summary>
+```js
+// Before — manual trig
+for (let i = 0; i < 12; i++) {
+  const angle = i * 30 * Math.PI / 180;
+  markers.push(marker.translate(r * Math.cos(angle), r * Math.sin(angle), 0));
+}
 
-```ts
-interface CircularLayoutOptions {
-  /** Angle of the first element in degrees (default: 0 = +X axis). */
-  startDeg?: number;
-  /** Center X coordinate (default: 0). */
-  centerX?: number;
-  /** Center Y coordinate (default: 0). */
-  centerY?: number;
+// After — declarative
+for (const {x, y} of circularLayout(12, r)) {
+  markers.push(marker.translate(x, y, 0));
 }
 ```
 
-</details>
+`circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]`
 
-<details><summary><code>LayoutPoint</code></summary>
+**`CircularLayoutOptions`**
+- `startDeg?: number` — Angle of the first element in degrees (default: 0 = +X axis).
+- `centerX?: number` — Center X coordinate (default: 0).
+- `centerY?: number` — Center Y coordinate (default: 0).
 
-```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
-```
+`LayoutPoint`: `{ x: number, y: number }`
 
-</details>
+#### `circularPattern()` — Repeat a shape in a circular pattern around an axis and union the copies.
 
-#### `circularPattern()`
+**Details**
 
-```ts
-circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
-```
+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.
 
-Repeat a shape in a circular pattern around an axis and union the copies. Simple usage (Z axis, matches legacy signature): circularPattern(shape, 6) circularPattern(shape, 6, 10, 20)           // centerX=10, centerY=20 Advanced usage (arbitrary axis): circularPattern(shape, 6, { axis: [1, 0, 0], origin: [0, 0, 50] })
+Two calling conventions: - **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)` - **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
 
-<details><summary><code>CircularPatternOptions</code></summary>
+**Example**
 
 ```ts
-interface CircularPatternOptions {
-  /** Center X of the rotation (default: 0). Used when axis is Z (legacy mode). */
-  centerX?: number;
-  /** Center Y of the rotation (default: 0). Used when axis is Z (legacy mode). */
-  centerY?: number;
-}
+// 8 holes evenly spaced around origin
+circularPattern(cylinder(12, 4).translate(30, 0, -1), 8)
+
+// Circular pattern around X axis
+circularPattern(myFeature, 4, { axis: [1, 0, 0], origin: [0, 0, 50] })
 ```
 
-</details>
+`circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape`
 
-#### `circularPattern2d()`
+**`CircularPatternOptions`**
+- `centerX?: number` — Center X of the rotation (default: 0). Used when axis is Z (legacy mode).
+- `centerY?: number` — Center Y of the rotation (default: 0). Used when axis is Z (legacy mode).
 
-```ts
-circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
-```
+#### `circularPattern2d()` — Repeat a 2D sketch in a circular pattern around a center point and union the copies.
 
-Repeat a sketch in a circular pattern around a center point
+`circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch`
 
-#### `linearPattern()`
+#### `linearPattern()` — Repeat a shape in a linear pattern along a direction vector and union the copies.
 
-```ts
-linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
-```
+**Details**
 
-Repeat a shape in a linear pattern along a direction vector and union the copies.
+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.
 
-#### `linearPattern2d()`
+**Example**
 
 ```ts
-linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+// 5 cylinders, 20mm apart along X
+linearPattern(cylinder(10, 3), 5, 20, 0)
 ```
 
-Repeat a sketch in a linear pattern
+`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`
+
+#### `mirrorCopy()` — Mirror a shape across a plane and union the mirror with the original.
 
-#### `mirrorCopy()`
+**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
-mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+// Mirror across the YZ plane (X=0)
+mirrorCopy(box(50, 30, 10), [1, 0, 0])
 ```
 
-Mirror a shape across a plane defined by its normal and union the mirror with the original.
+`mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape`
 
 ---
 
@@ -954,177 +968,190 @@ Mirror a shape across a plane defined by its normal and union the mirror with th
 
 Define geometry by relationships and let a solver find positions.
 
-#### `addPolygon()`
+#### `addPolygon()` — Add a general polygon concept to the builder.
 
-```ts
-addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon
-```
+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.
 
-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. The user is responsible for all dimensional constraints. ```ts const sk = constrainedSketch(); const tri = addPolygon(sk, { points: [[0,0],[100,0],[50,80]] }); sk.fix(tri.vertex(0), 0, 0); sk.length(tri.side(0), 100); ```
+Use `sk.addPolygon()` as the shorthand builder method.
 
-<details><summary><code>PolygonOptions</code></summary>
+**Example**
 
 ```ts
-interface PolygonOptions {
-  /** Whether to register a closed loop for sketch generation. Default: true. */
-  addLoop?: boolean;
-  /** Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false. */
-  blockRotation?: boolean;
-}
+const sk = constrainedSketch();
+const tri = sk.addPolygon({ points: [[0,0],[100,0],[50,80]] });
+sk.fix(tri.vertex(0), 0, 0);
+sk.length(tri.side(0), 100);
+return sk.solve().extrude(5);
 ```
 
-</details>
+`addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon`
 
-<details><summary><code>ConstrainedPolygon</code></summary>
+**`PolygonOptions`**
+- `addLoop?: boolean` — Whether to register a closed loop for sketch generation. Default: true.
+- `blockRotation?: boolean` — Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false.
 
-```ts
-interface ConstrainedPolygon {
-  /** CCW-ordered PointIds. */
-  vertices: PointId[];
-  /** CCW-ordered LineIds. `sides[i]` runs from `vertices[i]` → `vertices[(i+1) % n]`. */
-  sides: LineId[];
-  /** ShapeId for `shapeWidth`, `shapeHeight`, `shapeArea`, `shapeCentroidX/Y`. */
-  shape: ShapeId;
-}
-```
+**`ConstrainedPolygon`**
+- `vertices: PointId[]` — CCW-ordered PointIds.
+- `sides: LineId[]` — CCW-ordered LineIds. `sides[i]` runs from `vertices[i]` → `vertices[(i+1) % n]`.
+- `shape: ShapeId` — ShapeId for `shapeWidth`, `shapeHeight`, `shapeArea`, `shapeCentroidX/Y`.
+
+#### `addRect()` — Add an axis-aligned rectangle concept to the builder.
+
+Creates 4 vertices (CCW: bl→br→tr→tl), 4 sides, 4 structural constraints (`horizontal`/`vertical` on each side), CCW winding, a center point, a loop, and a shape. Returns a `ConstrainedRect` handle with 4 DOF (x, y, width, height).
 
-</details>
+Use `sk.rect()` as the shorthand builder method.
 
-#### `addRect()`
+**Example**
 
 ```ts
-addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect
+const sk = constrainedSketch();
+const r = sk.rect({ x: 0, y: 0, width: 100, height: 50 });
+sk.fix(r.bottomLeft, 0, 0);
+sk.length(r.bottom, 120);  // override initial width
+return sk.solve().extrude(10);
 ```
 
-Add an axis-aligned rectangle concept to the builder. Creates 4 vertices (CCW: bl→br→tr→tl), 4 sides, applies 4 structural constraints (`horizontal`/`vertical` on each side), enforces CCW winding, registers a loop and a shape, and returns a `ConstrainedRect` handle. ```ts const sk = constrainedSketch(); const rect = addRect(sk, { x: 0, y: 0, width: 100, height: 50 }); sk.fix(rect.bottomLeft, 0, 0); sk.length(rect.bottom, 120); ```
+`addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect`
 
-<details><summary><code>RectOptions</code></summary>
+**`RectOptions`**
 
-```ts
-interface RectOptions {
-  /** Bottom-left x coordinate. Default: 0. */
-  x?: number;
-  /** Bottom-left y coordinate. Default: 0. */
-  y?: number;
-  /** Width (along x). Default: 10. */
-  width?: number;
-  /** Height (along y). Default: 10. */
-  height?: number;
-  /** Prevent 180° rotation (ensures bottom edge points rightward). Default: false. */
-  blockRotation?: boolean;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `x?` | `number` | Bottom-left x coordinate. Default: 0. |
+| `y?` | `number` | Bottom-left y coordinate. Default: 0. |
+| `width?` | `number` | Width (along x). Default: 10. |
+| `height?` | `number` | Height (along y). Default: 10. |
+| `blockRotation?` | `boolean` | Prevent 180° rotation (ensures bottom edge points rightward). Default: false. |
 
-</details>
+**`ConstrainedRect`**
 
-<details><summary><code>ConstrainedRect</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `bottom` | `LineId` | bottom-left → bottom-right |
+| `right` | `LineId` | bottom-right → top-right |
+| `top` | `LineId` | top-right → top-left |
+| `left` | `LineId` | top-left → bottom-left |
+| `center` | `PointId` | Center point constrained to the geometric center via `midpoint` on the diagonal. Can be used in further constraints: `sk.fix(rect.center, 0, 0)`, `sk.coincident(rect.center, other)`. |
+| `shape` | `ShapeId` | ShapeId for `shapeWidth`, `shapeHeight`, `shapeArea`, `shapeCentroidX/Y`. |
+| `bottomLeft`, `bottomRight`, `topRight`, `topLeft` | | — |
 
-```ts
-interface ConstrainedRect {
-  bottomLeft: PointId;
-  bottomRight: PointId;
-  topRight: PointId;
-  topLeft: PointId;
-  /** bottom-left → bottom-right */
-  bottom: LineId;
-  /** bottom-right → top-right */
-  right: LineId;
-  /** top-right → top-left */
-  top: LineId;
-  /** top-left → bottom-left */
-  left: LineId;
-  /** Center point constrained to the geometric center via `midpoint` on the diagonal. Can be used in further constraints: `sk.fix(rect.center, 0, 0)`, `sk.coincident(rect.center, other)`. */
-  center: PointId;
-  /** ShapeId for `shapeWidth`, `shapeHeight`, `shapeArea`, `shapeCentroidX/Y`. */
-  shape: ShapeId;
-}
-```
+#### `addRegularPolygon()` — Add a regular n-gon concept to the builder.
 
-</details>
+Vertices are placed at `(cx + r·cos(startAngle + i·2π/n), cy + r·sin(...))`. Equal-radius and equal-side constraints enforce regularity (4 DOF: center x/y, radius, rotation). The center point is tracked by the solver and exposed via the returned handle.
 
-#### `addRegularPolygon()`
+Use `sk.regularPolygon()` as the shorthand builder method.
+
+**Example**
 
 ```ts
-addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon
+const sk = constrainedSketch();
+const hex = sk.regularPolygon({ sides: 6, radius: 25 });
+sk.fix(hex.center, 0, 0);
+sk.length(hex.side(0), 30);  // all sides change (equal constraint)
+return sk.solve().extrude(5);
 ```
 
-Add a regular n-gon concept to the builder. Vertices are placed at `(cx + r·cos(startAngle + i·2π/n), cy + r·sin(...))`. Equal-side constraints enforce regularity. The center point is constrained to the centroid via midpoint constraints on the first diagonal. ```ts const sk = constrainedSketch(); const hex = addRegularPolygon(sk, { sides: 6, radius: 25, cx: 0, cy: 0 }); sk.fix(hex.center, 0, 0); sk.length(hex.side(0), 30);  // changes all sides (equal constraint) ```
+`addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon`
 
-<details><summary><code>RegularPolygonOptions</code></summary>
+**`RegularPolygonOptions`**
 
-```ts
-interface RegularPolygonOptions {
-  /** Number of sides (minimum 3). */
-  sides: number;
-  /** Circumradius — distance from center to vertex. Default: 10. */
-  radius?: number;
-  /** Center x coordinate. Default: 0. */
-  cx?: number;
-  /** Center y coordinate. Default: 0. */
-  cy?: number;
-  /** Angle (in degrees) of vertex[0] measured from the +X axis (CCW positive). Default: 0 (rightmost vertex). */
-  startAngle?: number;
-  /** Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false. */
-  blockRotation?: boolean;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `sides` | `number` | Number of sides (minimum 3). |
+| `radius?` | `number` | Circumradius — distance from center to vertex. Default: 10. |
+| `cx?` | `number` | Center x coordinate. Default: 0. |
+| `cy?` | `number` | Center y coordinate. Default: 0. |
+| `startAngle?` | `number` | Angle (in degrees) of vertex[0] measured from the +X axis (CCW positive). Default: 0 (rightmost vertex). |
+| `blockRotation?` | `boolean` | Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false. |
 
-</details>
 
+**`ConstrainedRegularPolygon`** extends ConstrainedPolygon
+- `center: PointId` — Center point. Use `sk.fix(poly.center, x, y)` to pin location, or `sk.coincident(poly.center, other)` to align with other geometry.
 
-<details><summary><code>ConstrainedRegularPolygon</code> extends ConstrainedPolygon</summary>
+#### `circle()` — Create an analytic 2D circle for measurement, construction, and extrusion.
+
+**Example**
 
 ```ts
-interface ConstrainedRegularPolygon extends ConstrainedPolygon {
-  /** Center point. Use `sk.fix(poly.center, x, y)` to pin location, or `sk.coincident(poly.center, other)` to align with other geometry. */
-  center: PointId;
-}
+const c = circle(0, 0, 25);
+c.diameter; c.circumference; c.area;
+c.pointAtAngle(90);  // Point2D at top (90° CCW from +X)
+
+// Extrude to cylinder with named faces
+const cyl = c.extrude(30);
+cyl.face('top');   // FaceRef (planar)
+cyl.face('side');  // FaceRef (curved)
+
+Circle2D.fromDiameter(point(0, 0), 50);
 ```
 
-</details>
+`circle(cx: number, cy: number, radius: number): Circle2D`
 
-#### `circle()`
+#### `constrainedSketch()` — Create a parametric 2D sketch driven by geometric constraints and a nonlinear solver.
 
-```ts
-circle(cx: number, cy: number, radius: number): Circle2D
-```
+**Workflow**
 
-Create an analytic 2D circle for measurement, construction, and extrusion. Provides diameter, circumference, area, and toSketch().
+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`).
 
-#### `constrainedSketch()`
+**Example**
 
 ```ts
-constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder
+const sk = constrainedSketch();
+const p1 = sk.point(0, 0);
+const p2 = sk.point(50, 0);
+const l1 = sk.line(p1, p2);
+sk.fix(p1, 0, 0);
+sk.horizontal(l1);
+sk.length(l1, 50);
+return sk.solve().extrude(10);
 ```
 
-Build a parametric 2D sketch with geometric constraints solved by the built-in constraint solver.
-
-<details><summary><code>ConstrainedSketchOptions</code></summary>
+**Solver status**
 
 ```ts
-interface ConstrainedSketchOptions {
-  /** When true, adding a constraint that cannot be satisfied throws instead of silently discarding it. */
-  strict?: boolean;
-}
+const result = sk.solve();
+result.constraintMeta.status;   // 'fully' | 'under' | 'over' | 'over-redundant'
+result.constraintMeta.dof;      // 0 = fully constrained
+result.constraintMeta.maxError; // residual — should be < 1e-6
+result.inspect();               // human-readable summary
+result.withUpdatedConstraint('cst-5', 120); // update a dimension without rebuilding
 ```
 
-</details>
+`constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder`
+
+**`ConstrainedSketchOptions`**
+- `strict?: boolean` — When true, adding a constraint that cannot be satisfied throws instead of silently discarding it.
 
-#### `line()`
+#### `line()` — Create an analytic 2D line segment between two points.
+
+**Example**
 
 ```ts
-line(x1: number, y1: number, x2: number, y2: number): Line2D
+const l = line(0, 0, 50, 0);
+l.length; l.midpoint; l.angle; l.direction;
+l.parallel(10);          // parallel line offset 10 (positive = left)
+l.intersect(l2);         // Point2D — treats lines as infinite
+l.intersectSegment(l2);  // Point2D or null — segments only
+
+Line2D.fromPointAndAngle(point(0, 0), 45, 100);
+Line2D.fromPointAndDirection(point(0, 0), [1, 1], 50);
 ```
 
-Create an analytic 2D line segment between two points. Provides length, midpoint, angle, intersection, and parallel helpers.
+`line(x1: number, y1: number, x2: number, y2: number): Line2D`
+
+#### `point()` — Create an analytic 2D point for measurement and construction geometry.
 
-#### `point()`
+**Example**
 
 ```ts
-point(x: number, y: number): Point2D
+const p = point(10, 20);
+p.distanceTo(point(30, 40));  // Euclidean distance
+p.midpointTo(point(30, 40)); // midpoint
+p.translate(5, 5);           // new shifted point
+p.toTuple();                 // [10, 20]
 ```
 
-Create an analytic 2D point for measurement and construction geometry.
+`point(x: number, y: number): Point2D`
 
 ---
 
@@ -1140,167 +1167,155 @@ Position geometry relative to other geometry using semantic anchors.
 
 Compose parts with joints for kinematic simulation.
 
-#### `assembly()`
+#### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
-```ts
-assembly(name?: string): Assembly
-```
+**Details**
 
-Create an assembly container with named parts and joints for kinematic mechanisms. Build with addPart(), addJoint(), addJointCoupling(), addGearCoupling(), then solve() to get positioned parts. Supports revolute, prismatic, and fixed joint types.
+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.
 
-#### `bomToCsv()`
+Three joint types are supported: `'revolute'` (hinge), `'prismatic'` (slider), and `'fixed'` (rigid attachment). Use `addPart()` to add geometry, `addJoint()` (or the shorthands `addRevolute()`, `addPrismatic()`, `addFixed()`) to connect parts, and `solve()` to compute world-space positions at a given joint state.
 
-```ts
-bomToCsv(rows: BomRow[]): string
-```
+The higher-level `connect()` API uses declared **connectors** to compute joint frames automatically. The `match()` API uses typed connectors (with gender and type metadata) for automatic compatibility validation and joint creation.
 
-Convert BOM rows from a solved assembly into a CSV string.
+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.
 
-<details><summary><code>BomRow</code></summary>
+**Example**
 
 ```ts
-interface BomRow {
-  part: string;
-  qty: number;
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  notes?: string;
-  metadata?: PartMetadata;
-}
+const mech = assembly("Arm")
+  .addPart("base", box(80, 80, 20, true), {
+    metadata: { material: "PETG", process: "FDM", qty: 1 },
+  })
+  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
+  .addRevolute("shoulder", "base", "link", {
+    axis: [0, 1, 0],
+    min: -30, max: 120, default: 25,
+    frame: Transform.identity().translate(0, 0, 20),
+  });
+
+return mech; // auto-solved at defaults, renders all parts
 ```
 
-</details>
+`assembly(name?: string): Assembly`
 
-<details><summary><code>PartMetadata</code></summary>
+#### `bomToCsv()` — Convert an array of BOM rows into a CSV string.
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+**Details**
 
-</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.
 
-#### `joint()`
+`bomToCsv(rows: BomRow[]): string`
 
-```ts
-joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
-```
+**`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
 
-Create a revolute (hinge) joint. Auto-creates a param slider and rotates the shape.
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-<details><summary><code>RevoluteJointOpts</code></summary>
+#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
 
-```ts
-interface RevoluteJointOpts {
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  reverse?: boolean;
-}
-```
+**Details**
 
-</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.
 
-#### `jointsView()`
+**Example**
 
 ```ts
-jointsView(options?: JointsViewOptions): void
+const arm = joint("Shoulder", armShape, [0, 0, 20], {
+  axis: [0, 1, 0],
+  min: -30, max: 120, default: 25,
+});
+return arm;
 ```
 
-Configure runtime joint controls that animate object transforms in the viewport without re-running the script.
+`joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape`
 
-<details><summary><code>JointsViewOptions</code></summary>
+`RevoluteJointOpts`: `{ min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
 
-```ts
-interface JointsViewOptions {
-  enabled?: boolean;
-  joints?: JointViewInput[];
-  couplings?: JointViewCouplingInput[];
-  animations?: JointViewAnimationInput[];
-  defaultAnimation?: string;
-}
-```
+#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
 
-</details>
+**Details**
 
-<details><summary><code>JointViewInput</code></summary>
+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.
 
-```ts
-interface JointViewInput {
-  name: string;
-  child: string;
-  parent?: string;
-  type?: JointViewType;
-  axis?: JointViewAxis;
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  hidden?: boolean;
-}
+**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.
+
+```js
+// BAD — double rotation
+const solved = mech.solve({ shoulder: 45, elbow: 30 });
+jointsView({ joints: [{ name: 'shoulder', ... }] });
+return solved;
+
+// GOOD — rest pose, jointsView controls all posing
+const solved = mech.solve({ shoulder: 0, elbow: 0 });
+jointsView({
+  joints: [
+    { name: 'shoulder', child: 'Upper Arm', default: 45, ... },
+    { name: 'elbow', child: 'Forearm', parent: 'Upper Arm', default: 30, ... },
+  ],
+});
+return solved;
 ```
 
-</details>
+**Pivot coordinates** are world-space positions of each joint origin at rest pose. For `addRevolute('shoulder', 'Base', 'Link', { frame: Transform.identity().translate(0, 0, 20) })` where "Base" is at world origin, the pivot is `[0, 0, 20]`.
 
-<details><summary><code>JointViewCouplingInput</code></summary>
+**Fixed attachments** that must follow a parent during animation need a zero-angle revolute joint in the chain:
 
-```ts
-interface JointViewCouplingInput {
-  joint: string;
-  terms: JointViewCouplingTermInput[];
-  offset?: number;
-}
+```js
+{ name: 'EE_Follow', child: 'End Effector', parent: 'Last Link',
+  type: 'revolute', axis: [0, 0, 1], pivot: [linkLength, 0, 0],
+  min: 0, max: 0, default: 0 }
 ```
 
-</details>
+Animation values are interpolated linearly between keyframes. ForgeCAD does **not** auto-wrap revolute values across `-180/180`. Keep keyframe values continuous — a `-180 -> 171` jump spins the part the long way around. Use `-180 -> -189` instead. Author high-speed multi-turn joints as accumulating angles (`0, 360, 720, ...`) with `continuous: true`.
 
-<details><summary><code>JointViewCouplingTermInput</code></summary>
+**Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
 
-```ts
-interface JointViewCouplingTermInput {
-  joint: string;
-  ratio?: number;
-}
+```js
+keyframes: [
+  { ticks: 3, values: { Shoulder: 20 } },  // slow segment (3x weight)
+  { ticks: 1, values: { Shoulder: -10 } }, // fast segment (1x weight)
+  { values: { Shoulder: 20 } },            // last keyframe; ticks ignored
+]
+// positions: 0, 0.75, 1.0
 ```
 
-</details>
+Mixing explicit `at` and omitted `at` in the same animation is not allowed.
 
-<details><summary><code>JointViewAnimationInput</code></summary>
+**Example**
 
-```ts
-interface JointViewAnimationInput {
-  name: string;
-  duration?: number;
-  loop?: boolean;
-  continuous?: boolean;
-  keyframes: JointViewAnimationKeyframeInput[];
-}
+```js
+jointsView({
+  joints: [{
+    name: 'Shoulder', child: 'Upper Arm', parent: 'Base',
+    type: 'revolute', axis: [0, -1, 0], pivot: [0, 0, 46],
+    min: -30, max: 110, default: 15,
+  }],
+  animations: [{
+    name: 'Walk Cycle', duration: 1.6, loop: true,
+    keyframes: [
+      { values: { Shoulder: 20 } },
+      { values: { Shoulder: -10 } },
+      { values: { Shoulder: 20 } },
+    ],
+  }],
+});
 ```
 
-</details>
+`jointsView(options?: JointsViewOptions): void`
 
-<details><summary><code>JointViewAnimationKeyframeInput</code></summary>
+**`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
 
-```ts
-interface JointViewAnimationKeyframeInput {
-  /** Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights. */
-  at?: number;
-  /** Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored. */
-  ticks?: number;
-  values: Record<string, number>;
-}
-```
+**`JointViewInput`**: `name: string`, `child: string`, `parent?: string`, `type?: JointViewType`, `axis?: JointViewAxis`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `hidden?: boolean`
+
+`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
+
+`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
+
+`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
 
-</details>
+**`JointViewAnimationKeyframeInput`**
+- `at?: number` — Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights.
+- `ticks?: number` — Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored.
+- Also: `values: Record<string, number>`
 
 ---
 
@@ -1308,784 +1323,590 @@ interface JointViewAnimationKeyframeInput {
 
 Declare user-facing controls that drive model geometry.
 
-#### `boolParam()`
+#### `boolParam()` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-```ts
-boolParam(name: string, defaultValue: boolean): boolean
-```
+**Details**
 
-Declare a boolean parameter. Returns the current boolean value. Renders as a checkbox in the UI.
+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.
 
-#### `choiceParam()`
+**Example**
 
 ```ts
-choiceParam(name: string, defaultValue: string, choices: string[]): string
+const showHoles = boolParam("Show Holes", true);
+if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
+return plate;
 ```
 
-Declare a choice parameter. Returns the selected string label. Renders as a dropdown in the UI. `defaultValue` must match one of the supplied `choices`. Overrides may be passed either as the choice label or as a numeric index, but labels are preferred because they are clearer in CLI/import usage.
-
-#### `listParam()`
+Override via import:
 
 ```ts
-listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
+const pan = require("./pan.forge.js", { "Show Lid": 0 });
 ```
 
-Declare a list parameter — an array of struct items with per-field controls. Returns the current list of items (with overrides applied). Each item is an object whose fields match the keys in defaultItems. Boolean fields (marked with `boolean: true` in field defs) return as booleans. Choice fields (marked with `choices: [...]` in field defs) return as strings. All other fields return as numbers.
+`boolParam(name: string, defaultValue: boolean): boolean`
 
-<details><summary><code>ListParamFieldDef</code></summary>
+#### `choiceParam()` — Declare a choice parameter that renders as a dropdown in the UI.
 
-```ts
-interface ListParamFieldDef {
-  min?: number;
-  max?: number;
-  step?: number;
-  unit?: string;
-  integer?: boolean;
-  boolean?: boolean;
-  choices?: string[];
-}
-```
+**Details**
+
+`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.
 
-</details>
+Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
 
-#### `param()`
+**Example**
 
 ```ts
-param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
+const panStyle = choiceParam("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
+if (panStyle === "wok") return buildWok();
 ```
 
-Declare a parameter. Returns the current value (default or overridden). Each call registers the param for UI generation.
-
-#### `dim()`
+Override via import:
 
 ```ts
-dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void
+const pan = require("./pan.forge.js", { "Pan Style": "wok" });
 ```
 
-Add a dimension annotation between two points.
-
-<details><summary><code>DimOpts</code></summary>
+Override via CLI:
 
-```ts
-interface DimOpts {
-  offset?: number;
-  label?: string;
-  color?: string;
-  component?: string | string[];
-  currentComponent?: boolean;
-}
+```bash
+forgecad run model.forge.js --param "Pan Style=wok"
 ```
 
-</details>
+`choiceParam(name: string, defaultValue: string, choices: string[]): string`
 
-#### `dimLine()`
+#### `listParam()` — Declare a list parameter — an array of struct items with per-field UI controls.
 
-```ts
-dimLine(l: Line2D, opts?: DimOpts): void
-```
+**Details**
 
-Add a dimension annotation along a Line2D.
+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.
 
----
+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`
 
-## C12: Dimensional Demotion
+`listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]`
 
-Extract 2D geometry from a 3D solid (section, projection).
+`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
 
-#### `faceProfile()`
+#### `param()` — Declare a numeric parameter that renders as a slider in the UI.
 
-```ts
-faceProfile(shape: Shape, face: FaceSelector): Sketch
-```
+**Details**
 
-#### `intersectWithPlane()`
+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
-intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch
-```
+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
 
-Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
+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`).
 
-#### `projectToPlane()`
+**Example**
 
 ```ts
-projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
+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 });
 ```
 
-Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
+**Parameter overrides** — key must match `name` exactly:
 
----
+```ts
+// Via require()
+const bracket = require("./bracket.forge.js", { Width: 80 });
 
-## C13: Export & Output
+// Via CLI
+// forgecad run model.forge.js --param "Wall Thickness=3"
+```
 
-Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF).
+`param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number`
 
-#### `bom()`
+#### `dim()` — Add a dimension annotation between two points.
 
-```ts
-bom(quantity: number, description: string, opts?: BomOpts): void
-```
+**Details**
 
-Add a bill-of-materials entry.
+Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
 
-<details><summary><code>BomOpts</code></summary>
+Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or `Point2D` objects (Z is treated as 0 for 2D inputs).
 
-```ts
-interface BomOpts {
-  /** Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" */
-  unit?: string;
-  /** Optional explicit grouping key used during report aggregation. */
-  key?: string;
-}
-```
+**Ownership Rules (Report Pages)**
 
-</details>
+- `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.
 
-#### `robotExport()`
+**Example**
 
 ```ts
-robotExport(options: RobotExportOptions): CollectedRobotExport
+dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
+dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
+dim([0, 0, 0], [100, 0, 0], { component: "Base", color: "#00AAFF" });
 ```
 
-Declare that the current script should export an assembly as a robot package for the SDF CLI. Configures inertial properties, joint limits, and optional plugins (e.g. diff-drive for Gazebo).
-
-<details><summary><code>RobotExportOptions</code></summary>
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
 
-```ts
-interface 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;
-}
-```
+`dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void`
 
-</details>
+`DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
 
-<details><summary><code>RobotLinkExportOptions</code></summary>
+#### `dimLine()` — Add a dimension annotation along a `Line2D`.
 
-```ts
-interface RobotLinkExportOptions {
-  massKg?: number;
-  densityKgM3?: number;
-  collision?: "visual" | "convex" | "box" | "none";
-}
-```
+**Details**
 
-</details>
+Convenience wrapper around { points from a constrained-sketch `Line2D` entity. All `opts` are forwarded unchanged.
 
-<details><summary><code>RobotJointExportOptions</code></summary>
+**Example**
 
 ```ts
-interface RobotJointExportOptions {
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
 ```
 
-</details>
+`dimLine(l: Line2D, opts?: DimOpts): void`
 
-<details><summary><code>RobotDiffDrivePluginOptions</code></summary>
+---
 
-```ts
-interface RobotDiffDrivePluginOptions {
-  leftJoints: string[];
-  rightJoints: string[];
-  wheelSeparationMm: number;
-  wheelRadiusMm: number;
-  topic?: string;
-  odomTopic?: string;
-  tfTopic?: string;
-  frameId?: string;
-  odomFrameId?: string;
-  maxLinearVelocity?: number;
-  maxAngularVelocity?: number;
-  linearAcceleration?: number;
-  angularAcceleration?: number;
-}
-```
+## C12: Dimensional Demotion
 
-</details>
+Extract 2D geometry from a 3D solid (section, projection).
 
-<details><summary><code>RobotJointStatePublisherOptions</code></summary>
+#### `faceProfile()` — Extract the boundary profile of a named face as a 2D sketch.
 
-```ts
-interface RobotJointStatePublisherOptions {
-  enabled?: boolean;
-  joints?: string[];
-  topic?: string;
-  updateRate?: number;
-}
-```
+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.
 
-</details>
+`faceProfile(shape: Shape, face: FaceSelector): Sketch`
 
-<details><summary><code>RobotWorldOptions</code></summary>
+#### `intersectWithPlane()` — Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
 
-```ts
-interface RobotWorldOptions {
-  name?: string;
-  generateDemoWorld?: boolean;
-  spawnPose?: RobotPose6;
-  keyboardTeleop?: RobotWorldKeyboardTeleopOptions;
-}
-```
+`intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch`
 
-</details>
+#### `projectToPlane()` — Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
 
-<details><summary><code>RobotWorldKeyboardTeleopOptions</code></summary>
+`projectToPlane(shape: Shape, plane: PlaneSpec): Sketch`
 
-```ts
-interface RobotWorldKeyboardTeleopOptions {
-  enabled?: boolean;
-  linearStep?: number;
-  angularStep?: number;
-}
-```
+---
 
-</details>
+## C13: Export & Output
 
-<details><summary><code>CollectedRobotExport</code></summary>
+Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF).
 
-```ts
-interface CollectedRobotExport {
-  modelName: string;
-  assembly: AssemblyDefinition;
-  state: JointState;
-  static: boolean;
-  selfCollide: boolean;
-  allowAutoDisable: boolean;
-  links: Record<string, RobotLinkExportOptions>;
-  joints: Record<string, RobotJointExportOptions>;
-  diffDrive?: RobotDiffDrivePluginOptions;
-  jointStatePublisher?: RobotJointStatePublisherOptions;
-  world: RobotWorldOptions | null;
-}
-```
+#### `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.
 
-</details>
+- `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.
 
-<details><summary><code>AssemblyDefinition</code></summary>
+**Example**
 
 ```ts
-interface AssemblyDefinition {
-  name: string;
-  parts: AssemblyPartDef[];
-  joints: AssemblyJointDef[];
-  jointCouplings: AssemblyJointCouplingDef[];
-}
+const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
+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
 ```
 
-</details>
+`bom(quantity: number, description: string, opts?: BomOpts): void`
 
-<details><summary><code>AssemblyPartDef</code></summary>
+**`BomOpts`**
+- `unit?: string` — Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces"
+- `key?: string` — Optional explicit grouping key used during report aggregation.
 
-```ts
-interface AssemblyPartDef {
-  name: string;
-  part: AssemblyPart;
-  base: Transform;
-  metadata?: PartMetadata;
-}
-```
+#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
 
-</details>
+**Details**
 
-<details><summary><code>PartMetadata</code></summary>
+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`
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+**Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
-</details>
+| 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 | |
 
-<details><summary><code>AssemblyJointDef</code></summary>
+**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.
+
+**Example**
 
 ```ts
-interface AssemblyJointDef {
-  name: string;
-  type: JointType;
-  parent: string;
-  child: string;
-  frame: Transform;
-  axis: Vec3;
-  min?: number;
-  max?: number;
-  defaultValue: number;
-  unit?: string;
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
+const rover = assembly("Scout")
+  .addPart("Chassis", box(300, 220, 50, true))
+  .addPart("Left Wheel", cylinder(30, 60, undefined, 48, true))
+  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, 140, 60),
+    effort: 20, velocity: 1080,
+  });
 
-</details>
+robotExport({
+  assembly: rover,
+  modelName: "Scout",
+  links: {
+    Chassis: { massKg: 10 },
+    "Left Wheel": { massKg: 0.8 },
+  },
+  plugins: {
+    diffDrive: {
+      leftJoints: ["leftWheel"], rightJoints: ["rightWheel"],
+      wheelSeparationMm: 280, wheelRadiusMm: 60,
+    },
+  },
+  world: { generateDemoWorld: true },
+});
+```
 
-<details><summary><code>AssemblyJointCouplingDef</code></summary>
+**CLI usage**
 
-```ts
-interface AssemblyJointCouplingDef {
-  joint: string;
-  terms: JointCouplingTermRecord[];
-  offset: number;
-}
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
 ```
 
-</details>
+`robotExport(options: RobotExportOptions): CollectedRobotExport`
 
-<details><summary><code>JointCouplingTermRecord</code></summary>
+**`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`
 
-```ts
-interface JointCouplingTermRecord {
-  joint: string;
-  ratio: number;
-}
-```
+`RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
 
-</details>
+`RobotJointExportOptions`: `{ effort?: number, velocity?: number, damping?: number, friction?: number }`
 
-#### `sheetMetal()`
+**`RobotDiffDrivePluginOptions`**: `leftJoints: string[]`, `rightJoints: string[]`, `wheelSeparationMm: number`, `wheelRadiusMm: number`, `topic?: string`, `odomTopic?: string`, `tfTopic?: string`, `frameId?: string`, `odomFrameId?: string`, `maxLinearVelocity?: number`, `maxAngularVelocity?: number`, `linearAcceleration?: number`, `angularAcceleration?: number`
 
-```ts
-sheetMetal(options: SheetMetalOptions): SheetMetalPart
-```
+`RobotJointStatePublisherOptions`: `{ enabled?: boolean, joints?: string[], topic?: string, updateRate?: number }`
 
-Create a sheet-metal part with flanges, bend allowances, and flat pattern unfolding. Define the base panel, thickness, bend radius, and K-factor, then chain .flange() and .cutout() calls. Materialize with .folded() or .flatPattern().
+`RobotWorldOptions`: `{ name?: string, generateDemoWorld?: boolean, spawnPose?: RobotPose6, keyboardTeleop?: RobotWorldKeyboardTeleopOptions }`
 
-<details><summary><code>SheetMetalOptions</code></summary>
+`RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-```ts
-interface SheetMetalOptions {
-  width: number;
-  height: number;
-  thickness: number;
-  bendRadius: number;
-  kFactor: number;
-  kind?: "rect";
-  size: number;
-}
-```
+**`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world: RobotWorldOptions | null`
 
-</details>
+`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
 
-#### `sketchToDxf()`
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-```ts
-sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
-```
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible). For regular sketches, each polygon loop becomes a closed LWPOLYLINE. For constraint sketches, exports LINE, CIRCLE, and ARC entities from the constraint edge geometry.
+**`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`
 
-<details><summary><code>SketchDxfOptions</code></summary>
+`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
 
-```ts
-interface SketchDxfOptions {
-  /** DXF layer name. Default: "0" */
-  layer?: string;
-  /** DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black) */
-  colorIndex?: number;
-}
-```
+`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
-</details>
+#### `sheetMetal()` — Create a parametric sheet metal part with flanges, bend allowances, and flat-pattern unfolding.
 
-#### `sketchToSvg()`
+**Details**
 
-```ts
-sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
-```
+`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.
 
-Export a 2D sketch as an SVG string. For regular sketches, exports filled polygon regions. For constraint sketches, exports line/arc/circle edge geometry. The SVG uses the sketch's native coordinate system (Y-up) with a transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
+**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.
 
-<details><summary><code>SketchSvgOptions</code></summary>
+**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.
+
+**Example**
 
 ```ts
-interface SketchSvgOptions {
-  /** Stroke color. Default: "black" */
-  stroke?: string;
-  /** Stroke width in sketch units. Default: 0.5 */
-  strokeWidth?: number;
-  /** Fill color. Default: "none" */
-  fill?: string;
-  /** Padding around the sketch bounding box in sketch units. Default: 2 */
-  padding?: number;
-  /** If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. */
-  pixelsPerUnit?: number;
-}
+const cover = sheetMetal({
+  panel: { width: 180, height: 110 },
+  thickness: 1.5,
+  bendRadius: 2,
+  bendAllowance: { kFactor: 0.42 },
+  cornerRelief: { size: 4 },
+})
+  .flange('top',    { length: 18 })
+  .flange('right',  { length: 18 })
+  .flange('bottom', { length: 18 })
+  .flange('left',   { length: 18 })
+  .cutout('panel', rect(72, 36, true), { selfAnchor: 'center' })
+  .cutout('flange-right', roundedRect(26, 10, 5, true), { selfAnchor: 'center' });
+
+const folded = cover.folded();
+const flat   = cover.flatPattern();
 ```
 
-</details>
+`sheetMetal(options: SheetMetalOptions): SheetMetalPart`
 
----
+**`SheetMetalOptions`**
 
-## C14: Visual & Debugging
+| Option | Type | Description |
+|--------|------|-------------|
+| `width` | `number` | Width of the panel along the X axis. |
+| `height` | `number` | Height of the panel along the Y axis. |
+| `thickness` | `number` | Sheet thickness in mm. Applied uniformly across the panel and all flanges. |
+| `bendRadius` | `number` | Inside bend radius in mm. Must be ≥ 0. Typically 0.5–2× the sheet thickness. |
+| `kFactor` | `number` | K-factor (neutral-axis offset, 0–1). |
+| `kind?` | `"rect"` | Relief shape — only `'rect'` is supported in v1. |
+| `size` | `number` | Side length of the square relief cut in mm. |
 
-Control viewport appearance and debugging aids.
+#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
-#### `explodeView()`
+**Details**
 
-```ts
-explodeView(options?: ExplodeViewOptions): void
-```
+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.
 
-Configure viewport exploded-view behavior for the current script execution. Multiple calls merge; later values override earlier ones.
+The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
 
-<details><summary><code>ExplodeViewOptions</code></summary>
+**Example**
 
 ```ts
-interface ExplodeViewOptions {
-  /** Set false to disable viewport explode offsets for this script output. */
-  enabled?: boolean;
-  /** Scales the UI explode amount. Default: 1 */
-  amountScale?: number;
-  /** Per-depth stage multipliers (depth 1 = first level). If depth exceeds this array, the last value is reused. Default when omitted: reciprocal depth (1, 1/2, 1/3, ...) */
-  stages?: number[];
-  /** Global direction mode fallback. Default: 'radial' */
-  mode?: ExplodeViewDirection;
-  /** Global axis lock fallback. */
-  axisLock?: ExplodeAxis;
-  /** Per-object overrides by final object name. */
-  byName?: Record<string, ExplodeViewDirective>;
-  /** Per-tree-path overrides using slash-separated object tree segments. */
-  byPath?: Record<string, ExplodeViewDirective>;
-}
+const s = rect(100, 60);
+const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-</details>
+`sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string`
 
-<details><summary><code>ExplodeDirective</code></summary>
+**`SketchDxfOptions`**
+- `layer?: string` — DXF layer name. Default: "0"
+- `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
 
-```ts
-interface ExplodeDirective {
-  /** Multiplier applied to `amount` for this node */
-  stage?: number;
-  /** Direction mode for this node */
-  direction?: ExplodeDirection;
-  /** Optional axis lock after direction is resolved */
-  axisLock?: ExplodeAxis;
-}
-```
+#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
 
-</details>
+**Details**
 
-<details><summary><code>ExplodeViewDirective</code> extends ExplodeDirective</summary>
+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
-interface ExplodeViewDirective extends ExplodeDirective {
-}
+const s = rect(100, 60);
+const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
 ```
 
-</details>
+`sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string`
 
-#### `cutPlane()`
+**`SketchSvgOptions`**
 
-```ts
-cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `stroke?` | `string` | Stroke color. Default: "black" |
+| `strokeWidth?` | `number` | Stroke width in sketch units. Default: 0.5 |
+| `fill?` | `string` | Fill color. Default: "none" |
+| `padding?` | `number` | Padding around the sketch bounding box in sketch units. Default: 2 |
+| `pixelsPerUnit?` | `number` | If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. |
 
-<details><summary><code>CutPlaneOptions</code></summary>
+---
 
-```ts
-interface CutPlaneOptions {
-  /** Optional offset along the plane normal (primarily for object-form overload). */
-  offset?: number;
-  /** Object names to keep uncut for this plane. */
-  exclude?: CutPlaneExcludeInput;
-}
-```
+## C14: Visual & Debugging
 
-</details>
+Control viewport appearance and debugging aids.
 
-#### `scene()`
+#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
 
-```ts
-scene(options: SceneOptions): void
-```
+**Details**
 
-Configure the scene environment for the current script execution. Controls camera, lighting, background, fog, and post-processing. Multiple calls merge; later values override earlier ones. ```js scene({ background: '#0a0a0a', camera: { position: [200, 100, 150], target: [0, 0, 30], fov: 60 }, lights: [ { type: 'ambient', color: '#1a1a2e', intensity: 0.2 }, { type: 'point', position: [0, 0, 100], color: '#ff6b35', intensity: 2 }, ], fog: { color: '#0a0a0a', near: 100, far: 500 }, postProcessing: { bloom: { intensity: 1.5, threshold: 0.8, radius: 0.4 }, }, }); ```
+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.
 
-<details><summary><code>SceneOptions</code></summary>
+Multiple calls merge — later values override earlier ones on a per-key basis. `byName` and `byPath` maps are merged entry-by-entry.
 
-```ts
-interface SceneOptions {
-  background?: string | SceneBackgroundGradient;
-  camera?: SceneCameraConfig;
-  lights?: SceneLightConfig[];
-  environment?: SceneEnvironmentConfig;
-  fog?: SceneFogConfig;
-  postProcessing?: ScenePostProcessingConfig;
-  ground?: SceneGroundConfig;
-  /** Default capture parameters for `forgecad capture` — CLI flags override these. */
-  capture?: SceneCaptureConfig;
-}
+For programmatic explode applied before returning (without the slider), use `lib.explode()` instead.
+
+**Example**
+
+```js
+explodeView({
+  amountScale: 1.2,
+  stages: [0.35, 0.8],
+  mode: 'radial',
+  byPath: { 'Drive/Shaft': { direction: [1, 0, 0], stage: 1.6 } },
+});
 ```
 
-</details>
+`explodeView(options?: ExplodeViewOptions): void`
 
-<details><summary><code>SceneBackgroundGradient</code></summary>
+**`ExplodeViewOptions`**
 
-```ts
-interface SceneBackgroundGradient {
-  top: string;
-  bottom: string;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled?` | `boolean` | Set false to disable viewport explode offsets for this script output. |
+| `amountScale?` | `number` | Scales the UI explode amount. Default: 1 |
+| `stages?` | `number[]` | Per-depth stage multipliers (depth 1 = first level). If depth exceeds this array, the last value is reused. Default when omitted: reciprocal depth (1, 1/2, 1/3, ...) |
+| `mode?` | `ExplodeViewDirection` | Global direction mode fallback. Default: 'radial' |
+| `axisLock?` | `ExplodeAxis` | Global axis lock fallback. |
+| `byName?` | `Record<string, ExplodeViewDirective>` | Per-object overrides by final object name. |
+| `byPath?` | `Record<string, ExplodeViewDirective>` | Per-tree-path overrides using slash-separated object tree segments. |
 
-</details>
+**`ExplodeDirective`**
+- `stage?: number` — Multiplier applied to `amount` for this node
+- `direction?: ExplodeDirection` — Direction mode for this node
+- `axisLock?: ExplodeAxis` — Optional axis lock after direction is resolved
 
-<details><summary><code>SceneCameraConfig</code></summary>
+#### `cutPlane()`
 
-```ts
-interface SceneCameraConfig {
-  fov?: number;
-  type?: "perspective" | "orthographic";
-}
-```
+`cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void`
 
-</details>
+**`CutPlaneOptions`**
+- `offset?: number` — Optional offset along the plane normal (primarily for object-form overload).
+- `exclude?: CutPlaneExcludeInput` — Object names to keep uncut for this plane.
 
-<details><summary><code>SceneLightConfig</code></summary>
+#### `scene()` — Configure the scene environment for the current script execution.
 
-```ts
-interface SceneLightConfig {
-  type: SceneLightType;
-  color?: string;
-  intensity?: number;
-  /** Ground color for hemisphere lights */
-  groundColor?: string;
-  /** Sky color alias for hemisphere lights (same as color) */
-  skyColor?: string;
-  /** Spot light cone angle in radians */
-  angle?: number;
-  /** Spot light penumbra (0–1) */
-  penumbra?: number;
-  /** Point/spot light decay */
-  decay?: number;
-  /** Point/spot light distance (0 = infinite) */
-  distance?: number;
-  /** Whether this light casts shadows */
-  castShadow?: boolean;
-}
-```
+**Details**
 
-</details>
+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.
 
-<details><summary><code>SceneEnvironmentConfig</code></summary>
+When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
 
-```ts
-interface SceneEnvironmentConfig {
-  /** Built-in preset name or 'none' to disable */
-  preset?: "studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none";
-  /** Environment map intensity */
-  intensity?: number;
-  /** Use environment map as scene background */
-  background?: boolean;
-}
-```
+Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
 
-</details>
+Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
 
-<details><summary><code>SceneFogConfig</code></summary>
+All numeric values accept `param()` expressions.
 
-```ts
-interface SceneFogConfig {
-  color?: string;
-  /** Linear fog near distance */
-  near?: number;
-  /** Linear fog far distance */
-  far?: number;
-  /** Exponential fog density (if set, uses FogExp2 instead of linear Fog) */
-  density?: number;
-}
+**Example**
+
+```js
+scene({
+  background: { top: '#000814', bottom: '#001d3d' },
+  camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  lights: [
+    { type: 'ambient', color: '#001233', intensity: 0.08 },
+    { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
+    { type: 'point', position: [-100, 60, 20], color: '#f72585', intensity: 3, distance: 350 },
+    { type: 'directional', position: [50, -30, 200], color: '#ffd60a', intensity: 1.2 },
+    { type: 'hemisphere', skyColor: '#003566', groundColor: '#000814', intensity: 0.2 },
+  ],
+  fog: { color: '#000814', near: 100, far: 450 },
+  postProcessing: {
+    bloom: { intensity: param('bloom', 1.5, 0, 4), threshold: 0.5, radius: 0.7 },
+    vignette: { darkness: 0.8, offset: 0.25 },
+    grain: { intensity: 0.08 },
+    toneMappingExposure: param('exposure', 1.5, 0.5, 4),
+  },
+});
 ```
 
-</details>
+`scene(options: SceneOptions): void`
 
-<details><summary><code>ScenePostProcessingConfig</code></summary>
+**`SceneOptions`**
 
-```ts
-interface ScenePostProcessingConfig {
-  bloom?: SceneBloomConfig;
-  vignette?: SceneVignetteConfig;
-  grain?: SceneGrainConfig;
-  toneMappingExposure?: number;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
+| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
-</details>
+`SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
-<details><summary><code>SceneBloomConfig</code></summary>
+`SceneCameraConfig`: `{ fov?: number, type?: "perspective" | "orthographic" }`
 
-```ts
-interface SceneBloomConfig {
-  intensity?: number;
-  threshold?: number;
-  radius?: number;
-}
-```
+**`SceneLightConfig`**
 
-</details>
+| Option | Type | Description |
+|--------|------|-------------|
+| `groundColor?` | `string` | Ground color for hemisphere lights |
+| `skyColor?` | `string` | Sky color alias for hemisphere lights (same as color) |
+| `angle?` | `number` | Spot light cone angle in radians |
+| `penumbra?` | `number` | Spot light penumbra (0–1) |
+| `decay?` | `number` | Point/spot light decay |
+| `distance?` | `number` | Point/spot light distance (0 = infinite) |
+| `castShadow?` | `boolean` | Whether this light casts shadows |
+| `type`, `color?`, `intensity?` | | — |
 
-<details><summary><code>SceneVignetteConfig</code></summary>
+**`SceneEnvironmentConfig`**
+- `preset?: "studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none"` — Built-in preset name or 'none' to disable
+- `intensity?: number` — Environment map intensity
+- `background?: boolean` — Use environment map as scene background
 
-```ts
-interface SceneVignetteConfig {
-  darkness?: number;
-  offset?: number;
-}
-```
+**`SceneFogConfig`**
+- `near?: number` — Linear fog near distance
+- `far?: number` — Linear fog far distance
+- `density?: number` — Exponential fog density (if set, uses FogExp2 instead of linear Fog)
+- Also: `color?: string`
 
-</details>
+`ScenePostProcessingConfig`: `{ bloom?: SceneBloomConfig, vignette?: SceneVignetteConfig, grain?: SceneGrainConfig, toneMappingExposure?: number }`
 
-<details><summary><code>SceneGrainConfig</code></summary>
+`SceneBloomConfig`: `{ intensity?: number, threshold?: number, radius?: number }`
 
-```ts
-interface SceneGrainConfig {
-  intensity?: number;
-}
-```
+`SceneVignetteConfig`: `{ darkness?: number, offset?: number }`
 
-</details>
+`SceneGrainConfig`: `{ intensity?: number }`
 
-<details><summary><code>SceneGroundConfig</code></summary>
+**`SceneGroundConfig`**
 
-```ts
-interface SceneGroundConfig {
-  /** Show a ground plane */
-  visible?: boolean;
-  /** Ground color */
-  color?: string;
-  /** Offset below the model's bounding box minimum Z. Default 0 (flush with model bottom). */
-  offset?: number;
-  /** Receive shadows on the ground */
-  receiveShadow?: boolean;
-}
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `visible?` | `boolean` | Show a ground plane |
+| `color?` | `string` | Ground color |
+| `offset?` | `number` | Offset below the model's bounding box minimum Z. Default 0 (flush with model bottom). |
+| `receiveShadow?` | `boolean` | Receive shadows on the ground |
 
-</details>
+**`SceneCaptureConfig`**
 
-<details><summary><code>SceneCaptureConfig</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `framesPerTurn?` | `number` | Frames for one full orbit rotation (default: 72) |
+| `holdFrames?` | `number` | Frozen frames before motion starts (default: 6) |
+| `pitchDeg?` | `number` | Orbit pitch angle in degrees (default: auto from camera) |
+| `fps?` | `number` | Output frame rate (default: 24) |
+| `size?` | `number` | Output frame size in pixels (default: 960) |
+| `background?` | `string` | Canvas background color for capture (default: '#252526') |
 
-```ts
-interface SceneCaptureConfig {
-  /** Frames for one full orbit rotation (default: 72) */
-  framesPerTurn?: number;
-  /** Frozen frames before motion starts (default: 6) */
-  holdFrames?: number;
-  /** Orbit pitch angle in degrees (default: auto from camera) */
-  pitchDeg?: number;
-  /** Output frame rate (default: 24) */
-  fps?: number;
-  /** Output frame size in pixels (default: 960) */
-  size?: number;
-  /** Canvas background color for capture (default: '#252526') */
-  background?: string;
-}
-```
+#### `showLabels()` — Highlight all user-labeled faces on a shape for visual debugging.
 
-</details>
+Shows each user-authored label name in the viewport for visual debugging. Returns the shape unchanged for chaining: `return showLabels(myShape)`.
 
-#### `viewConfig()`
+`showLabels(shape: Shape): Shape`
 
-```ts
-viewConfig(options?: ViewConfigOptions): void
-```
+#### `viewConfig()` — Configure viewport helper visuals for the current script execution.
 
-Configure runtime viewport visuals for the current script execution. Multiple calls merge; later values override earlier ones.
+**Details**
 
-<details><summary><code>ViewConfigOptions</code></summary>
+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.
 
-```ts
-interface ViewConfigOptions {
-  jointOverlay?: JointOverlayViewConfigOptions;
-}
+This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
+
+**Example**
+
+```js
+viewConfig({
+  jointOverlay: {
+    axisColor: '#13dfff',
+    arcColor: '#ff7a1a',
+    axisLineRadiusScale: 0.03,
+    arcLineRadiusScale: 0.022,
+  },
+});
 ```
 
-</details>
+`viewConfig(options?: ViewConfigOptions): void`
 
-<details><summary><code>JointOverlayViewConfigOptions</code></summary>
+`ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
 
-```ts
-interface JointOverlayViewConfigOptions {
-  enabled?: boolean;
-  axisColor?: string;
-  axisCoreColor?: string;
-  arcColor?: string;
-  zeroColor?: string;
-  arcVisualLimitDeg?: number;
-  axisLengthScale?: number;
-  axisLengthMin?: number;
-  axisLineRadiusScale?: number;
-  axisLineRadiusMin?: number;
-  axisLineRadiusMax?: number;
-  spokeLineRadiusScale?: number;
-  spokeLineRadiusMin?: number;
-  spokeLineRadiusMax?: number;
-  arcLineRadiusScale?: number;
-  arcLineRadiusMin?: number;
-  arcLineRadiusMax?: number;
-  axisDotRadiusScale?: number;
-  axisDotRadiusMin?: number;
-  axisArrowRadiusScale?: number;
-  axisArrowRadiusMin?: number;
-  axisArrowLengthScale?: number;
-  axisArrowLengthMin?: number;
-  axisArrowOffsetFactor?: number;
-  arcRadiusScale?: number;
-  arcRadiusMin?: number;
-  arcDotRadiusScale?: number;
-  arcDotRadiusMin?: number;
-  arcArrowRadiusScale?: number;
-  arcArrowRadiusMin?: number;
-  arcArrowLengthScale?: number;
-  arcArrowLengthMin?: number;
-  arcArrowOffsetFactor?: number;
-  arcStepDeg?: number;
-  arcMinSteps?: number;
-  arcTubeSegmentsMin?: number;
-  arcTubeSegmentsFactor?: number;
-  arcTubeRadialSegments?: number;
-}
-```
+**`JointOverlayViewConfigOptions`**: `enabled?: boolean`, `axisColor?: string`, `axisCoreColor?: string`, `arcColor?: string`, `zeroColor?: string`, `arcVisualLimitDeg?: number`, `axisLengthScale?: number`, `axisLengthMin?: number`, `axisLineRadiusScale?: number`, `axisLineRadiusMin?: number`, `axisLineRadiusMax?: number`, `spokeLineRadiusScale?: number`, `spokeLineRadiusMin?: number`, `spokeLineRadiusMax?: number`, `arcLineRadiusScale?: number`, `arcLineRadiusMin?: number`, `arcLineRadiusMax?: number`, `axisDotRadiusScale?: number`, `axisDotRadiusMin?: number`, `axisArrowRadiusScale?: number`, `axisArrowRadiusMin?: number`, `axisArrowLengthScale?: number`, `axisArrowLengthMin?: number`, `axisArrowOffsetFactor?: number`, `arcRadiusScale?: number`, `arcRadiusMin?: number`, `arcDotRadiusScale?: number`, `arcDotRadiusMin?: number`, `arcArrowRadiusScale?: number`, `arcArrowRadiusMin?: number`, `arcArrowLengthScale?: number`, `arcArrowLengthMin?: number`, `arcArrowOffsetFactor?: number`, `arcStepDeg?: number`, `arcMinSteps?: number`, `arcTubeSegmentsMin?: number`, `arcTubeSegmentsFactor?: number`, `arcTubeRadialSegments?: number`
 
-</details>
+#### `spec()` — Create a named, reusable bundle of verification checks.
 
-#### `spec()`
+**Details**
 
-```ts
-spec(name: string, checkFn: (...args: any[]) => void): Spec
-```
+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.
 
-Create a named spec — a reusable bundle of verification checks. ```js const fitSpec = spec("Fits enclosure", (shape) => { verify.lessThan("Width",  shape.boundingBox().max[0] - shape.boundingBox().min[0], 200); verify.notEmpty("Has geometry", shape); }); fitSpec.check(myShape);   // grouped as "Fits enclosure" in the Checks panel fitSpec.check(otherShape); // can be reused on multiple shapes ``` calls `verify.*` methods. Any verify calls made inside this function are tagged with the spec name for grouped display.
+`spec.check()` returns a `SpecResult` — you can inspect it programmatically or ignore the return value and let the Checks panel show results.
 
-<details><summary><code>Spec</code></summary>
+**Example**
 
 ```ts
-interface Spec {
-  /** The display name of this spec */
-  name: string;
-}
+const printable = spec("Fits printer bed", (shape) => {
+  verify.notEmpty("Has geometry", shape);
+  const bb = shape.boundingBox();
+  verify.lessThan("Width  < 220mm", bb.max[0] - bb.min[0], 220);
+  verify.lessThan("Depth  < 220mm", bb.max[1] - bb.min[1], 220);
+  verify.lessThan("Height < 250mm", bb.max[2] - bb.min[2], 250);
+});
+
+// Reuse on multiple shapes
+printable.check(bracket);
+printable.check(standoff);
+
+// Check relationships between parts
+const fitSpec = spec("Assembly fit", (partA, partB) => {
+  verify.notColliding("No interference", partA, partB, 10);
+});
+fitSpec.check(bracket, standoff);
 ```
 
-</details>
+**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`
+
+**`Spec`**
+- `name: string` — The display name of this spec
 
 ---
 
@@ -2093,13 +1914,17 @@ interface Spec {
 
 Bring external geometry or other ForgeCAD modules into the current script.
 
-#### `group()`
+#### `group()` — Group multiple shapes/sketches for joint transforms without merging into a single mesh.
 
-```ts
-group(...items: GroupInput[]): ShapeGroup
-```
+Unlike union(), colors and individual identities are preserved. Children can be plain shapes, named descriptors ({ name, shape/sketch/group }), or nested groups. The returned ShapeGroup supports all Shape transforms (translate, rotate, etc.).
+
+**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);
+
+// 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 multiple shapes/sketches for joint transforms without merging into a single mesh. Unlike union(), colors and individual identities are preserved. Children can be plain shapes, named descriptors ({ name, shape/sketch/group }), or nested groups. The returned ShapeGroup supports all Shape transforms (translate, rotate, etc.).
+`group(...items: GroupInput[]): ShapeGroup`
 
 ---