forgecad 0.6.3 → 0.8.0

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

@@ -1,27 +1,25 @@
 # API by Concept
 
-> **Auto-generated** from `@concept` tags in `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Every public API function belongs to one of 16 fundamental concepts. This document groups them by concept rather than by module, making it easy to see the full set of operations for each idea.
 
 ## Concepts
 
-- **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(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. *(50 functions)*
+- **[C2: Boolean Combination](#c2-boolean-combination)** — Combine same-dimension geometry using CSG set operations. *(6 functions)*
 - **[C3: Rigid Transform](#c3-rigid-transform)** — Reposition or reorient geometry without changing its shape. *(3 functions)*
 - **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(12 functions)*
 - **[C5: Topology Query](#c5-topology-query)** — Select or inspect named faces and edges on a shape. *(3 functions)*
 - **[C6: Edge Feature](#c6-edge-feature)** — Modify edges of a solid — fillets, chamfers, draft, offset. *(7 functions)*
 - **[C7: Pattern Replication](#c7-pattern-replication)** — Duplicate geometry in regular arrangements (linear, circular, mirror). *(6 functions)*
-- **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(7 functions)*
-- **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(0 functions)*
+- **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(17 functions)*
+- **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(6 functions)*
 - **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(4 functions)*
-- **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(6 functions)*
+- **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(7 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(5 functions)*
-- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(5 functions)*
+- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(26 functions)*
 - **[C15: Import & Composition](#c15-import-composition)** — Bring external geometry or other ForgeCAD modules into the current script. *(1 functions)*
-- **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(0 functions)*
+- **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(4 functions)*
 
 ---
 
@@ -29,1362 +27,1882 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 
 Create geometry from parameters — no input geometry required.
 
-#### `arcBridgeBetweenRects()`
+#### `sdf.sphere()` — Create an SDF sphere centered at the origin.
 
 ```ts
-arcBridgeBetweenRects(rectA: RectAreaArg, rectB: RectAreaArg, segments?: number): Shape
+sdf.sphere(radius: number): SdfShape
 ```
 
-Build an arc bridge between two rectangular areas.
-
-#### `circle2d()`
+#### `sdf.box()` — Create an SDF box centered at the origin with given full dimensions (not half-extents).
 
 ```ts
-circle2d(radius: number, segments?: number): Sketch
+sdf.box(x: number, y: number, z: number): SdfShape
 ```
 
-Create a 2D circle centered at the origin. Use segments for lower-poly approximations.
-
-#### `ellipse()`
+#### `sdf.cylinder()` — Create an SDF cylinder centered at the origin, axis along Z.
 
 ```ts
-ellipse(rx: number, ry: number, segments?: number): Sketch
+sdf.cylinder(height: number, radius: number): SdfShape
 ```
 
-Create a 2D ellipse centered at the origin with the given X and Y radii.
-
-#### `loadFont()`
+#### `sdf.torus()` — Create an SDF torus centered at the origin, lying in the XY plane.
 
 ```ts
-loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font
+sdf.torus(majorRadius: number, minorRadius: number): SdfShape
 ```
 
-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)
-
-#### `ngon()`
+#### `sdf.capsule()` — Create an SDF capsule centered at the origin, axis along Z.
 
 ```ts
-ngon(sides: number, radius: number): Sketch
+sdf.capsule(height: number, radius: number): SdfShape
 ```
 
-Create a regular polygon (equilateral triangle, hexagon, etc.) inscribed in a circle of the given radius.
-
-#### `path()`
+#### `sdf.cone()` — Create an SDF cone with base at z=0 and tip at z=height.
 
 ```ts
-path(): PathBuilder
+sdf.cone(height: number, radius: number): SdfShape
 ```
 
-Create a path builder for constructing 2D outlines.
-
-#### `polar()`
+#### `sdf.smoothUnion()` — Smooth union — blends shapes together with a smooth transition radius.
 
 ```ts
-polar(length: number, angleDeg: number, from?: [ number, number ]): [ number, number ]
+sdf.smoothUnion(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
 ```
 
-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) ```
-
-#### `polygon()`
+#### `sdf.smoothDifference()` — Smooth difference — smoothly subtracts b from a.
 
 ```ts
-polygon(points: ([ number, number ] | Point2D)[]): Sketch
+sdf.smoothDifference(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
 ```
 
-Create a 2D polygon from an array of [x, y] points or Point2D objects. Winding is normalized to CCW.
-
-#### `polygonVertices()`
+#### `sdf.smoothIntersection()` — Smooth intersection — smoothly intersects a and b.
 
 ```ts
-polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
+sdf.smoothIntersection(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape
 ```
 
-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); ```
-
-<details><summary><code>PolygonVerticesOptions</code></summary>
+#### `sdf.morph()` — Morph between two SDF shapes. t=0 → a, t=1 → b.
 
 ```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;
-}
+sdf.morph(a: SdfShape, b: SdfShape, t: number): SdfShape
 ```
 
-</details>
-
-<details><summary><code>LayoutPoint</code></summary>
+#### `sdf.blend()` — Spatially blend between two SDF patterns. The blend function receives (x, y, z) and returns 0..1: 0 = fully pattern `a`, 1 = fully pattern `b`.
 
 ```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
+sdf.blend(a: SdfShape, b: SdfShape, fn: (x: number, y: number, z: number) => number, options?: BlendOptions): SdfShape
 ```
 
-</details>
+**`BlendOptions`**
+- `constants?: Record<string, number>` — Optional named constants accessible in the blend function.
 
-#### `rect()`
+#### `sdf.gyroid()` — Gyroid TPMS lattice — the most common lattice for additive manufacturing.
 
 ```ts
-rect(width: number, height: number, center?: boolean): Sketch
+sdf.gyroid(options: TpmsOptions): SdfShape
 ```
 
-Create a 2D rectangle. When center is true, the origin is at the rectangle center; otherwise at the bottom-left corner.
+`TpmsOptions`: `{ cellSize: number, thickness: number }`
 
-#### `arcSlot()`
+#### `sdf.schwarzP()` — Schwarz-P TPMS lattice — isotropic pore structure.
 
 ```ts
-arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
+sdf.schwarzP(options: TpmsOptions): SdfShape
 ```
 
-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 ```
-
-#### `routePerimeter()`
+#### `sdf.diamond()` — Diamond TPMS lattice — stiffest TPMS structure.
 
 ```ts
-routePerimeter(steps: PerimeterStep[]): Sketch
+sdf.diamond(options: TpmsOptions): SdfShape
 ```
 
-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 }, ]) ```
-
-#### `roundedRect()`
+#### `sdf.lidinoid()` — Lidinoid TPMS lattice — visually distinct from gyroid, popular in research and art.
 
 ```ts
-roundedRect(width: number, height: number, radius: number, center?: boolean): Sketch
+sdf.lidinoid(options: TpmsOptions): SdfShape
 ```
 
-Create a 2D rectangle with rounded corners. The radius is clamped to fit within the dimensions.
-
-#### `slot()`
+#### `sdf.noise()` — 3D Simplex noise field — produces organic, natural-looking displacements.
 
 ```ts
-slot(length: number, width: number): Sketch
+sdf.noise(options?: NoiseOptions): SdfShape
 ```
 
-Create a slot (stadium/discorectangle) — a rectangle with semicircular ends, centered at origin.
+**`NoiseOptions`**
 
-#### `spline2d()`
+| Option | Type | Description |
+|--------|------|-------------|
+| `scale?` | `number` | Spatial frequency — smaller = larger features. Default: 0.1 |
+| `amplitude?` | `number` | Peak displacement amplitude. Default: 1 |
+| `octaves?` | `number` | fBm octaves (1 = plain simplex, higher = more detail). Default: 1 |
+| `seed?` | `number` | Seed for deterministic variation. Default: 0 |
+
+#### `sdf.voronoi()` — 3D Voronoi pattern — organic cellular structures like bone, coral, or soap bubbles.
 
 ```ts
-spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
+sdf.voronoi(options?: VoronoiOptions): SdfShape
 ```
 
-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.
+**`VoronoiOptions`**
 
-<details><summary><code>Spline2DOptions</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `cellSize?` | `number` | Size of each Voronoi cell in world units. Default: 10 |
+| `wallThickness?` | `number` | Wall thickness between cells. Default: 1 |
+| `seed?` | `number` | Seed for deterministic variation. Default: 0 |
+| `suppressionThreshold?` | `number` | Projection weight for membrane suppression (0..1). Controls how much of the surface-normal distance component is removed from Voronoi cell distances. 0 = no projection (classic 3D voronoi with membranes). 1 = full tangent-plane projection (pure 2D pattern on surface). Default: 0.85. Only active when voronoi is intersected with another shape. |
+
+#### `sdf.honeycomb()` — Honeycomb (hexagonal) lattice pattern. Intersect with your shape to apply.
 
 ```ts
-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";
-}
+sdf.honeycomb(options?: HoneycombOptions): SdfShape
 ```
 
-</details>
+**`HoneycombOptions`**
+- `cellSize?: number` — Size of each hex cell. Default: 8
+- `wallThickness?: number` — Wall thickness. Default: 1
 
-#### `star()`
+#### `sdf.waves()` — Sinusoidal wave ridges — parallel ridges along an axis.
 
 ```ts
-star(points: number, outerR: number, innerR: number): Sketch
+sdf.waves(options?: WavesOptions): SdfShape
 ```
 
-Create a star shape with alternating outer and inner radii.
+**`WavesOptions`**
+- `wavelength?: number` — Distance between wave peaks. Default: 10
+- `amplitude?: number` — Height of waves. Default: 1
+- `axis?: "x" | "y" | "z"` — Axis along which waves propagate: 'x', 'y', or 'z'. Default: 'x'
 
-#### `stroke()`
+#### `sdf.knurl()` — Knurl pattern — crossed helical grooves for grips and handles.
 
 ```ts
-stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"): Sketch
+sdf.knurl(options?: KnurlOptions): SdfShape
 ```
 
-Create a stroked polyline sketch from an array of 2D points.
+**`KnurlOptions`**
+- `pitch?: number` — Distance between knurl ridges. Default: 3
+- `depth?: number` — Depth of knurl grooves. Default: 0.5
+- `angle?: number` — Helix angle in degrees. Default: 30
 
-#### `text2d()`
+#### `sdf.perforated()` — Perforated plate pattern — regular array of cylindrical holes.
 
 ```ts
-text2d(content: string, options?: TextOptions): Sketch
+sdf.perforated(options?: PerforatedOptions): SdfShape
 ```
 
-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' })
+**`PerforatedOptions`**
+- `radius?: number` — Hole radius. Default: 3
+- `spacing?: number` — Center-to-center spacing. Default: 8
 
-<details><summary><code>TextOptions</code></summary>
+#### `sdf.scales()` — Fish/dragon scale pattern — overlapping circular scales in hex-packed rows.
 
 ```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;
-}
+sdf.scales(options?: ScalesOptions): SdfShape
 ```
 
-</details>
+**`ScalesOptions`**
+- `size?: number` — Scale diameter. Default: 5
+- `depth?: number` — How much scales protrude. Default: 0.8
 
-#### `textWidth()`
+#### `sdf.brick()` — Brick/stone wall pattern — running bond with mortar grooves.
 
 ```ts
-textWidth(content: string, options?: Pick<TextOptions, "size" | "letterSpacing" | "font">): number
+sdf.brick(options?: BrickOptions): SdfShape
 ```
 
-Returns the rendered width of a string in model units (same options as text2d).
+**`BrickOptions`**
 
----
+| Option | Type | Description |
+|--------|------|-------------|
+| `width?` | `number` | Brick width. Default: 10 |
+| `height?` | `number` | Brick height. Default: 5 |
+| `depth?` | `number` | Mortar groove depth. Default: 0.5 |
+| `mortar?` | `number` | Mortar gap width. Default: 1 |
 
-## C2: Boolean Combination
+#### `sdf.weave()` — Grid lattice pattern — two families of infinite slabs crossing at 90°.
 
-Combine same-dimension geometry using CSG set operations.
+```ts
+sdf.weave(options?: WeaveOptions): SdfShape
+```
 
-#### `difference2d()`
+**`WeaveOptions`**
+- `spacing?: number` — Thread center-to-center spacing (for intersection patterns). Default: 5
+- `threadRadius?: number` — Thread half-width. Default: 1
+
+#### `sdf.basketWeave()` — Basket weave surface pattern — threads with over-under crossings in UV space. Returns a SurfacePattern for use with `.surfaceDisplace()`.
 
 ```ts
-difference2d(...inputs: SketchOperandInput[]): Sketch
+sdf.basketWeave(options?: BasketWeaveOptions): SurfacePattern
 ```
 
-Subtract 2D sketches from a base sketch. The first sketch is the base; all others are subtracted.
+**`BasketWeaveOptions`**
+- `spacing?: number` — Spacing between threads in mm (both directions). Default: 3
+- `threadWidth?: number` — Thread width in mm. Default: 1.5
+- `depth?: number` — Thread protrusion depth in mm. Default: 0.8
 
-#### `intersection2d()`
+#### `sdf.twist()` — Twist an SDF shape around the Z axis.
 
 ```ts
-intersection2d(...inputs: SketchOperandInput[]): Sketch
+sdf.twist(shape: SdfShape, degreesPerUnit: number): SdfShape
 ```
 
-Keep only the overlapping area of the input sketches (intersection boolean).
-
-#### `union2d()`
+#### `sdf.bend()` — Bend an SDF shape around the Z axis.
 
 ```ts
-union2d(...inputs: SketchOperandInput[]): Sketch
+sdf.bend(shape: SdfShape, radius: number): SdfShape
 ```
 
-Combine 2D sketches into a single profile (additive boolean). Accepts individual sketches or arrays.
+#### `sdf.repeat()` — Repeat an SDF shape in space.
 
----
+```ts
+sdf.repeat(shape: SdfShape, spacing: Vec3, count?: Vec3): SdfShape
+```
 
-## C3: Rigid Transform
+#### `sdf.SurfacePattern()` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
 
-Reposition or reorient geometry without changing its shape.
+```ts
+sdf.SurfacePattern: typeof SurfacePattern
+```
 
-#### `degrees()`
+#### `sdf.fromFunction()` — Create an SDF shape from an arbitrary distance function. You must provide bounds since the function is opaque.
 
 ```ts
-degrees(deg: number): number
+sdf.fromFunction(fn: (x: number, y: number, z: number) => number, bounds: { min: Vec3; max: Vec3; }, constants?: Record<string, number>): SdfShape
 ```
 
-Convert degrees to degrees (identity — for readability in scripts)
+#### `circle2d()` — Create a 2D circle centered at the origin.
 
-#### `radians()`
+Omit `segments` for a smooth (auto-tessellated) circle. Pass an integer to get a regular polygon approximation — e.g. `6` for a hexagon, `8` for an octagon.
 
 ```ts
-radians(rad: number): number
+circle2d(25).extrude(10);          // smooth cylinder
+circle2d(25, 6).extrude(10);       // hexagonal prism
 ```
 
-Convert radians to degrees
+```ts
+circle2d(radius: number, segments?: number): Sketch
+```
 
-#### `composeChain()`
+#### `ellipse()` — Create a 2D ellipse centered at the origin.
 
 ```ts
-composeChain(...steps: TransformInput[]): Transform
+ellipse(30, 15).extrude(5);
+ellipse(30, 15, 32).extrude(5); // lower-resolution approximation
 ```
 
-Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
+```ts
+ellipse(rx: number, ry: number, segments?: number): Sketch
+```
 
----
+#### `loadFont()` — Pre-load and cache a font for use with `text2d()`.
 
-## C4: Dimensional Promotion
+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.
 
-Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
+Built-in font names that work everywhere (browser + CLI):
 
-#### `connectEdges()`
+- `'sans-serif'` or `'inter'` — bundled Inter Regular
 
 ```ts
-connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
+const font = loadFont('/path/to/Arial Bold.ttf');
+text2d('Title', { size: 12, font }).extrude(1.5);
+text2d('Subtitle', { size: 8, font }).extrude(1);
 ```
 
-<details><summary><code>EdgeSegment</code></summary>
-
-```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;
-}
+```ts
+loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype.Font
 ```
 
-</details>
+#### `ngon()` — Create a regular polygon inscribed in a circle of the given radius.
 
-<details><summary><code>TransitionCurveOptions</code></summary>
+`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).
 
 ```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;
-}
+ngon(6, 20).extrude(10); // hexagonal prism, circumradius 20
 ```
 
-</details>
-
-<details><summary><code>TransitionSurfaceOptions</code> extends TransitionCurveOptions</summary>
-
 ```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;
-}
+ngon(sides: number, radius: number): Sketch
 ```
 
-</details>
-
-<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;
-}
-```
+#### `path()` — Create a new `PathBuilder` for tracing a 2D outline point by point.
 
-</details>
+`PathBuilder` is a fluent API for constructing 2D profiles using a mix of line segments, arcs, bezier curves, and splines. Always start with `.moveTo(x, y)` to set the starting point. Call `.close()` to get a filled `Sketch`, or `.stroke(width)` to thicken an open polyline into a solid profile.
 
-#### `hermiteTransition()`
+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`.
 
 ```ts
-hermiteTransition(a: EdgeEndpoint, b: EdgeEndpoint): HermiteCurve3D
-```
+// Closed triangle
+const triangle = path().moveTo(0, 0).lineH(50).lineV(30).close();
 
-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
+// L-shaped bracket as a stroke
+const bracket = path().moveTo(0, 0).lineH(50).lineV(-70).lineAngled(20, 235).stroke(4);
 
-<details><summary><code>EdgeEndpoint</code></summary>
+// 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();
+```
 
 ```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;
-}
+path(): PathBuilder
 ```
 
-</details>
+#### `polygon()` — Create a 2D polygon from an array of `[x, y]` points or `Point2D` objects.
 
-#### `hermiteTransitionG2()`
+Winding order is normalized automatically — clockwise (CW) input is silently reversed to CCW before being passed to the geometry kernel.
 
 ```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
+polygon([[0, 0], [50, 0], [25, 40]]).extrude(5); // triangle
 ```
 
-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.
-
-<details><summary><code>QuinticHermiteCurveEndpoint</code></summary>
-
 ```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;
-}
+polygon(points: ([ number, number ] | Point2D)[]): Sketch
 ```
 
-</details>
+#### `polygonVertices()` — Compute the vertex positions of a regular polygon.
 
-#### `loft()`
+Default orientation places the first vertex at the top (90 degrees), matching the convention used by `ngon()`.
 
-```ts
-loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
-```
+Eliminates manual Math.sqrt(3) for triangles, pentagon vertex math, etc:
 
-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().
+```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];
 
-<details><summary><code>LoftOptions</code></summary>
+// After — declarative
+const [v1, v2, v3] = polygonVertices(3, r);
+```
 
 ```ts
-interface LoftOptions {
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-}
+polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
 ```
 
-</details>
+**`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).
+
+`LayoutPoint`: `{ x: number, y: number }`
 
-#### `loftAlongSpine()`
+#### `rect()` — Create a 2D rectangle centered at the origin.
 
 ```ts
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$4[], tValues: number[], options?: LoftAlongSpineOptions): Shape
+rect(40, 20).extrude(5);
 ```
 
-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().
-
-<details><summary><code>LoftAlongSpineOptions</code></summary>
-
 ```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;
-}
+rect(width: number, height: number): Sketch
 ```
 
-</details>
+#### `arcSlot()` — Create an arc-shaped slot (banana / annular sector) centered at the origin.
 
-#### `spline3d()`
+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.
 
 ```ts
-spline3d(points: Vec3$4[], options?: Spline3DOptions): Curve3D
+arcSlot(135, 74, 40).extrude(5); // pitch R135, 74° sweep, 40mm wide
 ```
 
-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.
-
-<details><summary><code>Spline3DOptions</code></summary>
-
 ```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;
-}
+arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
 ```
 
-</details>
+#### `roundedRect()` — Create a 2D rectangle with rounded corners, centered at the origin.
 
-#### `surfacePatch()`
+The corner radius is automatically clamped to `min(width/2, height/2)` so it can never exceed the shape dimensions.
 
 ```ts
-surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
+roundedRect(60, 30, 5).extrude(3);
 ```
 
-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.
-
-<details><summary><code>SurfacePatchOptions</code></summary>
-
 ```ts
-interface SurfacePatchOptions {
-  /** Number of samples along each direction. Default 24. */
-  resolution?: number;
-  /** Thickness of the generated solid. Default 0.5. */
-  thickness?: number;
-}
+roundedRect(width: number, height: number, radius: number): Sketch
 ```
 
-</details>
-
-#### `sweep()`
+#### `slot()` — Create a slot (oblong / stadium shape) — a rectangle with semicircular ends, centered at the origin.
 
 ```ts
-sweep(profile: Sketch, path: Curve3D | Vec3$4[], options?: SweepOptions): Shape
+slot(40, 10).extrude(3); // 40mm long, 10mm wide slot
 ```
 
-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.
-
-<details><summary><code>SweepOptions</code></summary>
-
 ```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;
-}
+slot(length: number, width: number): Sketch
 ```
 
-</details>
+#### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
-#### `variableSweep()`
+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.
 
 ```ts
-variableSweep(spine: Curve3D | Vec3$4[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
+spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
 ```
 
-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.
+**`Spline2DOptions`**
 
-<details><summary><code>VariableSweepSection</code></summary>
+| 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.
 
 ```ts
-interface VariableSweepSection {
-  /** Parameter along the spine (0 = start, 1 = end). */
-  t: number;
-  /** Cross-section profile at this station. */
-  profile: Sketch;
-}
+star(5, 30, 12).extrude(4); // five-pointed star
 ```
 
-</details>
-
-<details><summary><code>VariableSweepOptions</code></summary>
-
 ```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;
-}
+star(points: number, outerR: number, innerR: number): Sketch
 ```
 
-</details>
-
-#### `transitionCurve()`
+#### `stroke()` — Create a stroked polyline sketch from an array of 2D points.
 
 ```ts
-transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
+stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"): Sketch
 ```
 
-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 }, ); ```
-
-<details><summary><code>TransitionEdge</code></summary>
+#### `text2d()` — Build a filled 2D Sketch from a text string.
 
-```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 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.
 
-</details>
+Alignment reference table:
 
-#### `transitionCurveFromPoints()`
+| `align` | `baseline` | Origin | |------------|--------------|-------------------------------------| | `'left'` | `'baseline'` | Bottom-left of first char (default) | | `'center'` | `'center'` | Dead center of text block | | `'right'` | `'top'` | Top-right corner |
 
 ```ts
-transitionCurveFromPoints(startPoint: Vec3$7, startTangent: Vec3$7, endPoint: Vec3$7, endTangent: Vec3$7, options?: TransitionCurveOptions): HermiteCurve3D
-```
+// Extruded nameplate
+text2d('FORGE CAD', { size: 8 }).extrude(1.2);
 
-Convenience: create a transition curve from raw coordinate data. Useful when you have endpoints and directions as plain arrays without constructing TransitionEdge objects.
+// Centered label on the XY plane
+text2d('V 2.0', { size: 6, align: 'center', baseline: 'center' });
 
-#### `transitionSurface()`
+// 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));
 
-```ts
-transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+// 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);
 ```
 
-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 }, ); ```
+```ts
+text2d(content: string, options?: TextOptions): Sketch
+```
 
----
+**`TextOptions`**
 
-## C5: Topology Query
+| 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.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. |
 
-Select or inspect named faces and edges on a shape.
+#### `textWidth()` — Measure the rendered advance width of a string without creating any geometry.
 
-#### `coalesceEdges()`
+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.
 
 ```ts
-coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
+const w = textWidth('SERIAL: 001', { size: 6 });
+const plate = box(w + 10, 12, 2);
 ```
 
-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.
-
-<details><summary><code>EdgeSegment</code></summary>
-
-```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;
-}
+```ts
+textWidth(content: string, options?: Pick<TextOptions, "size" | "letterSpacing" | "font">): number
 ```
 
-</details>
+#### `box()` — Create a rectangular box. Centered on XY, base at Z=0.
 
-#### `selectEdge()`
+For named faces, build from a labeled sketch: `rect(x, y).labelEdges('s', 'e', 'n', 'w').extrude(z, { labels: { start: 'bottom', end: 'top' } })`.
 
 ```ts
-selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment
-```
-
-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.
-
-<details><summary><code>EdgeQuery</code></summary>
-
-```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;
-}
+box(x: number, y: number, z: number): Shape
 ```
 
-</details>
+#### `cylinder()` — Create a cylinder or cone with named faces and edges. Centered on XY, base at Z=0.
 
-<details><summary><code>BoundingRegion</code></summary>
+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.
 
 ```ts
-interface BoundingRegion {
-  xMin?: number;
-  xMax?: number;
-  yMin?: number;
-  yMax?: number;
-  zMin?: number;
-  zMax?: number;
-}
+cylinder(height: number, radius: number, radiusTop?: number, segments?: number): Shape
 ```
 
-</details>
-
-#### `selectEdges()`
+#### `sphere()` — Create a sphere centered at the origin. Use segments for lower-poly approximations.
 
 ```ts
-selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+sphere(radius: number, segments?: number): Shape
 ```
 
-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.
+#### `torus()` — Create a torus (donut shape) lying in the XY plane. Centered on all axes (origin is the ring center).
+
+```ts
+torus(majorRadius: number, minorRadius: number, segments?: number): Shape
+```
 
 ---
 
-## C6: Edge Feature
+## C2: Boolean Combination
 
-Modify edges of a solid — fillets, chamfers, draft, offset.
+Combine same-dimension geometry using CSG set operations.
+
+#### `difference2d()` — Subtract one or more 2D sketches from a base sketch.
 
-#### `filletEdgeSegment()`
+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.
 
 ```ts
-filletEdgeSegment(shape: Shape, segment: EdgeSegment, radius: number, segments?: number): Shape
+const donut = difference2d(circle2d(50), circle2d(30));
 ```
 
-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().
-
-<details><summary><code>EdgeSegment</code></summary>
-
 ```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;
-}
+difference2d(...inputs: SketchOperandInput[]): Sketch
 ```
 
-</details>
+#### `intersection2d()` — Keep only the area where all input sketches overlap (intersection boolean).
 
-#### `chamferEdgeSegment()`
+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.
 
 ```ts
-chamferEdgeSegment(shape: Shape, segment: EdgeSegment, size: number): Shape
+const lens = intersection2d(circle2d(30).translate(-10, 0), circle2d(30).translate(10, 0));
 ```
 
-Apply a chamfer (beveled edge) to a mesh-selected edge. Works on any straight edge of any shape — not limited to tracked box edges.
-
-#### `chamfer()`
-
 ```ts
-chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
+intersection2d(...inputs: SketchOperandInput[]): Sketch
 ```
 
-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] })
+#### `union2d()` — Combine 2D sketches into a single profile using an additive boolean union.
 
-#### `draft()`
+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.
 
 ```ts
-draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
+const cross = union2d(rect(60, 10), rect(10, 60));
 ```
 
-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()`
-
 ```ts
-fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
+union2d(...inputs: SketchOperandInput[]): Sketch
 ```
 
-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)
+#### `union()` — Combine shapes into a single solid (additive boolean).
 
-#### `offsetSolid()`
+Accepts individual shapes, or an array of shapes. The first operand's color is preserved in the result.
 
 ```ts
-offsetSolid(shape: Shape, thickness: number): Shape
+union(...inputs: ShapeOperandInput[]): Shape
 ```
 
-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)
+#### `difference()` — Subtract shapes from a base shape (subtractive boolean).
 
-#### `filletCorners()`
+The first shape is the base; all subsequent shapes are subtracted from it. Accepts individual shapes, or an array of shapes.
 
 ```ts
-filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
+difference(...inputs: ShapeOperandInput[]): Shape
 ```
 
-Create a polygon from points with specified corners rounded to arc fillets. Each corner spec identifies a vertex index and radius.
+#### `intersection()` — Keep only the overlapping volume of the input shapes (intersection boolean).
 
-<details><summary><code>FilletCornerSpec</code></summary>
+Requires at least two shapes. Accepts individual shapes, or an array.
 
 ```ts
-interface FilletCornerSpec {
-  index: number;
-  radius: number;
-  segments?: number;
-}
+intersection(...inputs: ShapeOperandInput[]): Shape
 ```
 
-</details>
-
 ---
 
-## C7: Pattern Replication
+## C3: Rigid Transform
 
-Duplicate geometry in regular arrangements (linear, circular, mirror).
+Reposition or reorient geometry without changing its shape.
+
+#### `degrees()` — Identity function that returns degrees unchanged.
 
-#### `circularLayout()`
+Use for clarity when the unit of an angle value would otherwise be ambiguous — e.g. `param("Angle", degrees(45))`.
 
 ```ts
-circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
+degrees(deg: number): number
 ```
 
-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)); } ```
+#### `radians()` — Convert radians to degrees.
 
-<details><summary><code>CircularLayoutOptions</code></summary>
+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.
 
 ```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;
-}
+radians(rad: number): number
 ```
 
-</details>
-
-<details><summary><code>LayoutPoint</code></summary>
+#### `composeChain()` — Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
 
 ```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
+composeChain(...steps: TransformInput[]): Transform
 ```
 
-</details>
+---
 
-#### `circularPattern()`
+## C4: Dimensional Promotion
 
-```ts
-circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
-```
+Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
 
-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] })
+#### `nurbs3d()` — Create a NURBS curve from control points.
 
-<details><summary><code>CircularPatternOptions</code></summary>
+With default options, creates a cubic non-rational B-spline with uniform clamped knots. Set `weights` for rational curves (exact circles, conics). Set `degree` for linear (1), quadratic (2), cubic (3), or higher-order curves.
 
-```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;
-}
+```js
+// Simple cubic B-spline through control points
+const curve = nurbs3d([[0,0,0], [10,5,0], [20,-5,10], [30,0,5]]);
+const tube = sweep(circle(2), curve);
 ```
 
-</details>
-
-#### `circularPattern2d()`
+```js
+// Rational quadratic — exact circular arc
+const arc = nurbs3d(
+  [[10,0,0], [10,10,0], [0,10,0]],
+  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
+);
+```
 
 ```ts
-circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
+nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
 ```
 
-Repeat a sketch in a circular pattern around a center point
+**`NurbsCurve3DOptions`**
 
-#### `linearPattern()`
+| Option | Type | Description |
+|--------|------|-------------|
+| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
+| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
+| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
+| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
 
-```ts
-linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
-```
+#### `nurbsSurface()` — Create a NURBS surface from a grid of control points.
 
-Repeat a shape in a linear pattern along a direction vector and union the copies.
+The control grid is indexed as `controlGrid[u][v]` — each row is a curve in the V direction, and columns trace curves in the U direction.
 
-#### `linearPattern2d()`
+With default options, creates a bicubic non-rational B-spline surface with uniform clamped knots.
 
-```ts
-linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+```js
+// Simple 4×4 control grid — a gently curved surface
+const grid = [
+  [[0,0,0], [10,0,2], [20,0,2], [30,0,0]],
+  [[0,10,1], [10,10,5], [20,10,5], [30,10,1]],
+  [[0,20,1], [10,20,5], [20,20,5], [30,20,1]],
+  [[0,30,0], [10,30,2], [20,30,2], [30,30,0]],
+];
+const surface = nurbsSurface(grid, { thickness: 2 });
 ```
 
-Repeat a sketch in a linear pattern
-
-#### `mirrorCopy()`
-
 ```ts
-mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+nurbsSurface(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape
 ```
 
-Mirror a shape across a plane defined by its normal and union the mirror with the original.
+**`NurbsSurfaceOptions`**
 
----
-
-## C8: Constraint Solving
+| Option | Type | Description |
+|--------|------|-------------|
+| `degreeU?` | `number` | Degree in U direction (default 3). |
+| `degreeV?` | `number` | Degree in V direction (default 3). |
+| `weights?` | `number[][]` | Weights grid — same dimensions as controlGrid (default: all 1.0). |
+| `knotsU?` | `number[]` | Knot vector in U direction (default: uniform clamped). |
+| `knotsV?` | `number[]` | Knot vector in V direction (default: uniform clamped). |
+| `thickness?` | `number` | Sheet thickness — if > 0, thickens the surface into a solid (default 0 = surface only). |
+| `resolution?` | `number` | Tessellation resolution — points per direction (default 32). |
 
-Define geometry by relationships and let a solver find positions.
+#### `connectEdges()` — Create a transition surface or solid bridge between two edge segments.
 
-#### `addPolygon()`
+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.
 
 ```ts
-addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon
+connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
 ```
 
-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); ```
+**`EdgeSegment`**
 
-<details><summary><code>PolygonOptions</code></summary>
+| 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` | | — |
 
-```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;
-}
-```
+**`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.
 
-</details>
+**`TransitionSurfaceOptions`** extends TransitionCurveOptions
 
-<details><summary><code>ConstrainedPolygon</code></summary>
+| 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` | 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` | | — |
 
-```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;
-}
-```
+**`ConnectEdgesOptions`** extends TransitionSurfaceOptions
 
-</details>
+| 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` | Explicit tangent for edge A. |
+| `tangentB?` | `Vec3` | Explicit tangent for edge B. |
+| `flipA?` | `boolean` | Flip tangent A. |
+| `flipB?` | `boolean` | Flip tangent B. |
 
-#### `addRect()`
+#### `hermiteTransitionG2()` — 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.
 
 ```ts
-addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect
+hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
 ```
 
-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); ```
+**`QuinticHermiteCurveEndpoint`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point` | `Vec3` | Position |
+| `tangent` | `Vec3` | Tangent direction (will be normalized internally) |
+| `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
+| `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
 
-<details><summary><code>RectOptions</code></summary>
+#### `loft()` — 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().
 
 ```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;
-}
+loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-</details>
-
-<details><summary><code>ConstrainedRect</code></summary>
-
-```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;
-}
-```
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
 
-</details>
+#### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
-#### `addRegularPolygon()`
+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
-addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon
-```
+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].
 
-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) ```
+Internally uses variableSweep infrastructure with SDF interpolation.
 
-<details><summary><code>RegularPolygonOptions</code></summary>
+Performance note: uses level-set meshing, heavier than simple loft().
 
 ```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;
-}
+loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3[], tValues: number[], options?: LoftAlongSpineOptions): Shape
 ```
 
-</details>
+**`LoftAlongSpineOptions`**
 
+| 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` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
-<details><summary><code>ConstrainedRegularPolygon</code> extends ConstrainedPolygon</summary>
+#### `spline3d()` — Create a reusable 3D spline curve object (Catmull-Rom).
+
+The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
 
 ```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;
-}
+spline3d(points: Vec3[], options?: Spline3DOptions): Curve3D
 ```
 
-</details>
+**`Spline3DOptions`**
+- `closed?: boolean` — Closed loop (default false).
+- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
 
-#### `circle()`
+#### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
 
-```ts
-circle(cx: number, cy: number, radius: number): Circle2D
-```
+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)
 
-Create an analytic 2D circle for measurement, construction, and extrusion. Provides diameter, circumference, area, and toSketch().
+The interior is filled using bilinear Coons patch interpolation: P(u,v) = Lc(u,v) + Ld(u,v) - B(u,v)
 
-#### `constrainedSketch()`
+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.
 
 ```ts
-constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder
+surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
 ```
 
-Build a parametric 2D sketch with geometric constraints solved by the built-in constraint solver.
+**`SurfacePatchOptions`**
+- `resolution?: number` — Number of samples along each direction. Default 24.
+- `thickness?: number` — Thickness of the generated solid. Default 0.5.
 
-<details><summary><code>ConstrainedSketchOptions</code></summary>
+#### `sweep()`
 
 ```ts
-interface ConstrainedSketchOptions {
-  /** When true, adding a constraint that cannot be satisfied throws instead of silently discarding it. */
-  strict?: boolean;
-}
+sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape
 ```
 
-</details>
+**`SweepOptions`**
 
-#### `line()`
+| 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` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
-```ts
-line(x1: number, y1: number, x2: number, y2: number): Line2D
-```
+#### `variableSweep()` — Sweep a variable cross-section along a 3D spine curve.
 
-Create an analytic 2D line segment between two points. Provides length, midpoint, angle, intersection, and parallel helpers.
+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.
 
-#### `point()`
+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.
 
 ```ts
-point(x: number, y: number): Point2D
+variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
 ```
 
-Create an analytic 2D point for measurement and construction geometry.
-
----
+**`VariableSweepSection`**
+- `t: number` — Parameter along the spine (0 = start, 1 = end).
+- `profile: Sketch` — Cross-section profile at this station.
 
-## C9: Spatial Placement
+**`VariableSweepOptions`**
 
-Position geometry relative to other geometry using semantic anchors.
+| 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` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
-*No free functions — see class methods (Shape, Sketch, ConstrainedSketchBuilder).*
+#### `transitionCurve()` — 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`.
 
-## C10: Assembly & Kinematics
+The curve maintains G1 continuity (matching tangent direction) at both endpoints. Weight parameters control the shape of the transition.
 
-Compose parts with joints for kinematic simulation.
+```js
+```js
 
-#### `assembly()`
+// 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] }, );
 
-```ts
-assembly(name?: string): Assembly
 ```
 
-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.
-
-#### `bomToCsv()`
+// 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 },
+);
+```
 
 ```ts
-bomToCsv(rows: BomRow[]): string
+transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
 ```
 
-Convert BOM rows from a solved assembly into a CSV string.
+**`TransitionEdge`**
+- `point: Vec3` — Connection point on the edge. Can be any point along the edge where the transition should connect.
+- `tangent: Vec3` — Tangent direction at the connection point. This is the direction the curve should initially follow when leaving this edge. For a straight edge, this is typically the edge direction pointing "outward" (away from the body of the edge, toward the other edge).
+- `normal?: Vec3` — Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector.
 
-<details><summary><code>BomRow</code></summary>
+#### `transitionSurface()` — Create a solid transition surface between two edges by sweeping a profile along a Hermite transition curve.
 
-```ts
-interface BomRow {
-  part: string;
-  qty: number;
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  notes?: string;
-  metadata?: PartMetadata;
-}
-```
+This produces a watertight solid that smoothly connects the two edges. Works with both Manifold and OCCT backends.
 
-</details>
+```js
+```js
 
-<details><summary><code>PartMetadata</code></summary>
+// 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
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
 ```
 
-</details>
+// 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 },
+);
+```
+
+```ts
+transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+```
+
+---
+
+## C5: Topology Query
+
+Select or inspect named faces and edges on a shape.
+
+#### `coalesceEdges()` — Merge collinear edge segments into longer logical edges.
+
+Tessellation often splits one geometric edge into multiple short segments. `coalesceEdges` groups adjacent collinear segments and merges each group into a single `EdgeSegment` spanning the full extent. This is usually needed before passing edges to `fillet()` or `chamfer()` on non-primitive shapes.
+
+The `tolerance` controls the maximum perpendicular distance from collinearity before two segments are considered non-collinear. Default: `0.01`.
+
+```ts
+const topEdges = selectEdges(part, { atZ: 20 });
+for (const edge of coalesceEdges(topEdges)) {
+  result = fillet(result, 2, edge);
+}
+```
+
+```ts
+coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
+```
+
+**`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` | | — |
+
+#### `selectEdge()` — Select the single best-matching edge from a shape.
+
+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.
+
+```ts
+// Chamfer one specific edge near a known point
+const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
+result = chamfer(result, 1.5, bottomEdge);
+```
+
+```ts
+selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment
+```
+
+**`EdgeQuery`**
+
+| 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 }`
+
+#### `selectEdges()` — Select all edges from a shape that match the given query.
+
+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.
+
+```ts
+// 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);
+}
+```
+
+```ts
+selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+```
+
+---
+
+## C6: Edge Feature
+
+Modify edges of a solid — fillets, chamfers, draft, offset.
+
+#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
+
+Produces a 45° bevel at the specified `size` (distance from edge). Works on both straight and curved edges. Supports OCCT and Manifold backends.
+
+The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
+
+```ts
+// Chamfer all edges
+chamfer(myShape, 1)
+
+// Chamfer only vertical edges
+chamfer(myShape, 2, { parallel: [0, 0, 1] })
+```
+
+```ts
+chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
+```
+
+#### `draft()` — Apply a draft angle (taper) to vertical faces for mold extraction.
+
+Adds a taper angle to the vertical faces of a solid so that it can be extracted from a mold. The neutral plane is the Z position where the draft angle is zero — faces above and below are tapered symmetrically. Typical values for injection molding are 1–5°.
+
+Requires the OCCT backend. Throws on Manifold.
+
+```ts
+// 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)
+```
+
+```ts
+draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
+```
+
+#### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
+
+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.
+
+```ts
+// 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)
+```
+
+```ts
+fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
+```
+
+#### `offsetSolid()` — Uniformly offset all surfaces of a solid inward or outward.
+
+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.
+
+```ts
+// Grow a box outward by 1mm on all sides
+offsetSolid(myBox, 1)
+
+// Shrink a shape inward by 0.5mm
+offsetSolid(myShape, -0.5)
+```
+
+```ts
+offsetSolid(shape: Shape, thickness: number): Shape
+```
+
+#### `chamfer2d()` — Bevel a named vertical edge of a shape with a 45° chamfer.
+
+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.
+
+```ts
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const chamfered = chamfer2d(b.toShape(), b.edge('vert-br'), 3, [-1, -1]);
+```
+
+```ts
+chamfer2d(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape
+```
+
+**`EdgeRef`**
+- `query?: EdgeQueryRef` — Compiler-owned edge query when available.
+- Also: `name: EdgeName`
+
+#### `fillet2d()` — Round a named vertical edge of a shape with a circular fillet.
+
+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]`
+
+```ts
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const filleted = fillet2d(b.toShape(), b.edge('vert-br'), 5, [-1, -1]);
+```
+
+```ts
+fillet2d(shape: Shape, edge: EdgeRef, radius: number, quadrant?: [ number, number ], segments?: number): Shape
+```
+
+#### `filletCorners()` — Create a polygon from points with specific corners rounded to arc fillets.
+
+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.
+
+```ts
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
+```
+
+```ts
+filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
+```
+
+`FilletCornerSpec`: `{ index: number, radius: number, segments?: number }`
+
+---
+
+## C7: Pattern Replication
+
+Duplicate geometry in regular arrangements (linear, circular, mirror).
+
+#### `circularLayout()` — 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));
+}
+```
+
+```ts
+circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
+```
+
+**`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).
+
+`LayoutPoint`: `{ x: number, y: number }`
+
+#### `circularPattern()` — Repeat a shape in a circular pattern around an axis and union the copies.
+
+Distributes `count` copies evenly around the rotation axis (360° / count per step). All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy — post-merge face identity via owner-scoped canonical queries still works for pattern descendants.
+
+Two calling conventions:
+
+- **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)`
+- **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
+
+```ts
+// 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] })
+```
+
+```ts
+circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
+```
+
+**`CircularPatternOptions`**
+- `centerX?: number` — Center X of the rotation (default: 0). Used when axis is Z (legacy mode).
+- `centerY?: number` — Center Y of the rotation (default: 0). Used when axis is Z (legacy mode).
+
+#### `circularPattern2d()` — Repeat a 2D sketch in a circular pattern around a center point and union the copies.
+
+```ts
+circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
+```
+
+#### `linearPattern()` — Repeat a shape in a linear pattern along a direction vector and union the copies.
+
+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.
+
+```ts
+// 5 cylinders, 20mm apart along X
+linearPattern(cylinder(10, 3), 5, 20, 0)
+```
+
+```ts
+linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
+```
+
+#### `linearPattern2d()` — Repeat a 2D sketch in a linear pattern and union the copies.
+
+```ts
+linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+```
+
+#### `mirrorCopy()` — Mirror a shape across a plane and union the mirror with the original.
+
+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.
+
+```ts
+// Mirror across the YZ plane (X=0)
+mirrorCopy(box(50, 30, 10), [1, 0, 0])
+```
+
+```ts
+mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+```
+
+---
+
+## C8: Constraint Solving
+
+Define geometry by relationships and let a solver find positions.
+
+#### `Constraint.makeParallel()` — Constrain two lines to be parallel.
+
+```ts
+Constraint.makeParallel(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.enforceAngle()` — Constrain the signed angle from line `a` to line `b`.
+
+```ts
+Constraint.enforceAngle(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg, angleDeg: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.horizontal()` — Constrain a line to be horizontal.
+
+```ts
+Constraint.horizontal(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.vertical()` — Constrain a line to be vertical.
+
+```ts
+Constraint.vertical(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.equalLength()` — Constrain two lines to have equal length.
+
+```ts
+Constraint.equalLength(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.distance()` — Constrain the distance between two points.
+
+```ts
+Constraint.distance(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg, value: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.fix()` — Fix a point at a specific coordinate.
+
+```ts
+Constraint.fix(builder: ConstrainedSketchBuilder, pt: PointArg, x: number, y: number): ConstrainedSketchBuilder
+```
+
+#### `Constraint.coincident()` — Constrain two points to occupy the same location.
+
+```ts
+Constraint.coincident(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.perpendicular()` — Constrain two lines to be perpendicular.
+
+```ts
+Constraint.perpendicular(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder
+```
+
+#### `Constraint.length()` — Constrain the length of a line.
+
+```ts
+Constraint.length(builder: ConstrainedSketchBuilder, line: LineArg, value: number): ConstrainedSketchBuilder
+```
+
+#### `addPolygon()` — Add a general polygon concept to the builder.
+
+Creates n vertices and n sides (CCW: `sides[i]` from `vertices[i]` → `vertices[(i+1) % n]`). Applies a `ccw` constraint to enforce winding. All dimensional constraints (lengths, angles, position) are left to the caller.
+
+Use `sk.addPolygon()` as the shorthand builder method.
+
+```ts
+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);
+```
+
+```ts
+addPolygon(sk: ConstrainedSketchBuilder, options: PolygonOptions): ConstrainedPolygon
+```
+
+**`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.
+
+**`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).
+
+Use `sk.rect()` as the shorthand builder method.
+
+```ts
+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);
+```
+
+```ts
+addRect(sk: ConstrainedSketchBuilder, options?: RectOptions): ConstrainedRect
+```
+
+**`RectOptions`**
+
+| 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. |
+
+**`ConstrainedRect`**
+
+| 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` | | — |
+
+#### `addRegularPolygon()` — Add a regular n-gon concept to the builder.
+
+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.
+
+Use `sk.regularPolygon()` as the shorthand builder method.
+
+```ts
+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);
+```
+
+```ts
+addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions): ConstrainedRegularPolygon
+```
+
+**`RegularPolygonOptions`**
+
+| 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. |
+
+
+**`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.
+
+#### `circle()` — Create an analytic 2D circle for measurement, construction, and extrusion.
+
+```ts
+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);
+```
+
+```ts
+circle(cx: number, cy: number, radius: number): Circle2D
+```
+
+#### `constrainedSketch()` — Create a parametric 2D sketch driven by geometric constraints and a nonlinear solver.
+
+**Workflow**
+
+1. Create a builder with `constrainedSketch()`.
+2. Add geometry — points, lines, circles, arcs — using the builder methods.
+3. Add constraints (`horizontal`, `length`, `fix`, etc.) to drive the geometry.
+4. Call `.solve()` to run the solver and get a `ConstraintSketch` (which extends `Sketch`).
+
+```ts
+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);
+```
+
+**Solver status**
+
+```ts
+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
+```
+
+```ts
+constrainedSketch(options?: ConstrainedSketchOptions): ConstrainedSketchBuilder
+```
+
+**`ConstrainedSketchOptions`**
+- `strict?: boolean` — When true, adding a constraint that cannot be satisfied throws instead of silently discarding it.
+
+#### `line()` — Create an analytic 2D line segment between two points.
+
+```ts
+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);
+```
+
+```ts
+line(x1: number, y1: number, x2: number, y2: number): Line2D
+```
+
+#### `point()` — Create an analytic 2D point for measurement and construction geometry.
+
+```ts
+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]
+```
+
+```ts
+point(x: number, y: number): Point2D
+```
+
+---
+
+## C9: Spatial Placement
+
+Position geometry relative to other geometry using semantic anchors.
+
+
+#### `Points.distance()` — Euclidean distance between two 3D points.
+
+```ts
+Points.readonly distance: typeof distance
+```
+
+#### `Points.midpoint()` — Center point between two 3D points.
+
+```ts
+Points.readonly midpoint: typeof midpoint
+```
+
+#### `Points.lerp()` — Linearly interpolate between two 3D points. t=0 returns a, t=1 returns b.
+
+```ts
+Points.readonly lerp: typeof lerp
+```
+
+#### `Points.direction()` — Unit direction vector from a to b. Throws if a and b are the same point.
+
+```ts
+Points.readonly direction: typeof direction
+```
+
+#### `Points.offset()` — Move a point along a direction vector by a given amount.
+
+```ts
+Points.readonly offset: typeof offset
+```
+
+#### `Points.polar()` — Compute a 2D point at distance and angle (degrees) from an optional origin.
+
+```ts
+Points.readonly polar: typeof polar
+```
+
+---
+
+## C10: Assembly & Kinematics
+
+Compose parts with joints for kinematic simulation.
+
+#### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
+
+**Use this from iteration 1 for any model with moving parts.** Hinges, sliders, gears, articulated fingers, doors — all start with `assembly()`, not with manual rotation math. Don't build a static "extended pose" first and refactor to an assembly later: joint sliders, animations, sweeps, collision detection, and robot export all flow from the kinematic graph.
+
+An assembly models a mechanism as a directed graph of parts connected by joints. Parts are the nodes; joints are directed edges from parent to child. The graph must be a forest (no cycles). Root parts (those with no incoming joint) are anchored to world space.
+
+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.
+
+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.
+
+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.
+
+```ts
+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
+```
+
+```ts
+assembly(name?: string): Assembly
+```
+
+#### `bomToCsv()` — Convert an array of BOM rows into a CSV string.
+
+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.
+
+```ts
+bomToCsv(rows: BomRow[]): string
+```
+
+**`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
+
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+
+#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
+
+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.
 
-#### `joint()`
+```ts
+const arm = joint("Shoulder", armShape, [0, 0, 20], {
+  axis: [0, 1, 0],
+  min: -30, max: 120, default: 25,
+});
+return arm;
+```
 
 ```ts
 joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
 ```
 
-Create a revolute (hinge) joint. Auto-creates a param slider and rotates the shape.
+`RevoluteJointOpts`: `{ min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
 
-<details><summary><code>RevoluteJointOpts</code></summary>
+#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
 
-```ts
-interface RevoluteJointOpts {
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  reverse?: boolean;
-}
+Defines joints (revolute or prismatic), optional gear/rack couplings, and named animations. The viewport resolves transforms through the joint chain at display time — the script geometry is computed only once at rest pose.
+
+**Critical:** Solve the assembly at **rest pose** (all animated joints = 0). The viewport applies `jointsView` transforms on top of the returned scene. If geometry is already solved at non-zero angles, animation will double-rotate everything.
+
+```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]`.
 
-#### `jointsView()`
+**Fixed attachments** that must follow a parent during animation need a zero-angle revolute joint in the chain:
 
-```ts
-jointsView(options?: JointsViewOptions): void
+```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 }
 ```
 
-Configure runtime joint controls that animate object transforms in the viewport without re-running the script.
+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>JointsViewOptions</code></summary>
+**Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
 
-```ts
-interface JointsViewOptions {
-  enabled?: boolean;
-  joints?: JointViewInput[];
-  couplings?: JointViewCouplingInput[];
-  animations?: JointViewAnimationInput[];
-  defaultAnimation?: string;
-}
+```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>JointViewInput</code></summary>
+```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 } },
+    ],
+  }],
+});
+```
 
 ```ts
-interface JointViewInput {
-  name: string;
-  child: string;
-  parent?: string;
-  type?: JointViewType;
-  axis?: JointViewAxis;
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  hidden?: boolean;
-}
+jointsView(options?: JointsViewOptions): void
 ```
 
-</details>
+**`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
+
+**`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 }`
 
-<details><summary><code>JointViewCouplingInput</code></summary>
+`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
+
+`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
+
+**`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>`
+
+---
+
+## C11: Parameterization & UI
+
+Declare user-facing controls that drive model geometry.
+
+#### `Param.number()` — Declare a numeric parameter that renders as a slider in the UI.
+
+Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+
+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
+
+The `unit` option is cosmetic only — no conversion is performed. Use `integer: true` for counts, sides, quantities (rounds to whole numbers; step defaults to `1`).
 
 ```ts
-interface JointViewCouplingInput {
-  joint: string;
-  terms: JointViewCouplingTermInput[];
-  offset?: number;
-}
+const width = Param.number("Width", 50);
+const angle = Param.number("Angle", 45, { min: 0, max: 180, unit: "°" });
+const sides = Param.number("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-</details>
+**Parameter overrides** — key must match `name` exactly:
+
+```ts
+// Via require()
+const bracket = require("./bracket.forge.js", { Width: 80 });
+
+// Via CLI
+// forgecad run model.forge.js --param "Wall Thickness=3"
+```
 
-<details><summary><code>JointViewCouplingTermInput</code></summary>
+Also available as the shorthand alias `param()`.
 
 ```ts
-interface JointViewCouplingTermInput {
-  joint: string;
-  ratio?: number;
-}
+Param.number(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
 ```
 
-</details>
+#### `Param.string()` — Declare a string parameter that renders as a text input in the UI.
 
-<details><summary><code>JointViewAnimationInput</code></summary>
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
 
 ```ts
-interface JointViewAnimationInput {
-  name: string;
-  duration?: number;
-  loop?: boolean;
-  continuous?: boolean;
-  keyframes: JointViewAnimationKeyframeInput[];
-}
+const label = Param.string("Label", "Hello World");
+const name  = Param.string("Name", "Part-001", { maxLength: 20 });
 ```
 
-</details>
+Override via import:
 
-<details><summary><code>JointViewAnimationKeyframeInput</code></summary>
+```ts
+const tag = require("./tag.forge.js", { Label: "Custom Text" });
+```
+
+Only available as `Param.string()` — no standalone alias.
 
 ```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>;
-}
+Param.string(name: string, defaultValue: string, opts?: { maxLength?: number; }): string
 ```
 
-</details>
+#### `Param.bool()` — Declare a boolean parameter that 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.
 
-## C11: Parameterization & UI
+```ts
+const showHoles = Param.bool("Show Holes", true);
+if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
+return plate;
+```
 
-Declare user-facing controls that drive model geometry.
+Override via import:
+
+```ts
+const pan = require("./pan.forge.js", { "Show Lid": 0 });
+```
 
-#### `boolParam()`
+Also available as the shorthand alias `boolParam()`.
 
 ```ts
-boolParam(name: string, defaultValue: boolean): boolean
+Param.bool(name: string, defaultValue: boolean): boolean
 ```
 
-Declare a boolean parameter. Returns the current boolean value. Renders as a checkbox in the UI.
+#### `Param.choice()` — Declare a choice parameter that renders as a dropdown in the UI.
 
-#### `choiceParam()`
+`defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `Param.choice` over `Param.number` when a slider would hide intent — named choices like `"wok"` are self-describing.
+
+Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
 
 ```ts
-choiceParam(name: string, defaultValue: string, choices: string[]): string
+const panStyle = Param.choice("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
+if (panStyle === "wok") return buildWok();
 ```
 
-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", { "Pan Style": "wok" });
 ```
 
-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.
+Override via CLI:
+
+```bash
+forgecad run model.forge.js --param "Pan Style=wok"
+```
 
-<details><summary><code>ListParamFieldDef</code></summary>
+Also available as the shorthand alias `choiceParam()`.
 
 ```ts
-interface ListParamFieldDef {
-  min?: number;
-  max?: number;
-  step?: number;
-  unit?: string;
-  integer?: boolean;
-  boolean?: boolean;
-  choices?: string[];
-}
+Param.choice(name: string, defaultValue: string, choices: string[]): string
 ```
 
-</details>
+#### `Param.list()` — Declare a list parameter — an array of struct items with per-field UI controls.
+
+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.
 
-#### `param()`
+Field types:
+
+- Boolean fields (`boolean: true` in field defs) return as `boolean`
+- Choice fields (`choices: [...]` in field defs) return as `string`
+- All other fields return as `number`
 
 ```ts
-param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
+Param.list<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
 ```
 
-Declare a parameter. Returns the current value (default or overridden). Each call registers the param for UI generation.
+`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
+
+#### `dim()` — Add a dimension annotation between two points.
 
-#### `dim()`
+Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
+
+Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or `Point2D` objects (Z is treated as 0 for 2D inputs).
+
+**Ownership Rules (Report Pages)**
+
+- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
+- `component: "Part Name"` — route dimension to another named returned object.
+- Multiple owners: dimension is shared and appears on the assembly overview page.
+- No ownership set: report export infers ownership via endpoint-in-bbox.
 
 ```ts
-dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void
+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" });
 ```
 
-Add a dimension annotation between two points.
-
-<details><summary><code>DimOpts</code></summary>
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
 
 ```ts
-interface DimOpts {
-  offset?: number;
-  label?: string;
-  color?: string;
-  component?: string | string[];
-  currentComponent?: boolean;
-}
+dim(from: PointArg, to: PointArg, opts?: DimOpts): void
 ```
 
-</details>
+`DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
+
+#### `dimLine()` — Add a dimension annotation along a `Line2D`.
 
-#### `dimLine()`
+Convenience wrapper around { points from a constrained-sketch `Line2D` entity. All `opts` are forwarded unchanged.
 
 ```ts
-dimLine(l: Line2D, opts?: DimOpts): void
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
 ```
 
-Add a dimension annotation along a Line2D.
+```ts
+dimLine(l: Line2D, opts?: DimOpts): void
+```
 
 ---
 
@@ -1392,700 +1910,618 @@ Add a dimension annotation along a Line2D.
 
 Extract 2D geometry from a 3D solid (section, projection).
 
-#### `faceProfile()`
+#### `faceProfile()` — Extract the boundary profile of a named face as a 2D sketch.
+
+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.
 
 ```ts
 faceProfile(shape: Shape, face: FaceSelector): Sketch
 ```
 
-#### `intersectWithPlane()`
+#### `intersectWithPlane()` — Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
 
 ```ts
 intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch
 ```
 
-Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
-
-#### `projectToPlane()`
+#### `projectToPlane()` — Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
 
 ```ts
 projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
 ```
 
-Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
-
 ---
 
 ## C13: Export & Output
 
 Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF).
 
-#### `bom()`
+#### `bom()` — Register a Bill of Materials entry for report export.
+
+BOM entries are accumulated during script execution and exported alongside the model in report views. Rows are grouped by normalized `description + unit`. Pass an explicit `key` to force multiple descriptions to collapse into a single line item.
+
+- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts).
+- `unit` defaults to `"pieces"` when omitted or empty.
+- The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
+
+```ts
+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
+
+// Structured metadata for richer reports:
+bom(tubeLen, "rectangular steel tube", {
+  unit: "mm",
+  material: "steel",
+  section: [30, 20],
+  wall: 3,
+});
+```
 
 ```ts
 bom(quantity: number, description: string, opts?: BomOpts): void
 ```
 
-Add a bill-of-materials entry.
+**`BomOpts`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `unit?` | `string` | Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" |
+| `key?` | `string` | Optional explicit grouping key used during report aggregation. |
+| `material?` | `string` | Material name, e.g. "steel", "birch plywood", "nylon" |
+| `dimensions?` | `number[]` | Overall dimensions `[width, height]` or `[width, height, thickness]` in the entry's unit |
+| `section?` | `number[]` | Cross-section dimensions `[w, h]` for tubes and profiles |
+| `wall?` | `number` | Wall thickness for hollow sections (mm) |
+| `diameter?` | `number` | Diameter for round stock, bolts, dowels (mm) |
+| `length?` | `number` | Length for fasteners (mm) |
+| `process?` | `string` | Manufacturing process, e.g. "laser cut", "CNC", "welded" |
+| `notes?` | `string` | Free-form notes |
+| `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
+
+#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
+
+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`
 
-<details><summary><code>BomOpts</code></summary>
+**Collision mesh modes** (set per-link via `links["PartName"].collision`):
+
+| Mode | Description | Default | |------|-------------|---------| | `'convex'` | Convex hull (separate `_collision.stl`) | Yes | | `'box'` | AABB primitive — fastest physics | | | `'visual'` | Same mesh as visual — exact but slow | | | `'none'` | No collision geometry | |
+
+**Unit conventions:**
+
+- Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
+- Prismatic distances are in mm in Forge; exported in meters.
+- `massKg` is preferred; `densityKgM3` is used when mass is unknown.
+- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```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;
-}
+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,
+  });
+
+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>
+**CLI usage**
 
-#### `robotExport()`
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
+```
 
 ```ts
 robotExport(options: RobotExportOptions): CollectedRobotExport
 ```
 
-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).
+**`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`
 
-<details><summary><code>RobotExportOptions</code></summary>
+`RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
 
-```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;
-}
-```
+`RobotJointExportOptions`: `{ effort?: number, velocity?: number, damping?: number, friction?: number }`
 
-</details>
+**`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`
 
-<details><summary><code>RobotLinkExportOptions</code></summary>
+`RobotJointStatePublisherOptions`: `{ enabled?: boolean, joints?: string[], topic?: string, updateRate?: number }`
 
-```ts
-interface RobotLinkExportOptions {
-  massKg?: number;
-  densityKgM3?: number;
-  collision?: "visual" | "convex" | "box" | "none";
-}
-```
+`RobotWorldOptions`: `{ name?: string, generateDemoWorld?: boolean, spawnPose?: RobotPose6, keyboardTeleop?: RobotWorldKeyboardTeleopOptions }`
 
-</details>
+`RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-<details><summary><code>RobotJointExportOptions</code></summary>
+**`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`
 
-```ts
-interface RobotJointExportOptions {
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
+`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
 
-</details>
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-<details><summary><code>RobotDiffDrivePluginOptions</code></summary>
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-```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;
-}
-```
+**`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>
+`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
 
-<details><summary><code>RobotJointStatePublisherOptions</code></summary>
+`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
-```ts
-interface RobotJointStatePublisherOptions {
-  enabled?: boolean;
-  joints?: string[];
-  topic?: string;
-  updateRate?: number;
-}
-```
+#### `sheetMetal()` — Create a parametric sheet metal part with flanges, bend allowances, and flat-pattern unfolding.
 
-</details>
+`sheetMetal()` keeps one semantic model and derives both a folded 3D solid and an accurate flat pattern from it. The K-factor bend allowance is applied during unfolding. This is a strict v1 subset — it does not infer sheet metal from arbitrary solids.
 
-<details><summary><code>RobotWorldOptions</code></summary>
+**Recommended authoring order:**
 
-```ts
-interface RobotWorldOptions {
-  name?: string;
-  generateDemoWorld?: boolean;
-  spawnPose?: RobotPose6;
-  keyboardTeleop?: RobotWorldKeyboardTeleopOptions;
-}
-```
+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>
+**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.
 
-<details><summary><code>RobotWorldKeyboardTeleopOptions</code></summary>
+```ts
+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();
+```
 
 ```ts
-interface RobotWorldKeyboardTeleopOptions {
-  enabled?: boolean;
-  linearStep?: number;
-  angularStep?: number;
-}
+sheetMetal(options: SheetMetalOptions): SheetMetalPart
 ```
 
-</details>
+**`SheetMetalOptions`**
 
-<details><summary><code>CollectedRobotExport</code></summary>
+| 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. |
 
-```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;
-}
-```
+#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
-</details>
+For regular sketches, each polygon loop becomes a closed `LWPOLYLINE`. For constrained sketches, exports raw `LINE`, `CIRCLE`, and `ARC` entities from the constraint edge geometry, which preserves internal/shared edges that `toPolygons()` would merge away.
 
-<details><summary><code>AssemblyDefinition</code></summary>
+The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
 
 ```ts
-interface AssemblyDefinition {
-  name: string;
-  parts: AssemblyPartDef[];
-  joints: AssemblyJointDef[];
-  jointCouplings: AssemblyJointCouplingDef[];
-}
+const s = rect(100, 60);
+const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-</details>
-
-<details><summary><code>AssemblyPartDef</code></summary>
-
 ```ts
-interface AssemblyPartDef {
-  name: string;
-  part: AssemblyPart;
-  base: Transform;
-  metadata?: PartMetadata;
-}
+sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
 ```
 
-</details>
+**`SketchDxfOptions`**
+- `layer?: string` — DXF layer name. Default: "0"
+- `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
 
-<details><summary><code>PartMetadata</code></summary>
+#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+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.
 
-</details>
+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).
 
-<details><summary><code>AssemblyJointDef</code></summary>
+```ts
+const s = rect(100, 60);
+const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
+```
 
 ```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;
-}
+sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
 ```
 
-</details>
+**`SketchSvgOptions`**
 
-<details><summary><code>AssemblyJointCouplingDef</code></summary>
+| 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. |
 
-```ts
-interface AssemblyJointCouplingDef {
-  joint: string;
-  terms: JointCouplingTermRecord[];
-  offset: number;
-}
-```
+---
 
-</details>
+## C14: Visual & Debugging
+
+Control viewport appearance and debugging aids.
 
-<details><summary><code>JointCouplingTermRecord</code></summary>
+#### `verify.that()` — Custom predicate check.
 
 ```ts
-interface JointCouplingTermRecord {
-  joint: string;
-  ratio: number;
-}
+verify.that(label: string, check: () => boolean, message?: string): void
 ```
 
-</details>
-
-#### `sheetMetal()`
+#### `verify.equal()` — Check that two numbers are approximately equal (within tolerance).
 
 ```ts
-sheetMetal(options: SheetMetalOptions): SheetMetalPart
+verify.equal(label: string, actual: number, expected: number, tolerance?: number, message?: string): void
 ```
 
-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().
-
-<details><summary><code>SheetMetalOptions</code></summary>
+#### `verify.notEqual()` — Check that two numbers are NOT equal (differ by more than tolerance).
 
 ```ts
-interface SheetMetalOptions {
-  width: number;
-  height: number;
-  thickness: number;
-  bendRadius: number;
-  kFactor: number;
-  kind?: "rect";
-  size: number;
-}
+verify.notEqual(label: string, actual: number, unexpected: number, tolerance?: number, message?: string): void
 ```
 
-</details>
-
-#### `sketchToDxf()`
+#### `verify.greaterThan()` — Check that actual > min.
 
 ```ts
-sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
+verify.greaterThan(label: string, actual: number, min: number, message?: string): void
 ```
 
-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.
-
-<details><summary><code>SketchDxfOptions</code></summary>
+#### `verify.lessThan()` — Check that actual < max.
 
 ```ts
-interface SketchDxfOptions {
-  /** DXF layer name. Default: "0" */
-  layer?: string;
-  /** DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black) */
-  colorIndex?: number;
-}
+verify.lessThan(label: string, actual: number, max: number, message?: string): void
 ```
 
-</details>
-
-#### `sketchToSvg()`
+#### `verify.inRange()` — Check that min <= actual <= max.
 
 ```ts
-sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
+verify.inRange(label: string, actual: number, min: number, max: number, message?: string): void
 ```
 
-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).
-
-<details><summary><code>SketchSvgOptions</code></summary>
+#### `verify.centersCoincide()` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
 
 ```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;
-}
+verify.centersCoincide(label: string, a: ShapeLike, b: ShapeLike, tolerance?: number): void
 ```
 
-</details>
+#### `verify.notColliding()` — Check that two shapes do not collide (minGap > 0).
 
----
+```ts
+verify.notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: number): void
+```
 
-## C14: Visual & Debugging
+#### `verify.minClearance()` — Check that a minimum clearance gap exists between two shapes.
 
-Control viewport appearance and debugging aids.
+```ts
+verify.minClearance(label: string, a: ShapeLike, b: ShapeLike, minGap: number, searchLength?: number): void
+```
 
-#### `explodeView()`
+#### `verify.parallel()` — Check that two face normals are parallel (within toleranceDeg degrees).
 
 ```ts
-explodeView(options?: ExplodeViewOptions): void
+verify.parallel(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
 ```
 
-Configure viewport exploded-view behavior for the current script execution. Multiple calls merge; later values override earlier ones.
-
-<details><summary><code>ExplodeViewOptions</code></summary>
+#### `verify.perpendicular()` — Check that two face normals are perpendicular (within toleranceDeg degrees).
 
 ```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>;
-}
+verify.perpendicular(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
 ```
 
-</details>
-
-<details><summary><code>ExplodeDirective</code></summary>
+#### `verify.coplanar()` — Check that a face is coplanar with (same plane as) another face, meaning they are parallel AND their centers lie on the same plane.
 
 ```ts
-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;
-}
+verify.coplanar(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number, toleranceMm?: number): void
 ```
 
-</details>
-
-<details><summary><code>ExplodeViewDirective</code> extends ExplodeDirective</summary>
+#### `verify.faceAt()` — Check that a face center lies at a specific position (within toleranceMm).
 
 ```ts
-interface ExplodeViewDirective extends ExplodeDirective {
-}
+verify.faceAt(label: string, face: FaceRefLike, expectedPos: [ number
 ```
 
-</details>
-
-#### `cutPlane()`
+#### `verify.sameDirection()` — Check that two face normals point in the same direction (not antiparallel). Stricter than parallel — both |angle| AND sign must match.
 
 ```ts
-cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void
+verify.sameDirection(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
 ```
 
-<details><summary><code>CutPlaneOptions</code></summary>
+#### `verify.isEmpty()` — Check that a shape is empty.
 
 ```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;
-}
+verify.isEmpty(label: string, shape: ShapeLike, message?: string): void
 ```
 
-</details>
-
-#### `scene()`
+#### `verify.notEmpty()` — Check that a shape is NOT empty.
 
 ```ts
-scene(options: SceneOptions): void
+verify.notEmpty(label: string, shape: ShapeLike, message?: string): void
 ```
 
-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 }, }, }); ```
-
-<details><summary><code>SceneOptions</code></summary>
+#### `verify.volumeApprox()` — Check that a shape's volume is approximately equal to expected (mm³).
 
 ```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;
-}
+verify.volumeApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
 ```
 
-</details>
-
-<details><summary><code>SceneBackgroundGradient</code></summary>
+#### `verify.areaApprox()` — Check that a shape's surface area is approximately equal to expected (mm²).
 
 ```ts
-interface SceneBackgroundGradient {
-  top: string;
-  bottom: string;
-}
+verify.areaApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
 ```
 
-</details>
-
-<details><summary><code>SceneCameraConfig</code></summary>
+#### `verify.boundingBoxSize()` — Check that a shape's bounding box has approximately the given size.
 
 ```ts
-interface SceneCameraConfig {
-  fov?: number;
-  type?: "perspective" | "orthographic";
-}
+verify.boundingBoxSize(label: string, shape: ShapeLike, expectedSize: [ number
 ```
 
-</details>
-
-<details><summary><code>SceneLightConfig</code></summary>
-
-```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;
-}
-```
+#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
 
-</details>
+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>SceneEnvironmentConfig</code></summary>
+Multiple calls merge — later values override earlier ones on a per-key basis. `byName` and `byPath` maps are merged entry-by-entry.
+
+For programmatic explode applied before returning (without the slider), use `lib.explode()` instead.
+
+```js
+explodeView({
+  amountScale: 1.2,
+  stages: [0.35, 0.8],
+  mode: 'radial',
+  byPath: { 'Drive/Shaft': { direction: [1, 0, 0], stage: 1.6 } },
+});
+```
 
 ```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;
-}
+explodeView(options?: ExplodeViewOptions): void
 ```
 
-</details>
+**`ExplodeViewOptions`**
+
+| 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><summary><code>SceneFogConfig</code></summary>
+**`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
+
+#### `cutPlane()`
 
 ```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;
-}
+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>ScenePostProcessingConfig</code></summary>
+#### `mock()` — Register a mock (context) object for visualization and collision checking.
 
-```ts
-interface ScenePostProcessingConfig {
-  bloom?: SceneBloomConfig;
-  vignette?: SceneVignetteConfig;
-  grain?: SceneGrainConfig;
-  toneMappingExposure?: number;
-}
-```
+Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via `require()`. This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
+
+The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
 
-</details>
+Mock objects participate in `forgecad run` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
 
-<details><summary><code>SceneBloomConfig</code></summary>
+In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.
 
 ```ts
-interface SceneBloomConfig {
-  intensity?: number;
-  threshold?: number;
-  radius?: number;
-}
-```
+// bracket.forge.js
+const wall = mock(box(100, 200, 10).translate(0, 0, -5), "wall");
+const bolt = mock(cylinder(3, 15).translate(10, 15, 0), "bolt");
 
-</details>
+const bracket = box(20, 30, 5);
+verify.notColliding("bracket vs wall", bracket, wall);
 
-<details><summary><code>SceneVignetteConfig</code></summary>
+return bracket;
+// When imported: only bracket is exported
+// When run directly: bracket + wall + bolt all visible
+```
 
 ```ts
-interface SceneVignetteConfig {
-  darkness?: number;
-  offset?: number;
-}
+mock<T extends Shape>(shape: T, name?: string): T
 ```
 
-</details>
+#### `scene()` — Configure the scene environment for the current script execution.
 
-<details><summary><code>SceneGrainConfig</code></summary>
+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.
 
-```ts
-interface SceneGrainConfig {
-  intensity?: number;
-}
-```
+When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
+
+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>SceneGroundConfig</code></summary>
+All numeric values accept `param()` expressions.
+
+```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),
+  },
+});
+```
 
 ```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;
-}
+scene(options: SceneOptions): void
 ```
 
-</details>
+**`SceneOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
+| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+
+`SceneBackgroundGradient`: `{ top: string, bottom: string }`
+
+`SceneCameraConfig`: `{ fov?: number, type?: "perspective" | "orthographic" }`
+
+**`SceneLightConfig`**
+
+| 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?` | | — |
+
+**`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
+
+**`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`
+
+`ScenePostProcessingConfig`: `{ bloom?: SceneBloomConfig, vignette?: SceneVignetteConfig, grain?: SceneGrainConfig, toneMappingExposure?: number }`
+
+`SceneBloomConfig`: `{ intensity?: number, threshold?: number, radius?: number }`
+
+`SceneVignetteConfig`: `{ darkness?: number, offset?: number }`
 
-<details><summary><code>SceneCaptureConfig</code></summary>
+`SceneGrainConfig`: `{ intensity?: number }`
+
+**`SceneGroundConfig`**
+
+| 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 |
+
+**`SceneCaptureConfig`**
+
+| 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') |
+
+#### `showLabels()` — Highlight all user-labeled faces on a shape for visual debugging.
+
+Shows each user-authored label name in the viewport for visual debugging. Returns the shape unchanged for chaining: `return showLabels(myShape)`.
 
 ```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(shape: Shape): Shape
 ```
 
-</details>
+#### `viewConfig()` — Configure viewport helper visuals for the current script execution.
+
+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.
 
-#### `viewConfig()`
+This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
+
+```js
+viewConfig({
+  jointOverlay: {
+    axisColor: '#13dfff',
+    arcColor: '#ff7a1a',
+    axisLineRadiusScale: 0.03,
+    arcLineRadiusScale: 0.022,
+  },
+});
+```
 
 ```ts
 viewConfig(options?: ViewConfigOptions): void
 ```
 
-Configure runtime viewport visuals for the current script execution. Multiple calls merge; later values override earlier ones.
+`ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
 
-<details><summary><code>ViewConfigOptions</code></summary>
+**`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`
 
-```ts
-interface ViewConfigOptions {
-  jointOverlay?: JointOverlayViewConfigOptions;
-}
-```
+#### `spec()` — Create a named, reusable bundle of verification checks.
 
-</details>
-
-<details><summary><code>JointOverlayViewConfigOptions</code></summary>
-
-```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;
-}
-```
+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.
 
-</details>
+Specs can be defined in separate `.forge.js` files and imported via `require()` to share them across models.
 
-#### `spec()`
+`spec.check()` returns a `SpecResult` — you can inspect it programmatically or ignore the return value and let the Checks panel show results.
 
 ```ts
-spec(name: string, checkFn: (...args: any[]) => void): Spec
-```
+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);
 
-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.
+// Check relationships between parts
+const fitSpec = spec("Assembly fit", (partA, partB) => {
+  verify.notColliding("No interference", partA, partB, 10);
+});
+fitSpec.check(bracket, standoff);
+```
 
-<details><summary><code>Spec</code></summary>
+**Spec-first workflow:** Write specs before building geometry. Checks go from red to green as you build — effectively TDD for CAD.
 
 ```ts
-interface Spec {
-  /** The display name of this spec */
-  name: string;
-}
+spec(name: string, checkFn: (...args: any[]) => void): Spec
 ```
 
-</details>
+**`Spec`**
+- `name: string` — The display name of this spec
 
 ---
 
@@ -2093,20 +2529,72 @@ 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.
+
+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.
+
+```js
+// BAD — every sub-part repeats the parent's global offset
+const unitX = 0, unitY = -18, unitZ = 70;
+const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ);
+const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+```
+
+// GOOD — build at origin, group, translate once const body = roundedBox(100, 20, 32, 4); const panel = box(98, 2, 18).translate(0, -12, 4); const louver = box(88, 2, 6).translate(0, -14, -11); const indoorUnit = group( { name: 'Body', shape: body }, { name: 'Panel', shape: panel }, { name: 'Louver', shape: louver }, ).translate(0, -18, 70);
 
 ```ts
 group(...items: GroupInput[]): ShapeGroup
 ```
 
-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.).
-
 ---
 
 ## C16: Part Library
 
 Pre-built parametric parts accessible via `lib.*`.
 
-*No free functions — see class methods (Shape, Sketch, ConstrainedSketchBuilder).*
+#### `Wood.board()` — Create a wood board with metadata for manufacturing.
+
+The board is a box(width, height, thickness) centered on XY, base at Z=0. Width along X, height along Y, thickness along Z (0 to thickness).
+
+```ts
+Wood.readonly board: (width: number, height: number, thickness: number, opts?: WoodBoardOptions) => WoodBoard
+```
+
+**`WoodBoardOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `species?` | `string` | Wood species, e.g. "birch", "oak", "plywood". Default: "wood" |
+| `material?` | `string` | Material description for BOM, e.g. "birch plywood". Default: species value |
+| `grain?` | `string` | Grain direction: "long" (along width) or "cross" (along height). Default: "long" |
+| `color?` | `string` | Color hex string for visualization. Default: "#d2b48c" (tan/wood) |
+| `autoBom?` | `boolean` | If false, skip automatic BOM registration. Default: true |
+
+#### `Wood.dado()` — Cut a dado (channel) across the face of a host board for a guest board to sit in.
+
+Mutates `host.shape` by subtracting a rectangular channel.
+
+```ts
+Wood.readonly dado: typeof dado
+```
+
+#### `Wood.rabbet()` — Cut a rabbet (L-shaped step) along an edge of a board.
+
+Mutates `board.shape` by subtracting a step from the specified edge.
+
+```ts
+Wood.readonly rabbet: typeof rabbet
+```
+
+#### `Wood.mortiseAndTenon()` — Cut a mortise in one board and shape a tenon on another.
+
+Mutates both boards — subtracts the mortise pocket and removes shoulder material to form the tenon.
+
+```ts
+Wood.readonly mortiseAndTenon: typeof mortiseAndTenon
+```
 
 ---