forgecad 0.6.3 → 0.8.0

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

@@ -5,1667 +5,1621 @@ skill-order: 100
 
 # Core API
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 3D primitives, boolean operations, transforms, patterns, imports, and parameters.
 
+## Contents
+
+- [Boolean Operations](#boolean-operations) — `union`, `difference`, `intersection`
+- [Edge Features](#edge-features) — `fillet`, `chamfer`, `draft`, `offsetSolid`
+- [Patterns & Layout](#patterns-layout) — `selectEdges`, `selectEdge`, `coalesceEdges`, `filletCorners`, `circularLayout`, `polygonVertices`, `linearPattern`, `circularPattern`, `linearPattern2d`, `circularPattern2d`, `mirrorCopy`
+- [Imports & Composition](#imports-composition) — `require`, `importSvgSketch`, `importMesh`, `importStep`
+- [Parameters](#parameters) — `Param.number`, `Param.string`, `Param.bool`, `Param.choice`, `Param.list`
+- [Grouping & Local Coordinates](#grouping-local-coordinates) — `group`
+- [Section & Projection](#section-projection) — `intersectWithPlane`, `faceProfile`, `projectToPlane`
+- [Transforms](#transforms) — `composeChain`
+- [Verification](#verification) — `spec`
+- [Shape](#shape) — Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
+- [Transform](#transform)
+- [ShapeGroup](#shapegroup) — Children, Transforms, Placement, Connectors, References
+- [SurfacePattern](#surfacepattern)
+- [ANCHOR3D_NAMES](#anchor3d-names)
+- [verify](#verify)
+- [Constraint](#constraint)
+- [Points](#points)
+- [connector](#connector)
+
 ## Functions
 
-### 3D Primitives
+### Boolean Operations
 
-Create basic 3D shapes.
+#### `union()` — Combine shapes into a single solid (additive boolean).
 
-#### `box()`
+Accepts individual shapes, or an array of shapes. The first operand's color is preserved in the result.
 
 ```ts
-box$1(x: number, y: number, z: number, center?: boolean): Shape
+union(...inputs: ShapeOperandInput[]): 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.).
+#### `difference()` — Subtract shapes from a base shape (subtractive boolean).
 
-#### `cylinder()`
+The first shape is the base; all subsequent shapes are subtracted from it. Accepts individual shapes, or an array of shapes.
 
 ```ts
-cylinder$1(height: number, radius: number, radiusTop?: number, segments?: number, center?: boolean): Shape
+difference(...inputs: ShapeOperandInput[]): 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).
+#### `intersection()` — Keep only the overlapping volume of the input shapes (intersection boolean).
 
-#### `sphere()`
+Requires at least two shapes. Accepts individual shapes, or an array.
 
 ```ts
-sphere$1(radius: number, segments?: number): Shape
+intersection(...inputs: ShapeOperandInput[]): Shape
 ```
 
-Create a sphere centered at the origin. Use segments for lower-poly approximations. @concept primitive
+### Edge Features
 
-### Boolean Operations
+#### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
 
-Combine shapes using set operations.
+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.
 
-#### `union()`
-
-```ts
-union(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
-```
+The `edges` parameter is flexible:
 
-Combine shapes into a single solid (additive boolean). Accepts individual shapes or arrays. @concept boolean
+- 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
 
-#### `difference()`
+Throws if no edges match the selection, or if `radius` is not a positive finite number.
 
 ```ts
-difference(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
-```
+// Fillet all edges
+fillet(myShape, 2)
 
-Subtract shapes from a base shape. The first shape is the base; all subsequent shapes are subtracted. @concept boolean
+// Fillet only top convex edges
+fillet(myShape, 1.5, { atZ: 20, convex: true })
 
-#### `intersection()`
+// Fillet vertical edges selected beforehand
+const edges = selectEdges(myShape, { parallel: [0, 0, 1] })
+fillet(myShape, 3, edges)
+```
 
 ```ts
-intersection(...shapes: (_ShapeOperand | _ShapeOperand[])[]): Shape
+fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
 ```
 
-Keep only the overlapping volume of the input shapes (intersection boolean). @concept boolean
+#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
 
-### Patterns & Topology
+Produces a 45° bevel at the specified `size` (distance from edge). Works on both straight and curved edges. Supports OCCT and Manifold backends.
 
-Repeat, mirror, fillet, and chamfer geometry.
+The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
-#### `filletEdgeSegment()`
+```ts
+// Chamfer all edges
+chamfer(myShape, 1)
+
+// Chamfer only vertical edges
+chamfer(myShape, 2, { parallel: [0, 0, 1] })
+```
 
 ```ts
-filletEdgeSegment(shape: Shape, segment: EdgeSegment, radius: number, segments?: number): Shape
+chamfer(shape: Shape, size: number, edges?: EdgeSelector): 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().
+#### `draft()` — Apply a draft angle (taper) to vertical faces for mold extraction.
 
-<details><summary><code>EdgeSegment</code></summary>
+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
-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;
-}
-```
+Requires the OCCT backend. Throws on Manifold.
 
-</details>
+```ts
+// Add 3° draft to a box for injection molding
+draft(myBox, 3)
 
-#### `chamferEdgeSegment()`
+// Draft with custom pull direction and neutral plane
+draft(myShape, 2, [0, 0, 1], 10)
+```
 
 ```ts
-chamferEdgeSegment(shape: Shape, segment: EdgeSegment, size: number): Shape
+draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: 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.
+#### `offsetSolid()` — Uniformly offset all surfaces of a solid inward or outward.
+
+Unlike `shell()`, which hollows a solid by removing one face, `offsetSolid()` produces a new solid whose every surface is shifted by `thickness`. Positive values grow the shape outward; negative values shrink it inward.
 
-#### `selectEdges()`
+Requires the OCCT backend. Throws on Manifold.
 
 ```ts
-selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+// Grow a box outward by 1mm on all sides
+offsetSolid(myBox, 1)
+
+// Shrink a shape inward by 0.5mm
+offsetSolid(myShape, -0.5)
 ```
 
-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;
-}
+```ts
+offsetSolid(shape: Shape, thickness: number): Shape
 ```
 
-</details>
+### Patterns & Layout
+
+#### `selectEdges()` — Select all edges from a shape that match the given query.
+
+Extracts sharp edges from the mesh (dihedral angle > 1°), applies all filters in the query, and returns the matching `EdgeSegment[]`. When `near` is specified the results are sorted closest-first.
 
-<details><summary><code>BoundingRegion</code></summary>
+Works on any shape — primitives, booleans, shells, and imported meshes. Use this when tracked topology is unavailable (e.g. after a difference or on imported geometry). For simpler cases, pass an `EdgeQuery` directly to `fillet()` or `chamfer()` instead of calling `selectEdges` separately.
 
 ```ts
-interface BoundingRegion {
-  xMin?: number;
-  xMax?: number;
-  yMin?: number;
-  yMax?: number;
-  zMin?: number;
-  zMax?: 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>
+```ts
+selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
+```
+
+**`EdgeQuery`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `near?` | `Vec3` | Sort by proximity to this point (closest first). When used with `selectEdge`, picks the closest match. |
+| `parallel?` | `Vec3` | Filter: edge direction approximately parallel to this vector. |
+| `perpendicular?` | `Vec3` | Filter: edge direction approximately perpendicular to this vector. |
+| `convex?` | `boolean` | Filter: only convex (outside corner) edges. |
+| `concave?` | `boolean` | Filter: only concave (inside corner) edges. |
+| `minAngle?` | `number` | Filter: minimum dihedral angle in degrees. |
+| `maxAngle?` | `number` | Filter: maximum dihedral angle in degrees. |
+| `minLength?` | `number` | Filter: minimum edge length. |
+| `maxLength?` | `number` | Filter: maximum edge length. |
+| `within?` | `BoundingRegion` | Filter: edge midpoint must be within this bounding region. |
+| `atZ?` | `number` | Shorthand: edge midpoint Z ≈ this value (within `tolerance`). Equivalent to `within: { zMin: atZ - tol, zMax: atZ + tol }`. |
+| `tolerance?` | `number` | Position tolerance for approximate matches (default: `1.0`). Used by `atZ` and `near`. |
+| `angleTolerance?` | `number` | Angular tolerance in degrees for `parallel`/`perpendicular` filters (default: `10`). |
+
+`BoundingRegion`: `{ xMin?: number, xMax?: number, yMin?: number, yMax?: number, zMin?: number, zMax?: number }`
+
+**`EdgeSegment`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `index` | `number` | Stable index within the extraction (deterministic for a given mesh). |
+| `direction` | `Vec3` | Normalized direction from start → end. |
+| `dihedralAngle` | `number` | Dihedral angle in degrees (0 = coplanar, 180 = knife edge). |
+| `convex` | `boolean` | true = outside corner (convex), false = inside corner (concave). |
+| `normalA` | `Vec3` | Normal of first adjacent face. |
+| `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
+| `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
+| `start`, `end`, `midpoint`, `length` | | — |
+
+#### `selectEdge()` — Select the single best-matching edge from a shape.
 
-#### `selectEdge()`
+When `near` is specified, returns the edge whose midpoint is closest to that point. Otherwise returns the first matching edge in mesh order. Throws if no edges match the query — useful as a guard when you expect exactly one result.
+
+```ts
+// Chamfer one specific edge near a known point
+const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
+result = chamfer(result, 1.5, bottomEdge);
+```
 
 ```ts
 selectEdge(shape: Shape, query?: EdgeQuery): EdgeSegment
 ```
 
-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()` — Merge collinear edge segments into longer logical edges.
 
-#### `coalesceEdges()`
+Tessellation often splits one geometric edge into multiple short segments. `coalesceEdges` groups adjacent collinear segments and merges each group into a single `EdgeSegment` spanning the full extent. This is usually needed before passing edges to `fillet()` or `chamfer()` on non-primitive shapes.
+
+The `tolerance` controls the maximum perpendicular distance from collinearity before two segments are considered non-collinear. Default: `0.01`.
+
+```ts
+const topEdges = selectEdges(part, { atZ: 20 });
+for (const edge of coalesceEdges(topEdges)) {
+  result = fillet(result, 2, edge);
+}
+```
 
 ```ts
 coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
 ```
 
-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.
+#### `filletCorners()` — Create a polygon from points with specific corners rounded to arc fillets.
 
-#### `arcBridgeBetweenRects()`
+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
-arcBridgeBetweenRects(rectA: RectAreaArg, rectB: RectAreaArg, segments?: number): Shape
-```
+Constraints:
 
-Build an arc bridge between two rectangular areas.
+- 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
 
-#### `filletEdge()`
+Use `offset(-r).offset(+r)` instead if you want to round **all** convex corners uniformly. Use `filletCorners` when you need selective or mixed sharp/rounded profiles.
 
 ```ts
-filletEdge(shape: Shape, edge: EdgeRef, radius: number, quadrant?: [ number, number ], segments?: number): Shape
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
 ```
 
-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;
-}
+filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
 ```
 
-</details>
+`FilletCornerSpec`: `{ index: number, radius: number, segments?: number }`
 
-#### `chamferEdge()`
+#### `circularLayout()` — Compute evenly-spaced positions around a circle.
 
-```ts
-chamferEdge(shape: Shape, edge: EdgeRef, size: number, quadrant?: [ number, number ]): Shape
-```
+Eliminates the most common trig pattern in CAD scripts:
 
-Bevel a named edge of a shape with a 45-degree chamfer of the given size. Requires a compile-covered target.
+```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));
+}
 
-#### `filletCorners()`
+// After — declarative
+for (const {x, y} of circularLayout(12, r)) {
+  markers.push(marker.translate(x, y, 0));
+}
+```
 
 ```ts
-filletCorners(points: PointInput[], corners: FilletCornerSpec[]): Sketch
+circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
 ```
 
-Create a polygon from points with specified corners rounded to arc fillets. Each corner spec identifies a vertex index and radius.
+**`CircularLayoutOptions`**
+- `startDeg?: number` — Angle of the first element in degrees (default: 0 = +X axis).
+- `centerX?: number` — Center X coordinate (default: 0).
+- `centerY?: number` — Center Y coordinate (default: 0).
+
+`LayoutPoint`: `{ x: number, y: number }`
+
+#### `polygonVertices()` — 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()`](/docs/sketch#ngon).
+
+Eliminates manual Math.sqrt(3) for triangles, pentagon vertex math, etc:
 
-<details><summary><code>FilletCornerSpec</code></summary>
+```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);
+```
 
 ```ts
-interface FilletCornerSpec {
-  index: number;
-  radius: number;
-  segments?: number;
-}
+polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
 ```
 
-</details>
+**`PolygonVerticesOptions`**
+- `startDeg?: number` — Angle of the first vertex in degrees (default: 90 = top).
+- `centerX?: number` — Center X coordinate (default: 0).
+- `centerY?: number` — Center Y coordinate (default: 0).
+
+#### `linearPattern()` — Repeat a shape in a linear pattern along a direction vector and union the copies.
+
+Creates `count` copies of `shape`, each offset by `(dx*i, dy*i, dz*i)` from the original. All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy so face identity via owner-scoped canonical queries still works post-merge.
 
-#### `linearPattern()`
+```ts
+// 5 cylinders, 20mm apart along X
+linearPattern(cylinder(10, 3), 5, 20, 0)
+```
 
 ```ts
 linearPattern(shape: Shape, count: number, dx: number, dy: number, dz?: number): Shape
 ```
 
-Repeat a shape in a linear pattern along a direction vector and union the copies.
+#### `circularPattern()` — Repeat a shape in a circular pattern around an axis and union the copies.
+
+Distributes `count` copies evenly around the rotation axis (360° / count per step). All copies are unioned into a single `Shape`. Distinct compiler ownership is assigned to each copy — post-merge face identity via owner-scoped canonical queries still works for pattern descendants.
 
-#### `circularPattern()`
+Two calling conventions:
+
+- **Simple** (Z axis): `circularPattern(shape, 6)` or `circularPattern(shape, 6, centerX, centerY)`
+- **Advanced** (arbitrary axis): `circularPattern(shape, 6, { axis, origin })`
+
+```ts
+// 8 holes evenly spaced around origin
+circularPattern(cylinder(12, 4).translate(30, 0, -1), 8)
+
+// Circular pattern around X axis
+circularPattern(myFeature, 4, { axis: [1, 0, 0], origin: [0, 0, 50] })
+```
 
 ```ts
 circularPattern(shape: Shape, count: number, centerXOrOpts?: number | CircularPatternOptions, centerY?: number): Shape
 ```
 
-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] })
+**`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).
 
-<details><summary><code>CircularPatternOptions</code></summary>
+#### `linearPattern2d()` — Repeat a 2D sketch in a linear pattern and union the copies.
 
 ```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;
-}
+linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+```
+
+#### `circularPattern2d()` — Repeat a 2D sketch in a circular pattern around a center point and union the copies.
+
+```ts
+circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
 ```
 
-</details>
+#### `mirrorCopy()` — Mirror a shape across a plane and union the mirror with the original.
 
-#### `mirrorCopy()`
+The mirror plane passes through the origin and is defined by its normal vector. The mirrored copy is unioned with the original to produce a single symmetric Shape.
 
 ```ts
-mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+// Mirror across the YZ plane (X=0)
+mirrorCopy(box(50, 30, 10), [1, 0, 0])
 ```
 
-Mirror a shape across a plane defined by its normal and union the mirror with the original.
+```ts
+mirrorCopy(shape: Shape, normal: [ number, number, number ]): Shape
+```
 
 ### Imports & Composition
 
-Import model files and SVG assets from other files.
+#### `require()` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
 
-#### `require()`
+When importing a `.forge.js` file, the return value is what the script returns. If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
 
-```ts
-require$1(path: string, paramOverrides?: Record<string, number>): any
+**Parameter scoping:** Parameters declared in required files are automatically namespaced with a `"filename#N / "` prefix (e.g. `"bracket.forge.js#1 / Width"`). This prevents collisions when multiple files declare same-named params. Each file's params appear as separate sliders.
+
+**Parameter overrides:** When passing overrides, use the bare param name (not the scoped name). Overrides are type-checked — unrecognized keys throw an error with typo suggestions.
+
+**Multi-file assembly pattern** — pass cross-cutting design values from the assembly to parts:
+
+```js
+// assembly.forge.js — owns cross-cutting params, passes to parts
+const wall = param("Wall", 3);
+const baseH = param("Base Height", 20);
+
+const mount = require('./motor-mount.forge.js', { Wall: wall });
+const base  = require('./base-body.forge.js', { Wall: wall, Height: baseH });
 ```
 
-Import a module with optional ForgeCAD parameter overrides. Returns the module's exports. @concept import
+**Metadata pattern** — parts publish interface data alongside geometry:
 
-#### `importSvgSketch()`
+```js
+// motor-mount.forge.js
+return { shape: mount, bolts: { dia: 5.3, pos: holePositions } };
+
+// base-body.forge.js
+const mount = require('./motor-mount.forge.js');
+mount.bolts.pos  // access the metadata
+mount.shape       // access the geometry
+```
 
 ```ts
-importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
+require(path: string, paramOverrides?: Record<string, number | string>): any
 ```
 
-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;
-}
+#### `importSvgSketch()` — Parse an SVG file and return it as a Sketch with options for region filtering, scaling, and simplification.
+
+```ts
+importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
 ```
 
-</details>
+**`SvgImportOptions`**
 
-### Parameters
+| 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. |
 
-Declare user-adjustable parameters with UI controls.
+#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF) as a Shape.
 
-#### `param()`
+```ts
+importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
+```
+
+#### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires `setActiveBackend('occt')`.
 
 ```ts
-param(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
+importStep(fileName: string): Shape
 ```
 
-Declare a parameter. Returns the current value (default or overridden). Each call registers the param for UI generation.
+### Parameters
 
-#### `boolParam()`
+#### `Param.number()` — Declare a numeric parameter that renders as a slider in the UI.
+
+Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+
+Default range rules when options are omitted:
+
+- `min` defaults to `0`
+- `max` defaults to `defaultValue * 4`
+- `step` is auto-calculated: `1` for integer params, `0.1` for ranges ≤ 100, `1` for larger ranges
+
+The `unit` option is cosmetic only — no conversion is performed. Use `integer: true` for counts, sides, quantities (rounds to whole numbers; step defaults to `1`).
 
 ```ts
-boolParam(name: string, defaultValue: boolean): boolean
+const width = Param.number("Width", 50);
+const angle = Param.number("Angle", 45, { min: 0, max: 180, unit: "°" });
+const sides = Param.number("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-Declare a boolean parameter. Returns the current boolean value. Renders as a checkbox in the UI.
+**Parameter overrides** — key must match `name` exactly:
 
-### Grouping
+```ts
+// Via require()
+const bracket = require("./bracket.forge.js", { Width: 80 });
 
-Organize multiple shapes into named groups.
+// Via CLI
+// forgecad run model.forge.js --param "Wall Thickness=3"
+```
 
-#### `group()`
+Also available as the shorthand alias `param()`.
 
 ```ts
-group(...items: GroupInput[]): ShapeGroup
+Param.number(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number
 ```
 
-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.).
+#### `Param.string()` — Declare a string parameter that renders as a text input in the UI.
 
-### Section & Projection
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
 
-Slice or project 3D shapes to 2D.
+```ts
+const label = Param.string("Label", "Hello World");
+const name  = Param.string("Name", "Part-001", { maxLength: 20 });
+```
 
-#### `intersectWithPlane()`
+Override via import:
 
 ```ts
-intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch
+const tag = require("./tag.forge.js", { Label: "Custom Text" });
+```
+
+Only available as `Param.string()` — no standalone alias.
+
+```ts
+Param.string(name: string, defaultValue: string, opts?: { maxLength?: number; }): string
 ```
 
-Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
+#### `Param.bool()` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-#### `projectToPlane()`
+Internally stored as `0`/`1`. When overriding from CLI or `require()`, pass `1` for true and `0` for false. The `name` string is the override key.
 
 ```ts
-projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
+const showHoles = Param.bool("Show Holes", true);
+if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
+return plate;
 ```
 
-Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
+Override via import:
 
-### Other
+```ts
+const pan = require("./pan.forge.js", { "Show Lid": 0 });
+```
 
-#### `composeChain()`
+Also available as the shorthand alias `boolParam()`.
 
 ```ts
-composeChain(...steps: TransformInput[]): Transform
+Param.bool(name: string, defaultValue: boolean): boolean
 ```
 
-Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
+#### `Param.choice()` — Declare a choice parameter that renders as a dropdown in the UI.
+
+`defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `Param.choice` over `Param.number` when a slider would hide intent — named choices like `"wok"` are self-describing.
 
-#### `portFactory()`
+Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
 
 ```ts
-portFactory(input: PortInput): PortDef
+const panStyle = Param.choice("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
+if (panStyle === "wok") return buildWok();
 ```
 
-<details><summary><code>PortInput</code></summary>
+Override via import:
 
 ```ts
-interface PortInput {
-  kind?: JointType;
-  min?: number;
-  max?: number;
-}
+const pan = require("./pan.forge.js", { "Pan Style": "wok" });
 ```
 
-</details>
+Override via CLI:
 
-<details><summary><code>PortDef</code></summary>
+```bash
+forgecad run model.forge.js --param "Pan Style=wok"
+```
+
+Also available as the shorthand alias `choiceParam()`.
 
 ```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>;
-}
+Param.choice(name: string, defaultValue: string, choices: string[]): string
 ```
 
-</details>
+#### `Param.list()` — Declare a list parameter — an array of struct items with per-field UI controls.
 
-#### `connectorFactory()`
+Each item in the list is a struct whose fields each render as their own control (slider, checkbox, or dropdown). The user can add/remove rows up to `minItems`/`maxItems` bounds.
+
+Field types:
+
+- Boolean fields (`boolean: true` in field defs) return as `boolean`
+- Choice fields (`choices: [...]` in field defs) return as `string`
+- All other fields return as `number`
 
 ```ts
-connectorFactory(connectorType: string, input: PortInput, measurements?: Record<string, number | string>): ConnectorInput
+Param.list<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
 ```
 
+`ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
+
+### Grouping & Local Coordinates
+
+#### `group()` — Group multiple shapes/sketches for joint transforms without merging into a single mesh.
+
+Unlike union(), colors and individual identities are preserved. Children can be plain shapes, named descriptors ({ name, shape/sketch/group }), or nested groups. The returned ShapeGroup supports all Shape transforms (translate, rotate, etc.).
+
+**Local coordinate pattern:** Build child parts at the origin (local coordinates), then group and translate once to place the whole assembly. This eliminates the error-prone pattern of manually adding parent offsets to every sub-part.
 
-<details><summary><code>ConnectorInput</code> extends PortInput</summary>
+```js
+// BAD — every sub-part repeats the parent's global offset
+const unitX = 0, unitY = -18, unitZ = 70;
+const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ);
+const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+```
+
+// GOOD — build at origin, group, translate once const body = roundedBox(100, 20, 32, 4); const panel = box(98, 2, 18).translate(0, -12, 4); const louver = box(88, 2, 6).translate(0, -14, -11); const indoorUnit = group( { name: 'Body', shape: body }, { name: 'Panel', shape: panel }, { name: 'Louver', shape: louver }, ).translate(0, -18, 70);
 
 ```ts
-interface ConnectorInput extends PortInput {
-  connectorType: string;
-  gender: ConnectorGender$1;
-  measurements?: Record<string, number | string>;
-}
+group(...items: GroupInput[]): ShapeGroup
 ```
 
-</details>
+### Section & Projection
 
-#### `polar()`
+#### `intersectWithPlane()` — Cross-section: slice a 3D shape with a plane and return the intersection as a 2D Sketch.
 
 ```ts
-polar(length: number, angleDeg: number, from?: [ number, number ]): [ number, number ]
+intersectWithPlane(shape: Shape, plane: PlaneSpec): Sketch
 ```
 
-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) ```
+#### `faceProfile()` — Extract the boundary profile of a named face as a 2D sketch.
 
-#### `fillet()`
+The result is returned in the face's local 2D coordinate system, making it convenient for offsets, pocket profiles, or follow-up sketch operations driven by an existing face.
 
 ```ts
-fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
+faceProfile(shape: Shape, face: FaceSelector): Sketch
 ```
 
-Apply fillets (rounded edges) to one or more edges of a shape. Works on both straight and curved edges. Supports OCCT and Manifold backends. When using OCCT, all edges are filleted in a single kernel operation for best quality. When using Manifold, edges are filleted sequentially. - EdgeSegment: a single edge from selectEdge() - EdgeSegment[]: multiple edges from selectEdges() - EdgeQuery: inline query (same options as selectEdges) - undefined: all sharp edges on the shape // Fillet all edges fillet(myShape, 2) // Fillet edges at the top fillet(myShape, 1.5, { atZ: 20, convex: true }) // Fillet specific edges const edges = selectEdges(myShape, { parallel: [0, 0, 1] }) fillet(myShape, 3, edges)
-
-#### `chamfer()`
+#### `projectToPlane()` — Orthographically project a 3D shape onto a plane and return the silhouette as a 2D Sketch.
 
 ```ts
-chamfer(shape: Shape, size: number, edges?: EdgeSelector): Shape
+projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
 ```
 
-Apply chamfers (beveled edges) to one or more edges of a shape. Works on both straight and curved edges. Supports OCCT and Manifold backends. // Chamfer all edges chamfer(myShape, 1) // Chamfer vertical edges only chamfer(myShape, 2, { parallel: [0, 0, 1] })
+### Transforms
 
-#### `draft()`
+#### `composeChain()` — Compose transforms in chain order. Equivalent to Transform.identity().mul(a).mul(b).mul(c)...
 
 ```ts
-draft(shape: Shape, angleDeg: number, pullDirection?: [ number, number, number ], neutralPlaneOffset?: number): Shape
+composeChain(...steps: TransformInput[]): Transform
 ```
 
-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)
+### Verification
+
+#### `spec()` — Create a named, reusable bundle of verification checks.
+
+A spec groups related `verify.*` calls under a collapsible header in the Checks panel. This makes large check suites scannable. Specs can be applied to multiple shapes and can check relationships between parts.
+
+Specs can be defined in separate `.forge.js` files and imported via `require()` to share them across models.
 
-#### `offsetSolid()`
+`spec.check()` returns a `SpecResult` — you can inspect it programmatically or ignore the return value and let the Checks panel show results.
 
 ```ts
-offsetSolid(shape: Shape, thickness: number): Shape
-```
+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);
+});
 
-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)
+// Reuse on multiple shapes
+printable.check(bracket);
+printable.check(standoff);
 
-#### `choiceParam()`
+// Check relationships between parts
+const fitSpec = spec("Assembly fit", (partA, partB) => {
+  verify.notColliding("No interference", partA, partB, 10);
+});
+fitSpec.check(bracket, standoff);
+```
+
+**Spec-first workflow:** Write specs before building geometry. Checks go from red to green as you build — effectively TDD for CAD.
 
 ```ts
-choiceParam(name: string, defaultValue: string, choices: string[]): string
+spec(name: string, checkFn: (...args: any[]) => void): Spec
 ```
 
-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.
+**`Spec`**
+- `name: string` — The display name of this spec
+
+---
 
-#### `listParam()`
+## Classes
+
+### `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).
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `materialProps` | `ShapeMaterialProps | undefined` | — |
+
+**Appearance**
+
+#### `color()` — Set the color of this shape (hex string, e.g. "#ff0000"). Returns a new Shape with the color applied.
 
 ```ts
-listParam<T extends Record<string, number | boolean | string>>(name: string, defaultItems: T[], opts: { ... }): T[]
+color(value: string | undefined): Shape
 ```
 
-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.
+#### `material()` — Set PBR material properties for this shape's visual appearance.
+
+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.
 
-<details><summary><code>ListParamFieldDef</code></summary>
+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()`](/docs/viewport#scene).
+
+```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);
+```
 
 ```ts
-interface ListParamFieldDef {
-  min?: number;
-  max?: number;
-  step?: number;
-  unit?: string;
-  integer?: boolean;
-  boolean?: boolean;
-  choices?: string[];
-}
+material(props: ShapeMaterialProps): Shape
 ```
 
-</details>
+**Face Topology**
+
+#### `face()` — 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.
+
+`.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.
 
-#### `distance()`
+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.
 
 ```ts
-distance(a: Vec3, b: Vec3): number
-```
+// 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
 
-#### `midpoint()`
+// 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
+```
 
 ```ts
-midpoint(a: Vec3, b: Vec3): Vec3
+face(selector: FaceSelector): FaceRef
 ```
 
-#### `lerp()`
+#### `faces()` — Return all faces matching a query, or all mesh-detected faces when no query is given.
 
 ```ts
-lerp(a: Vec3, b: Vec3, t: number): Vec3
+faces(query?: FaceQuery): FaceRef[]
 ```
 
-#### `direction()`
+#### `faceNames()` — List defended semantic face names currently available on this shape, including user labels from `labelFaces()`.
 
 ```ts
-direction(a: Vec3, b: Vec3): Vec3
+faceNames(): string[]
 ```
 
-#### `offset()`
+#### `labelFaces()` — Assign user-chosen labels to faces identified by their canonical position keys.
+
+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`).
+
+```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
+```
 
 ```ts
-offset(point: Vec3, dir: Vec3, amount: number): Vec3
+labelFaces(mapping: Record<string, string>): Shape
 ```
 
-#### `loftAlongSpine()`
+#### `prefixLabels()` — Prefix all user-authored face labels (both sketch-edge labels and labelFaces labels). Returns a new shape with modified labels.
 
 ```ts
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3$4[], tValues: number[], options?: LoftAlongSpineOptions): Shape
+prefixLabels(prefix: string): 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><summary><code>LoftAlongSpineOptions</code></summary>
+#### `renameLabel()` — Rename a single face label. Returns a new shape.
 
 ```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;
-}
+renameLabel(from: string, to: string): Shape
 ```
 
-</details>
-
-#### `variableSweep()`
+#### `dropLabels()` — Remove specific face labels. Returns a new shape.
 
 ```ts
-variableSweep(spine: Curve3D | Vec3$4[], sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
+dropLabels(...names: string[]): 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.
+#### `dropAllLabels()` — Remove all face labels. Returns a new shape.
+
+```ts
+dropAllLabels(): Shape
+```
 
-<details><summary><code>VariableSweepSection</code></summary>
+#### `faceHistory()` — Get the transformation history for a specific face.
 
 ```ts
-interface VariableSweepSection {
-  /** Parameter along the spine (0 = start, 1 = end). */
-  t: number;
-  /** Cross-section profile at this station. */
-  profile: Sketch;
-}
+faceHistory(name: string): FaceTransformationHistory
 ```
 
-</details>
+**Edge Topology**
 
-<details><summary><code>VariableSweepOptions</code></summary>
+#### `edge()` — Get a named topology edge. Only available on shapes with tracked topology (from box/cylinder/extrude).
 
 ```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;
-}
+edge(name: string): EdgeRef
 ```
 
-</details>
-
-#### `loadFont()`
+#### `edgeNames()` — List named topology edge names. Returns empty array if shape has no tracked topology.
 
 ```ts
-loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype$1.Font
+edgeNames(): string[]
 ```
 
-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)
+#### `edgesOf()` — Return all boundary edges of a named face.
+
+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.
+
+```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'))
 
-#### `hermiteTransition()`
+// 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 })
+```
 
 ```ts
-hermiteTransition(a: EdgeEndpoint, b: EdgeEndpoint): HermiteCurve3D
+edgesOf(faceLabel: string, options?: EdgesOfOptions): EdgeSegment[]
 ```
 
-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
+#### `edgesBetween()` — Return edges shared between two named faces.
+
+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."
 
-<details><summary><code>EdgeEndpoint</code></summary>
+The second argument can be a single face name or an array (edges between A and any of B1, B2, ...).
+
+```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'])
+```
 
 ```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;
-}
+edgesBetween(faceA: string, faceB: string | string[]): EdgeSegment[]
 ```
 
-</details>
+**Transforms**
 
-#### `hermiteTransitionG2()`
+#### `translate()` — Move the shape relative to its current position. All transforms are immutable and return new shapes.
 
 ```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
+translate(x: number, y: number, z: number): Shape
 ```
 
-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.
+#### `translatePolar()` — Translate using polar coordinates (radius + angle in degrees). Eliminates manual `r * Math.cos(angle * PI/180)` calculations.
 
-<details><summary><code>QuinticHermiteCurveEndpoint</code></summary>
+Example: `shape.translatePolar(50, 30)` moves 50mm at 30 degrees from +X.
 
 ```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;
-}
+translatePolar(radius: number, angleDeg: number, z?: number): Shape
 ```
 
-</details>
+#### `moveTo()` — Position the shape so its bounding box min corner is at the given global coordinate.
 
-#### `circularLayout()`
+```ts
+moveTo(x: number, y: number, z: number): Shape
+```
+
+#### `moveToLocal()` — Position the shape relative to another shape's local coordinate system (bounding box min corner).
 
 ```ts
-circularLayout(count: number, radius: number, options?: CircularLayoutOptions): LayoutPoint[]
+moveToLocal(target: Shape | { toShape(): Shape; }, x: number, y: number, z: number): Shape
 ```
 
-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)); } ```
+#### `rotate()` — Rotate around an arbitrary axis through the origin.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape
+```
 
-<details><summary><code>CircularLayoutOptions</code></summary>
+#### `rotateX()` — Rotate around the X axis by the given angle in degrees.
 
 ```ts
-interface CircularLayoutOptions {
-  /** Angle of the first element in degrees (default: 0 = +X axis). */
-  startDeg?: number;
-  /** Center X coordinate (default: 0). */
-  centerX?: number;
-  /** Center Y coordinate (default: 0). */
-  centerY?: number;
-}
+rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape
 ```
 
-</details>
+#### `rotateY()` — Rotate around the Y axis by the given angle in degrees.
+
+```ts
+rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape
+```
 
-<details><summary><code>LayoutPoint</code></summary>
+#### `rotateZ()` — Rotate around the Z axis by the given angle in degrees.
 
 ```ts
-interface LayoutPoint {
-  x: number;
-  y: number;
-}
+rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Shape
 ```
 
-</details>
+#### `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.
 
-#### `polygonVertices()`
+```ts
+rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: RotationPointLike, targetPoint: RotationPointLike, options?: RotateAroundToOptions): Shape
+```
+
+#### `transform()` — Apply a 4x4 affine transform matrix (column-major) or a Transform object.
 
 ```ts
-polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
+transform(m: Mat4 | Transform): Shape
 ```
 
-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); ```
+#### `scale()` — Scale the shape uniformly or per-axis from the shape's bounding box center. Accepts a single number or [x, y, z] array.
+
+```ts
+scale(v: number | [ number, number, number ]): Shape
+```
 
-<details><summary><code>PolygonVerticesOptions</code></summary>
+#### `scaleAround()` — Scale the shape uniformly or per-axis from an explicit pivot point.
 
 ```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;
-}
+scaleAround(pivot: [ number, number, number ], v: number | [ number, number, number ]): Shape
 ```
 
-</details>
+#### `mirror()` — Mirror across a plane through the shape's bounding box center, defined by its normal vector.
+
+```ts
+mirror(normal: [ number, number, number ]): Shape
+```
 
-#### `routePerimeter()`
+#### `mirrorThrough()` — Mirror across a plane through an explicit point, defined by its normal vector.
 
 ```ts
-routePerimeter(steps: PerimeterStep[]): Sketch
+mirrorThrough(point: [ number, number, number ], normal: [ number, number, number ]): Shape
 ```
 
-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 }, ]) ```
+#### `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. The shape's origin stays at [0,0,0] — translate after pointAlong to position it.
 
-#### `linearPattern2d()`
+Example: cylinder(40, 5).pointAlong([1, 0, 0]) — lays cylinder along X, starting at origin
 
 ```ts
-linearPattern2d(sketch: Sketch, count: number, dx: number, dy?: number): Sketch
+pointAlong(direction: [ number, number, number ]): Shape
 ```
 
-Repeat a sketch in a linear pattern
+**Booleans & Cutting**
 
-#### `circularPattern2d()`
+#### `add()` — Union this shape with others (additive boolean). Method form of union().
 
 ```ts
-circularPattern2d(sketch: Sketch, count: number, centerXOrOpts?: number | { centerX?: number; centerY?: number; startDeg?: number; }, centerY?: number): Sketch
+add(...others: ShapeOperandInput[]): Shape
 ```
 
-Repeat a sketch in a circular pattern around a center point
-
-#### `arcSlot()`
+#### `subtract()` — Subtract other shapes from this one. Method form of difference().
 
 ```ts
-arcSlot(pitchRadius: number, sweepDeg: number, thickness: number): Sketch
+subtract(...others: ShapeOperandInput[]): Shape
 ```
 
-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 ```
+#### `intersect()` — Keep only the overlap with other shapes. Method form of intersection().
+
+```ts
+intersect(...others: ShapeOperandInput[]): Shape
+```
 
-#### `surfacePatch()`
+#### `split()` — Split into [inside, outside] by another shape.
 
 ```ts
-surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
+split(cutter: Shape | { toShape(): Shape; }): [ Shape, Shape ]
 ```
 
-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.
+#### `splitByPlane()` — Split by infinite plane. Returns [positive-side, negative-side].
+
+```ts
+splitByPlane(normal: [ number, number, number ], originOffset?: number): [ Shape, Shape ]
+```
 
-<details><summary><code>SurfacePatchOptions</code></summary>
+#### `trimByPlane()` — Keep the positive side of the plane and discard the opposite side.
 
 ```ts
-interface SurfacePatchOptions {
-  /** Number of samples along each direction. Default 24. */
-  resolution?: number;
-  /** Thickness of the generated solid. Default 0.5. */
-  thickness?: number;
-}
+trimByPlane(normal: [ number, number, number ], originOffset?: number): Shape
 ```
 
-</details>
+**Features**
 
-#### `transitionCurve()`
+#### `shell()` — 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).
 
 ```ts
-transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
+shell(thickness: number, opts?: { openFaces?: string[]; }): Shape
 ```
 
-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 }, ); ```
+#### `pocket()` — Cut a pocket (cavity) into this solid through the named face.
 
-<details><summary><code>TransitionEdge</code></summary>
+```js
+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 })
+```
 
 ```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;
-}
+pocket(face: FaceSelector, depth: number, opts?: PocketOptions): Shape
 ```
 
-</details>
+#### `boss()` — Add a boss (protrusion) from the named face.
 
-<details><summary><code>TransitionCurveOptions</code></summary>
+```js
+box(100, 100, 20).boss('top', 5)
+box(100, 100, 20).boss('top', 10, { scale: 0.6 })
+```
 
 ```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;
-}
+boss(face: FaceSelector, height: number, opts?: BossOptions): Shape
 ```
 
-</details>
+#### `hole()` — Drill a hole into this solid at a face.
 
-#### `transitionSurface()`
+```js
+box(50, 50, 20).hole('top', { diameter: 8, depth: 10 })
+box(50, 50, 20).hole('top', { diameter: 6, counterbore: { diameter: 12, depth: 3 } })
+```
 
 ```ts
-transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+hole(faceOrRef: SketchFaceTarget | FaceRef, opts: ShapeHoleOptions): Shape
 ```
 
-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 }, ); ```
+#### `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.
 
-<details><summary><code>TransitionSurfaceOptions</code> extends TransitionCurveOptions</summary>
+```js
+const profile = circle2d(10).onFace(body, 'top');
+body.cutout(profile, { depth: 5 })
+```
 
 ```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;
-}
+cutout(sketch: Sketch, opts?: ShapeCutoutOptions): Shape
 ```
 
-</details>
+**Placement**
 
-#### `transitionCurveFromPoints()`
+#### `placeReference()` — Translate the shape so the given anchor or reference lands on the target coordinate.
 
-```ts
-transitionCurveFromPoints(startPoint: Vec3$7, startTangent: Vec3$7, endPoint: Vec3$7, endTangent: Vec3$7, options?: TransitionCurveOptions): HermiteCurve3D
-```
+Accepts any built-in anchor name (`'bottom'`, `'center'`, `'top-front-left'`, etc.) or a custom placement reference attached via `withReferences()`.
 
-Convenience: create a transition curve from raw coordinate data. Useful when you have endpoints and directions as plain arrays without constructing TransitionEdge objects.
+```javascript
+// Ground a shape — put its bottom face center at Z = 0
+shape.placeReference('bottom', [0, 0, 0])
 
-#### `connectEdges()`
+// Center at the world origin
+shape.placeReference('center', [0, 0, 0])
+
+// Align left edge to X = 10
+shape.placeReference('left', [10, 0, 0])
+```
 
 ```ts
-connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
+placeReference(ref: PlacementAnchorLike, target: [ number, number, number ], offset?: [ number, number, number ]): Shape
 ```
 
-<details><summary><code>EdgeSegment</code></summary>
+#### `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.
 
 ```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;
-}
+attachTo(target: ShapeAnchorTarget, targetAnchor: PlacementAnchorLike, selfAnchor?: PlacementAnchorLike, offset?: [ number, number, number ]): Shape
 ```
 
-</details>
+#### `onFace()` — Place this shape on a face of a parent shape.
 
+Think of it like sticking a label on a box surface:
 
-<details><summary><code>ConnectEdgesOptions</code> extends TransitionSurfaceOptions</summary>
+- `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)
 
 ```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;
-}
+onFace(parent: ShapeAnchorTarget, face: "front" | "back" | "left" | "right" | "top" | "bottom", opts?: { u?: number; v?: number; protrude?: number; }): Shape
 ```
 
-</details>
+#### `seatInto()` — 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');
 
-#### `spec()`
+// 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 });
+```
 
 ```ts
-spec(name: string, checkFn: (...args: any[]) => void): Spec
+seatInto(target: Shape, surface: string, options?: SeatIntoOptions): Shape
 ```
 
-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.
+#### `seatOver()` — Slide this shape until a target's labeled face is fully covered (inside this shape).
 
-<details><summary><code>Spec</code></summary>
+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');
+```
 
 ```ts
-interface Spec {
-  /** The display name of this spec */
-  name: string;
-}
+seatOver(target: Shape, targetSurface: string, options?: SeatIntoOptions): Shape
 ```
 
-</details>
+**Connectors**
 
-#### `faceProfile()`
+#### `withConnectors()` — Attach named connectors — attachment points that survive transforms and imports. Connectors can be bare (position + orientation) or typed (with connectorType/gender for compatibility matching).
 
 ```ts
-faceProfile(shape: Shape, face: FaceSelector): Sketch
+withConnectors(connectors: Record<string, ConnectorInput>): Shape
 ```
 
-#### `fingerJointProfile()`
+#### `connectorNames()` — List all connector names on this shape.
 
 ```ts
-fingerJointProfile(length: number, thickness: number, options?: FingerJointOptions): FingerJointResult
+connectorNames(): string[]
 ```
 
-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.
-
-<details><summary><code>FingerJointOptions</code></summary>
+#### `connectorsByType()` — Get all connectors of a given type.
 
 ```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";
-}
+connectorsByType(type: string): Array<{ name: string; port: PortDef; }>
 ```
 
-</details>
-
-<details><summary><code>FingerJointResult</code></summary>
+#### `connectorDistance()` — Distance between two connector origins on this shape.
 
 ```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;
-}
+connectorDistance(nameA: string, nameB: string): number
 ```
 
-</details>
-
-#### `tabSlotProfile()`
+#### `connectorMeasurements()` — Get measurements metadata from a connector.
 
 ```ts
-tabSlotProfile(length: number, thickness: number, options?: TabSlotOptions): TabSlotResult
+connectorMeasurements(name: string): Record<string, number | string>
 ```
 
-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.
+#### `matchTo()` — Position this shape by matching connectors to a target.
+
+Overloads:
 
-<details><summary><code>TabSlotOptions</code></summary>
+- Single pair: `matchTo(target, selfConn, targetConn, options?)`
+- Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)`
+- Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
 
 ```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;
-}
+matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): Shape
 ```
 
-</details>
+**References**
 
-<details><summary><code>TabSlotResult</code></summary>
+#### `withReferences()` — Attach named placement references that survive normal transforms and imports.
 
 ```ts
-interface TabSlotResult {
-  tabs: Sketch;
-  slots: Sketch;
-}
+withReferences(refs: PlacementReferenceInput): Shape
 ```
 
-</details>
-
-#### `livingHingeProfile()`
+#### `referenceNames()` — List named placement references carried by this shape.
 
 ```ts
-livingHingeProfile(length: number, width: number, options?: LivingHingeOptions): Sketch
+referenceNames(kind?: PlacementReferenceKind): string[]
 ```
 
-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.
-
-<details><summary><code>LivingHingeOptions</code></summary>
+#### `referencePoint()` — Resolve a named placement reference or built-in anchor to a 3D point.
 
 ```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;
-}
+referencePoint(ref: PlacementAnchorLike): [ number, number, number ]
 ```
 
-</details>
-
-#### `snapFitProfile()`
+#### `withPorts()` — Deprecated alias for `withConnectors()`.
 
 ```ts
-snapFitProfile(thickness: number, options?: SnapFitOptions): SnapFitResult
+withPorts(ports: Record<string, PortInput>): Shape
 ```
 
-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.
-
-<details><summary><code>SnapFitOptions</code></summary>
+#### `portNames()` — Deprecated alias for `connectorNames()`.
 
 ```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";
-}
+portNames(): string[]
 ```
 
-</details>
+**Measurement**
 
-<details><summary><code>SnapFitResult</code></summary>
+#### `boundingBox()` — Get the axis-aligned bounding box as { min: [x,y,z], max: [x,y,z] }.
 
 ```ts
-interface SnapFitResult {
-  tab: Sketch;
-  slot: Sketch;
-}
+boundingBox(): ShapeRuntimeBounds
 ```
 
-</details>
-
-#### `kerfCompensateOutline()`
+#### `volume()` — Volume in mm cubed.
 
 ```ts
-kerfCompensateOutline(sketch: Sketch, kerf: number): Sketch
+volume(): number
 ```
 
-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.
+#### `surfaceArea()` — Surface area in mm squared.
 
-#### `kerfCompensateTabs()`
+```ts
+surfaceArea(): number
+```
+
+#### `isEmpty()` — True if the shape contains no geometry.
 
 ```ts
-kerfCompensateTabs(sketch: Sketch, kerf: number): Sketch
+isEmpty(): boolean
 ```
 
-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.
+#### `numBodies()` — Number of disconnected solid bodies in this shape.
+
+```ts
+numBodies(): number
+```
 
-#### `kerfCompensateSlots()`
+#### `numTri()` — Triangle count of the mesh representation.
 
 ```ts
-kerfCompensateSlots(sketch: Sketch, kerf: number): Sketch
+numTri(): number
 ```
 
-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.
+**Other**
 
-#### `kerfCompensatePart()`
+#### `clone()` — Return a new Shape wrapper for explicit duplication in scripts.
 
 ```ts
-kerfCompensatePart(baseProfile: Sketch, joints: PartJoints, kerf: number): Sketch
+clone(): Shape
 ```
 
-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.
+#### `geometryInfo()` — Inspect which backend/representation produced this solid.
 
-<details><summary><code>PartJoints</code></summary>
+```ts
+geometryInfo(): GeometryInfo
+```
+
+#### `getMesh()` — Extract triangle mesh for Three.js rendering
 
 ```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[];
-}
+getMesh(): ShapeRuntimeMesh
 ```
 
-</details>
+#### `slice()` — Slice the runtime solid by a plane normal to local Z at the given offset.
+
+```ts
+slice(offset?: number): any
+```
 
-#### `lookupKerf()`
+#### `project()` — Orthographically project the runtime solid onto the local XY plane.
 
 ```ts
-lookupKerf(material: string, thickness: number, laserType?: string): number | undefined
+project(): any
 ```
 
-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.
+### `Transform`
 
-#### `flatPanel()`
+#### `identity()` — Return the identity transform.
 
 ```ts
-flatPanel(name: string, width: number, height: number, thickness: number, options?: FlatPartOptions): FlatPart
+static identity(): Transform
 ```
 
-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.
-
-<details><summary><code>FlatPartOptions</code></summary>
+#### `from()` — Wrap an existing `Transform` or raw 4x4 matrix as a `Transform`.
 
 ```ts
-interface FlatPartOptions {
-  material?: string;
-  qty?: number;
-  color?: string;
-}
+static from(input: TransformInput): Transform
 ```
 
-</details>
+#### `translation()` — Create a translation transform.
+
+```ts
+static translation(x: number, y: number, z: number): Transform
+```
 
-#### `flatPart()`
+#### `scale()` — Create a uniform or per-axis scale transform.
 
 ```ts
-flatPart(name: string, profile: Sketch, thickness: number, edges?: Record<string, { start: [ number, number ]; end: [ number, number ]; }>, options?: FlatPartOptions): FlatPart
+static scale(v: number | Vec3): Transform
 ```
 
-Create a flat part from an arbitrary profile with user-named edges. Edge normals are computed automatically (perpendicular to direction, rotated 90deg CW).
+#### `rotationAxis()` — Create a rotation around an arbitrary axis, optionally about a pivot.
 
-#### `fingerJoint()`
+```ts
+static rotationAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `rotateAroundTo()` — Solve the rotation needed to move one point onto a target line or plane.
 
 ```ts
-fingerJoint(partA: FlatPart, edgeNameA: string, partB: FlatPart, edgeNameB: string, options?: FingerJointOptions & { foldAngle?: number; }): void
+static rotateAroundTo(axis: Vec3, pivot: Vec3, movingPoint: Vec3, targetPoint: Vec3, options?: RotateAroundToOptions): Transform
 ```
 
-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.
+#### `mul()` — Compose transforms in chain order: `a.mul(b)` applies `a`, then `b`.
+
+```ts
+mul(other: TransformInput): Transform
+```
 
-#### `tabSlot()`
+#### `translate()` — Translate after the current transform.
 
 ```ts
-tabSlot(partA: FlatPart, edgeNameA: string, partB: FlatPart, edgeNameB: string, options?: TabSlotOptions & { foldAngle?: number; }): void
+translate(x: number, y: number, z: number): Transform
 ```
 
-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.
+#### `rotateAxis()` — Rotate after the current transform.
 
-#### `assemblyPreview()`
+```ts
+rotateAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `inverse()` — Return the inverse transform.
 
 ```ts
-assemblyPreview(parts: FlatPart[], joints: JointRecord[], options?: AssemblyPreviewOptions): AssemblyPreviewResult
+inverse(): Transform
 ```
 
-<details><summary><code>JointRecord</code></summary>
+#### [`point()`](/docs/sketch#point) — Transform a point using homogeneous coordinates.
 
 ```ts
-interface JointRecord {
-  type: "finger" | "tabSlot" | "snapFit";
-  partA: string;
-  partB: string;
-  edgeA: string;
-  edgeB: string;
-  /** Fold angle in degrees. Default: 90. */
-  foldAngle: number;
-}
+point(p: Vec3): Vec3
 ```
 
-</details>
+#### `vector()` — Transform a direction vector without translation.
+
+```ts
+vector(v: Vec3): Vec3
+```
 
-<details><summary><code>AssemblyPreviewOptions</code></summary>
+#### `toArray()` — Return the transform as a raw 4x4 matrix array.
 
 ```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;
-}
+toArray(): Mat4
 ```
 
-</details>
+### `ShapeGroup`
 
-<details><summary><code>AssemblyPreviewResult</code></summary>
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `children` | `GroupChild[]` | — |
+| `childNames` | `Array<string | undefined>` | — |
+
+**Children**
+
+#### `child()` — Return the named child by name. Throws if not found. Useful when importing a multipart group and working on components individually.
 
 ```ts
-interface AssemblyPreviewResult {
-  /** All part shapes grouped for display. */
-  shapes: ShapeGroup;
-  /** Individual transformed shapes keyed by part name. */
-  partShapes: Map<string, Shape>;
-}
+child(name: string): GroupChild
 ```
 
-</details>
-
-#### `assemblyInstructions()`
+#### `childName()` — Return the optional name of the child at `index`.
 
 ```ts
-assemblyInstructions(parts: FlatPart[], joints: JointRecord[], options?: AssemblyInstructionsOptions): AssemblyInstructionsResult
+childName(index: number): string | undefined
 ```
 
-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)
+**Transforms**
 
-<details><summary><code>AssemblyInstructionsOptions</code></summary>
+#### `translate()` — Move the entire group by (x, y, z). All children move together as a unit.
 
 ```ts
-interface AssemblyInstructionsOptions {
-  /** Part to start from. Default: part with most joint connections. */
-  rootPart?: string;
-}
+translate(x: number, y: number, z: number): ShapeGroup
 ```
 
-</details>
-
-<details><summary><code>AssemblyInstructionsResult</code></summary>
+#### `moveTo()` — Move the group so its bounding-box min corner lands at the given coordinate.
 
 ```ts
-interface AssemblyInstructionsResult {
-  steps: AssemblyStep[];
-  /** Total number of parts in the assembly. */
-  totalParts: number;
-  /** Parts not connected to the joint graph (orphans). */
-  orphanParts: string[];
-}
+moveTo(x: number, y: number, z: number): ShapeGroup
 ```
 
-</details>
-
-<details><summary><code>AssemblyStep</code></summary>
-
-```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[];
-}
+#### `moveToLocal()` — Move the group relative to another part's bounding-box min corner.
+
+```ts
+moveToLocal(target: Shape | ShapeGroup, x: number, y: number, z: number): ShapeGroup
 ```
 
-</details>
+#### `rotate()` — Rotate the group around an arbitrary axis through the origin.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
 
-#### `formatInstructions()`
+#### `rotateX()` — Rotate the group around the X axis.
 
 ```ts
-formatInstructions(result: AssemblyInstructionsResult): string
+rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
 ```
 
-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.
+#### `rotateY()` — Rotate the group around the Y axis.
+
+```ts
+rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
 
-#### `laserKit()`
+#### `rotateZ()` — Rotate the group around the Z axis.
 
 ```ts
-laserKit(options?: LaserKitOptions): LaserKit
+rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
 ```
 
-Top-level factory for creating a LaserKit container.
+#### `rotateAroundAxis()` — Rotate around an arbitrary axis, optionally through a pivot point.
+
+```ts
+rotateAroundAxis(axis: [ number, number, number ], angleDeg: number, pivot?: [ number, number, number ]): ShapeGroup
+```
 
-<details><summary><code>LaserKitOptions</code></summary>
+#### `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.
 
 ```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;
-}
+rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: Anchor3D | [ number, number, number ], targetPoint: Anchor3D | [ number, number, number ], options?: RotateAroundToOptions): ShapeGroup
 ```
 
-</details>
+#### `pointAlong()` — Reorient the group so its local Z axis points along `direction`.
+
+```ts
+pointAlong(direction: [ number, number, number ]): ShapeGroup
+```
 
-#### `torus()`
+#### `transform()` — Apply a 4x4 transform matrix or `Transform` to all 3D children.
 
 ```ts
-torus$1(majorRadius: number, minorRadius: number, segments?: number): Shape
+transform(m: Mat4 | Transform): ShapeGroup
 ```
 
-Create a torus (donut shape) centered at the origin, lying in the XY plane. @concept primitive
+#### `scale()` — Scale uniformly or per-axis from the group's bounding-box center.
 
-#### `importMesh()`
+```ts
+scale(v: number | [ number, number, number ]): ShapeGroup
+```
+
+#### `scaleAround()` — Scale uniformly or per-axis from an explicit pivot point.
 
 ```ts
-importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
+scaleAround(pivot: [ number, number, number ], v: number | [ number, number, number ]): ShapeGroup
 ```
 
-Import an external mesh file (STL, OBJ, 3MF) as a Shape. @concept import
+#### `mirror()` — Mirror across a plane through the group's bounding-box center.
 
-#### `highlight()`
+```ts
+mirror(normal: [ number, number, number ]): ShapeGroup
+```
+
+#### `mirrorThrough()` — Mirror across a plane through an explicit point.
 
 ```ts
-highlight(entityId: string, opts?: HighlightOptions): void
+mirrorThrough(point: [ number, number, number ], normal: [ number, number, number ]): ShapeGroup
 ```
 
-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
+**Placement**
+
+#### `placeReference()` — Translate the group so the given anchor or reference lands on the target coordinate.
 
-<details><summary><code>HighlightOptions</code></summary>
+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]);
+```
 
 ```ts
-interface HighlightOptions {
-  color?: string;
-  label?: string;
-  pulse?: boolean;
-  /** Size hint for points (radius in mm) or planes (disc radius in mm). */
-  size?: number;
-}
+placeReference(ref: PlacementAnchorLike, target: [ number, number, number ], offset?: [ number, number, number ]): ShapeGroup
 ```
 
-</details>
+#### `attachTo()` — Attach this group to a face or anchor on another part.
 
-#### `highlight()`
+`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.
 
 ```ts
-highlight(point: [ number, number, number ], opts?: HighlightOptions): void
+attachTo(target: Shape | ShapeGroup, targetAnchor: Anchor3D | string, selfAnchor?: Anchor3D, offset?: [ number, number, number ]): ShapeGroup
 ```
 
-#### `highlight()`
+#### `onFace()` — Place this group on a face of a parent shape. See Shape.onFace() for full documentation.
 
 ```ts
-highlight(edge: [ [ number, number, number ], [ number, number, number ] ], opts?: HighlightOptions): void
+onFace(parent: Shape | ShapeGroup, face: "front" | "back" | "left" | "right" | "top" | "bottom", opts?: { u?: number; v?: number; protrude?: number; }): ShapeGroup
 ```
 
-#### `highlight()`
+**Connectors**
+
+#### `withConnectors()` — Attach named connectors — attachment points that survive transforms. Connectors can be bare (position + orientation) or typed (with connectorType/gender for compatibility matching).
 
 ```ts
-highlight(plane: { normal: [ number, number, number ]; offset: number; }, opts?: HighlightOptions): void
+withConnectors(connectors: Record<string, ConnectorInput>): ShapeGroup
 ```
 
-#### `highlight()`
+#### `connectorNames()` — List all connector names, including "ChildName.connectorName" from named children.
 
 ```ts
-highlight(plane: { normal: [ number, number, number ]; point: [ number, number, number ]; }, opts?: HighlightOptions): void
+connectorNames(): string[]
 ```
 
-#### `highlight()`
+#### `connectorsByType()` — Get all connectors of a given type, including from named children.
 
 ```ts
-highlight(shape: Shape, opts?: HighlightOptions): void
+connectorsByType(type: string): Array<{ name: string; port: PortDef; }>
 ```
 
-#### `highlight()`
+#### `connectorDistance()` — Distance between two connector origins on this group (supports dotted child paths).
 
 ```ts
-highlight(face: FaceRef, opts?: HighlightOptions): void
+connectorDistance(nameA: string, nameB: string): number
 ```
 
-<details><summary><code>FaceRef</code></summary>
+#### `connectorMeasurements()` — Get measurements metadata from a connector (supports dotted child paths).
 
 ```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;
-}
+connectorMeasurements(name: string): Record<string, number | string>
 ```
 
-</details>
+#### `matchTo()` — Position this group by matching connectors to a target. Connector names support dotted paths into named children: "ChildName.connectorName".
 
-<details><summary><code>FaceDescendantMetadata</code></summary>
+Overloads:
+
+- Single pair: `matchTo(target, selfConn, targetConn, options?)`
+- Dictionary (same target): `matchTo(target, { selfConn: targetConn, ... }, options?)`
+- Multi-target: `matchTo([ [target1, selfConn1, targetConn1], ... ], options?)`
 
 ```ts
-interface FaceDescendantMetadata {
-  kind: "single" | "face-set";
-  semantic: FaceDescendantSemantic;
-  memberCount: number;
-  memberNames: string[];
-  coplanar: boolean;
-}
+matchTo(targetOrPairs: Shape | ShapeGroup | Array<[ Shape | ShapeGroup, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): ShapeGroup
 ```
 
-</details>
+**References**
+
+#### `withReferences()` — Attach named placement references to this group. References survive normal transforms (translate/rotate/scale/mirror/transform).
 
-#### `highlight()`
+```javascript
+const bracket = group(
+  { name: 'Left', shape: leftShape },
+  { name: 'Right', shape: rightShape },
+).withReferences({
+  points: { mountCenter: [0, 0, 0] },
+});
+```
 
 ```ts
-highlight(edge: EdgeRef, opts?: HighlightOptions): void
+withReferences(refs: PlacementReferenceInput): ShapeGroup
 ```
 
-<details><summary><code>EdgeRef</code></summary>
+#### `referenceNames()` — List named placement references carried by this group.
 
 ```ts
-interface EdgeRef {
-  name: EdgeName;
-  /** Compiler-owned edge query when available. */
-  query?: EdgeQueryRef;
-}
+referenceNames(kind?: PlacementReferenceKind): string[]
 ```
 
-</details>
+#### `referencePoint()` — Resolve a named placement reference or built-in Anchor3D to a 3D point. Named refs take priority over built-in anchors.
 
----
+```ts
+referencePoint(ref: PlacementAnchorLike): [ number, number, number ]
+```
 
-## Classes
+#### `withPorts()` — Backward-compatible alias for `withConnectors()`.
 
-### `Shape`
+```ts
+withPorts(ports: Record<string, PortInput>): ShapeGroup
+```
 
-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).
+#### `portNames()` — Backward-compatible alias for `connectorNames()`.
 
-**Properties:**
+```ts
+portNames(): string[]
+```
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `materialProps` | `ShapeMaterialProps | undefined` | — |
+**Other**
 
-**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 })
+#### `clone()` — Return a deep-cloned ShapeGroup tree (refs copied).
 
-### `Transform`
+```ts
+clone(): ShapeGroup
+```
 
-**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
+#### `boundingBox()` — Return the combined 3D bounding box of all children.
 
-### `ShapeGroup`
+```ts
+boundingBox(): { min: [ number, number, number ]; max: [ number, number, number ]; }
+```
 
-**Properties:**
+#### `color()` — Return a copy of the group with the given display color applied to each child.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `children` | `GroupChild[]` | — |
-| `childNames` | `Array<string | undefined>` | — |
+```ts
+color(hex: string): ShapeGroup
+```
 
-**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`
+### `SurfacePattern`
 
 **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.
+| `body` | `string` | Function body: receives (u, v) in surface mm, returns height displacement. |
+| `constants` | `Record<string, number>` | Named constants injected into the function. |
 
 ---
 
@@ -1675,49 +1629,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, b: ShapeLike, tolerance?: number): void` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
+- `notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: number): void` — Check that two shapes do not collide (minGap > 0).
+- `minClearance(label: string, a: ShapeLike, b: ShapeLike, 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, message?: string): void` — Check that a shape is empty.
+- `notEmpty(label: string, shape: ShapeLike, message?: string): void` — Check that a shape is NOT empty.
+- `volumeApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void` — Check that a shape's volume is approximately equal to expected (mm³).
+- `areaApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void` — Check that a shape's surface area is approximately equal to expected (mm²).
+- `boundingBoxSize(label: string, shape: ShapeLike, 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.