forgecad 0.6.3 → 0.7.0

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

@@ -13,1454 +13,563 @@ skill-order: 100
 
 ### 3D Primitives
 
-Create basic 3D shapes.
+#### `box()` — Create a rectangular box. Centered on XY, base at Z=0.
 
-#### `box()`
+For named faces, build from a labeled sketch: `rect(x, y).labelEdges('s', 'e', 'n', 'w').extrude(z, { labels: { start: 'bottom', end: 'top' } })`.
 
-```ts
-box$1(x: number, y: number, z: number, center?: boolean): Shape
-```
+`box$1(x: number, y: number, z: number): Shape`
 
-Create a rectangular box with named faces and edges. When center is false (default), one corner sits at the origin. Returns a Shape with faces (top, bottom, side-left, side-right, side-top, side-bottom) and edges (vert-bl, vert-br, vert-tr, vert-tl, etc.).
+#### `cylinder()` — Create a cylinder or cone with named faces and edges. Centered on XY, base at Z=0.
 
-#### `cylinder()`
+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
-cylinder$1(height: number, radius: number, radiusTop?: number, segments?: number, center?: boolean): Shape
-```
+`cylinder$1(height: number, radius: number, radiusTop?: number, segments?: number): Shape`
 
-Create a cylinder or cone with named faces and edges. When radiusTop differs from radius, creates a tapered cone. Use segments for regular prisms. Returns a Shape with faces (top, bottom, side) and edges (top-rim, bottom-rim).
+#### `sphere()` — Create a sphere centered at the origin. Use segments for lower-poly approximations.
 
-#### `sphere()`
+`sphere$1(radius: number, segments?: number): Shape`
 
-```ts
-sphere$1(radius: number, segments?: number): Shape
-```
+#### `torus()` — Create a torus (donut shape) lying in the XY plane. Centered on all axes (origin is the ring center).
 
-Create a sphere centered at the origin. Use segments for lower-poly approximations. @concept primitive
+`torus$1(majorRadius: number, minorRadius: number, segments?: number): Shape`
 
 ### Boolean Operations
 
-Combine shapes using set operations.
-
-#### `union()`
-
-```ts
-union(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
-```
-
-Combine shapes into a single solid (additive boolean). Accepts individual shapes or arrays. @concept boolean
-
-#### `difference()`
-
-```ts
-difference(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
-```
-
-Subtract shapes from a base shape. The first shape is the base; all subsequent shapes are subtracted. @concept boolean
-
-#### `intersection()`
-
-```ts
-intersection(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
-```
-
-Keep only the overlapping volume of the input shapes (intersection boolean). @concept boolean
-
-### Patterns & Topology
-
-Repeat, mirror, fillet, and chamfer geometry.
-
-#### `filletEdgeSegment()`
-
-```ts
-filletEdgeSegment(shape: Shape, segment: EdgeSegment, radius: number, segments?: number): Shape
-```
-
-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;
-}
-```
-
-</details>
-
-#### `chamferEdgeSegment()`
-
-```ts
-chamferEdgeSegment(shape: Shape, segment: EdgeSegment, size: number): Shape
-```
-
-Apply a chamfer (beveled edge) to a mesh-selected edge. Works on any straight edge of any shape — not limited to tracked box edges.
-
-#### `selectEdges()`
-
-```ts
-selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
-```
-
-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.
-
-<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;
-}
-```
-
-</details>
-
-<details><summary><code>BoundingRegion</code></summary>
-
-```ts
-interface BoundingRegion {
-  xMin?: number;
-  xMax?: number;
-  yMin?: number;
-  yMax?: number;
-  zMin?: number;
-  zMax?: number;
-}
-```
-
-</details>
-
-#### `selectEdge()`
-
-```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.
-
-#### `coalesceEdges()`
-
-```ts
-coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
-```
-
-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.
-
-#### `arcBridgeBetweenRects()`
-
-```ts
-arcBridgeBetweenRects(rectA: RectAreaArg, rectB: RectAreaArg, segments?: number): Shape
-```
-
-Build an arc bridge between two rectangular areas.
-
-#### `filletEdge()`
-
-```ts
-filletEdge(shape: Shape, edge: EdgeRef, radius: number, quadrant?: [ number, number ], segments?: number): Shape
-```
-
-Round a named edge of a shape with a circular fillet of the given radius. Requires a compile-covered target.
-
-<details><summary><code>EdgeRef</code></summary>
-
-```ts
-interface EdgeRef {
-  name: EdgeName;
-  /** Compiler-owned edge query when available. */
-  query?: EdgeQueryRef;
-}
-```
-
-</details>
-
-#### `chamferEdge()`
-
-```ts
-chamferEdge(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape
-```
-
-Bevel a named edge of a shape with a 45-degree chamfer of the given size. Requires a compile-covered target.
-
-#### `filletCorners()`
-
-```ts
-filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
-```
-
-Create a polygon from points with specified corners rounded to arc fillets. Each corner spec identifies a vertex index and radius.
-
-<details><summary><code>FilletCornerSpec</code></summary>
-
-```ts
-interface FilletCornerSpec {
-  index: number;
-  radius: number;
-  segments?: number;
-}
-```
-
-</details>
-
-#### `linearPattern()`
-
-```ts
-linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
-```
-
-Repeat a shape in a linear pattern along a direction vector and union the copies.
-
-#### `circularPattern()`
-
-```ts
-circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
-```
+#### `union()` — Combine shapes into a single solid (additive boolean).
 
-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] })
+Accepts individual shapes, or an array of shapes. The first operand's color is preserved in the result.
 
-<details><summary><code>CircularPatternOptions</code></summary>
+`union(...inputs: ShapeOperandInput[]): Shape`
 
-```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;
-}
-```
+#### `difference()` — Subtract shapes from a base shape (subtractive boolean).
 
-</details>
+The first shape is the base; all subsequent shapes are subtracted from it. Accepts individual shapes, or an array of shapes.
 
-#### `mirrorCopy()`
+`difference(...inputs: ShapeOperandInput[]): Shape`
 
-```ts
-mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
-```
+#### `intersection()` — Keep only the overlapping volume of the input shapes (intersection boolean).
 
-Mirror a shape across a plane defined by its normal and union the mirror with the original.
+Requires at least two shapes. Accepts individual shapes, or an array.
 
-### Imports & Composition
+`intersection(...inputs: ShapeOperandInput[]): Shape`
 
-Import model files and SVG assets from other files.
+### Edge Features
 
-#### `require()`
-
-```ts
-require$1(path: string, paramOverrides?: Record<string, number>): any
-```
-
-Import a module with optional ForgeCAD parameter overrides. Returns the module's exports. @concept import
-
-#### `importSvgSketch()`
-
-```ts
-importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
-```
-
-Parse an SVG file and return it as a Sketch with options for region filtering, scaling, and simplification. @concept import
-
-<details><summary><code>SvgImportOptions</code></summary>
-
-```ts
-interface SvgImportOptions {
-  /** Which geometry channels to include: - `auto`: prefer fills; if no fill geometry exists, fall back to strokes - `fill`: import only filled regions - `stroke`: import only stroke geometry - `fill-and-stroke`: include both */
-  include?: "auto" | "fill" | "stroke" | "fill-and-stroke";
-  /** Keep all disconnected regions, or only the largest. */
-  regionSelection?: "all" | "largest";
-  /** Keep at most this many regions (largest-first). */
-  maxRegions?: number;
-  /** Drop regions below this absolute area threshold. */
-  minRegionArea?: number;
-  /** Drop regions below this ratio of largest-region area. */
-  minRegionAreaRatio?: number;
-  /** Curve flattening tolerance in SVG user units. Smaller = more segments, higher fidelity. */
-  flattenTolerance?: number;
-  /** Minimum segment count for arc discretization. */
-  arcSegments?: number;
-  /** Global scale applied after SVG parsing. */
-  scale?: number;
-  /** Maximum imported sketch width. If exceeded, geometry is uniformly downscaled to fit. */
-  maxWidth?: number;
-  /** Maximum imported sketch height. If exceeded, geometry is uniformly downscaled to fit. */
-  maxHeight?: number;
-  /** Recenter imported geometry so its 2D bounds center is at CAD origin. */
-  centerOnOrigin?: boolean;
-  /** Simplification tolerance for final sketch cleanup. */
-  simplify?: number;
-  /** Flip SVG Y-down coordinates to CAD Y-up. Enabled by default. */
-  invertY?: boolean;
-}
-```
-
-</details>
-
-### Parameters
-
-Declare user-adjustable parameters with UI controls.
-
-#### `param()`
-
-```ts
-param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
-```
-
-Declare a parameter. Returns the current value (default or overridden). Each call registers the param for UI generation.
-
-#### `boolParam()`
-
-```ts
-boolParam(name: string, defaultValue: boolean): boolean
-```
-
-Declare a boolean parameter. Returns the current boolean value. Renders as a checkbox in the UI.
-
-### Grouping
-
-Organize multiple shapes into named groups.
-
-#### `group()`
-
-```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.).
-
-### Section & Projection
-
-Slice or project 3D shapes to 2D.
-
-#### `intersectWithPlane()`
-
-```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()`
-
-```ts
-projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
-```
-
-Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
-
-### Other
-
-#### `composeChain()`
-
-```ts
-composeChain(...steps: TransformInput[]): Transform
-```
-
-Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
-
-#### `portFactory()`
-
-```ts
-portFactory(input: PortInput): PortDef
-```
-
-<details><summary><code>PortInput</code></summary>
-
-```ts
-interface PortInput {
-  kind?: JointType;
-  min?: number;
-  max?: number;
-}
-```
-
-</details>
-
-<details><summary><code>PortDef</code></summary>
-
-```ts
-interface PortDef {
-  origin: Vec3;
-  axis: Vec3;
-  up: Vec3;
-  extent?: number;
-  kind?: JointType;
-  min?: number;
-  max?: number;
-  connectorType?: string;
-  gender?: ConnectorGender;
-  measurements?: Record<string, number | string>;
-}
-```
-
-</details>
-
-#### `connectorFactory()`
-
-```ts
-connectorFactory(connectorType: string, input: PortInput, measurements?: Record<string, number | string>): ConnectorInput
-```
-
-
-<details><summary><code>ConnectorInput</code> extends PortInput</summary>
-
-```ts
-interface ConnectorInput extends PortInput {
-  connectorType: string;
-  gender: ConnectorGender$1;
-  measurements?: Record<string, number | string>;
-}
-```
-
-</details>
-
-#### `polar()`
-
-```ts
-polar(length: number, angleDeg: number, from?: [ number, number ]): [ number, number ]
-```
-
-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) ```
-
-#### `fillet()`
-
-```ts
-fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
-```
-
-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)
-
-#### `chamfer()`
-
-```ts
-chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
-```
-
-Apply chamfers (beveled edges) to one or more edges of a shape. Works on both straight and curved edges. Supports OCCT and Manifold backends. // Chamfer all edges chamfer(myShape, 1) // Chamfer vertical edges only chamfer(myShape, 2, { parallel: [0, 0, 1] })
-
-#### `draft()`
-
-```ts
-draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
-```
-
-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)
-
-#### `offsetSolid()`
-
-```ts
-offsetSolid(shape: Shape, thickness: number): 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)
-
-#### `choiceParam()`
-
-```ts
-choiceParam(name: string, defaultValue: string, choices: string[]): string
-```
-
-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()`
-
-```ts
-listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
-```
-
-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.
-
-<details><summary><code>ListParamFieldDef</code></summary>
-
-```ts
-interface ListParamFieldDef {
-  min?: number;
-  max?: number;
-  step?: number;
-  unit?: string;
-  integer?: boolean;
-  boolean?: boolean;
-  choices?: string[];
-}
-```
-
-</details>
-
-#### `distance()`
-
-```ts
-distance(a: Vec3, b: Vec3): number
-```
+#### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
 
-#### `midpoint()`
+**Details**
 
-```ts
-midpoint(a: Vec3, b: Vec3): Vec3
-```
+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.
 
-#### `lerp()`
+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
 
-```ts
-lerp(a: Vec3, b: Vec3, t: number): Vec3
-```
+Throws if no edges match the selection, or if `radius` is not a positive finite number.
 
-#### `direction()`
+**Example**
 
 ```ts
-direction(a: Vec3, b: Vec3): Vec3
-```
+// Fillet all edges
+fillet(myShape, 2)
 
-#### `offset()`
+// Fillet only top convex edges
+fillet(myShape, 1.5, { atZ: 20, convex: true })
 
-```ts
-offset(point: Vec3, dir: Vec3, amount: number): Vec3
+// Fillet vertical edges selected beforehand
+const edges = selectEdges(myShape, { parallel: [0, 0, 1] })
+fillet(myShape, 3, edges)
 ```
 
-#### `loftAlongSpine()`
+`fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape`
 
-```ts
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$4[], tValues: number[], options?: LoftAlongSpineOptions): Shape
-```
+#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
 
-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**
 
-<details><summary><code>LoftAlongSpineOptions</code></summary>
+Produces a 45° bevel at the specified `size` (distance from edge). Works on both straight and curved edges. Supports OCCT and Manifold backends.
 
-```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;
-}
-```
-
-</details>
+The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
-#### `variableSweep()`
+**Example**
 
 ```ts
-variableSweep(spine: Curve3D | Vec3$4[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
-```
-
-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.
-
-<details><summary><code>VariableSweepSection</code></summary>
+// Chamfer all edges
+chamfer(myShape, 1)
 
-```ts
-interface VariableSweepSection {
-  /** Parameter along the spine (0 = start, 1 = end). */
-  t: number;
-  /** Cross-section profile at this station. */
-  profile: Sketch;
-}
+// Chamfer only vertical edges
+chamfer(myShape, 2, { parallel: [0, 0, 1] })
 ```
 
-</details>
+`chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape`
 
-<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;
-}
-```
+#### `draft()` — Apply a draft angle (taper) to vertical faces for mold extraction.
 
-</details>
+**Details**
 
-#### `loadFont()`
+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°.
 
-```ts
-loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font
-```
+Requires the OCCT backend. Throws on Manifold.
 
-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)
-
-#### `hermiteTransition()`
+**Example**
 
 ```ts
-hermiteTransition(a: EdgeEndpoint, b: EdgeEndpoint): HermiteCurve3D
-```
-
-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
-
-<details><summary><code>EdgeEndpoint</code></summary>
+// Add 3° draft to a box for injection molding
+draft(myBox, 3)
 
-```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;
-}
+// Draft with custom pull direction and neutral plane
+draft(myShape, 2, [0, 0, 1], 10)
 ```
 
-</details>
-
-#### `hermiteTransitionG2()`
+`draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape`
 
-```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
-```
+#### `offsetSolid()` — Uniformly offset all surfaces of a solid inward or outward.
 
-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**
 
-<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;
-}
-```
+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.
 
-</details>
+Requires the OCCT backend. Throws on Manifold.
 
-#### `circularLayout()`
+**Example**
 
 ```ts
-circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
-```
-
-Compute evenly-spaced positions around a circle. Eliminates the most common trig pattern in CAD scripts: ```js // Before — manual trig for (let i = 0; i < 12; i++) { const angle = i * 30 * Math.PI / 180; markers.push(marker.translate(r * Math.cos(angle), r * Math.sin(angle), 0)); } // After — declarative for (const {x, y} of circularLayout(12, r)) { markers.push(marker.translate(x, y, 0)); } ```
+// Grow a box outward by 1mm on all sides
+offsetSolid(myBox, 1)
 
-<details><summary><code>CircularLayoutOptions</code></summary>
-
-```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;
-}
+// Shrink a shape inward by 0.5mm
+offsetSolid(myShape, -0.5)
 ```
 
-</details>
-
-<details><summary><code>LayoutPoint</code></summary>
+`offsetSolid(shape: Shape, thickness: number): Shape`
 
-```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
-```
+### Patterns & Layout
 
-</details>
+#### `selectEdges()` — Select all edges from a shape that match the given query.
 
-#### `polygonVertices()`
+**Details**
 
-```ts
-polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
-```
+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.
 
-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); ```
+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.
 
-<details><summary><code>PolygonVerticesOptions</code></summary>
+**Example**
 
 ```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;
+// 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);
 }
 ```
 
-</details>
-
-#### `routePerimeter()`
-
-```ts
-routePerimeter(steps: PerimeterStep[]): Sketch
-```
-
-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 }, ]) ```
-
-#### `linearPattern2d()`
+`selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]`
 
-```ts
-linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
-```
-
-Repeat a sketch in a linear pattern
-
-#### `circularPattern2d()`
-
-```ts
-circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
-```
+**`EdgeQuery`**
 
-Repeat a sketch in a circular pattern around a center point
+| 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`). |
 
-#### `arcSlot()`
+`BoundingRegion`: `{ xMin?: number, xMax?: number, yMin?: number, yMax?: number, zMin?: number, zMax?: number }`
 
-```ts
-arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
-```
+**`EdgeSegment`**
 
-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 ```
+| 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` | | — |
 
-#### `surfacePatch()`
+#### `selectEdge()` — Select the single best-matching edge from a shape.
 
-```ts
-surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
-```
+**Details**
 
-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.
+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.
 
-<details><summary><code>SurfacePatchOptions</code></summary>
+**Example**
 
 ```ts
-interface SurfacePatchOptions {
-  /** Number of samples along each direction. Default 24. */
-  resolution?: number;
-  /** Thickness of the generated solid. Default 0.5. */
-  thickness?: number;
-}
+// Chamfer one specific edge near a known point
+const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
+result = chamfer(result, 1.5, bottomEdge);
 ```
 
-</details>
+`selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment`
 
-#### `transitionCurve()`
+#### `coalesceEdges()` — Merge collinear edge segments into longer logical edges.
 
-```ts
-transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
-```
+**Details**
 
-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 }, ); ```
+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.
 
-<details><summary><code>TransitionEdge</code></summary>
+The `tolerance` controls the maximum perpendicular distance from collinearity before two segments are considered non-collinear. Default: `0.01`.
 
-```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;
-}
-```
-
-</details>
-
-<details><summary><code>TransitionCurveOptions</code></summary>
+**Example**
 
 ```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;
+const topEdges = selectEdges(part, { atZ: 20 });
+for (const edge of coalesceEdges(topEdges)) {
+  result = fillet(result, 2, edge);
 }
 ```
 
-</details>
-
-#### `transitionSurface()`
-
-```ts
-transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
-```
+`coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]`
 
-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 }, ); ```
+#### `filletCorners()` — Create a polygon from points with specific corners rounded to arc fillets.
 
+**Details**
 
-<details><summary><code>TransitionSurfaceOptions</code> extends TransitionCurveOptions</summary>
+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.
 
-```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;
-}
-```
+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
 
-</details>
+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.
 
-#### `transitionCurveFromPoints()`
+**Example**
 
 ```ts
-transitionCurveFromPoints(startPoint: Vec3$7, startTangent: Vec3$7, endPoint: Vec3$7, endTangent: Vec3$7, options?: TransitionCurveOptions): HermiteCurve3D
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
 ```
 
-Convenience: create a transition curve from raw coordinate data. Useful when you have endpoints and directions as plain arrays without constructing TransitionEdge objects.
+`filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch`
 
-#### `connectEdges()`
+`FilletCornerSpec`: `{ index: number, radius: number, segments?: number }`
 
-```ts
-connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
-```
+#### `circularLayout()` — Compute evenly-spaced positions around a circle.
 
-<details><summary><code>EdgeSegment</code></summary>
+Eliminates the most common trig pattern in CAD scripts:
 
-```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;
+```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));
 }
-```
 
-</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;
+// After — declarative
+for (const {x, y} of circularLayout(12, r)) {
+  markers.push(marker.translate(x, y, 0));
 }
 ```
 
-</details>
+`circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]`
 
-#### `spec()`
-
-```ts
-spec(name: string, checkFn: (...args: any[]) => void): Spec
-```
+**`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).
 
-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.
+`LayoutPoint`: `{ x: number, y: number }`
 
-<details><summary><code>Spec</code></summary>
+#### `polygonVertices()` — Compute the vertex positions of a regular polygon.
 
-```ts
-interface Spec {
-  /** The display name of this spec */
-  name: string;
-}
-```
+Default orientation places the first vertex at the top (90 degrees), matching the convention used by `ngon()`.
 
-</details>
+Eliminates manual Math.sqrt(3) for triangles, pentagon vertex math, etc:
 
-#### `faceProfile()`
+```js
+// Before — manual equilateral triangle
+const v1 = [center.x - r/2, center.y + r * Math.sqrt(3)/2];
+const v2 = [center.x - r/2, center.y - r * Math.sqrt(3)/2];
+const v3 = [center.x + r, center.y];
 
-```ts
-faceProfile(shape: Shape, face: FaceSelector): Sketch
+// After — declarative
+const [v1, v2, v3] = polygonVertices(3, r);
 ```
 
-#### `fingerJointProfile()`
+`polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]`
 
-```ts
-fingerJointProfile(length: number, thickness: number, options?: FingerJointOptions): FingerJointResult
-```
+**`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).
 
-Generate a finger joint edge profile for two mating edges. The tab side gets finger protrusions along its bottom edge (y=0), the slot side gets matching gaps cut from its edge. Both profiles span [0, length] along X and [0, thickness] along Y.
+#### `linearPattern()` — Repeat a shape in a linear pattern along a direction vector and union the copies.
 
-<details><summary><code>FingerJointOptions</code></summary>
+**Details**
 
-```ts
-interface FingerJointOptions {
-  /** Explicit finger count (must be odd, >= 3). Default: auto from length/thickness. */
-  fingers?: number;
-  /** Explicit finger width. Default: auto. */
-  fingerWidth?: number;
-  /** Extra clearance per side (mm). Default: 0. */
-  clearance?: number;
-  /** Laser kerf (mm). Default: 0. */
-  kerf?: number;
-  /** Whether edge starts with full finger or half. Default: 'full'. */
-  endStyle?: "full" | "half";
-}
-```
-
-</details>
+Creates `count` copies of `shape`, each offset by `(dx*i, dy*i, dz*i)` from the original. All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy so face identity via owner-scoped canonical queries still works post-merge.
 
-<details><summary><code>FingerJointResult</code></summary>
+**Example**
 
 ```ts
-interface FingerJointResult {
-  /** Even-position finger rects (tabs for side A, slots for side B). */
-  tabProfile: Sketch;
-  /** Odd-position finger rects (tabs for side B, slots for side A). */
-  matingProfile: Sketch;
-  /** Legacy: full rectangle minus odd slot cuts. */
-  slotProfile: Sketch;
-}
+// 5 cylinders, 20mm apart along X
+linearPattern(cylinder(10, 3), 5, 20, 0)
 ```
 
-</details>
-
-#### `tabSlotProfile()`
-
-```ts
-tabSlotProfile(length: number, thickness: number, options?: TabSlotOptions): TabSlotResult
-```
+`linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape`
 
-Generate tabs on one edge and matching slots for the mating panel face. Tabs protrude in +Y from y=0, spanning the tab width along X. Slots are the cutout geometry to subtract from the mating panel.
+#### `circularPattern()` — Repeat a shape in a circular pattern around an axis and union the copies.
 
-<details><summary><code>TabSlotOptions</code></summary>
+**Details**
 
-```ts
-interface TabSlotOptions {
-  /** Number of tabs. Default: auto (length / (4 * thickness)). */
-  tabCount?: number;
-  /** Tab width. Default: 2 * thickness. */
-  tabWidth?: number;
-  /** Extra clearance per side (mm). Default: 0. */
-  clearance?: number;
-  /** Laser kerf (mm). Default: 0. */
-  kerf?: number;
-  /** Distance from panel edges to first/last tab center. Default: thickness. */
-  inset?: number;
-}
-```
+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.
 
-</details>
+Two calling conventions: - **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)` - **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
 
-<details><summary><code>TabSlotResult</code></summary>
+**Example**
 
 ```ts
-interface TabSlotResult {
-  tabs: Sketch;
-  slots: Sketch;
-}
-```
-
-</details>
+// 8 holes evenly spaced around origin
+circularPattern(cylinder(12, 4).translate(30, 0, -1), 8)
 
-#### `livingHingeProfile()`
-
-```ts
-livingHingeProfile(length: number, width: number, options?: LivingHingeOptions): Sketch
+// Circular pattern around X axis
+circularPattern(myFeature, 4, { axis: [1, 0, 0], origin: [0, 0, 50] })
 ```
 
-Generate a living hinge slit pattern to subtract from a panel. The pattern fills a region [0, length] x [0, width] with staggered slits that allow the material to flex.
+`circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape`
 
-<details><summary><code>LivingHingeOptions</code></summary>
+**`CircularPatternOptions`**
+- `centerX?: number` — Center X of the rotation (default: 0). Used when axis is Z (legacy mode).
+- `centerY?: number` — Center Y of the rotation (default: 0). Used when axis is Z (legacy mode).
 
-```ts
-interface LivingHingeOptions {
-  /** Slit pattern style. Default: 'straight'. */
-  pattern?: "straight" | "serpentine";
-  /** Explicit slit width (beyond kerf). Default: 0. */
-  slitWidth?: number;
-  /** Distance between slit rows. Default: 2 * thickness. */
-  rowSpacing?: number;
-  /** Length of each slit. Default: 0.7 * (length - 2 * landWidth). */
-  slitLength?: number;
-  /** Uncut material between slit ends and row edges. Default: 2 * thickness. */
-  landWidth?: number;
-  /** Target bend radius - auto-computes row spacing. Overrides rowSpacing. */
-  bendRadius?: number;
-  /** Material thickness (needed for bend radius calc). Default: 3. */
-  thickness?: number;
-}
-```
+#### `linearPattern2d()` — Repeat a 2D sketch in a linear pattern and union the copies.
 
-</details>
+`linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch`
 
-#### `snapFitProfile()`
+#### `circularPattern2d()` — Repeat a 2D sketch in a circular pattern around a center point and union the copies.
 
-```ts
-snapFitProfile(thickness: number, options?: SnapFitOptions): SnapFitResult
-```
+`circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch`
 
-Generate a cantilever snap-fit tab and matching slot. The tab beam extends in +Y from y=0, with a barb/arrow tip at the top. The slot is the cutout for the mating panel.
+#### `mirrorCopy()` — Mirror a shape across a plane and union the mirror with the original.
 
-<details><summary><code>SnapFitOptions</code></summary>
+**Details**
 
-```ts
-interface SnapFitOptions {
-  /** Tab beam length. Default: 4 * thickness. */
-  tabLength?: number;
-  /** Tab beam width. Default: thickness. */
-  tabWidth?: number;
-  /** How much the barb protrudes beyond the beam. Default: 0.3 * thickness. */
-  overhang?: number;
-  /** Slot clearance per side. Default: 0.1. */
-  clearance?: number;
-  /** Laser kerf. Default: 0. */
-  kerf?: number;
-  /** Barb style. Default: 'barb'. */
-  style?: "arrow" | "barb";
-}
-```
-
-</details>
-
-<details><summary><code>SnapFitResult</code></summary>
-
-```ts
-interface SnapFitResult {
-  tab: Sketch;
-  slot: Sketch;
-}
-```
-
-</details>
+The mirror plane passes through the origin and is defined by its normal vector. The mirrored copy is unioned with the original to produce a single symmetric Shape.
 
-#### `kerfCompensateOutline()`
+**Example**
 
 ```ts
-kerfCompensateOutline(sketch: Sketch, kerf: number): Sketch
+// Mirror across the YZ plane (X=0)
+mirrorCopy(box(50, 30, 10), [1, 0, 0])
 ```
 
-Apply kerf compensation to a complete part outline (outer boundary + holes). Offsets inward by half-kerf: the outer boundary shrinks and inner holes grow. This is correct because the laser beam removes material on both sides of the cut line.
+`mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape`
 
-#### `kerfCompensateTabs()`
-
-```ts
-kerfCompensateTabs(sketch: Sketch, kerf: number): Sketch
-```
-
-Apply kerf compensation to joint protrusions (tabs, fingers). These grow by half-kerf so they are slightly oversized and fit tightly in their mating slots after the laser removes material.
-
-#### `kerfCompensateSlots()`
+### Imports & Composition
 
-```ts
-kerfCompensateSlots(sketch: Sketch, kerf: number): Sketch
-```
+#### `require()` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
 
-Apply kerf compensation to joint cutouts (slots, holes that receive tabs). These grow by half-kerf so tabs can fit into them after the laser removes material from both sides of the slot walls.
+`require$1(path: string, paramOverrides?: Record<string, number>): any`
 
-#### `kerfCompensatePart()`
+#### `importSvgSketch()` — Parse an SVG file and return it as a Sketch with options for region filtering, scaling, and simplification.
 
-```ts
-kerfCompensatePart(baseProfile: Sketch, joints: PartJoints, kerf: number): Sketch
-```
+`importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch`
 
-Build a kerf-compensated part profile. 1. Start with the base profile. 2. Kerf-compensate each tab addition (grow by kerf/2), then union with base. 3. Kerf-compensate each slot subtraction (grow by kerf/2), then subtract from base. 4. Kerf-compensate the resulting outline (shrink by kerf/2). Order matters: joints modify geometry BEFORE outline compensation so the final inward offset applies uniformly to the assembled profile.
+**`SvgImportOptions`**
 
-<details><summary><code>PartJoints</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `include?` | `"auto" | "fill" | "stroke" | "fill-and-stroke"` | Which geometry channels to include: - `auto`: prefer fills; if no fill geometry exists, fall back to strokes - `fill`: import only filled regions - `stroke`: import only stroke geometry - `fill-and-stroke`: include both |
+| `regionSelection?` | `"all" | "largest"` | Keep all disconnected regions, or only the largest. |
+| `maxRegions?` | `number` | Keep at most this many regions (largest-first). |
+| `minRegionArea?` | `number` | Drop regions below this absolute area threshold. |
+| `minRegionAreaRatio?` | `number` | Drop regions below this ratio of largest-region area. |
+| `flattenTolerance?` | `number` | Curve flattening tolerance in SVG user units. Smaller = more segments, higher fidelity. |
+| `arcSegments?` | `number` | Minimum segment count for arc discretization. |
+| `scale?` | `number` | Global scale applied after SVG parsing. |
+| `maxWidth?` | `number` | Maximum imported sketch width. If exceeded, geometry is uniformly downscaled to fit. |
+| `maxHeight?` | `number` | Maximum imported sketch height. If exceeded, geometry is uniformly downscaled to fit. |
+| `centerOnOrigin?` | `boolean` | Recenter imported geometry so its 2D bounds center is at CAD origin. |
+| `simplify?` | `number` | Simplification tolerance for final sketch cleanup. |
+| `invertY?` | `boolean` | Flip SVG Y-down coordinates to CAD Y-up. Enabled by default. |
 
-```ts
-interface PartJoints {
-  /** Geometry to ADD to the base profile (tabs, fingers protruding from edges). */
-  additions?: Sketch[];
-  /** Geometry to SUBTRACT from the base profile (slots, holes for mating tabs). */
-  subtractions?: Sketch[];
-}
-```
+#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF) as a Shape.
 
-</details>
+`importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape`
 
-#### `lookupKerf()`
+### Parameters
 
-```ts
-lookupKerf(material: string, thickness: number, laserType?: string): number | undefined
-```
+#### `param()` — Declare a numeric parameter that renders as a slider in the UI.
 
-Look up kerf for a material + thickness + laser combo. If `laserType` is omitted, returns the first matching material + thickness entry. Returns `undefined` when no match is found.
+**Details**
 
-#### `flatPanel()`
+Each `param()` call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
 
-```ts
-flatPanel(name: string, width: number, height: number, thickness: number, options?: FlatPartOptions): FlatPart
-```
+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
 
-Create a rectangular flat panel with 4 named edges. Profile origin at bottom-left corner. Edges: bottom (y=0), right (x=width), top (y=height), left (x=0). Edge traversal follows CCW winding order.
+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`).
 
-<details><summary><code>FlatPartOptions</code></summary>
+**Example**
 
 ```ts
-interface FlatPartOptions {
-  material?: string;
-  qty?: number;
-  color?: string;
-}
+const width = param("Width", 50);
+const angle = param("Angle", 45, { min: 0, max: 180, unit: "°" });
+const sides = param("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-</details>
-
-#### `flatPart()`
+**Parameter overrides** — key must match `name` exactly:
 
 ```ts
-flatPart(name: string, profile: Sketch, thickness: number, edges?: Record<string, { start: [ number, number ]; end: [ number, number ]; }>, options?: FlatPartOptions): FlatPart
-```
-
-Create a flat part from an arbitrary profile with user-named edges. Edge normals are computed automatically (perpendicular to direction, rotated 90deg CW).
+// Via require()
+const bracket = require("./bracket.forge.js", { Width: 80 });
 
-#### `fingerJoint()`
-
-```ts
-fingerJoint(partA: FlatPart, edgeNameA: string, partB: FlatPart, edgeNameB: string, options?: FingerJointOptions & { foldAngle?: number; }): void
+// Via CLI
+// forgecad run model.forge.js --param "Wall Thickness=3"
 ```
 
-Connect two parts with finger joints along specified edges. Adds finger geometry to partA's edge, cuts matching slots from partB's edge. The joint profiles are positioned along each edge using rotation + translation.
+`param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number`
 
-#### `tabSlot()`
+#### `boolParam()` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-```ts
-tabSlot(partA: FlatPart, edgeNameA: string, partB: FlatPart, edgeNameB: string, options?: TabSlotOptions & { foldAngle?: number; }): void
-```
+**Details**
 
-Connect two parts with tab-and-slot joints along specified edges. Adds tab geometry to partA's edge, cuts matching slots from partB's edge.
+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.
 
-#### `assemblyPreview()`
+**Example**
 
 ```ts
-assemblyPreview(parts: FlatPart[], joints: JointRecord[], options?: AssemblyPreviewOptions): AssemblyPreviewResult
+const showHoles = boolParam("Show Holes", true);
+if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
+return plate;
 ```
 
-<details><summary><code>JointRecord</code></summary>
+Override via import:
 
 ```ts
-interface JointRecord {
-  type: "finger" | "tabSlot" | "snapFit";
-  partA: string;
-  partB: string;
-  edgeA: string;
-  edgeB: string;
-  /** Fold angle in degrees. Default: 90. */
-  foldAngle: number;
-}
+const pan = require("./pan.forge.js", { "Show Lid": 0 });
 ```
 
-</details>
+`boolParam(name: string, defaultValue: boolean): boolean`
 
-<details><summary><code>AssemblyPreviewOptions</code></summary>
+#### `choiceParam()` — Declare a choice parameter that renders as a dropdown in the UI.
 
-```ts
-interface AssemblyPreviewOptions {
-  /** Kerf compensation passed to each part's solid(). Default: 0 */
-  kerf?: number;
-  /** Fold amount: 0 = flat layout, 1 = fully assembled. Default: 1 */
-  fold?: number;
-  /** Explode distance: 0 = assembled, >0 = parts spread outward. Default: 0 */
-  explode?: number;
-}
-```
+**Details**
 
-</details>
+`defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `choiceParam` over `param` when a slider would hide intent — named choices like `"wok"` are self-describing.
 
-<details><summary><code>AssemblyPreviewResult</code></summary>
+Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
 
-```ts
-interface AssemblyPreviewResult {
-  /** All part shapes grouped for display. */
-  shapes: ShapeGroup;
-  /** Individual transformed shapes keyed by part name. */
-  partShapes: Map<string, Shape>;
-}
-```
-
-</details>
-
-#### `assemblyInstructions()`
+**Example**
 
 ```ts
-assemblyInstructions(parts: FlatPart[], joints: JointRecord[], options?: AssemblyInstructionsOptions): AssemblyInstructionsResult
+const panStyle = choiceParam("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
+if (panStyle === "wok") return buildWok();
 ```
 
-Generate step-by-step assembly instructions from flat parts and joints. Algorithm: 1. Build adjacency graph from joints 2. Pick root part (most connections, or user-specified) 3. BFS from root, creating one step per part addition 4. Each step describes: which part to add, where it connects, how to orient it Heuristics for step ordering: - Start with the part that has the most connections (the base) - Add parts that connect to already-assembled parts first (BFS order) - Among candidates at the same BFS depth, prefer parts with more connections to already-assembled parts (structurally stable)
-
-<details><summary><code>AssemblyInstructionsOptions</code></summary>
+Override via import:
 
 ```ts
-interface AssemblyInstructionsOptions {
-  /** Part to start from. Default: part with most joint connections. */
-  rootPart?: string;
-}
+const pan = require("./pan.forge.js", { "Pan Style": "wok" });
 ```
 
-</details>
+Override via CLI:
 
-<details><summary><code>AssemblyInstructionsResult</code></summary>
-
-```ts
-interface AssemblyInstructionsResult {
-  steps: AssemblyStep[];
-  /** Total number of parts in the assembly. */
-  totalParts: number;
-  /** Parts not connected to the joint graph (orphans). */
-  orphanParts: string[];
-}
+```bash
+forgecad run model.forge.js --param "Pan Style=wok"
 ```
 
-</details>
+`choiceParam(name: string, defaultValue: string, choices: string[]): string`
 
-<details><summary><code>AssemblyStep</code></summary>
+#### `listParam()` — Declare a list parameter — an array of struct items with per-field UI controls.
 
-```ts
-interface AssemblyStep {
-  /** 1-based step number. */
-  stepNumber: number;
-  /** Human-readable instruction. */
-  description: string;
-  /** The part being added in this step. */
-  partName: string;
-  /** Part number (for cross-ref with cut sheets). */
-  partNumber: number;
-  /** Which existing part it connects to. */
-  connectsTo: string;
-  /** Joint type used. */
-  jointType: "finger" | "tabSlot" | "snapFit";
-  /** The edge on the new part. */
-  newPartEdge: string;
-  /** The edge on the existing part. */
-  existingPartEdge: string;
-  /** Fold angle in degrees. */
-  foldAngle: number;
-  /** Part names in the assembly so far (after this step). */
-  assembledParts: string[];
-}
-```
+**Details**
 
-</details>
+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.
 
-#### `formatInstructions()`
+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
-formatInstructions(result: AssemblyInstructionsResult): string
-```
+`listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]`
 
-Format assembly instructions as a human-readable text document. Includes a "Step 0" preamble identifying the base part, followed by numbered steps, and a note about any orphan parts.
+`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
 
-#### `laserKit()`
+### Grouping & Local Coordinates
 
-```ts
-laserKit(options?: LaserKitOptions): LaserKit
-```
+#### `group()` — Group multiple shapes/sketches for joint transforms without merging into a single mesh.
 
-Top-level factory for creating a LaserKit container.
+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.).
 
-<details><summary><code>LaserKitOptions</code></summary>
+**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.
 
-```ts
-interface LaserKitOptions {
-  /** Default material label for parts that don't specify one. */
-  material?: string;
-  /** Stock sheet width in mm (default 600). */
-  sheetWidth?: number;
-  /** Stock sheet height in mm (default 400). */
-  sheetHeight?: number;
-  /** Laser kerf in mm (default 0.2). */
-  kerf?: number;
-}
-```
+// 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);
 
-</details>
+// 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);
 
-#### `torus()`
+`group(...items: GroupInput[]): ShapeGroup`
 
-```ts
-torus$1(majorRadius: number, minorRadius: number, segments?: number): Shape
-```
+### Section & Projection
 
-Create a torus (donut shape) centered at the origin, lying in the XY plane. @concept primitive
+#### `intersectWithPlane()` — Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
 
-#### `importMesh()`
+`intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch`
 
-```ts
-importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
-```
+#### `faceProfile()` — Extract the boundary profile of a named face as a 2D sketch.
 
-Import an external mesh file (STL, OBJ, 3MF) as a Shape. @concept import
+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.
 
-#### `highlight()`
+`faceProfile(shape: Shape, face: FaceSelector): Sketch`
 
-```ts
-highlight(entityId: string, opts?: HighlightOptions): void
-```
+#### `projectToPlane()` — Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
 
-Highlight any geometry for visual debugging in the viewport. Supported inputs: - `string` — sketch entity ID (e.g. `'L0'`, `'P0'`, `'C0'`) - `[x, y, z]` — 3D point - `[[x1,y1,z1], [x2,y2,z2]]` — edge (line segment) - `{ normal: [x,y,z], offset: number }` — plane by normal + distance from origin - `{ normal: [x,y,z], point: [x,y,z] }` — plane by normal + point on plane - `Shape` — highlight entire 3D shape - `FaceRef` (from `shape.face('top')`) — highlight as plane at face center - `EdgeRef` (from `shape.edge('left')`) — highlight as edge segment
+`projectToPlane(shape: Shape, plane: PlaneSpec): Sketch`
 
-<details><summary><code>HighlightOptions</code></summary>
+### Transforms
 
-```ts
-interface HighlightOptions {
-  color?: string;
-  label?: string;
-  pulse?: boolean;
-  /** Size hint for points (radius in mm) or planes (disc radius in mm). */
-  size?: number;
-}
-```
+#### `composeChain()` — Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
 
-</details>
-
-#### `highlight()`
-
-```ts
-highlight(point: [ number, number, number ], opts?: HighlightOptions): void
-```
-
-#### `highlight()`
-
-```ts
-highlight(edge: [ [ number, number, number ], [ number, number, number ] ], opts?: HighlightOptions): void
-```
+`composeChain(...steps: TransformInput[]): Transform`
 
-#### `highlight()`
+### Verification
 
-```ts
-highlight(plane: { normal: [ number, number, number ]; offset: number; }, opts?: HighlightOptions): void
-```
+#### `spec()` — Create a named, reusable bundle of verification checks.
 
-#### `highlight()`
+**Details**
 
-```ts
-highlight(plane: { normal: [ number, number, number ]; point: [ number, number, number ]; }, opts?: HighlightOptions): void
-```
+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.
 
-#### `highlight()`
+Specs can be defined in separate `.forge.js` files and imported via `require()` to share them across models.
 
-```ts
-highlight(shape: Shape, opts?: HighlightOptions): void
-```
+`spec.check()` returns a `SpecResult` — you can inspect it programmatically or ignore the return value and let the Checks panel show results.
 
-#### `highlight()`
+**Example**
 
 ```ts
-highlight(face: FaceRef, opts?: HighlightOptions): void
-```
+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);
+});
 
-<details><summary><code>FaceRef</code></summary>
+// Reuse on multiple shapes
+printable.check(bracket);
+printable.check(standoff);
 
-```ts
-interface FaceRef {
-  name: FaceName;
-  /** Compiler-owned face query when available. */
-  query?: FaceQueryRef;
-  /** True when the face can host a 2D sketch placement frame */
-  planar?: boolean;
-  /** Shared descendant-resolution metadata when this face is a semantic region/set. */
-  descendant?: FaceDescendantMetadata;
-}
+// Check relationships between parts
+const fitSpec = spec("Assembly fit", (partA, partB) => {
+  verify.notColliding("No interference", partA, partB, 10);
+});
+fitSpec.check(bracket, standoff);
 ```
 
-</details>
-
-<details><summary><code>FaceDescendantMetadata</code></summary>
-
-```ts
-interface FaceDescendantMetadata {
-  kind: "single" | "face-set";
-  semantic: FaceDescendantSemantic;
-  memberCount: number;
-  memberNames: string[];
-  coplanar: boolean;
-}
-```
+**Spec-first workflow:** Write specs before building geometry. Checks go from red to green as you build — effectively TDD for CAD.
 
-</details>
+`spec(name: string, checkFn: (...args: any[]) => void): Spec`
 
-#### `highlight()`
-
-```ts
-highlight(edge: EdgeRef, opts?: HighlightOptions): void
-```
-
-<details><summary><code>EdgeRef</code></summary>
-
-```ts
-interface EdgeRef {
-  name: EdgeName;
-  /** Compiler-owned edge query when available. */
-  query?: EdgeQueryRef;
-}
-```
-
-</details>
+**`Spec`**
+- `name: string` — The display name of this spec
 
 ---
 
@@ -1468,7 +577,9 @@ interface EdgeRef {
 
 ### `Shape`
 
-Core 3D solid shape. All operations are immutable and return new shapes. Supports transforms (translate, rotate, scale, mirror, transform, rotateAround, pointAlong), booleans (add, subtract, intersect), cutting (split, splitByPlane, trimByPlane), shelling, anchor positioning (attachTo, onFace), placement references, and queries (volume, surfaceArea, boundingBox, isEmpty, numTri, geometryInfo).
+Core 3D solid shape. All operations are immutable and return new shapes.
+
+Supports transforms (translate, rotate, scale, mirror, transform, rotateAround, pointAlong), booleans (add, subtract, intersect), cutting (split, splitByPlane, trimByPlane), shelling, anchor positioning (attachTo, onFace), placement references, and queries (volume, surfaceArea, boundingBox, isEmpty, numTri, geometryInfo).
 
 **Properties:**
 
@@ -1478,87 +589,90 @@ Core 3D solid shape. All operations are immutable and return new shapes. Support
 
 **Methods:**
 
-- `setColor()` — Set the color of this shape (hex string, e.g. "#ff0000")
-- `color()` — Alias for setColor
-- `material()` — Set material properties for this shape's visual appearance. Returns a new Shape with the specified material properties merged. ```js box(50, 50, 50).material({ metalness: 0.9, roughness: 0.1 }); sphere(30).material({ emissive: '#ff6b35', emissiveIntensity: 2 }); cylinder(40, 20).material({ opacity: 0.3 }); ```
-- `clone()` — Return a new Shape wrapper for explicit duplication in scripts.
-- `duplicate()` — Alias for clone()
-- `geometryInfo()` — Inspect which backend/representation produced this solid.
-- `withReferences()` — Attach named placement references that survive normal transforms and imports.
-- `referenceNames()` — List named placement references carried by this shape.
-- `withPorts()` — Attach named assembly ports (origin + axis + up) that survive transforms and imports.
-- `portNames()` — List named port identifiers carried by this shape.
-- `referencePoint()` — Resolve a named placement reference or built-in anchor to a 3D point.
-- `face()` — Resolve a semantic face by name or query.  Works on compile-covered shapes and, as a fallback, on any planar-faced mesh (e.g. the result of boolean ops) via coplanar triangle clustering.
-- `faces()` — Return all faces matching a query, or all mesh-detected faces when no query is given.
-- `faceNames()` — List defended semantic face names currently available on this shape.
-- `edge()` — Get a named topology edge. Only available on shapes with tracked topology (from box/cylinder/extrude).
-- `edgeNames()` — List named topology edge names. Returns empty array if shape has no tracked topology.
-- `faceHistory()` — Get the transformation history for a specific face.
-- `placeReference()` — Translate the shape so the given reference lands on the target coordinate.
-- `translatePolar()` — Translate using polar coordinates (radius + angle in degrees). Eliminates manual `r * Math.cos(angle * PI/180)` calculations. Example: `shape.translatePolar(50, 30)` moves 50mm at 30 degrees from +X.
-- `translate()` — Move the shape relative to its current position. All transforms are immutable and return new shapes.
-- `moveTo()` — Position the shape so its bounding box min corner is at the given global coordinate.
-- `moveToLocal()` — Position the shape relative to another shape's local coordinate system (bounding box min corner).
-- `rotate()` — Rotate using Euler angles in degrees around the shape's bounding box center.
-- `rotateAround()` — Rotate using Euler angles in degrees around an explicit pivot point.
-- `transform()` — Apply a 4x4 affine transform matrix (column-major) or a Transform object.
-- `scale()` — Scale the shape uniformly or per-axis from the shape's bounding box center. Accepts a single number or [x, y, z] array.
-- `scaleAround()` — Scale the shape uniformly or per-axis from an explicit pivot point.
-- `mirror()` — Mirror across a plane through the shape's bounding box center, defined by its normal vector.
-- `mirrorThrough()` — Mirror across a plane through an explicit point, defined by its normal vector.
-- `pointAlong()` — Reorient a shape so its primary axis (Z) points along the given direction. Useful for laying cylinders/extrusions along X or Y without thinking about Euler angles. Example: cylinder(40, 5).pointAlong([1, 0, 0]) — lays cylinder along X
-- `rotateAroundAxis()` — Rotate around an arbitrary axis through a pivot point. Equivalent to: translate(-pivot) → rotate around axis → translate(+pivot)
-- `rotateAroundTo()` — Rotate around an axis until a moving point reaches the target line/plane defined by the axis and target point. `movingPoint` / `targetPoint` may be raw world points or this shape's anchors/references.
-- `add()` — Union this shape with others (additive boolean). Method form of union().
-- `subtract()` — Subtract other shapes from this one. Method form of difference().
-- `intersect()` — Keep only the overlap with other shapes. Method form of intersection().
-- `union()` — Alias for add() — matches the free-function union() naming.
-- `difference()` — Alias for subtract() — matches the free-function difference() naming.
-- `intersection()` — Alias for intersect() — matches the free-function intersection() naming.
-- `split()` — Split into [inside, outside] by another shape.
-- `splitByPlane()` — Split by infinite plane. Returns [positive-side, negative-side].
-- `trimByPlane()` — Keep the positive side of the plane and discard the opposite side.
-- `shell()` — Hollow out compile-covered boxes, cylinders, and straight extrudes. `openFaces` names any subset of the base shape's faces to leave open (no wall). Box bases accept any of: top, bottom, front (=side-bottom), back (=side-top), left (=side-left), right (=side-right), or the raw internal names. Cylinder and extrude bases accept top and bottom only.
-- `boundingBox()` — Get the axis-aligned bounding box as { min: [x,y,z], max: [x,y,z] }.
-- `volume()` — Volume in mm cubed.
-- `surfaceArea()` — Surface area in mm squared.
-- `isEmpty()` — True if the shape contains no geometry.
-- `numBodies()` — Number of disconnected solid bodies in this shape.
-- `numTri()` — Triangle count of the mesh representation.
-- `getMesh()` — Extract triangle mesh for Three.js rendering
-- `slice()` — Slice the runtime solid by a plane normal to local Z at the given offset.
-- `project()` — Orthographically project the runtime solid onto the local XY plane.
-- `attachTo()` — Position this shape relative to another using named 3D anchor points. Anchors are bounding-box-relative: 'center', face centers ('top', 'front', ...), edge midpoints ('top-front', 'back-left', ...), and corners ('top-front-left', ...). Anchor word order is flexible: 'front-left' and 'left-front' are equivalent. Named placement references (from withReferences) can also be used as anchors.
-- `onFace()` — Place this shape on a face of a parent shape. Think of it like sticking a label on a box surface: - `face` picks which surface ('front', 'back', 'top', etc.) - `u, v` position within that face's 2D plane (from center) - front/back: u = left/right (X), v = up/down (Z) - left/right: u = forward/back (Y), v = up/down (Z) - top/bottom: u = left/right (X), v = forward/back (Y) - `protrude` = how far the child sticks out (positive = outward from face)
-- `withConnectors()` — Attach named connectors (typed, gendered ports) that survive transforms.
-- `connectorNames()` — List connector names (ports that have a connectorType).
-- `connectorsByType()` — Get all connectors of a given type.
-- `connectorDistance()` — Distance between two connector origins on this shape.
-- `connectorMeasurements()` — Get measurements metadata from a connector.
-- `matchTo()` — Position this shape by matching connectors to a target. Overloads: - Single pair: `matchTo(target, selfConn, targetConn, options?)` - Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)` - Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
-- `pocket()` — Cut a pocket (cavity) into this solid through the named face. box(100, 100, 20).pocket('top', 8) box(100, 100, 20).pocket('top', 8, { inset: 5 }) box(100, 100, 20).pocket('top', 8, { scale: 0.8 })
-- `boss()` — Add a boss (protrusion) from the named face. box(100, 100, 20).boss('top', 5) box(100, 100, 20).boss('top', 10, { scale: 0.6 })
-- `hole()` — Drill a hole into this solid at a face. box(50, 50, 20).hole('top', { diameter: 8, depth: 10 }) box(50, 50, 20).hole('top', { diameter: 6, counterbore: { diameter: 12, depth: 3 } })
-- `cutout()` — Cut a profile-shaped pocket through a face using a placed sketch. The sketch must be placed on a face with `Sketch.onFace(...)`. The cut follows the sketch's 2D profile. const profile = circle2d(10).onFace(body, 'top'); body.cutout(profile, { depth: 5 })
+- `color(value: string | undefined): Shape` — Set the color of this shape (hex string, e.g. "#ff0000"). Returns a new Shape with the color applied.
+- `material(props: ShapeMaterialProps): Shape` — Set PBR material properties for this shape's visual appearance. **Details** Returns a new Shape with the specified material properties merged on top of any previously set properties. All properties are optional — omitted keys retain their current value. Material properties survive transforms and boolean operations. Use `.color()` to set the base diffuse color; `.material()` controls how that color behaves under light (metalness, roughness, clearcoat) and can add emissive glow independent of lighting. Emissive glow pairs naturally with the `postProcessing.bloom` effect in `scene()`. **Example** ```js box(50, 50, 50).material({ metalness: 0.9, roughness: 0.1 }); // polished metal sphere(30).material({ emissive: '#ff6b35', emissiveIntensity: 2 }); // glowing cylinder(40, 20).material({ opacity: 0.4, clearcoat: 1.0, clearcoatRoughness: 0.02 }); // ice // Chainable with other shape methods box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).translate(0, 0, 50); ```
+- `clone(): Shape` — Return a new Shape wrapper for explicit duplication in scripts.
+- `geometryInfo(): GeometryInfo` — Inspect which backend/representation produced this solid.
+- `withReferences(refs: PlacementReferenceInput): Shape` — Attach named placement references that survive normal transforms and imports.
+- `referenceNames(kind?: PlacementReferenceKind): string[]` — List named placement references carried by this shape.
+- `withPorts(ports: Record<string, PortInput>): Shape` — Deprecated alias for `withConnectors()`.
+- `portNames(): string[]` — Deprecated alias for `connectorNames()`.
+- `referencePoint(ref: PlacementAnchorLike): [ number, number, number ]` — Resolve a named placement reference or built-in anchor to a 3D point.
+- `face(selector: FaceSelector): FaceRef` — Resolve a face by user-authored label or compiler-owned name. Returns a `FaceRef` that can be passed to `.onFace()`, `projectToPlane()`, or used directly in placement. **Details** `.face(name)` is a pure label lookup — it finds faces by user-authored labels, not by geometric queries. Labels are born in sketches via `.label()` / `.labelEdges()` and grow into face names through extrude, loft, revolve, and sweep. They are stable references that travel with the geometry. Labels must be unique within a shape. Use `.prefixLabels()` before combining shapes with `union()` / `difference()` to avoid collisions. Collision detection throws a clear error with a fix suggestion. For compile-covered shapes (extrude, loft, etc.) the lookup resolves via the shape's compile plan. As a fallback, planar-faced mesh shapes (e.g. results of boolean ops) are resolved via coplanar triangle clustering. **Example** ```ts // Edge labels become side face names after extrude const profile = path() .moveTo(0, 0) .lineTo(100, 0).label('floor') .lineTo(100, 50).label('wall') .lineTo(0, 50).label('ceiling') .closeLabel('left-wall'); const room = profile.extrude(30, { labels: { start: 'base', end: 'top' } }); room.face('floor'); // side face from the labeled edge room.face('base'); // base cap (user-specified) // .labelEdges() shorthand for sequential edge labeling const plate = rect(100, 50).labelEdges('south', 'east', 'north', 'west'); const solid = plate.extrude(20, { labels: { start: 'bottom', end: 'top' } }); solid.face('south'); // side face // Prefix before combining to avoid collisions const left = wing.prefixLabels('l/'); const right = wing.mirror([1, 0, 0]).prefixLabels('r/'); const full = union(left, right); full.face('l/upper'); // left wing upper surface ```
+- `faces(query?: FaceQuery): FaceRef[]` — Return all faces matching a query, or all mesh-detected faces when no query is given.
+- `faceNames(): string[]` — List defended semantic face names currently available on this shape, including user labels from `labelFaces()`.
+- `prefixLabels(prefix: string): Shape` — Prefix all user-authored face labels (both sketch-edge labels and labelFaces labels). Returns a new shape with modified labels.
+- `renameLabel(from: string, to: string): Shape` — Rename a single face label. Returns a new shape.
+- `dropLabels(...names: string[]): Shape` — Remove specific face labels. Returns a new shape.
+- `dropAllLabels(): Shape` — Remove all face labels. Returns a new shape.
+- `edge(name: string): EdgeRef` — Get a named topology edge. Only available on shapes with tracked topology (from box/cylinder/extrude).
+- `edgeNames(): string[]` — List named topology edge names. Returns empty array if shape has no tracked topology.
+- `labelFaces(mapping: Record<string, string>): Shape` — Assign user-chosen labels to faces identified by their canonical position keys. **Details** Primitives (`box`, `cylinder`) and extrusions have internal canonical face positions (`top`, `bottom`, `side`, `side-left`, etc.) but these are **not** labels — they are just position selectors. Use `labelFaces()` to give faces meaningful, project-specific names that survive through transforms, booleans, fillets, and chamfers. The mapping keys are canonical position selectors; the values are your labels. Labels are the recommended way to identify faces for topological edge queries (`edgesOf`, `edgesBetween`). **Example** ```js // Full workflow: label → query edges → fillet let plate = box(100, 60, 5).labelFaces({ top: 'work-surface', bottom: 'mount-face' }) plate = fillet(plate, 2, plate.edgesOf('work-surface')) // Cylinder: fillet the rim where cap meets barrel let tube = cylinder(30, 10).labelFaces({ top: 'cap', side: 'barrel' }) tube = fillet(tube, 1, tube.edgesBetween('cap', 'barrel')) // Prefix before combining shapes to avoid label collisions const left = plate.prefixLabels('l/') const right = plate.mirror([1, 0, 0]).prefixLabels('r/') const full = union(left, right) full.edgesOf('l/work-surface') // still works ```
+- `edgesOf(faceLabel: string, options?: EdgesOfOptions): EdgeSegment[]` — Return all boundary edges of a named face. **Details** Finds edges where one adjacent mesh face belongs to the target face and the other belongs to a different face. The result is coalesced (tessellation fragments merged) and can be passed directly to `fillet()` or `chamfer()`. This is a topological query — no coordinates, no tolerances, no minimum-length hacks. It works because an edge is the boundary between two faces. **Example** ```js // Fillet all top edges of a mounting plate let plate = box(120, 80, 6).labelFaces({ top: 'work-surface' }) plate = fillet(plate, 3, plate.edgesOf('work-surface')) // Shelled enclosure — fillet the outer lip let body = box(80, 50, 35).labelFaces({ top: 'opening' }) body = body.shell(2, { openFaces: ['top'] }) body = fillet(body, 1.5, body.edgesOf('opening')) // Filter: only concave edges (after a boolean subtraction) body.edgesOf('top', { concave: true }) ```
+- `edgesBetween(faceA: string, faceB: string | string[]): EdgeSegment[]` — Return edges shared between two named faces. **Details** An edge is "between" faces A and B when one of its adjacent mesh triangles belongs to A and the other belongs to B. This is the most precise topological edge selection — "fillet the edges where the top meets the wall." The second argument can be a single face name or an array (edges between A and any of B1, B2, ...). **Example** ```js // Fillet the edge where lid meets one wall let body = box(100, 60, 30).labelFaces({ top: 'lid', 'side-left': 'wall' }) body = fillet(body, 2, body.edgesBetween('lid', 'wall')) // Fillet a cylinder rim — where the flat cap meets the curved barrel let tube = cylinder(30, 10).labelFaces({ top: 'cap', side: 'barrel' }) tube = fillet(tube, 1, tube.edgesBetween('cap', 'barrel')) // Multiple target faces at once body.edgesBetween('lid', ['left-wall', 'right-wall', 'front-wall', 'back-wall']) ```
+- `faceHistory(name: string): FaceTransformationHistory` — Get the transformation history for a specific face.
+- `placeReference(ref: PlacementAnchorLike, target: [ number, number, number ], offset?: [ number, number, number ]): Shape` — Translate the shape so the given anchor or reference lands on the target coordinate. Accepts any built-in anchor name (`'bottom'`, `'center'`, `'top-front-left'`, etc.) or a custom placement reference attached via `withReferences()`. ```javascript // Ground a shape — put its bottom face center at Z = 0 shape.placeReference('bottom', [0, 0, 0]) // Center at the world origin shape.placeReference('center', [0, 0, 0]) // Align left edge to X = 10 shape.placeReference('left', [10, 0, 0]) ```
+- `translatePolar(radius: number, angleDeg: number, z?: number): Shape` — Translate using polar coordinates (radius + angle in degrees). Eliminates manual `r * Math.cos(angle * PI/180)` calculations. Example: `shape.translatePolar(50, 30)` moves 50mm at 30 degrees from +X.
+- `translate(x: number, y: number, z: number): Shape` — Move the shape relative to its current position. All transforms are immutable and return new shapes.
+- `moveTo(x: number, y: number, z: number): Shape` — Position the shape so its bounding box min corner is at the given global coordinate.
+- `moveToLocal(target: Shape | { toShape(): Shape; }, x: number, y: number, z: number): Shape` — Position the shape relative to another shape's local coordinate system (bounding box min corner).
+- `rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape` — Rotate around an arbitrary axis through the origin.
+- `rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape` — Rotate around the X axis by the given angle in degrees.
+- `rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape` — Rotate around the Y axis by the given angle in degrees.
+- `rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape` — Rotate around the Z axis by the given angle in degrees.
+- `transform(m: Mat4 | Transform): Shape` — Apply a 4x4 affine transform matrix (column-major) or a Transform object.
+- `scale(v: number | [ number, number, number ]): Shape` — Scale the shape uniformly or per-axis from the shape's bounding box center. Accepts a single number or [x, y, z] array.
+- `scaleAround(pivot: [ number, number, number ], v: number | [ number, number, number ]): Shape` — Scale the shape uniformly or per-axis from an explicit pivot point.
+- `mirror(normal: [ number, number, number ]): Shape` — Mirror across a plane through the shape's bounding box center, defined by its normal vector.
+- `mirrorThrough(point: [ number, number, number ], normal: [ number, number, number ]): Shape` — Mirror across a plane through an explicit point, defined by its normal vector.
+- `pointAlong(direction: [ number, number, number ]): Shape` — Reorient a shape so its primary axis (Z) points along the given direction. Useful for laying cylinders/extrusions along X or Y without thinking about Euler angles. The shape's origin stays at [0,0,0] — translate after pointAlong to position it. Example: cylinder(40, 5).pointAlong([1, 0, 0]) — lays cylinder along X, starting at origin
+- `rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: RotationPointLike, targetPoint: RotationPointLike, options?: RotateAroundToOptions): Shape` — Rotate around an axis until a moving point reaches the target line/plane defined by the axis and target point. `movingPoint` / `targetPoint` may be raw world points or this shape's anchors/references.
+- `add(...others: ShapeOperandInput[]): Shape` — Union this shape with others (additive boolean). Method form of union().
+- `subtract(...others: ShapeOperandInput[]): Shape` — Subtract other shapes from this one. Method form of difference().
+- `intersect(...others: ShapeOperandInput[]): Shape` — Keep only the overlap with other shapes. Method form of intersection().
+- `split(cutter: Shape | { toShape(): Shape; }): [ Shape, Shape ]` — Split into [inside, outside] by another shape.
+- `splitByPlane(normal: [ number, number, number ], originOffset?: number): [ Shape, Shape ]` — Split by infinite plane. Returns [positive-side, negative-side].
+- `trimByPlane(normal: [ number, number, number ], originOffset?: number): Shape` — Keep the positive side of the plane and discard the opposite side.
+- `shell(thickness: number, opts?: { openFaces?: string[]; }): Shape` — Hollow out compile-covered boxes, cylinders, and straight extrudes. `openFaces` names any subset of the base shape's labeled faces to leave open (no wall).
+- `boundingBox(): ShapeRuntimeBounds` — Get the axis-aligned bounding box as { min: [x,y,z], max: [x,y,z] }.
+- `volume(): number` — Volume in mm cubed.
+- `surfaceArea(): number` — Surface area in mm squared.
+- `isEmpty(): boolean` — True if the shape contains no geometry.
+- `numBodies(): number` — Number of disconnected solid bodies in this shape.
+- `numTri(): number` — Triangle count of the mesh representation.
+- `getMesh(): ShapeRuntimeMesh` — Extract triangle mesh for Three.js rendering
+- `slice(offset?: number): any` — Slice the runtime solid by a plane normal to local Z at the given offset.
+- `project(): any` — Orthographically project the runtime solid onto the local XY plane.
+- `attachTo(target: ShapeAnchorTarget, targetAnchor: PlacementAnchorLike, selfAnchor?: PlacementAnchorLike, offset?: [ number, number, number ]): Shape` — Position this shape relative to another using named 3D anchor points. Anchors are bounding-box-relative: 'center', face centers ('top', 'front', ...), edge midpoints ('top-front', 'back-left', ...), and corners ('top-front-left', ...). Anchor word order is flexible: 'front-left' and 'left-front' are equivalent. Named placement references (from withReferences) can also be used as anchors.
+- `onFace(parent: ShapeAnchorTarget, face: "front" | "back" | "left" | "right" | "top" | "bottom", opts?: { u?: number; v?: number; protrude?: number; }): Shape` — Place this shape on a face of a parent shape. Think of it like sticking a label on a box surface: - `face` picks which surface ('front', 'back', 'top', etc.) - `u, v` position within that face's 2D plane (from center) - front/back: u = left/right (X), v = up/down (Z) - left/right: u = forward/back (Y), v = up/down (Z) - top/bottom: u = left/right (X), v = forward/back (Y) - `protrude` = how far the child sticks out (positive = outward from face)
+- `seatInto(target: Shape, surface: string, options?: SeatIntoOptions): Shape` — Slide this shape along an axis until a labeled face is embedded in the target body. Position the shape roughly first (translate/rotate), then call seatInto to auto-adjust the penetration depth. No manual coordinate math needed. ```js // Wing root embeds into fuselage — adapts to any fuselage shape wing.translate(0, wingY, 0).seatInto(fuselage, 'root'); // Sensor pod sits flush on fuselage surface pod.translate(0, station, radius + 20).seatInto(fuselage, 'base', { depth: 'flush' }); // Antenna with 3mm gasket standoff mast.translate(0, station, radius + 50).seatInto(fuselage, 'mount', { depth: 'flush', gap: 3 }); ```
+- `seatOver(target: Shape, targetSurface: string, options?: SeatIntoOptions): Shape` — Slide this shape until a target's labeled face is fully covered (inside this shape). The inverse of `seatInto`: instead of embedding *your* face into the target, you move until the *target's* face is embedded inside you. ```js // Nacelle moves up until pylon's bottom face is inside the nacelle nacelle.translate(rough).seatOver(pylon, 'bottom'); // Cap slides down over a post until post's top face is covered cap.translate(rough).seatOver(post, 'top'); ```
+- `withConnectors(connectors: Record<string, ConnectorInput>): Shape` — Attach named connectors — attachment points that survive transforms and imports. Connectors can be bare (position + orientation) or typed (with connectorType/gender for compatibility matching).
+- `connectorNames(): string[]` — List all connector names on this shape.
+- `connectorsByType(type: string): Array<{ name: string; port: PortDef; }>` — Get all connectors of a given type.
+- `connectorDistance(nameA: string, nameB: string): number` — Distance between two connector origins on this shape.
+- `connectorMeasurements(name: string): Record<string, number | string>` — Get measurements metadata from a connector.
+- `matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): Shape` — Position this shape by matching connectors to a target. Overloads: - Single pair: `matchTo(target, selfConn, targetConn, options?)` - Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)` - Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
+- `pocket(face: FaceSelector, depth: number, opts?: PocketOptions): Shape` — Cut a pocket (cavity) into this solid through the named face. box(100, 100, 20).pocket('top', 8) box(100, 100, 20).pocket('top', 8, { inset: 5 }) box(100, 100, 20).pocket('top', 8, { scale: 0.8 })
+- `boss(face: FaceSelector, height: number, opts?: BossOptions): Shape` — Add a boss (protrusion) from the named face. box(100, 100, 20).boss('top', 5) box(100, 100, 20).boss('top', 10, { scale: 0.6 })
+- `hole(faceOrRef: SketchFaceTarget | FaceRef, opts: ShapeHoleOptions): Shape` — Drill a hole into this solid at a face. box(50, 50, 20).hole('top', { diameter: 8, depth: 10 }) box(50, 50, 20).hole('top', { diameter: 6, counterbore: { diameter: 12, depth: 3 } })
+- `cutout(sketch: Sketch, opts?: ShapeCutoutOptions): Shape` — Cut a profile-shaped pocket through a face using a placed sketch. The sketch must be placed on a face with `Sketch.onFace(...)`. The cut follows the sketch's 2D profile. const profile = circle2d(10).onFace(body, 'top'); body.cutout(profile, { depth: 5 })
 
 ### `Transform`
 
-**Methods:**
-
-- `static identity()` — static identity(): Transform
-- `static from()` — static from(input: TransformInput): Transform
-- `static translation()` — static translation(x: number, y: number, z: number): Transform
-- `static scale()` — static scale(v: number | Vec3): Transform
-- `static rotationAxis()` — static rotationAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
-- `static rotateAroundTo()` — static rotateAroundTo(axis: Vec3, pivot: Vec3, movingPoint: Vec3, targetPoint: V
-- `mul()` — Compose transforms in chain order. `a.mul(b)` means apply `a`, then `b`.
-- `translate()` — translate(x: number, y: number, z: number): Transform
-- `rotateAxis()` — rotateAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
-- `inverse()` — inverse(): Transform
-- `point()` — point(p: Vec3): Vec3
-- `vector()` — vector(v: Vec3): Vec3
-- `toArray()` — toArray(): Mat4
+- `static identity(): Transform` — Return the identity transform.
+- `static from(input: TransformInput): Transform` — Wrap an existing `Transform` or raw 4x4 matrix as a `Transform`.
+- `static translation(x: number, y: number, z: number): Transform` — Create a translation transform.
+- `static scale(v: number | Vec3): Transform` — Create a uniform or per-axis scale transform.
+- `static rotationAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform` — Create a rotation around an arbitrary axis, optionally about a pivot.
+- `static rotateAroundTo(axis: Vec3, pivot: Vec3, movingPoint: Vec3, targetPoint: Vec3, options?: RotateAroundToOptions): Transform` — Solve the rotation needed to move one point onto a target line or plane.
+- `mul(other: TransformInput): Transform` — Compose transforms in chain order: `a.mul(b)` applies `a`, then `b`.
+- `translate(x: number, y: number, z: number): Transform` — Translate after the current transform.
+- `rotateAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform` — Rotate after the current transform.
+- `inverse(): Transform` — Return the inverse transform.
+- `point(p: Vec3): Vec3` — Transform a point using homogeneous coordinates.
+- `vector(v: Vec3): Vec3` — Transform a direction vector without translation.
+- `toArray(): Mat4` — Return the transform as a raw 4x4 matrix array.
 
 ### `ShapeGroup`
 
@@ -1571,101 +685,40 @@ Core 3D solid shape. All operations are immutable and return new shapes. Support
 
 **Methods:**
 
-- `childName()` — childName(index: number): string | undefined
-- `child()` — Return the named child by name. Throws if not found. Useful when importing a multipart group and working on components individually.
-- `clone()` — Return a deep-cloned ShapeGroup tree (refs copied).
-- `duplicate()` — Alias for clone()
-- `translate()` — translate(x: number, y: number, z: number): ShapeGroup
-- `boundingBox()` — boundingBox(): { min: [ number, number, number ]; max: [ number, number, number 
-- `moveTo()` — Move so combined bounding box min corner is at the given global coordinate
-- `moveToLocal()` — Move so combined bounding box min corner is at target's bounding box min + (x, y, z) offset
-- `attachTo()` — attachTo(target: Shape | ShapeGroup, targetAnchor: Anchor3D | string, selfAnchor
-- `onFace()` — Place this group on a face of a parent shape. See Shape.onFace() for full documentation.
-- `rotate()` — Rotate using Euler angles in degrees around the group's bounding box center.
-- `rotateAround()` — Rotate using Euler angles in degrees around an explicit pivot point.
-- `rotateAroundAxis()` — Rotate around an arbitrary axis, optionally through a pivot point.
-- `rotateAroundTo()` — Rotate around an axis until a moving point reaches the target line/plane defined by the axis and target point. ShapeGroup string points use built-in anchors only.
-- `pointAlong()` — Reorient all 3D children so their primary axis (Z) points along direction. Sugar for a single group-wide axis rotation via Transform.rotationAxis(...).
-- `transform()` — Apply a 4x4 transform matrix or Transform object to all 3D children.
-- `scale()` — Scale uniformly or per-axis from the group's bounding box center.
-- `scaleAround()` — Scale uniformly or per-axis from an explicit pivot point.
-- `mirror()` — Mirror across a plane through the group's bounding box center.
-- `mirrorThrough()` — Mirror across a plane through an explicit point.
-- `color()` — color(hex: string): ShapeGroup
-- `withReferences()` — Attach named placement references to this group. References survive normal transforms (translate/rotate/scale/mirror/transform). ```javascript const bracket = group( { name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }, ).withReferences({ points: { mountCenter: [0, 0, 0] }, }); ```
-- `referenceNames()` — List named placement references carried by this group.
-- `withPorts()` — Attach named assembly ports (origin + axis + up) that survive transforms.
-- `portNames()` — List named port identifiers carried by this group.
-- `referencePoint()` — Resolve a named placement reference or built-in Anchor3D to a 3D point. Named refs take priority over built-in anchors.
-- `placeReference()` — Translate the group so the given reference lands on the target coordinate. ```javascript const placed = require('./bracket-assembly.forge.js').group .placeReference('mountCenter', [0, 0, 50]); ```
-- `withConnectors()` — Attach named connectors (typed, gendered ports) that survive transforms.
-- `connectorNames()` — List connector names (ports that have a connectorType), including "ChildName.connectorName" from named children.
-- `connectorsByType()` — Get all connectors of a given type, including from named children.
-- `connectorDistance()` — Distance between two connector origins on this group (supports dotted child paths).
-- `connectorMeasurements()` — Get measurements metadata from a connector (supports dotted child paths).
-- `matchTo()` — Position this group by matching connectors to a target. Connector names support dotted paths into named children: "ChildName.connectorName". Overloads: - Single pair: `matchTo(target, selfConn, targetConn, options?)` - Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)` - Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
-
-### `RouteBuilder`
-
-**Methods:**
-
-- `up()` — Vertical line going +Y. Length is optional (solver determines it from constraints).
-- `down()` — Vertical line going -Y. Length is optional.
-- `right()` — Horizontal line going +X. Length is optional.
-- `left()` — Horizontal line going -X. Length is optional.
-- `lineAt()` — Line at an arbitrary angle (degrees from +X). Length is optional.
-- `line()` — Line with solver-determined direction. Length is optional. Direction comes from tangency to previous arc or from constraints.
-- `toward()` — Line toward a specific point. Length defaults to the distance to that point.
-- `arcLeft()` — Tangent arc turning left relative to travel direction. or `{ minSweep: degrees }` to seed the geometry without constraining. `minSweep` guides the solver to the correct branch for arcs that sweep more than the default 90° seed.
-- `arcRight()` — Tangent arc turning right relative to travel direction. or `{ minSweep: degrees }` to seed without constraining.
-- `close()` — Close the route with a straight line back to the start point.
-- `done()` — Close the route back to its start point and register as a profile loop. No extra line segment is added. A coincident constraint connects the last point to the start, and tangency is added for G1 smoothness when arcs are at the junction. The session's incremental solver processes these constraints, keeping seed positions accurate for the final solve.
-- `get start()` — PointId of the route's start point.
-- `get end()` — PointId of the current cursor (route's end).
-- `startOf()` — Get the start point of a segment.
-- `endOf()` — Get the end point of a segment.
-
-### `FlatPart`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
-| `thickness` | `number` | — |
-| `options` | `FlatPartOptions` | — |
-
-**Methods:**
-
-- `get edges()` — All edges as a read-only map.
-- `edge()` — Look up a named edge. Throws if the edge does not exist.
-- `edgeNames()` — All edge names on this part.
-- `get partNumber()` — get partNumber(): number
-- `get joints()` — get joints(): readonly JointRecord[]
-- `get quantity()` — get quantity(): number
-- `addGeometry()` — Add geometry (e.g. protruding tabs) to the part profile.
-- `subtractGeometry()` — Subtract geometry (e.g. slot cuts) from the part profile.
-- `addJoint()` — Record a joint connection for assembly preview.
-- `profile()` — Final 2D profile with joints and optional kerf compensation.
-- `solid()` — 3D solid — extrude the profile by material thickness.
-
-### `LaserKit`
-
-**Methods:**
-
-- `get kerf()` — Laser kerf in mm.
-- `get parts()` — All registered parts (flat, in insertion order).
-- `get material()` — Default material label.
-- `get sheetWidth()` — Stock sheet width in mm.
-- `get sheetHeight()` — Stock sheet height in mm.
-- `addPart()` — Register a flat part with this kit. Assigns a sequential part number and records the quantity.
-- `cutSheets()` — Generate nested cut sheets using guillotine bin-packing.
-- `bom()` — Bill of materials listing every part with dimensions.
-- `partSvgs()` — Individual SVG string for each part profile, keyed by part name.
-- `inventorySvg()` — Combined inventory SVG showing all parts in a labeled grid.
-- `assemblyPreview()` — 3D fold-up preview of the assembled kit.
-- `assemblyInstructions()` — Step-by-step assembly instructions.
-- `formatInstructions()` — Human-readable assembly instructions text.
+- `childName(index: number): string | undefined` — Return the optional name of the child at `index`.
+- `child(name: string): GroupChild` — Return the named child by name. Throws if not found. Useful when importing a multipart group and working on components individually.
+- `clone(): ShapeGroup` — Return a deep-cloned ShapeGroup tree (refs copied).
+- `translate(x: number, y: number, z: number): ShapeGroup` — Move the entire group by (x, y, z). All children move together as a unit.
+- `boundingBox(): { min: [ number, number, number ]; max: [ number, number, number ]; }` — Return the combined 3D bounding box of all children.
+- `moveTo(x: number, y: number, z: number): ShapeGroup` — Move the group so its bounding-box min corner lands at the given coordinate.
+- `moveToLocal(target: Shape | ShapeGroup, x: number, y: number, z: number): ShapeGroup` — Move the group relative to another part's bounding-box min corner.
+- `attachTo(target: Shape | ShapeGroup, targetAnchor: Anchor3D | string, selfAnchor?: Anchor3D, offset?: [ number, number, number ]): ShapeGroup` — Attach this group to a face or anchor on another part. `targetAnchor` can be a built-in anchor name or a custom reference name on the target. `selfAnchor` selects the anchor on this group to align.
+- `onFace(parent: Shape | ShapeGroup, face: "front" | "back" | "left" | "right" | "top" | "bottom", opts?: { u?: number; v?: number; protrude?: number; }): ShapeGroup` — Place this group on a face of a parent shape. See Shape.onFace() for full documentation.
+- `rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup` — Rotate the group around an arbitrary axis through the origin.
+- `rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup` — Rotate the group around the X axis.
+- `rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup` — Rotate the group around the Y axis.
+- `rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup` — Rotate the group around the Z axis.
+- `rotateAroundAxis(axis: [ number, number, number ], angleDeg: number, pivot?: [ number, number, number ]): ShapeGroup` — Rotate around an arbitrary axis, optionally through a pivot point.
+- `rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: Anchor3D | [ number, number, number ], targetPoint: Anchor3D | [ number, number, number ], options?: RotateAroundToOptions): ShapeGroup` — Rotate around an axis until a moving point reaches the target line/plane defined by the axis and target point. ShapeGroup string points use built-in anchors only.
+- `pointAlong(direction: [ number, number, number ]): ShapeGroup` — Reorient the group so its local Z axis points along `direction`.
+- `transform(m: Mat4 | Transform): ShapeGroup` — Apply a 4x4 transform matrix or `Transform` to all 3D children.
+- `scale(v: number | [ number, number, number ]): ShapeGroup` — Scale uniformly or per-axis from the group's bounding-box center.
+- `scaleAround(pivot: [ number, number, number ], v: number | [ number, number, number ]): ShapeGroup` — Scale uniformly or per-axis from an explicit pivot point.
+- `mirror(normal: [ number, number, number ]): ShapeGroup` — Mirror across a plane through the group's bounding-box center.
+- `mirrorThrough(point: [ number, number, number ], normal: [ number, number, number ]): ShapeGroup` — Mirror across a plane through an explicit point.
+- `color(hex: string): ShapeGroup` — Return a copy of the group with the given display color applied to each child.
+- `withReferences(refs: PlacementReferenceInput): ShapeGroup` — Attach named placement references to this group. References survive normal transforms (translate/rotate/scale/mirror/transform). ```javascript const bracket = group( { name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }, ).withReferences({ points: { mountCenter: [0, 0, 0] }, }); ```
+- `referenceNames(kind?: PlacementReferenceKind): string[]` — List named placement references carried by this group.
+- `withPorts(ports: Record<string, PortInput>): ShapeGroup` — Backward-compatible alias for `withConnectors()`.
+- `portNames(): string[]` — Backward-compatible alias for `connectorNames()`.
+- `referencePoint(ref: PlacementAnchorLike): [ number, number, number ]` — Resolve a named placement reference or built-in Anchor3D to a 3D point. Named refs take priority over built-in anchors.
+- `placeReference(ref: PlacementAnchorLike, target: [ number, number, number ], offset?: [ number, number, number ]): ShapeGroup` — Translate the group so the given anchor or reference lands on the target coordinate. Accepts any built-in anchor name (`'bottom'`, `'center'`, `'top-front-left'`, etc.) or a custom placement reference attached via `withReferences()`. ```javascript // Ground a group — put its bottom at Z = 0 assembly.placeReference('bottom', [0, 0, 0]) // Use a custom reference from a multi-file part const placed = require('./bracket-assembly.forge.js').group .placeReference('mountCenter', [0, 0, 50]); ```
+- `withConnectors(connectors: Record<string, ConnectorInput>): ShapeGroup` — Attach named connectors — attachment points that survive transforms. Connectors can be bare (position + orientation) or typed (with connectorType/gender for compatibility matching).
+- `connectorNames(): string[]` — List all connector names, including "ChildName.connectorName" from named children.
+- `connectorsByType(type: string): Array<{ name: string; port: PortDef; }>` — Get all connectors of a given type, including from named children.
+- `connectorDistance(nameA: string, nameB: string): number` — Distance between two connector origins on this group (supports dotted child paths).
+- `connectorMeasurements(name: string): Record<string, number | string>` — Get measurements metadata from a connector (supports dotted child paths).
+- `matchTo(targetOrPairs: Shape | ShapeGroup | Array<[ Shape | ShapeGroup, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): ShapeGroup` — Position this group by matching connectors to a target. Connector names support dotted paths into named children: "ChildName.connectorName". Overloads: - Single pair: `matchTo(target, selfConn, targetConn, options?)` - Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)` - Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
 
 ---
 
@@ -1675,49 +728,48 @@ Core 3D solid shape. All operations are immutable and return new shapes. Support
 
 ### `verify`
 
-**Members:**
-
-- `that()` — Custom predicate check.
-- `equal()` — Check that two numbers are approximately equal (within tolerance).
-- `notEqual()` — Check that two numbers are NOT equal (differ by more than tolerance).
-- `greaterThan()` — Check that actual > min.
-- `lessThan()` — Check that actual < max.
-- `inRange()` — Check that min <= actual <= max.
-- `centersCoincide()` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
-- `notColliding()` — Check that two shapes do not collide (minGap > 0).
-- `minClearance()` — Check that a minimum clearance gap exists between two shapes.
-- `parallel()` — Check that two face normals are parallel (within toleranceDeg degrees).
-- `perpendicular()` — Check that two face normals are perpendicular (within toleranceDeg degrees).
-- `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.
-- `faceAt()` — Check that a face center lies at a specific position (within toleranceMm).
-- `sameDirection()` — Check that two face normals point in the same direction (not antiparallel). Stricter than parallel — both |angle| AND sign must match.
-- `isEmpty()` — Check that a shape is empty.
-- `notEmpty()` — Check that a shape is NOT empty.
-- `volumeApprox()` — Check that a shape's volume is approximately equal to expected (mm³).
-- `areaApprox()` — Check that a shape's surface area is approximately equal to expected (mm²).
-- `boundingBoxSize()` — Check that a shape's bounding box has approximately the given size.
+- `that(label: string, check: () => boolean, message?: string): void` — Custom predicate check.
+- `equal(label: string, actual: number, expected: number, tolerance?: number, message?: string): void` — Check that two numbers are approximately equal (within tolerance).
+- `notEqual(label: string, actual: number, unexpected: number, tolerance?: number, message?: string): void` — Check that two numbers are NOT equal (differ by more than tolerance).
+- `greaterThan(label: string, actual: number, min: number, message?: string): void` — Check that actual > min.
+- `lessThan(label: string, actual: number, max: number, message?: string): void` — Check that actual < max.
+- `inRange(label: string, actual: number, min: number, max: number, message?: string): void` — Check that min <= actual <= max.
+- `centersCoincide(label: string, a: ShapeLike$1, b: ShapeLike$1, tolerance?: number): void` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
+- `notColliding(label: string, a: ShapeLike$1, b: ShapeLike$1, searchLength?: number): void` — Check that two shapes do not collide (minGap > 0).
+- `minClearance(label: string, a: ShapeLike$1, b: ShapeLike$1, minGap: number, searchLength?: number): void` — Check that a minimum clearance gap exists between two shapes.
+- `parallel(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void` — Check that two face normals are parallel (within toleranceDeg degrees).
+- `perpendicular(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void` — Check that two face normals are perpendicular (within toleranceDeg degrees).
+- `coplanar(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number, toleranceMm?: number): void` — Check that a face is coplanar with (same plane as) another face, meaning they are parallel AND their centers lie on the same plane.
+- `faceAt(label: string, face: FaceRefLike, expectedPos: [ number` — Check that a face center lies at a specific position (within toleranceMm).
+- `sameDirection(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void` — Check that two face normals point in the same direction (not antiparallel). Stricter than parallel — both |angle| AND sign must match.
+- `isEmpty(label: string, shape: ShapeLike$1, message?: string): void` — Check that a shape is empty.
+- `notEmpty(label: string, shape: ShapeLike$1, message?: string): void` — Check that a shape is NOT empty.
+- `volumeApprox(label: string, shape: ShapeLike$1, expected: number, tolerance?: number): void` — Check that a shape's volume is approximately equal to expected (mm³).
+- `areaApprox(label: string, shape: ShapeLike$1, expected: number, tolerance?: number): void` — Check that a shape's surface area is approximately equal to expected (mm²).
+- `boundingBoxSize(label: string, shape: ShapeLike$1, expectedSize: [ number` — Check that a shape's bounding box has approximately the given size.
 
 ### `Constraint`
 
-**Members:**
-
-- `makeParallel()` — makeParallel(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): Constra
-- `enforceAngle()` — enforceAngle(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg, angleDeg
-- `horizontal()` — horizontal(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchB
-- `vertical()` — vertical(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBui
-- `equalLength()` — equalLength(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): Constrai
-- `distance()` — distance(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg, value: num
-- `fix()` — fix(builder: ConstrainedSketchBuilder, pt: PointArg, x: number, y: number): Cons
-- `coincident()` — coincident(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg): Constra
-- `perpendicular()` — perpendicular(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): Constr
-- `length()` — length(builder: ConstrainedSketchBuilder, line: LineArg, value: number): Constra
+- `makeParallel(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder` — Constrain two lines to be parallel.
+- `enforceAngle(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg, angleDeg: number): ConstrainedSketchBuilder` — Constrain the signed angle from line `a` to line `b`.
+- `horizontal(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder` — Constrain a line to be horizontal.
+- `vertical(builder: ConstrainedSketchBuilder, line: LineArg): ConstrainedSketchBuilder` — Constrain a line to be vertical.
+- `equalLength(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder` — Constrain two lines to have equal length.
+- `distance(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg, value: number): ConstrainedSketchBuilder` — Constrain the distance between two points.
+- `fix(builder: ConstrainedSketchBuilder, pt: PointArg, x: number, y: number): ConstrainedSketchBuilder` — Fix a point at a specific coordinate.
+- `coincident(builder: ConstrainedSketchBuilder, a: PointArg, b: PointArg): ConstrainedSketchBuilder` — Constrain two points to occupy the same location.
+- `perpendicular(builder: ConstrainedSketchBuilder, a: LineArg, b: LineArg): ConstrainedSketchBuilder` — Constrain two lines to be perpendicular.
+- `length(builder: ConstrainedSketchBuilder, line: LineArg, value: number): ConstrainedSketchBuilder` — Constrain the length of a line.
 
 ### `Points`
 
-**Members:**
+- `distance(a: Vec3, b: Vec3): number` — Euclidean distance between two 3D points.
+- `midpoint(a: Vec3, b: Vec3): Vec3` — Center point between two 3D points.
+- `lerp(a: Vec3, b: Vec3, t: number): Vec3` — Linearly interpolate between two 3D points. t=0 returns a, t=1 returns b.
+- `direction(a: Vec3, b: Vec3): Vec3` — Unit direction vector from a to b. Throws if a and b are the same point.
+- `offset(point: Vec3, dir: Vec3, amount: number): Vec3` — Move a point along a direction vector by a given amount.
+- `polar(length: number, angleDeg: number, from?: [ number, number ]): [ number, number ]` — Compute a 2D point at distance and angle (degrees) from an optional origin.
+
+### `connector`
 
-- `distance()` — Euclidean distance between two 3D points.
-- `midpoint()` — Center point between two 3D points.
-- `lerp()` — Linearly interpolate between two 3D points. t=0 returns a, t=1 returns b.
-- `direction()` — Unit direction vector from a to b. Throws if a and b are the same point.
-- `offset()` — Move a point along a direction vector by a given amount.
+Connector factory. Create attachment points: `connector({...})`, `connector.male(type, {...})`, etc.