forgecad 0.9.14 → 0.9.16

package/dist-skill/CONTEXT.md

@@ -123,7 +123,32 @@ const bomHelpers = require("./bom.js");
 bomHelpers.addFasteners(...);
 ```
 
-Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class Shape {}` collide with the injected runtime names. If you need a local helper, choose a project-specific name like `projectBom`, `sceneConfig`, or `makeShape`.
+Top-level lexical declarations such as `const bom = ...`, `let slot = ...`, `const lib = ...`, `const joint = ...`, or `class Shape {}` collide with the injected runtime names. This is checked when the script runs, so agents should treat these names as reserved before executing the model.
+
+Use project-specific local names instead:
+
+```javascript
+// BAD — `lib` and `slot` are injected runtime names.
+const lib = require("./wheel-lib.js");
+const slot = rect(20, 5);
+
+// GOOD — local names describe the project role.
+const wheelLib = require("./wheel-lib.js");
+const axleSlotSketch = rect(20, 5);
+```
+
+If a helper module exports a name that matches a ForgeCAD runtime name, keep the module under one local object name or rename during destructuring:
+
+```javascript
+// GOOD — no top-level `slot` declaration.
+const wheelHelpers = require("./wheel-helpers.js");
+const axleSlot = wheelHelpers.slot(...);
+
+// GOOD — imported helper is renamed.
+const { slot: makeAxleSlot } = require("./wheel-helpers.js");
+```
+
+The complete collision-reserved list is generated from the runtime source in [Runtime Names](../../generated/runtime-names.md). Check that list before using natural local names such as `lib`, `slot`, `joint`, `group`, `path`, `text2d`, `scene`, or `Shape`.
 
 ## Execution Model
 
@@ -162,6 +187,44 @@ return {
 };
 ```
 
+### Forge-Aware Builder Modules
+
+A `.forge.js` file can also return builder functions. Those functions keep access to
+the ForgeCAD runtime names from their defining file, so this is the supported way
+to share sketch, profile, shape, or assembly builders that need APIs such as
+`path()`, `circle2d()`, `box()`, or `assembly()`.
+
+This pattern works well when a file should be both directly inspectable and
+importable: render the flat profiles or part preview when the file is opened on
+its own, and export builders under a named object for the assembly file.
+
+```javascript
+// profiles.forge.js - inspectable on its own, reusable through require()
+function wheelProfile() {
+  return circle2d(40).subtract(circle2d(18));
+}
+
+return {
+  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
+  make: { wheelProfile },
+};
+```
+
+```javascript
+// main.forge.js - reuses the exact inspected profile
+const profiles = require('./profiles.forge.js');
+const wheel = profiles.make.wheelProfile().extrude(8);
+return wheel;
+```
+
+Keep builder modules pure over top-level constants, top-level `param()` values,
+or explicit function arguments. Do not declare new `param()` values inside an
+exported builder if callers need `require('./profiles.forge.js', { Width: 80 })`
+overrides: import overrides are validated while the module loads, before any
+exported builder is called. For plain constants, tables, math helpers, and
+formatting code that does not construct ForgeCAD geometry, use `.js` helper
+modules instead.
+
 Named return objects and named `group(...)` children can include `tags`. Tags are viewport metadata: they do not affect geometry, exports, face labels, or BOM rows, but the command palette can hide, show only, or focus every object with a selected tag.
 
 ```javascript
@@ -214,6 +277,46 @@ For organic shapes, smooth blending, TPMS lattices, and surface deformations. Re
 
 ---
 
+<!-- generated/runtime-names.md -->
+
+# Runtime Names
+
+Generated by `scripts/gen-api-docs.mjs` from `src/forge/script-runtime/runScript.ts`. Do not edit by hand.
+
+ForgeCAD injects API functions, classes, namespaces, and sandbox guard names into every `.forge.js` script. Top-level lexical declarations using these names collide with the injected runtime bindings when the script runs.
+
+Agents should avoid declaring these names with top-level `const`, `let`, destructured imports, or `class` declarations. Use project-specific local names such as `wheelLib`, `axleSlotSketch`, `driveJointConfig`, or `labelTextSketch` instead.
+
+These collision-reserved names are case-sensitive:
+
+```text
+activateBackend, Analysis, arcSlot, assembly, Assembly, assemblyInstructions, assemblyPreview, Blend
+bom, bomToCsv, boolParam, box, cameraTrajectory, Carrier, chamfer, chamferTrackedEdge
+choiceParam, circle, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d, coalesceEdges
+combine, COMMON_KERFS, compareWith, composeChain, connector, console, constrainedSketch, Constraint
+Counterbore, Curve, Curve3D, cutPlane, cylinder, degrees, difference, difference2d
+dim, dimLine, draft, ellipse, explodeView, faceProfile, fillet, filletCorners
+filletTrackedEdge, fingerJoint, flatPanel, flatPart, formatInstructions, Function, gcode, GCodeBuilder
+getActiveBackend, global, globalThis, group, highlight, Import, ImportedAssembly, importMesh
+importStep, importSvgSketch, initKernel, intersection, intersection2d, intersectWithPlane, joint, jointsView
+laserKit, lib, line, Line2D, linearPattern, linearPattern2d, listParam, loadFont
+loft, Loft, lookupKerf, mirrorCopy, mock, ngon, NurbsCurve3D, nurbsSurface
+NurbsSurface, offsetSolid, param, Param, path, point, Point2D, Points
+polygon, polygonVertices, port, Product, ProductHandleBuilder, ProductHandleFeature, ProductPanelBuilder, ProductRibbonBuilder
+ProductSkin, ProductSkinBuilder, ProductSpoutBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask
+radians, rect, Rectangle2D, Ribs, robotExport, roundedRect, Route3D, scene
+Sculpt, sdf, SdfShape, selectEdge, selectEdges, self, setActiveBackend, setImmediate
+setInterval, setTimeout, Shape, ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch
+sketchToDxf, sketchToSvg, slot, Slot, SolvedAssembly, spec, sphere, spline2d
+star, stroke, Surface, SurfaceBody, SurfaceMembers, surfacePatch, sweep, tabSlot
+text2d, textWidth, torus, toShape, Transform, union, union2d, variableSweep
+verify, viewConfig, Viewport, window, Wood
+```
+
+`showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.
+
+---
+
 <!-- generated/core.md -->
 
 # Core API
@@ -238,6 +341,8 @@ For organic shapes, smooth blending, TPMS lattices, and surface deformations. Re
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
+- [HermiteCurve3D](#hermitecurve3d)
+- [QuinticHermiteCurve3D](#quintichermitecurve3d)
 - [ShapeRef](#shaperef)
 - [ANCHOR3D_NAMES](#anchor3d-names)
 - [verify](#verify)
@@ -577,9 +682,9 @@ selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
 | `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`). |
+| `atZ?` | `number` | Shorthand: edge midpoint Z is approximately this value within `tolerance`. |
+| `tolerance?` | `number` | Position tolerance for approximate matches. Used by `atZ` and `near`. Default: `1.0`. |
+| `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 }`
 
@@ -631,7 +736,16 @@ coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
 
 #### `require()` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
 
-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.
+When importing a `.forge.js` file, most return values are passed through exactly as the script returns them. Assembly returns have one extra composition rule: an unsolved [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries, while a returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly). If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
+
+**Assembly return contract**
+
+| `.forge.js` return value | `require()` result |
+|---|---|
+| `Assembly` | `ImportedAssembly` |
+| `SolvedAssembly` | `SolvedAssembly` |
+
+[`ImportedAssembly`](/docs/assembly#importedassembly) exposes default-pose helpers such as `getPart()`, `collisionReport()`, and `minClearance()`. Use `solve(state)` first when inspecting a non-default pose.
 
 **Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
 
@@ -662,6 +776,26 @@ mount.bolts.pos  // access the metadata
 mount.shape       // access the geometry
 ```
 
+**Forge-aware builder module pattern** — use `.forge.js` modules for reusable sketch, profile, shape, or assembly builders that need ForgeCAD runtime APIs:
+
+```js
+// profiles.forge.js — inspectable on its own, reusable through require()
+function wheelProfile() {
+  return circle2d(40).subtract(circle2d(18));
+}
+
+return {
+  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
+  make: { wheelProfile },
+};
+
+// main.forge.js
+const profiles = require('./profiles.forge.js');
+const wheel = profiles.make.wheelProfile().extrude(8);
+```
+
+Keep exported builders pure over top-level constants, top-level `param()` values, or explicit function arguments. Do not declare new `param()` values inside an exported builder if callers need `require('./profiles.forge.js', { Width: 80 })` overrides: import overrides are validated while the module loads, before any exported builder is called. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
+
 ```ts
 require(path: string, paramOverrides?: Record<string, number | string>): any
 ```
@@ -690,10 +824,18 @@ importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
 | `simplify?` | `number` | Simplification tolerance for final sketch cleanup. |
 | `invertY?` | `boolean` | Flip SVG Y-down coordinates to CAD Y-up. Enabled by default. |
 
-#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF) as a Shape.
+#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF).
+
+By default, 3MF build items are flattened into one Shape for compatibility. Use `separateObjects: true` to import 3MF build items/resource objects as a named ShapeGroup whose children are targetable by `forgecad ls`. Use `object` to import one item by the stable ref/name reported by `forgecad run`.
+
+```js
+const all = importMesh("./assembly.3mf", { separateObjects: true });
+const pin = all.child("Pin #001");
+const plate = importMesh("./assembly.3mf", { object: "3mf:build:001:object:7" });
+```
 
 ```ts
-importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
+importMesh(fileName: string, options?: { scale?: number; center?: boolean; object?: string; separateObjects?: boolean; }): Shape | ShapeGroup
 ```
 
 #### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend.
@@ -1166,6 +1308,25 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 material(props: ShapeMaterialProps): Shape
 ```
 
+**`ShapeMaterialProps`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
+| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
+| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
+| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
+| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
+| `wireframe?` | `boolean` | Render as wireframe. Default: false |
+| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
+| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
+| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
+| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
+| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
+| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
+| `specularColor?` | `string` | Specular highlight tint. |
+| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+
 **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.
@@ -1286,6 +1447,15 @@ body.edgesOf('top', { concave: true })
 edgesOf(faceLabel: string, options?: EdgesOfOptions): EdgeSegment[]
 ```
 
+**`EdgesOfOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `exclude?` | `string \| string[]` | Exclude edges shared with these named faces. |
+| `convex?` | `boolean` | Additional geometric filter: only convex edges. |
+| `concave?` | `boolean` | Additional geometric filter: only concave edges. |
+| `minLength?` | `number` | Minimum edge length filter. |
+
 #### `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."
@@ -1367,6 +1537,8 @@ rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Sh
 rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: RotationPointLike, targetPoint: RotationPointLike, options?: RotateAroundToOptions): Shape
 ```
 
+`RotateAroundToOptions`: `{ mode?: RotateAroundToMode }`
+
 #### `transform()` — Apply a 4x4 affine transform matrix (column-major) or a Transform object.
 
 ```ts
@@ -1463,6 +1635,11 @@ box(100, 100, 20).pocket('top', 8, { scale: 0.8 })
 pocket(face: FaceSelector, depth: number, opts?: PocketOptions): Shape
 ```
 
+**`PocketOptions`**
+- `inset?: number` — Shrink the face boundary inward by this many mm before extruding. Produces angled walls when combined with depth. Default: 0 (full face).
+- `scale?: number` — Scale the face profile uniformly (e.g. 0.8 = 80% of the face area). Mutually exclusive with `inset`; `inset` takes precedence if both are set.
+- `join?: "Square" | "Round" | "Miter"` — Corner join style when using `inset`. Default: 'Round'.
+
 #### `boss()` — Add a boss (protrusion) from the named face.
 
 ```js
@@ -1485,6 +1662,30 @@ box(50, 50, 20).hole('top', { diameter: 6, counterbore: { diameter: 12, depth: 3
 hole(faceOrRef: SketchFaceTarget | FaceRef, opts: ShapeHoleOptions): Shape
 ```
 
+**`FaceRef`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `normal` | `[ number, number, number ]` | Normal direction of the face |
+| `center` | `[ number, number, number ]` | Center point of the face |
+| `query?` | `FaceQueryRef` | Compiler-owned face query when available. |
+| `planar?` | `boolean` | True when the face can host a 2D sketch placement frame |
+| `uAxis?` | `[ number, number, number ]` | Face-local horizontal axis for planar faces |
+| `vAxis?` | `[ number, number, number ]` | Face-local vertical axis for planar faces |
+| `surface?` | `FaceSurface` | Analytic surface family when the backend can identify one. |
+| `descendant?` | `FaceDescendantMetadata` | Shared descendant-resolution metadata when this face is a semantic region/set. |
+| `name` | | — |
+
+**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
+
+**`ShapeHoleOptions`**: `diameter: number`, `depth?: number`, `upToFace?: SketchFaceTarget | FaceRef`, `extent?: ShapeFeatureExtentOptions`, `u?: number`, `v?: number`, `counterbore?: { diameter: number; depth: number; }`, `countersink?: { diameter: number; angleDeg?: number; }`, `thread?: ShapeHoleThreadOptions`
+
+`ShapeFeatureExtentOptions`: `{ forward: ShapeFeatureExtentSideOptions, reverse?: ShapeFeatureExtentSideOptions }`
+
+`ShapeFeatureExtentSideOptions`: `{ depth?: number, upToFace?: SketchFaceTarget | FaceRef, through?: boolean }`
+
+**`ShapeHoleThreadOptions`**: `designation?: string`, `pitch?: number`, `class?: string`, `handedness?: "right" | "left"`, `depth?: number`, `modeled?: boolean`
+
 #### `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.
@@ -1498,6 +1699,8 @@ body.cutout(profile, { depth: 5 })
 cutout(sketch: Sketch, opts?: ShapeCutoutOptions): Shape
 ```
 
+**`ShapeCutoutOptions`**: `depth?: number`, `upToFace?: SketchFaceTarget | FaceRef`, `extent?: ShapeFeatureExtentOptions`, `taperScale?: number | [ number, number ]`
+
 **Placement**
 
 #### `placeReference()` — Translate the shape so the given anchor or reference lands on the target coordinate.
@@ -1561,6 +1764,11 @@ mast.translate(0, station, radius + 50).seatInto(fuselage, 'mount', { depth: 'fl
 seatInto(target: Shape, surface: string, options?: SeatIntoOptions): Shape
 ```
 
+**`SeatIntoOptions`**
+- `along?: [ number, number, number ]` — Movement axis. Default: inverted face normal (points into target).
+- `depth?: "full" | "flush" | number` — How deep to embed. 'full' = entire face inside. 'flush' = nearest point touches. number = mm past flush. Default: 'full'.
+- `gap?: number` — Standoff gap in mm. Positive = gap between face and target. Negative = extra penetration. Default: 0.
+
 #### `seatOver()` — Slide this shape until a target's labeled face is fully covered (inside this shape).
 
 The inverse of `seatInto`: instead of embedding *your* face into the target, you move until the *target's* face is embedded inside you.
@@ -1585,6 +1793,10 @@ seatOver(target: Shape, targetSurface: string, options?: SeatIntoOptions): Shape
 withConnectors(connectors: Record<string, ConnectorInput>): Shape
 ```
 
+**`PortInput`**: `origin?: [ number, number, number ]`, `axis?: [ number, number, number ]`, `start?: [ number, number, number ]`, `end?: [ number, number, number ]`, `up?: [ number, number, number ]`, `kind?: JointType`, `min?: number`, `max?: number`
+
+`ConnectorInput`: `{ connectorType?: string, gender?: ConnectorGender, measurements?: Record<string, number | string> }`
+
 #### `connectorNames()` — List all connector names on this shape.
 
 ```ts
@@ -1621,6 +1833,8 @@ Overloads:
 matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): Shape
 ```
 
+`MatchToOptions`: `{ force?: boolean, angle?: number, distance?: number }`
+
 **References**
 
 #### `withReferences()` — Attach named placement references that survive normal transforms and imports.
@@ -1629,6 +1843,12 @@ matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string
 withReferences(refs: PlacementReferenceInput): Shape
 ```
 
+**`PlacementReferenceInput`**: `points?: Record<string, [ number, number, number ]>`, `edges?: Record<string, PlacementEdgeRef>`, `surfaces?: Record<string, PlacementSurfaceRef>`, `objects?: Record<string, PlacementObjectInput>`
+
+`PlacementEdgeRef`: `{ start: Vec3, end: Vec3 }`
+
+`PlacementSurfaceRef`: `{ center: Vec3, normal: Vec3 }`
+
 #### `referenceNames()` — List named placement references carried by this shape.
 
 ```ts
@@ -1790,6 +2010,24 @@ translate(x: number, y: number, z: number): Transform
 rotateAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
 ```
 
+#### `rotateX()` — Rotate about the X axis after the current transform (parity with `Shape.rotateX`).
+
+```ts
+rotateX(angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `rotateY()` — Rotate about the Y axis after the current transform (parity with `Shape.rotateY`).
+
+```ts
+rotateY(angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `rotateZ()` — Rotate about the Z axis after the current transform (parity with `Shape.rotateZ`).
+
+```ts
+rotateZ(angleDeg: number, pivot?: Vec3): Transform
+```
+
 #### `inverse()` — Return the inverse transform.
 
 ```ts
@@ -2133,18 +2371,160 @@ constant(value?: number): Pattern2D
 sineWave(options: Pattern2DSineWaveOptions): Pattern2D
 ```
 
+**`Pattern2DSineWaveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `direction?` | `Vec2` | Direction the wave advances in UV space. Default: [1, 0]. |
+| `wavelength` | `number` | Distance between wave peaks in surface millimeters. |
+| `amplitude?` | `number` | Height amplitude in millimeters. Default: 1. |
+| `phase?` | `number` | Phase offset in radians. Default: 0. |
+| `bias?` | `number` | Constant height offset in millimeters. Default: 0. |
+
 #### `stripes()` — Create recessed stripe bands in UV space.
 
 ```ts
 stripes(options: Pattern2DStripesOptions): Pattern2D
 ```
 
+**`Pattern2DStripesOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `direction?` | `Vec2` | Direction perpendicular to the stripe bands in UV space. Default: [1, 0]. |
+| `spacing` | `number` | Center-to-center spacing in surface millimeters. |
+| `width` | `number` | Stripe width in surface millimeters. |
+| `depth?` | `number` | Stripe groove depth in millimeters. Default: 1. |
+
 #### `overUnderWeave()` — Create an over-under woven relief pattern in UV space.
 
 ```ts
 overUnderWeave(options: Pattern2DOverUnderWeaveOptions): Pattern2D
 ```
 
+**`Pattern2DOverUnderWeaveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `spacing` | `number \| Vec2` | Thread center-to-center spacing. A number uses the same spacing for U and V. |
+| `threadWidth` | `number \| Vec2` | Thread width. A number uses the same width for U and V. |
+| `depth?` | `number` | Thread groove depth in millimeters. Default: 0.8. |
+| `underScale?` | `number` | Relative height of the under-crossing thread. Default: 0.15. |
+
+### `HermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
+### `QuinticHermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `c0` | `Vec3` | Scaled second derivative at start (curvature * weight² * chordLength²) |
+| `c1` | `Vec3` | Scaled second derivative at end (curvature * weight² * chordLength²) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative, normalized) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
 ### `ShapeRef`
 
 A first-class reference path over a shape's semantic faces and face relationships.
@@ -2337,39 +2717,43 @@ Namespaced file import helpers for formats that should not add new lowercase glo
 
 ForgeCAD uses a **Z-up** right-handed coordinate system.
 
+For objects with a clear facing direction, model the front/face/nose/camera side toward **-Y**. The rear/back side is **+Y**. In code, a forward/fore direction vector is `[0, -1, 0]`.
+
 ## Axes
 
 | Axis | Direction       | Positive |
 |------|-----------------|----------|
 | X    | Left / Right    | Right    |
-| Y    | Forward / Back  | Forward  |
+| Y    | Front / Back    | Back     |
 | Z    | Up / Down       | Up       |
 
 ## Standard Views
 
+The camera position direction says where the camera sits relative to the model. A front view camera sits at `-Y` and looks toward `+Y`, so it sees the model's `-Y` front face.
+
 | View   | Camera position direction | Sees plane |
-|--------|--------------------------|------------|
-| Front  | −Y                       | XZ         |
-| Back   | +Y                       | XZ         |
+|--------|---------------------------|------------|
+| Front  | -Y                        | XZ         |
+| Back   | +Y                        | XZ         |
 | Right  | +X                       | YZ         |
-| Left   | −X                       | YZ         |
+| Left   | -X                       | YZ         |
 | Top    | +Z                       | XY         |
-| Bottom | −Z                       | XY         |
+| Bottom | -Z                       | XY         |
 
 ## GizmoViewcube Face Mapping
 
-Three.js BoxGeometry material indices vs ForgeCAD labels (Z-up remapping):
+Renderer/view-cube internals may have their own material ordering. Map any view-cube labels to the ForgeCAD directions below:
 
-| Index | Three.js direction | ForgeCAD label |
-|-------|--------------------|----------------|
-| 0     | +X                 | Right          |
-| 1     | −X                 | Left           |
-| 2     | +Y                 | Front          |
-| 3     | −Y                 | Back           |
-| 4     | +Z                 | Top            |
-| 5     | −Z                 | Bottom         |
+| Direction | ForgeCAD label |
+|-----------|----------------|
+| +X        | Right          |
+| -X        | Left           |
+| +Y        | Back           |
+| -Y        | Front          |
+| +Z        | Top            |
+| -Z        | Bottom         |
 
-Default drei labels are Y-up; ForgeCAD passes `faces={['Right','Left','Front','Back','Top','Bottom']}`.
+The face/anchor API is the source of truth: `front` resolves to the minimum-Y side and `back` resolves to the maximum-Y side.
 
 ## Grid
 
@@ -2397,7 +2781,7 @@ Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0
 
 ## Revolution Axis
 
-`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
+`Sketch.revolve()` produces a world Z-axis solid of revolution. Profile X = radial distance from the Z axis, Profile Y = world Z height after revolution. Profile should stay at X > 0 unless intentionally touching the axis.
 
 ## Boolean Winding (3D)
 
@@ -2423,7 +2807,7 @@ Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code t
 |---|---|---|---|
 | Winding | Any point order | CCW | `polygon()`, `path().close()` |
 | Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
-| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
+| Revolution | "revolve this profile" | Profile X = radius, Profile Y = world Z height | Documented and regression-tested |
 | Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
 | Transform order | Left-to-right chain | Post-multiply | Native match |
 
@@ -2439,6 +2823,16 @@ For any fixed assembly where parts are meant to stay in contact in the final mod
 
 Use raw `translate()` and `rotate()` when parts are intentionally free-floating or when you are doing quick exploratory layout. Use `attachTo()` for rough bounding-box placement. But if the relationship is a real interface, make it explicit with connectors.
 
+## Mechanisms: connector frames vs link points
+
+For serial articulated parts (hinges, hips, knees, levers, wheels), use `assembly().connect()` with connectors. `connect()` aligns the full connector frame: `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` locks the zero-angle twist of the child part. `up` is a local roll reference, not world up; author it explicitly whenever the rest pose matters.
+
+Do not use `addPart(..., { mate: { connector, toLink } })` when the part must point along a bone or inherit orientation from a link edge. Link mates are point attachments only: they translate the connector origin onto the solved link position and preserve the part's existing rotation. That is good for markers, sensors, labels, and debug handles. It is not a bone-frame API.
+
+Use link graphs (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) when the hard part is solving point positions, especially closed loops. Use connector-frame joints when the hard part is orienting real physical parts.
+
+For bilateral mechanisms, remember that connector-frame revolute values are physical axis-local values. Mirrored hinge axes need negated physical revolute values for the same mirrored pose, and physical limits mirror as `[min, max] -> [-max, -min]`. If you want `HipR: 10` and `HipL: 10` to mean the same semantic pose, drive a mirrored link graph or write an explicit state mapping instead of assuming equal connector-joint values are symmetric.
+
 ## Primitive origin convention
 
 All 3D primitives are **centered on XY, base at Z=0**:
@@ -2462,14 +2856,14 @@ Most positioning bugs come from manual coordinate arithmetic. Use these methods
 
 ## 1. Connectors + `matchTo()` — default for mating interfaces
 
-Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
+Define connectors on parts; `matchTo()` provides automatic alignment. With one connector pair, the child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model), and `up` pins the roll reference. With multiple connector pairs, the connector origins define the rigid transform; still author meaningful `axis` and `up` values so the same connectors remain useful for `connect()`, audits, and future matching.
 
 ```javascript
 const shelf = box(200, 120, 10).translate(0, 0, -5).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0], up: [0, 0, 1] }),
 });
 const panel = box(12, 120, 200).translate(0, 0, -100).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0], up: [0, 0, 1] }),
 });
 const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
 // Dictionary form for multiple pairs on same target:
@@ -3089,7 +3483,6 @@ addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions):
 | `startAngle?` | `number` | Angle (in degrees) of vertex[0] measured from the +X axis (CCW positive). Default: 0 (rightmost vertex). |
 | `blockRotation?` | `boolean` | Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false. |
 
-
 **`ConstrainedRegularPolygon`** extends ConstrainedPolygon
 - `center: PointId` — Center point. Use `sk.fix(poly.center, x, y)` to pin location, or `sk.coincident(poly.center, other)` to align with other geometry.
 
@@ -3329,7 +3722,7 @@ region(seed: [ number, number ]): Sketch
 extrude(height: number, opts?: { twist?: number; divisions?: number; scaleTop?: number | [ number, number ]; }): Shape
 ```
 
-#### `revolve()` — Revolve this 2D sketch around the Y axis to create a 3D solid of revolution.
+#### `revolve()` — Revolve this 2D sketch around the world Z axis. Sketch X is radius; sketch Y becomes world Z height.
 
 ```ts
 revolve(degrees?: number, segments?: number): Shape
@@ -3360,9 +3753,25 @@ Use this when a 2D profile should be oriented onto a 3D face before extrusion or
 onFace(parentOrFace: Shape | { toShape(): Shape; } | { _bbox(): { min: number[]; max: number[]; }; } | FaceRef, faceOrOpts?: "front" | "back" | "left" | "right" | "top" | "bottom" | string | FaceRef | { u?: number; v?: number; protrude?: number; selfAnchor?: Anchor; }, opts?: { u?: number; v?: number; protrude?: number; selfAnchor?: Anchor; }): Sketch
 ```
 
-**Labels**
+**`FaceRef`**
 
-#### `labelEdge()` — Label the single boundary edge (for circles, single-loop profiles). Returns a new sketch.
+| Option | Type | Description |
+|--------|------|-------------|
+| `normal` | `[ number, number, number ]` | Normal direction of the face |
+| `center` | `[ number, number, number ]` | Center point of the face |
+| `query?` | `FaceQueryRef` | Compiler-owned face query when available. |
+| `planar?` | `boolean` | True when the face can host a 2D sketch placement frame |
+| `uAxis?` | `[ number, number, number ]` | Face-local horizontal axis for planar faces |
+| `vAxis?` | `[ number, number, number ]` | Face-local vertical axis for planar faces |
+| `surface?` | `FaceSurface` | Analytic surface family when the backend can identify one. |
+| `descendant?` | `FaceDescendantMetadata` | Shared descendant-resolution metadata when this face is a semantic region/set. |
+| `name` | | — |
+
+**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
+
+**Labels**
+
+#### `labelEdge()` — Label the single boundary edge (for circles, single-loop profiles). Returns a new sketch.
 
 ```ts
 labelEdge(name: string): Sketch
@@ -3658,6 +4067,16 @@ regularPolygon(options: RegularPolygonOptions): ConstrainedRegularPolygon
 groupRect(options: GroupRectOptions): ConstrainedGroupRect
 ```
 
+**`GroupRectOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `x?` | `number` | Bottom-left x coordinate (world). Default: 0. |
+| `y?` | `number` | Bottom-left y coordinate (world). Default: 0. |
+| `width` | `number` | Width (along x in local coords). Required. |
+| `height` | `number` | Height (along y in local coords). Required. |
+| `allowRotation?` | `boolean` | Allow the solver to rotate this rectangle. Default: false. |
+
 **Geometric Constraints**
 
 #### `horizontal()` — Constrain a line to be horizontal (parallel to the X axis).
@@ -4001,6 +4420,23 @@ result.withUpdatedConstraint('cst-5', 120); // update a dimension without rebuil
 solve(options?: SolveOptions): ConstraintSketch | Sketch
 ```
 
+**`SolveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `iterations?` | `number` | Maximum number of LM outer iterations per restart. |
+| `tolerance?` | `number` | Infinity-norm residual tolerance for declaring convergence. |
+| `restarts?` | `number` | Number of deterministic restart seeds used by the global solver. |
+| `warmStartIterations?` | `number` | Optional projector iterations used only for initialisation, not as the main solver. |
+| `maxScaledStep?` | `number` | Maximum LM step length in scaled variable space. Larger = bolder, smaller = safer. |
+| `skipRedundancyCheck?` | `boolean` | Skip redundancy detection (safe when topology is unchanged and previous DOF >= 0). |
+| `presolveConstraintId?` | `string` | Run the targeted presolve hook for this constraint before the main solve. |
+| `fallbackRestarts?` | `number` | When set and the first solve exceeds tolerance*5, retry with this many restarts. |
+| `progressive?` | `boolean` | Add constraints progressively with short LM solves, all in one WASM call. |
+| `timeBudgetMs?` | `number` | Wall-clock time budget in ms for the entire solve. 0 = no limit. |
+| `debugConstructiveTranscript?` | `boolean` | Capture a readable constructive transcript in `constraintMeta.debug`. |
+| `debugSvgSnapshots?` | `boolean` | Capture SVG snapshots for constructive steps in `constraintMeta.debug`. |
+
 #### `solveConstraintsOnly()` — Run the solver without building a full `ConstraintSketch`.
 
 Lighter than `solve()` — skips profile and DOF analysis. Useful for lightweight constraint validation or progress monitoring mid-construction.
@@ -4409,15 +4845,13 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `Helix.path`, `Helix.coil`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `Curve.Blend`, `Curve.BlendG2`, `Curve.Arc`, `Curve.Line`, `Curve.Polyline`, `Curve.Spline`, `Curve.Nurbs`, `Curve.Fit`, `Curve.Trim`, `Curve.Reverse`, `Curve.Route`, `Curve.Helix`, `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `spline2d`, `loft`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
-- [HelixCurve](#helixcurve)
+- [Route3D](#route3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
 - [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
-- [HermiteCurve3D](#hermitecurve3d)
-- [QuinticHermiteCurve3D](#quintichermitecurve3d)
 - [ProductSkin](#productskin)
 - [ProductSurfaceRef](#productsurfaceref)
 - [ProductSurfaceBuilder](#productsurfacebuilder)
@@ -4439,6 +4873,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [SurfaceJoinBuilder](#surfacejoinbuilder)
 - [CounterboreBuilder](#counterborebuilder)
 - [RoundedSlotBuilder](#roundedslotbuilder)
+- [Curve](#curve)
 - [Surface](#surface)
 - [Blend](#blend)
 - [Analysis](#analysis)
@@ -4448,97 +4883,186 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Slot](#slot)
 - [Counterbore](#counterbore)
 - [Ribs](#ribs)
-- [Helix](#helix)
 
 ## Functions
 
 ### Curves & Surfacing
 
-#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+#### `Curve.Blend()` — Create an exact G1 blend curve between two directed endpoints.
+
+The returned curve is a cubic non-rational `NurbsCurve3D`: ForgeCAD converts the endpoint positions and tangents into Bezier control points, so the curve can feed `sweep` and exact surface boundaries through the existing `nurbs` IR rather than a sampled polyline.
+
+```js
+const rail = Curve.Blend(
+  { point: [0, 0, 0], tangent: [1, 0, 0], weight: 0.8 },
+  { point: [40, 20, 8], tangent: [0, 1, 0], weight: 0.8 },
+);
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.station(profile: Sketch, position: number): LoftStation
+Curve.Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D
 ```
 
-`LoftStation`: `{ profile: Sketch, position: number }`
+**`CurveBlendEndpoint`**
+- `point: Vec3` — Endpoint position.
+- `tangent: Vec3` — Tangent direction at this endpoint. Magnitude is ignored.
+- `weight?: number` — Tangent reach relative to the endpoint chord length. Default 1.
 
-#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+#### `Curve.BlendG2()` — Create an exact G2 blend curve between two directed endpoints.
+
+This is the curvature-aware companion to `Curve.Blend()`. It returns a degree-5 non-rational `NurbsCurve3D` that matches endpoint position, tangent direction, and optional curvature/second-derivative vectors.
+
+```js
+const rail = Curve.BlendG2(
+  { point: [0, 0, 0], tangent: [1, 0, 0], curvature: [0, 0.02, 0] },
+  { point: [50, 20, 0], tangent: [0, 1, 0], curvature: [-0.02, 0, 0] },
+);
+```
 
 ```ts
-Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D
 ```
 
-`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+**`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
+- `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
 
-#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+#### `Curve.Arc()` — Create an exact circular 3D arc from start, end, and start tangent.
+
+The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
+
+```js
+const rail = Curve.Arc({
+  start: [40, 0, 0],
+  end: [0, 40, 0],
+  tangent: [0, 1, 0],
+});
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Arc(options: CurveArcOptions): NurbsCurve3D
 ```
 
-#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+**`CurveArcOptions`**
+- `start: Vec3` — Arc start point.
+- `end: Vec3` — Arc end point.
+- `tangent: Vec3` — Tangent direction at the start point. Magnitude is ignored.
+
+#### `Curve.Line()` — Create an exact straight 3D NURBS line segment.
+
+```js
+const rail = Curve.Line([0, 0, 0], [80, 0, 15]);
+const rib = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Line(start: Vec3, end: Vec3): NurbsCurve3D
 ```
 
-#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+#### `Curve.Polyline()` — Create a polyline path as cloned 3D points.
+
+Polylines are exact as route/path input to `sweep`. Use `Curve.Route` when the centerline needs bend and endpoint-frame metadata.
 
 ```ts
-Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Polyline(points: Vec3[]): Vec3[]
 ```
 
-#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+#### `Curve.Spline()` — Create a smooth Catmull-Rom spline path.
+
+This is a smooth sampled curve object. Use `Curve.Nurbs` when the path must preserve exact control-point and knot data.
 
 ```ts
-Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Spline(points: Vec3[], options?: Spline3DOptions): Curve3D
 ```
 
-#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+**`Spline3DOptions`**
+- `closed?: boolean` — Closed loop (default false).
+- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
 
-The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+#### `Curve.Nurbs()` — Create an exact NURBS 3D curve from control points, weights, knots, and degree.
+
+```js
+const rail = Curve.Nurbs([[0, 0, 0], [30, 4, 12], [60, -4, 12], [90, 0, 0]]);
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
 ```
 
-#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+**`NurbsCurve3DOptions`**
 
-The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+| Option | Type | Description |
+|--------|------|-------------|
+| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
+| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
+| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
+| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
+
+#### `Curve.Fit()` — Fit a non-rational NURBS curve that interpolates every input point.
+
+This is global B-spline interpolation, not approximate curve reduction: ForgeCAD computes chord-length parameters, averaged clamped knots, solves the control points, then verifies the interpolation residual against `tolerance`.
+
+```js
+const rail = Curve.Fit(
+  [[0, 0, 0], [20, 8, 12], [50, -4, 18], [80, 0, 0]],
+  { degree: 3, tolerance: 0.001 },
+);
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+Curve.Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D
 ```
 
-#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+**`CurveFitOptions`**
+- `degree?: number` — Polynomial degree. Default is cubic, reduced automatically for short point lists.
+- `tolerance?: number` — Maximum allowed interpolation residual in model units. Default 1e-7.
 
-The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+#### `Curve.Trim()` — Extract an exact curve segment from normalized parameter `start` to `end`.
+
+`NurbsCurve3D` inputs are trimmed with exact knot insertion/subdomain extraction. Polyline point arrays are trimmed by arclength over their exact line segments. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
 
 ```ts
-Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>
 ```
 
-#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+#### `Curve.Reverse()` — Reverse an exact curve without changing its geometry.
 
-Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+`NurbsCurve3D` inputs reverse control points, weights, and knots. Polyline point arrays are cloned and reversed. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
 
 ```ts
-Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+Curve.Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
+#### `Curve.Route()` — Build analytic 3D line/arc routes for sweeps.
 
-**`LoftWithGuideRailsOptions`** extends LoftOptions
-- `axis?: LoftAxis` — Primary station axis. Default Z.
-- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
-- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+`Curve.Route.fromPolyline()` is the canonical route API. It returns a `Route3D` value object, preserving exact route segments, named port frames, and the lowerable `route3d` sweep compile plan.
+
+```js
+const route = Curve.Route.fromPolyline(
+  [[0, 0, 0], [0, 0, 50], [40, 0, 50]],
+  { cornerRadius: 12, startPort: 'inlet', endPort: 'outlet' },
+);
+const tube = sweep(circle2d(4), route);
+```
+
+```ts
+Curve.Route: typeof Route3D
+```
 
-#### `Helix.path()` — Create a metadata-bearing helical centerline around the Z axis.
+#### `Curve.Helix()` — Build helical paths and swept coils.
+
+`Curve.Helix` is the canonical namespace for helical paths and coils. It uses the same sweep-based lowering as other curve paths.
+
+```js
+const guide = Curve.Helix.path({ radius: 20, pitch: 6, turns: 4 });
+const spring = Curve.Helix.coil({ radius: 20, pitch: 6, turns: 4, wireRadius: 1 });
+```
 
 ```ts
-Helix.path(options: HelixOptions): HelixCurve
+Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }
 ```
 
 **`HelixOptions`**
@@ -4553,66 +5077,88 @@ Helix.path(options: HelixOptions): HelixCurve
 | `clockwise?` | `boolean` | Reverse winding direction when viewed from +Z. |
 | `samplesPerTurn?` | `number` | Point samples per turn for the metadata path. Default 32. |
 
-#### `Helix.coil()` — Create a solid helical coil by sweeping a profile through helix-local frames.
+`CurveHelixPath`: `{ radius: number, pitch: number, turns: number, height: number, startAngle: number, clockwise: boolean }`
 
-Overloads:
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
 
-- `Helix.coil(options: HelixCoilOptions): Shape`
-- `Helix.coil(profile: Sketch, options: HelixCoilOptions): Shape`
+`LoftStation`: `{ profile: Sketch, position: number }`
 
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
 
-**`HelixCoilOptions`** extends HelixOptions
-- `wireRadius?: number` — Radius of the circular wire profile. Required unless a custom profile is passed.
-- `profileSegments?: number` — Segment count for the default circular wire profile. Default 24.
-- `divisionsPerTurn?: number` — Sweep path samples per turn. Default 32.
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
 
-#### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
 
-The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
 
 ```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
 ```
 
-**`QuinticHermiteCurveEndpoint`**
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `point` | `Vec3` | Position |
-| `tangent` | `Vec3` | Tangent direction (will be normalized internally) |
-| `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
-| `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
 
-#### `nurbs3d()` — Create a NURBS curve from control points.
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
 
-With default options, creates a cubic non-rational B-spline with uniform clamped knots. Set `weights` for rational curves (exact circles, conics). Set `degree` for linear (1), quadratic (2), cubic (3), or higher-order curves.
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
 
-```js
-// Simple cubic B-spline through control points
-const curve = nurbs3d([[0,0,0], [10,5,0], [20,-5,10], [30,0,5]]);
-const tube = sweep(circle(2), curve);
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
 ```
 
-```js
-// Rational quadratic — exact circular arc
-const arc = nurbs3d(
-  [[10,0,0], [10,10,0], [0,10,0]],
-  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
-);
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
 ```
 
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
 ```ts
-nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
 ```
 
-**`NurbsCurve3DOptions`**
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
-| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
-| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
-| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
 
 #### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
@@ -4632,18 +5178,6 @@ spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
 | `strokeWidth?` | `number` | For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. |
 | `join?` | `"Round" \| "Square"` | Stroke join for open splines. Default 'Round'. |
 
-#### `spline3d()` — Create a reusable 3D spline curve object (Catmull-Rom).
-
-The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
-
-```ts
-spline3d(points: Vec3[], options?: Spline3DOptions): Curve3D
-```
-
-**`Spline3DOptions`**
-- `closed?: boolean` — Closed loop (default false).
-- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
-
 #### `loft()` — Loft between multiple sketches along Z stations.
 
 Profiles can differ in topology and vertex count: interpolation is done on signed-distance fields and meshed with level-set extraction. Heights must be strictly increasing. Compatible loft stacks can also stay on the maintained export-backend path.
@@ -4654,29 +5188,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-#### `loftAlongSpine()` — 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().
-
-```ts
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3[], tValues: number[], options?: LoftAlongSpineOptions): Shape
-```
-
-**`LoftAlongSpineOptions`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `samples?` | `number` | Number of samples when spine is a Curve3D. Default 48. |
-| `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
-| `boundsPadding?` | `number` | Optional extra bounds padding. |
-| `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
-
 #### `sweep()`
 
 ```ts
@@ -4800,106 +5311,6 @@ surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
 - `thickness?: number` — Thickness of the generated solid. Default 0 for an open exact sheet.
 - `approximate?: boolean` — Allow explicit approximation for non-exact curve inputs such as Curve3D samples.
 
-#### `transitionCurve()` — Create a smooth transition curve between two edges.
-
-Returns a `HermiteCurve3D` that starts at `edgeA.point` tangent to `edgeA.tangent` and ends at `edgeB.point` tangent to `edgeB.tangent`.
-
-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 }, );
-
-```
-
-```ts
-transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
-```
-
-**`TransitionEdge`**
-- `point: Vec3` — Connection point on the edge. Can be any point along the edge where the transition should connect.
-- `tangent: Vec3` — Tangent direction at the connection point. This is the direction the curve should initially follow when leaving this edge. For a straight edge, this is typically the edge direction pointing "outward" (away from the body of the edge, toward the other edge).
-- `normal?: Vec3` — Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector.
-
-**`TransitionCurveOptions`**
-- `weightA?: number` — Weight for the start edge. Controls tangent magnitude at the start. - 1.0 (default): balanced transition - > 1.0: curve follows start edge longer before turning - < 1.0: curve turns sooner at the start
-- `weightB?: number` — Weight for the end edge. Controls tangent magnitude at the end. - 1.0 (default): balanced transition - > 1.0: curve follows end edge longer before turning - < 1.0: curve turns sooner at the end
-- `samples?: number` — Number of sample points for the output polyline. Default 64. Higher values give smoother curves at the cost of more geometry.
-
-#### `transitionSurface()` — Create a solid transition surface between two edges by sweeping a profile along a Hermite transition curve.
-
-This produces a watertight solid that smoothly connects the two edges. Works with both Manifold and OCCT backends.
-
-```js
-// Circular tube connecting two edges
-const tube = transitionSurface(
-  { point: [0, 0, 0], tangent: [1, 0, 0] },
-  { point: [10, 5, 3], tangent: [0, 1, 0] },
-  { radius: 0.5 },
-);
-```
-
-// Custom profile with weights const custom = transitionSurface( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 3], tangent: [0, 1, 0] }, { profile: mySketch, weightA: 1.5, weightB: 0.8 }, );
-
-```
-
-```ts
-transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
-```
-
-
-**`TransitionSurfaceOptions`** extends TransitionCurveOptions
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `profile?` | `Sketch` | Cross-section profile to sweep along the transition curve. If omitted, a circular profile with `radius` is used. |
-| `radius?` | `number` | Radius of circular cross-section (used when `profile` is omitted). Default: 5% of chord length. |
-| `rectangleSection?` | `{ width: number; height: number; }` | Width and height for rectangular cross-section. Alternative to `radius` when `profile` is omitted. |
-| `up?` | `Vec3` | Preferred up vector for the sweep frame. Default: auto-detected. |
-| `edgeLength?` | `number` | Edge length for level-set meshing. Smaller = finer. |
-| `boundsPadding?` | `number` | Extra bounds padding for level-set meshing. |
-
-#### `connectEdges()` — Create a transition surface or solid bridge between two edge segments.
-
-Tangents can be inferred from neighboring geometry or supplied explicitly through `options`. This is useful for loft-like blends where you want a direct connection between two edge spans.
-
-```ts
-connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
-```
-
-**`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` | | — |
-
-
-**`ConnectEdgesOptions`** extends TransitionSurfaceOptions
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `endA?` | `EdgeEnd` | Which end of edge A to connect. Default: 'start'. |
-| `endB?` | `EdgeEnd` | Which end of edge B to connect. Default: 'start'. |
-| `tangentModeA?` | `TangentMode` | Tangent mode for edge A. Default: 'along'. |
-| `tangentModeB?` | `TangentMode` | Tangent mode for edge B. Default: 'along'. |
-| `tangentA?` | `Vec3` | Explicit tangent for edge A. |
-| `tangentB?` | `Vec3` | Explicit tangent for edge B. |
-| `flipA?` | `boolean` | Flip tangent A. |
-| `flipB?` | `boolean` | Flip tangent B. |
-
 ### Surface Members
 
 #### `surfaceBand()`
@@ -4979,47 +5390,76 @@ tangentAt(t: number): Vec3
 length(samples?: number): number
 ```
 
-### `HelixCurve`
+### `Route3D`
 
-Metadata-bearing helical curve around the Z axis. Use `Helix.path(...)` for sampling, placement, or `sweep()`, and `Helix.coil(...)` for helix-oriented solids.
+Metadata-bearing analytic 3D route made from line and arc segments.
 
-**Properties:**
+Use `Curve.Route.fromPolyline()` when you know the virtual design skeleton points and bend radius. ForgeCAD computes tangent trim points, bend arcs, total length, and named start/end port frames. Pass the route directly to `sweep()`.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `radius` | `number` | — |
-| `pitch` | `number` | — |
-| `turns` | `number` | — |
-| `height` | `number` | — |
-| `startAngle` | `number` | — |
-| `clockwise` | `boolean` | — |
+```js
+const route = Curve.Route.fromPolyline(
+  [[0, 0, 0], [0, 0, 80], [60, 0, 80]],
+  { cornerRadius: 24, startPort: "inlet", endPort: "outlet" },
+);
+const pipe = sweep(difference2d(circle2d(8), circle2d(6)), route);
+const outlet = route.port("outlet");
+```
 
-**Methods:**
+#### `fromPolyline()` — Build a line/arc route from virtual polyline corner points.
 
-#### `pointAt()`
+```ts
+static fromPolyline(points: Route3DVec3[], options?: Route3DFromPolylineOptions): Route3D
+```
+
+**`Route3DFromPolylineOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cornerRadius?` | `number` | Bend radius applied to every virtual interior corner. Default 0 keeps sharp polyline corners. |
+| `startPort?` | `string` | Name for the start port. Default "start". |
+| `endPort?` | `string` | Name for the end port. Default "end". |
+| `up?` | `Vec3` | Preferred up vector for deterministic port frames. Default [0, 0, 1]. |
+
+#### `length()` — Total centerline length, including line and bend arc segments.
 
 ```ts
-pointAt(t: number): Vec3
+get length(): number
 ```
 
-#### `tangentAt()`
+#### `segments()` — Exact line and arc segments that make up this route.
 
 ```ts
-tangentAt(t: number): Vec3
+get segments(): Route3DSegment[]
 ```
 
-#### `sample()`
+#### `ports()` — Named port frames, keyed by port name.
 
 ```ts
-sample(count?: number): Vec3[]
+get ports(): Record<string, RoutePortFrame>
 ```
 
-#### `length()`
+#### `port()` — Return one named route port frame.
+
+```ts
+port(name: string): RoutePortFrame
+```
+
+#### `toSweepPathPlan()` — Convert this route to the compile plan consumed by sweep().
+
+```ts
+toSweepPathPlan(): SweepPathCompilePlan
+```
+
+#### `toPolyline()` — Sample this analytic route as a polyline for inspection or backend lowering.
 
 ```ts
-length(): number
+toPolyline(options?: number | Route3DToPolylineOptions): Route3DVec3[]
 ```
 
+**`Route3DToPolylineOptions`**
+- `samples?: number` — Approximate target point count for the full route.
+- `maxAngleDeg?: number` — Maximum angular spacing on arc segments. Default 6 degrees.
+
 ### `NurbsCurve3D`
 
 **Properties:**
@@ -5393,120 +5833,6 @@ toPolyline(): [ number, number ][]
 closeOffset(delta: number, join?: "Round" | "Square" | "Miter"): Sketch
 ```
 
-### `HermiteCurve3D`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `p0` | `Vec3` | Start position |
-| `p1` | `Vec3` | End position |
-| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
-| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
-| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
-
-**Methods:**
-
-#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
-
-```ts
-pointAt(t: number): Vec3
-```
-
-#### `tangentAt()` — Evaluate tangent (first derivative) at parameter t ∈ [0, 1]
-
-```ts
-tangentAt(t: number): Vec3
-```
-
-#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
-
-```ts
-curvatureAt(t: number): Vec3
-```
-
-#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
-
-```ts
-sample(count?: number): Vec3[]
-```
-
-#### `length()` — Approximate arc length by sampling.
-
-```ts
-length(samples?: number): number
-```
-
-#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
-
-```ts
-sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
-```
-
-#### `toPolyline()` — Convert to a format compatible with sweep() path input.
-
-```ts
-toPolyline(samples?: number): Vec3[]
-```
-
-### `QuinticHermiteCurve3D`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `p0` | `Vec3` | Start position |
-| `p1` | `Vec3` | End position |
-| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
-| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
-| `c0` | `Vec3` | Scaled second derivative at start (curvature * weight² * chordLength²) |
-| `c1` | `Vec3` | Scaled second derivative at end (curvature * weight² * chordLength²) |
-| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
-
-**Methods:**
-
-#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
-
-```ts
-pointAt(t: number): Vec3
-```
-
-#### `tangentAt()` — Evaluate tangent (first derivative, normalized) at parameter t ∈ [0, 1]
-
-```ts
-tangentAt(t: number): Vec3
-```
-
-#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
-
-```ts
-curvatureAt(t: number): Vec3
-```
-
-#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
-
-```ts
-sample(count?: number): Vec3[]
-```
-
-#### `length()` — Approximate arc length by sampling.
-
-```ts
-length(samples?: number): number
-```
-
-#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
-
-```ts
-sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
-```
-
-#### `toPolyline()` — Convert to a format compatible with sweep() path input.
-
-```ts
-toPolyline(samples?: number): Vec3[]
-```
-
 ### `ProductSkin`
 
 **Properties:**
@@ -5939,7 +6265,6 @@ attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
 
 `ProductSurfaceRef`
 
-
 `ProductPanelAttachOptions`: `{ at?: Partial<ProductSkinRefQuery>, thickness?: number, material?: ProductMaterial, color?: string }`
 
 ### `ProductRibbonBuilder`
@@ -6263,6 +6588,8 @@ bottom(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSu
 pointAt(coordinate: CylinderSurfaceCoordinate): Vec3
 ```
 
+`CylinderSurfaceCoordinate`: `{ kind?: "cylinder", angle: number, z: number, offset?: number }`
+
 #### `mirrorPoint()`
 
 ```ts
@@ -6382,6 +6709,8 @@ bottom(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCo
 pointAt(coordinate: PlaneSurfaceCoordinate): Vec3
 ```
 
+`PlaneSurfaceCoordinate`: `{ kind?: "plane", x: number, y: number, offset?: number }`
+
 #### `mirrorPoint()`
 
 ```ts
@@ -6666,6 +6995,8 @@ boundaries(samples?: number): SurfaceBandBoundarySample[]
 withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>
 ```
 
+`SurfaceBandHoleInput`: `{ length: number, width: number, along?: number, across?: number }`
+
 #### `holes()` — Resolve recorded hole regions into member-local across/along loops.
 
 ```ts
@@ -6688,6 +7019,8 @@ holes(): SurfaceBandHoleRegion[]
 carrier(carrier: CarrierSurface): this
 ```
 
+`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
+
 #### `member()`
 
 ```ts
@@ -6732,6 +7065,8 @@ band(): this
 at(anchor: SurfaceAnchor<C>): this
 ```
 
+`SurfaceAnchor`: `{ carrier: CarrierSurface<C>, coordinate: C }`
+
 #### `size()`
 
 ```ts
@@ -6750,6 +7085,10 @@ path(path: SurfacePath<C> | SurfacePathBuilder<C>): this
 section(section: MemberSectionInput): this
 ```
 
+**`MemberSectionInput`**: `width?: number`, `thickness: number`, `edgeRadius?: number`, `direction?: MemberOutwardDirection`, `material?: ProductMaterial`, `stations?: MemberSectionStation[]`
+
+`MemberSectionStation`: `{ t: number, width?: number, thickness?: number }`
+
 #### `cap()`
 
 ```ts
@@ -6762,6 +7101,8 @@ cap(style: SurfaceBandCap): this
 slot(name: string, feature: MemberFeature | RoundedSlotBuilder): this
 ```
 
+**`MemberFeature`**: `type: MemberFeatureType`, `name?: string`, `length?: number`, `width?: number`, `diameter?: number`, `counterboreDiameter?: number`, `clearanceDiameter?: number`, `height?: number`, `depth?: number`, `count?: number`, `along?: number`, `across?: number`, `verticalTravel?: number`
+
 #### `cutout()`
 
 ```ts
@@ -6886,6 +7227,25 @@ toFeature(name?: string): MemberFeature
 
 ## Constants
 
+### `Curve`
+
+Canonical exact/smooth 3D curve constructors.
+
+`Curve.*` is the public home for reference curves and route centerlines that feed `sweep`, `variableSweep`, route visualization, and future path consumers. Standalone 3D curve constructors have been collapsed into this namespace.
+
+- `Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D` — Create an exact G1 blend curve between two directed endpoints. The returned curve is a cubic non-rational `NurbsCurve3D`: ForgeCAD converts the endpoint positions and tangents into Bezier control points, so the curve can feed `sweep` and exact surface boundaries through the existing `nurbs` IR rather than a sampled polyline.
+- `BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D` — Create an exact G2 blend curve between two directed endpoints. This is the curvature-aware companion to `Curve.Blend()`. It returns a degree-5 non-rational `NurbsCurve3D` that matches endpoint position, tangent direction, and optional curvature/second-derivative vectors.
+- `Arc(options: CurveArcOptions): NurbsCurve3D` — Create an exact circular 3D arc from start, end, and start tangent. The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
+- `Line(start: Vec3, end: Vec3): NurbsCurve3D` — Create an exact straight 3D NURBS line segment.
+- `Polyline(points: Vec3[]): Vec3[]` — Create a polyline path as cloned 3D points. Polylines are exact as route/path input to `sweep`. Use `Curve.Route` when the centerline needs bend and endpoint-frame metadata.
+- `Spline(points: Vec3[], options?: Spline3DOptions): Curve3D` — Create a smooth Catmull-Rom spline path. This is a smooth sampled curve object. Use `Curve.Nurbs` when the path must preserve exact control-point and knot data.
+- `Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D` — Create an exact NURBS 3D curve from control points, weights, knots, and degree.
+- `Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D` — Fit a non-rational NURBS curve that interpolates every input point. This is global B-spline interpolation, not approximate curve reduction: ForgeCAD computes chord-length parameters, averaged clamped knots, solves the control points, then verifies the interpolation residual against `tolerance`.
+- `Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>` — Extract an exact curve segment from normalized parameter `start` to `end`. `NurbsCurve3D` inputs are trimmed with exact knot insertion/subdomain extraction. Polyline point arrays are trimmed by arclength over their exact line segments. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
+- `Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>` — Reverse an exact curve without changing its geometry. `NurbsCurve3D` inputs reverse control points, weights, and knots. Polyline point arrays are cloned and reversed. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
+- `Route: typeof Route3D` — Build analytic 3D line/arc routes for sweeps. `Curve.Route.fromPolyline()` is the canonical route API. It returns a `Route3D` value object, preserving exact route segments, named port frames, and the lowerable `route3d` sweep compile plan.
+- `Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }` — Build helical paths and swept coils. `Curve.Helix` is the canonical namespace for helical paths and coils. It uses the same sweep-based lowering as other curve paths.
+
 ### `Surface`
 
 - `Plane(options: SurfacePlaneOptions): Shape` — Create a finite analytic plane sheet that can be trimmed, sewn, thickened, or used as a low-level face.
@@ -6968,32 +7328,18 @@ toFeature(name?: string): MemberFeature
 
 - `repeated(input: { count: number; height: number; }): MemberFeature` — Create repeated ribs that belong to a surface member before lowering.
 
-### `Helix`
-
-Helical curve helpers.
-
-```ts
-const guide = Helix.path({ radius: 20, pitch: 6, turns: 4 });
-const wire = Helix.coil({ radius: 20, pitch: 6, turns: 4, wireRadius: 1 });
-const rectangular = Helix.coil(rect(2, 1), { radius: 20, height: 30, turns: 5 });
-```
-
-- `path(options: HelixOptions): HelixCurve` — Create a metadata-bearing helical centerline around the Z axis.
-- `coil(options: HelixCoilOptions): Shape` — Create a solid helical coil by sweeping a circular profile through helix-local frames.
-- `coil(profile: Sketch, options: HelixCoilOptions): Shape` — Create a solid helical coil by sweeping a profile through helix-local frames.
-
 ---
 
 <!-- generated/assembly.md -->
 
 # Assembly API
 
-Kinematic assemblies, joints, couplings, and robot export.
+Assembly-owned links, constraints, connectors, solved poses, and robot export.
 
 ## Contents
 
-- [Assembly & Joints](#assembly-joints) — `bomToCsv`, `assembly`, `joint`
-- [Assembly](#assembly) — Structure, Connectors, References, Joints, Solving
+- [Assembly & Joints](#assembly-joints) — `bomToCsv`, `assembly`
+- [Assembly](#assembly) — Kinematics, Structure, Connectors, References, Solving
 - [ImportedAssembly](#importedassembly)
 - [SolvedAssembly](#solvedassembly)
 - [MateBuilder](#matebuilder)
@@ -7019,110 +7365,259 @@ bomToCsv(rows: BomRow[]): string
 | `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
 | `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
-#### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
+#### `assembly()` — Create an assembly container with named parts, connectors, and kinematic links.
+
+**Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
 
-**Use this from iteration 1 for any model with moving parts.** Hinges, sliders, gears, articulated fingers, doors — all start with `assembly()`, not with manual rotation math. Don't build a static "extended pose" first and refactor to an assembly later: joint sliders, animations, sweeps, collision detection, and robot export all flow from the kinematic graph.
+Links are named kinematic markers in the assembly. `edgeBetweenLinks()` records structural distances or visual relationships. `addAngleBetweenLinks()` records measured, limited, or controlled angles. These APIs solve point positions, not rigid-body frames.
 
-An assembly models a mechanism as a directed graph of parts connected by joints. Parts are the nodes; joints are directed edges from parent to child. The graph must be a forest (no cycles). Root parts (those with no incoming joint) are anchored to world space.
+`addPart(..., { mate })` attaches a part connector origin to a solved link point by translation only. It is right for markers and point-following geometry. Use `connect()` / `match()` for physical articulated parts that need full connector frame alignment and deterministic rest orientation.
 
-Three joint types are supported: `'revolute'` (hinge), `'prismatic'` (slider), and `'fixed'` (rigid attachment). Use `addPart()` to add geometry, `addJoint()` (or the shorthands `addRevolute()`, `addPrismatic()`, `addFixed()`) to connect parts, and `solve()` to compute world-space positions at a given joint state.
+Return an `Assembly` directly to expose its connector joints and driven link controls in the editor. Moving those controls re-runs the assembly solve with the new state, so closed-loop link/edge mechanisms move through the real kinematic solver instead of a viewport-only forward-kinematics approximation.
 
-The higher-level `connect()` API uses declared **connectors** to compute joint frames automatically. The `match()` API uses typed connectors (with gender and type metadata) for automatic compatibility validation and joint creation.
+If no link in a connected kinematic component is fixed, ForgeCAD chooses a deterministic gauge link for solving and reports a floating-component warning.
+
+The legacy joint-chain APIs still exist for compatibility and exporter plumbing. New work should choose between point-link kinematics and connector-frame joints based on whether the part needs orientation.
 
 For multi-file assemblies, a file that returns an `Assembly` is importable via [`require()`](/docs/core#require) and yields an `ImportedAssembly`. Use `mergeInto()` to flatten a sub-assembly into a parent assembly.
 
+**Point-link example**
+
+This snippet mates a marker to the solved `tip` point. It does not orient a bar along `ground -> tip`.
+
 ```ts
-const mech = assembly("Arm")
-  .addPart("base", box(80, 80, 20).translate(0, 0, -10), {
-    metadata: { material: "PETG", process: "FDM", qty: 1 },
+const marker = box(8, 8, 4).withConnectors({
+  center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
+});
+
+const mech = assembly("Linkage")
+  .link("ground", { at: [0, 0, 0], fixed: true })
+  .link("worldX", { at: [10, 0, 0], fixed: true })
+  .link("tip", { at: [40, 0, 0] })
+  .edgeBetweenLinks("ground", "tip", { name: "bar" })
+  .addAngleBetweenLinks("worldX", "ground", "tip", {
+    name: "theta",
+    control: { min: 0, max: 120, default: 30 },
   })
-  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
-  .addRevolute("shoulder", "base", "link", {
-    axis: [0, 1, 0],
-    min: -30, max: 120, default: 25,
-    frame: Transform.identity().translate(0, 0, 20),
+  .addPart("Tip marker", marker, { mate: { connector: "center", toLink: "tip" } });
+
+return mech;
+```
+
+```ts
+assembly(name?: string): Assembly
+```
+
+---
+
+## Classes
+
+### `Assembly`
+
+Container for a kinematic mechanism made up of links, relationships, and parts.
+
+Assembly has two related but different motion tools:
+
+- **Link graph kinematics** (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) solve named point positions. A link is a point, not a rigid-body frame or bone. Connector-to-link mates then place geometry on the solved graph: one mate translates a connector origin onto a link, two mates orient a part so it spans between two solved links, and a third mate pins roll about that span.
+- **Connector-frame joints** (`connect()` / `match()`) align full connector frames and derive joint frame + axis from `origin`, `axis`, and `up`. Use this for serial articulated geometry such as hips, knees, hinges, drums, sliders, and wheels where the physical part orientation matters.
+
+Use link graphs when the hard part is solving positions, especially closed loops. Use connector-frame joints when the hard part is a serial tree of explicit rigid-body joint frames such as hinges, sliders, drums, and wheels.
+
+**Point-link quick start**
+
+This attaches a marker to a solved point. It is intentionally not a bone or oriented part example.
+
+```ts
+const marker = box(8, 8, 4).withConnectors({
+  center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
+});
+
+const mech = assembly("Linkage")
+  .link("ground", { at: [0, 0, 0], fixed: true })
+  .link("worldX", { at: [10, 0, 0], fixed: true })
+  .link("tip", { at: [40, 0, 0] })
+  .edgeBetweenLinks("ground", "tip", { name: "bar" })
+  .addAngleBetweenLinks("worldX", "ground", "tip", {
+    name: "theta",
+    control: { min: 0, max: 120, default: 30 },
+  })
+  .addPart("Tip marker", marker, {
+    mate: { connector: "center", toLink: "tip" },
   });
 
-return mech; // auto-solved at defaults, renders all parts
+return mech;
+```
+
+Returning an unsolved `Assembly` keeps the graph available to the runtime. Return a `SolvedAssembly` directly for a specific control state:
+
+```ts
+return mech.solve({ theta: 60 });
+```
+
+**Frame-aware serial joint**
+
+```ts
+const hip = cylinder(12, 10).withConnectors({
+  socket: connector("hinge", {
+    origin: [0, 0, 6],
+    axis: [0, 0, 1],
+    up: [1, 0, 0],
+    kind: "revolute",
+  }),
+});
+
+const upperLeg = box(60, 10, 8).translate(30, 0, -4).withConnectors({
+  hip: connector("hinge", {
+    origin: [0, 0, 0],
+    axis: [0, 0, -1],
+    up: [1, 0, 0],
+    kind: "revolute",
+  }),
+});
+
+return assembly("Leg")
+  .addPart("Hip", hip)
+  .addPart("Upper Leg", upperLeg)
+  .connect("Hip.socket", "Upper Leg.hip", { as: "hip", min: -35, max: 55 })
+  .solve({ hip: 20 });
+```
+
+**Return types**
+
+| Return value | Standalone | `require()` result type |
+|---|---|---|
+| `Assembly` (unsolved) | yes | `ImportedAssembly` |
+| `SolvedAssembly` | yes | `SolvedAssembly` |
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | — |
+
+**Kinematics**
+
+#### `link()` — Add a named kinematic link to the assembly graph.
+
+Links are assembly-native solved points. They can exist before any geometry is attached, can be displayed by the viewport, and are solved by link/edge/angle constraints.
+
+A link is not a rigid-body frame. It has a world position but no orientation basis. Use `connect()` when a physical part must inherit a connector frame and rotate about a real hinge/slider axis.
+
+```ts
+link(name: string, options?: AssemblyLinkOptions): Assembly
+```
+
+**`AssemblyLinkOptions`**
+- `at?: [ number, number, number ]` — Initial world-space position of this link before kinematic constraints solve it.
+- `fixed?: boolean` — Keep the link locked at its authored `at` position during solves.
+- `metadata?: Record<string, unknown>` — User metadata carried through the kinematic graph for inspection and tooling.
+
+#### `edgeBetweenLinks()` — Add a relationship edge between two kinematic links.
+
+By default the edge captures the authored distance between links as a structural length. Pass `{ length: 'free' }` or `{ visualOnly: true }` for a non-structural overlay edge.
+
+```ts
+edgeBetweenLinks(a: string, b: string, options?: AssemblyEdgeBetweenLinksOptions): Assembly
+```
+
+**`AssemblyEdgeBetweenLinksOptions`**: `name?: string`, `length?: number | "lockCurrent" | "free"`, `min?: number`, `max?: number`, `visualOnly?: boolean`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
+`AssemblyKinematicControlOptions`: `{ min?: number, max?: number, default?: number, unit?: string }`
+
+#### `addAngleBetweenLinks()` — Add an angle relationship among three kinematic links.
+
+The middle link is the vertex. When `control` is set, `solve(state)` reads the control value from `state[name]` and solves dependent links from that driven angle.
+
+```ts
+addAngleBetweenLinks(a: string, b: string, c: string, options?: AssemblyAngleBetweenLinksOptions): Assembly
+```
+
+**`AssemblyAngleBetweenLinksOptions`**: `name?: string`, `value?: number`, `min?: number`, `max?: number`, `control?: boolean | AssemblyKinematicControlOptions`, `limit?: AssemblyKinematicLimitOptions`, `metadata?: Record<string, unknown>`
+
+`AssemblyKinematicLimitOptions`: `{ min?: number, max?: number }`
+
+#### `addAngleBetweenLinkSegmentAndWorldDirection()` — Add an absolute angle relationship from a world direction to a link segment.
+
+The first link is the vertex/pivot and the second link is the moving point. A value of `0` places `fromLink -> toLink` along `direction` in the mechanism plane; positive angles rotate counter-clockwise in that plane.
+
+Use `Points.polar(1, angleDeg)` when the reference direction is planar and angle-based instead of axis-aligned.
+
+```ts
+addAngleBetweenLinkSegmentAndWorldDirection(fromLink: string, toLink: string, direction: Vec3, options?: AssemblyAngleBetweenLinksOptions): Assembly
 ```
 
+#### `describeKinematics()` — Return the assembly-native kinematic graph definition.
+
 ```ts
-assembly(name?: string): Assembly
+describeKinematics(): AssemblyKinematicGraphDef
 ```
 
-#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
+**Structure**
+
+#### `addPart()` — Add a named part to the assembly.
+
+Connectors declared on the part (via `withConnectors()`) are captured automatically. Parts are positioned at world origin by default unless a `transform` is provided in `options`. For root parts (no incoming joint), `transform` is their final world position.
+
+`options.mate` is for point-link attachments. During `solve()`, ForgeCAD translates the part so the named connector origin lands on the solved link position. The part keeps its existing orientation; connector `axis` and `up` are not used for link mating. Use this for markers, sensors, labels, and other geometry that should ride on a solved point. Use `connect()` for oriented physical parts such as limbs, levers, hinges, and wheels.
 
-This is a convenience wrapper for single-shape, single-joint use cases. It calls `param()` to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
+When a part is a [`ShapeGroup`](/docs/core#shapegroup), name the group children explicitly to get readable viewport labels (e.g. `"Base Assembly.Body"` instead of `"Base Assembly.1"`):
 
 ```ts
-const arm = joint("Shoulder", armShape, [0, 0, 20], {
-  axis: [0, 1, 0],
-  min: -30, max: 120, default: 25,
-});
-return arm;
+const housing = group(
+  { name: "Body", shape: body },
+  { name: "Lid", shape: lid },
+);
+assembly.addPart("Base Assembly", housing);
 ```
 
 ```ts
-joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
+addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
 ```
 
-`RevoluteJointOpts`: `{ axis?: [ number, number, number ], min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
 
----
-
-## Classes
-
-### `Assembly`
-
-Container for a kinematic mechanism made up of named parts and joints.
+**`AssemblyPartMateInput`**
+- `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
+- `toLink: string` — Name of the link this connector's origin is pinned to.
+- `aimLink?: string` — Optional second link to orient toward. When set, the part is rotated so the connector's **axis** aims from `toLink` toward `aimLink`, posing an oriented bone instead of only translating it. For full pose without relying on a connector axis, declare a second mate (two connectors → two links).
 
-An assembly is a directed graph where **parts** are nodes and **joints** are directed edges from parent to child. The graph must be a forest (one or more trees with no cycles). Root parts (no incoming joint) are fixed to world space.
+#### `frame()` — Add a named rig frame to the assembly.
 
-Each joint carries a `frame` transform (from the parent part frame to the joint's zero-state frame) and a motion formula:
+A frame is a solved pose: `origin` plus orientation. `axis` is the frame's primary direction and `up` fixes roll around that axis. Use frames for robot links, joint axes, and parts that must carry orientation. Use `link()` for solved points in distance/angle graphs.
 
-```
-childWorld = parentWorld × frame × motion(value) × childBase
+```ts
+frame(name: string, options: AssemblyFrameOptions): Assembly
 ```
 
-Three joint types are supported:
+**`AssemblyFrameOptions`**: `origin: [ number, number, number ]`, `axis: [ number, number, number ]`, `up: [ number, number, number ]`, `fixed?: boolean`, `metadata?: Record<string, unknown>`
 
-- **revolute** — rotates the child around an axis by `value` degrees
-- **prismatic** — translates the child along an axis by `value` mm
-- **fixed** — no motion; rigidly attaches the child at `frame`
+#### `fixedJoint()` — Rigidly attach a child rig frame to a parent rig frame.
 
-**Quick start**
+Fixed joints carry frame hierarchy but do not expose a Motion control.
 
 ```ts
-const mech = assembly("Arm")
-  .addPart("base", box(80, 80, 20).translate(0, 0, -10))
-  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
-  .addJoint("shoulder", "revolute", "base", "link", {
-    axis: [0, 1, 0],
-    min: -30, max: 120, default: 25,
-    frame: Transform.identity().translate(0, 0, 20),
-  });
-
-return mech; // auto-solved at defaults
+fixedJoint(name: string, options: AssemblyFixedFrameJointOptions): Assembly
 ```
 
-Returning an unsolved `Assembly` auto-solves at default joint values. Return a `SolvedAssembly` directly for a specific pose:
+`AssemblyFixedFrameJointOptions`: `{ parent: string, child: string, metadata?: Record<string, unknown> }`
+
+#### `revoluteJoint()` — Add a revolute rig-frame joint.
+
+The child frame rotates around the parent frame's `axis` direction. Moving frame joints appear in Motion by default; pass `control: false` to keep the joint solved at its default value without showing a Motion control.
 
 ```ts
-return mech.solve({ shoulder: 60 });
+revoluteJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly
 ```
 
-**Return types**
+**`AssemblyMovingFrameJointOptions`**: `parent: string`, `child: string`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `control?: boolean`, `metadata?: Record<string, unknown>`
 
-| Return value | Standalone | `require()` result type |
-|---|---|---|
-| `Assembly` (unsolved) | yes | `ImportedAssembly` |
-| `SolvedAssembly` | yes | `SolvedAssembly` |
+#### `prismaticJoint()` — Add a prismatic rig-frame joint.
 
-**Properties:**
+The child frame translates along the parent frame's `axis` direction. Moving frame joints appear in Motion by default; pass `control: false` to keep the joint solved at its default value without showing a Motion control.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
+```ts
+prismaticJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly
+```
 
 **Connectors**
 
@@ -7142,6 +7637,10 @@ Use the single-argument overload to attach assembly-level connectors — these a
 withConnectors(partName: string, connectors: Record<string, ConnectorInput>): Assembly
 ```
 
+**`PortInput`**: `origin?: [ number, number, number ]`, `axis?: [ number, number, number ]`, `start?: [ number, number, number ]`, `end?: [ number, number, number ]`, `up?: [ number, number, number ]`, `kind?: JointType`, `min?: number`, `max?: number`
+
+`ConnectorInput`: `{ connectorType?: string, gender?: ConnectorGender, measurements?: Record<string, number | string> }`
+
 #### `getConnectors()` — Get connectors declared on a part in part-local space.
 
 ```ts
@@ -7158,23 +7657,35 @@ getConnector(ref: string): { partName: string; connectorName: string; connector:
 
 Connector references use `"PartName.connectorName"` format. The system aligns connector origins (child connector lands exactly on parent connector) and derives the joint frame and axis from the connector geometry — no manual `frame` or `axis` math needed.
 
+Use `connect()` for frame-aware articulated geometry. A connector's `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` is the secondary orientation vector that locks the part's zero-angle twist. If `up` is omitted, ForgeCAD chooses a deterministic perpendicular vector, but authored mechanisms should provide `up` whenever rest orientation matters.
+
 **Face-to-face convention:** Connectors always meet face-to-face, like a USB plug meeting a socket. Each connector's axis points "outward" from its part. When two connectors mate, the system brings them together so their axes oppose (anti-parallel). This is the same convention used by `matchTo()`.
 
 For a revolute joint (hinge), both connectors' axes should point outward from their respective parts along the hinge line. For a prismatic joint (slider), both axes should point along the slide direction from their part's perspective.
 
+**Mirrored revolute axes:** Revolute values follow the right-hand rule around the joint axis. If a bilateral mechanism mirrors a hinge axis, for example `[1, 0, 0]` on the right side and `[-1, 0, 0]` on the left side, the same physical `+theta` value rotates the two sides in opposite fore/aft senses. The mirrored pose uses the negated revolute value; physical limits mirror as `[min, max] -> [-max, -min]`. Prismatic joints do not have this handedness flip. For bilateral mechanisms, prefer side-neutral link controls or an explicit state mapping when you want equal semantic pose values on both sides.
+
 The joint type is inferred from the connector's `kind` field if not specified in `options`.
 
 When connectors are defined with `start`/`end`, you can control which point on each connector meets via `align` / `parentAlign` / `childAlign` (`'start'`, `'middle'`, `'end'`).
 
-Use `connect()` when connector origins must physically coincide (flange-to-flange, bolt-into-bore). For mechanisms where parts share an axis but are deliberately spaced apart, use `addRevolute()` with pre-positioned parts instead.
+Use `connect()` when connector origins must physically coincide (flange-to-flange, bolt-into-bore).
 
 ```ts
 // Hinge: both axes point outward along the hinge line
 const frame = box(100, 10, 80).withConnectors({
-  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, 1] }),
+  hinge: connector("hinge", {
+    origin: [0, 0, 40],
+    axis: [0, 0, 1],
+    up: [1, 0, 0],
+  }),
 });
 const door = box(60, 4, 80).withConnectors({
-  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, -1] }),
+  hinge: connector("hinge", {
+    origin: [0, 0, 40],
+    axis: [0, 0, -1],
+    up: [1, 0, 0],
+  }),
 });
 assembly("Door")
   .addPart("Frame", frame)
@@ -7186,6 +7697,16 @@ assembly("Door")
 connect(parentConnectorRef: string, childConnectorRef: string, options?: ConnectOptions): Assembly
 ```
 
+**`ConnectOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `flip?` | `boolean` | This parameter is ignored. If your connectors produce wrong orientation, fix the connector axis directions instead of using flip. |
+| `parentAlign?` | `PortAlign` | Which point on the parent connector to align: 'start', 'middle' (default), or 'end'. |
+| `childAlign?` | `PortAlign` | Which point on the child connector to align: 'start', 'middle' (default), or 'end'. |
+| `align?` | `PortAlign` | Shorthand: set both parentAlign and childAlign at once. |
+| `as?`, `type?`, `min?`, `max?`, `default?`, `unit?`, `effort?`, `velocity?`, `damping?`, `friction?` | | — |
+
 #### `match()` — Auto-create a joint by matching typed connectors between two parts.
 
 Connectors can carry a `connectorType` string and a `gender` (`'male'`, `'female'`, or `'neutral'`). `match()` validates type and gender compatibility (use `{ force: true }` to skip validation) and creates the joint automatically from the connector's `kind` metadata.
@@ -7208,13 +7729,15 @@ const mech = assembly("Door")
   .addPart("Frame", frame)
   .addPart("Door", door)
   .match("Door", "Frame", { hinge_top: "hinge_top", hinge_bottom: "hinge_bottom" });
-// Revolute connectors → auto-creates revolute joint. No manual addRevolute needed.
+// Matching connectors computes the placement relationship automatically.
 ```
 
 ```ts
 match(childPartName: string, parentPartName: string, pairs: Record<string, string>, options?: MatchToOptions & { as?: string; }): Assembly
 ```
 
+`MatchToOptions`: `{ force?: boolean, angle?: number, distance?: number }`
+
 **References**
 
 #### `withReferences()` — Attach named placement reference points to this assembly. These are surfaced automatically on the ImportedAssembly when this file is imported via require(), so consumers can use placeReference() without re-declaring them. Returns a new Assembly — does not mutate.
@@ -7223,22 +7746,28 @@ match(childPartName: string, parentPartName: string, pairs: Record<string, strin
 withReferences(refs: Pick<PlacementReferenceInput, "points">): Assembly
 ```
 
-**Solving**
+**`PlacementReferenceInput`**: `points?: Record<string, [ number, number, number ]>`, `edges?: Record<string, PlacementEdgeRef>`, `surfaces?: Record<string, PlacementSurfaceRef>`, `objects?: Record<string, PlacementObjectInput>`
+
+`PlacementEdgeRef`: `{ start: Vec3, end: Vec3 }`
+
+`PlacementSurfaceRef`: `{ center: Vec3, normal: Vec3 }`
 
-#### `solve()` — Solve the assembly at the given joint state and return positioned parts.
+**Solving**
 
-Performs a depth-first traversal of the joint graph. Each joint's value is taken from `state`, falling back to `defaultValue`. Coupled joints compute their value from source joints. Values outside `[min, max]` are clamped (a warning is added to `SolvedAssembly.warnings()`).
+#### `solve()` — Solve the assembly at the given control state and return positioned parts.
 
-If mate constraints were registered via `mate()`, the solver runs a pre-pass to derive base transforms, then the kinematic DFS applies joints on top of those positions.
+Solves assembly-native kinematic links first. Controlled `addAngleBetweenLinks()` relationships read values from `state` by name, clamp to their declared limits, and expose the solved graph on `SolvedAssembly.kinematics`. Angles solve in the plane of their three authored link positions, so a limb that swings out of the `z = 0` plane poses correctly; structural edges hold their bone lengths so a fully angle-driven serial chain follows forward kinematics.
 
-**Pitfall — [`jointsView`](/docs/viewport#jointsview) double-rotation:** When calling `toJointsView()`, always solve at the rest pose (all joint values = 0 or default). Solving at a non-zero angle and then animating will double-rotate parts. Use the `defaults` option on `toJointsView()` to set the initial display angle instead.
+Connector mates declared on `addPart(..., { mate })` attach geometry to solved links while preserving part and connector identity:
 
-This pitfall only applies when `toJointsView()` is active. If you only want a static posed result, return the solved assembly directly and skip `toJointsView()`.
+- one mate **positions** the connector origin on its link;
+- a mate with `aimLink` (or a second mate to another link) also **orients** the part, rotating an oriented bone to span its links rather than only translating it;
+- a third mate **pins the roll** about the bone axis (full frame), e.g. a bore or clevis that must face a specific way.
 
-**Example — static posed output (no `toJointsView()`)**
+Connector-frame joints created by `connect()` / `match()` are also evaluated; their values are read from `state` by joint name and clamped to joint limits.
 
 ```ts
-return mech.solve({ shoulder: 45, elbow: -20 });
+return mech.solve({ theta: 45 });
 ```
 
 ```ts
@@ -7253,156 +7782,30 @@ solve(state?: JointState): SolvedAssembly
 mate(fn: (m: MateBuilder) => void): Assembly
 ```
 
-#### `addFrame()` — Add a virtual reference frame (no geometry) to the assembly graph.
-
-Useful when you need a named pivot point or coordinate frame that has no visual geometry. Acts like a zero-volume part and can be connected to other parts via joints.
-
-```ts
-addFrame(name: string, options?: PartOptions): Assembly
-```
-
-#### `addPart()` — Add a named part to the assembly.
-
-Connectors declared on the part (via `withConnectors()`) are captured automatically. Parts are positioned at world origin by default unless a `transform` is provided in `options`. For root parts (no incoming joint), `transform` is their final world position.
-
-When a part is a [`ShapeGroup`](/docs/core#shapegroup), name the group children explicitly to get readable viewport labels (e.g. `"Base Assembly.Body"` instead of `"Base Assembly.1"`):
-
-```ts
-const housing = group(
-  { name: "Body", shape: body },
-  { name: "Lid", shape: lid },
-);
-assembly.addPart("Base Assembly", housing);
-```
-
-```ts
-addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
-```
-
-#### `addJoint()` — Add a kinematic joint between a parent and child part.
-
-`frame` is a transform from the **parent part frame** to the **joint frame at zero state**. The child's world position is computed as:
-
-```
-childWorld = parentWorld × frame × motion(value) × childBase
-```
-
-For revolute joints `value` is in degrees; for prismatic joints `value` is in mm. Coupled joints (see `addJointCoupling`) ignore the `state` value passed to `solve()` and compute their value from source joints.
-
-```ts
-addJoint(name: string, type: JointType, parent: string, child: string, options?: JointOptions): Assembly
-```
-
-#### `addRevolute()` — Shorthand for `addJoint(name, 'revolute', parent, child, options)`.
-
-```ts
-addRevolute(name: string, parent: string, child: string, options?: JointOptions): Assembly
-```
-
-#### `addPrismatic()` — Shorthand for `addJoint(name, 'prismatic', parent, child, options)`.
-
-```ts
-addPrismatic(name: string, parent: string, child: string, options?: JointOptions): Assembly
-```
-
-#### `addFixed()` — Shorthand for `addJoint(name, 'fixed', parent, child, options)`.
-
-Fixed joints rigidly attach a child part to its parent at `frame` with no motion. Before calling `mergeInto()`, use `addFixed()` to collapse multiple root parts into a single root.
-
-```ts
-addFixed(name: string, parent: string, child: string, options?: JointOptions): Assembly
-```
-
-#### `addJointCoupling()` — Link a joint's value to a linear combination of other joint values.
-
-The driven joint's value is computed as:
-
-```
-driven = offset + Σ(ratio_i × source_i)
-```
-
-Coupled joints ignore any value passed in `solve(state)` — a warning is emitted if you try to override one. Coupling cycles are rejected. You cannot sweep a coupled joint directly; sweep one of its source joints instead.
-
-```ts
-assembly
-  .addRevolute("Steering", "Base", "Turret", { axis: [0, 0, 1] })
-  .addRevolute("WheelDrive", "Turret", "Wheel", { axis: [1, 0, 0] })
-  .addRevolute("TopGear", "Base", "TopInput", { axis: [0, 0, 1] })
-  .addJointCoupling("TopGear", {
-    terms: [
-      { joint: "Steering", ratio: 1 },
-      { joint: "WheelDrive", ratio: 20 / 14 },
-    ],
-  });
-```
-
-```ts
-addJointCoupling(jointName: string, options: JointCouplingOptions): Assembly
-```
-
-#### `addGearCoupling()` — Link two revolute joints via a gear ratio.
-
-Choose exactly one ratio source:
+#### `edgeBetweenFrames()` — Add a visual skeleton edge between two rig frame origins.
 
-- `ratio` — explicit numeric ratio (driven/driver, negative for external mesh)
-- `pair` — a `GearRatioLike` from `lib.gearPair`, `lib.bevelGearPair`, etc. (uses `pair.jointRatio`)
-- `driverTeeth` + `drivenTeeth` — auto-computes ratio; use `mesh` to control sign (`'external'` = negative/opposite rotation, `'internal'` = positive, `'bevel'`/`'face'` = negative)
-
-When `pair` carries a `phaseDeg`, it is auto-applied as the coupling `offset` to align teeth correctly. Override with `offset: 0` if gear shapes already have the phase baked in.
-
-```ts
-const pair = lib.gearPair({ pinion: { module: 1.25, teeth: 14 }, gear: { module: 1.25, teeth: 42 } });
-assembly
-  .addRevolute("Pinion", "Base", "PinionPart", { axis: [0, 0, 1] })
-  .addRevolute("Driven", "Base", "GearPart", { axis: [0, 0, 1] })
-  .addGearCoupling("Driven", "Pinion", { pair });
-```
+Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
 
 ```ts
-addGearCoupling(drivenJointName: string, driverJointName: string, options?: GearCouplingOptions): Assembly
+edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly
 ```
 
-#### `sweepJoint()` — Sample a joint through its motion range, collecting collision data at each step.
+`AssemblyFrameEdgeOptions`: `{ name?: string, metadata?: Record<string, unknown> }`
 
-Divides `[from, to]` into `steps` intervals (producing `steps + 1` frames). At each sample, the assembly is solved with the sweeping joint at that value and `baseState` for all others. Returns one `JointSweepFrame` per sample with the joint value, collision findings, and any solve warnings.
+#### `linkToward()` — Create a derived link at a fixed distance from `fromLink` toward `towardLink`.
 
-You cannot sweep a coupled joint — sweep one of its source joints instead.
+Derived links are trace/reference points. They are recomputed after the primary link solve and cannot participate in structural edges or angle constraints.
 
 ```ts
-const sweep = mech.sweepJoint("elbow", -10, 135, 12, { shoulder: 35 });
-const hits = sweep.filter(frame => frame.collisions.length > 0);
-console.log(`Collisions at ${hits.length} of ${sweep.length} poses`);
+linkToward(name: string, fromLink: string, towardLink: string, distance: number): Assembly
 ```
 
-```ts
-sweepJoint(jointName: string, from: number, to: number, steps: number, baseState?: JointState, collisionOptions?: CollisionOptions): JointSweepFrame[]
-```
-
-#### `toJointsView()` — Derive viewport joint controls from the assembly graph and register them.
-
-Solves the assembly at rest (all joints = default), then converts each joint into a `JointViewInput` with world-space pivot and axis. Fixed joints become hidden zero-range revolute entries so attached parts follow their parent during animation. Joint couplings are forwarded to the viewport automatically.
+#### `linkAwayFrom()` — Create a derived link at a fixed distance from `fromLink` away from `awayFromLink`.
 
-This method is optional. Call it only when you want viewport joint sliders, coupled controls, or playback animations. If you only want geometry, return the `Assembly` or `SolvedAssembly` directly and skip `toJointsView()`.
-
-**Critical pitfall:** Always call `toJointsView()` before solving for display. Then solve at the **rest pose** (no state overrides) and return that solved assembly result directly. Do not flatten it with `.toGroup()` if you want the viewport joint animation to keep working.
-
-Do not solve at a non-zero angle when using `toJointsView()` — the viewport will apply the same rotation again, double-rotating the part.
-
-```ts
-mech.toJointsView({
-  defaults: { J1: 30 },
-  animations: [{
-    name: "Swing", duration: 2, loop: true,
-    keyframes: [{ values: { J1: -45 } }, { values: { J1: 45 } }, { values: { J1: -45 } }],
-  }],
-});
-
-// Solve at REST — viewport handles posing
-return mech.solve();
-```
+Use this for coupler trace/extension points such as the Chebyshev lambda linkage's point beyond the rocker joint.
 
 ```ts
-toJointsView(options?: ToJointsViewOptions): void
+linkAwayFrom(name: string, fromLink: string, awayFromLink: string, distance: number): Assembly
 ```
 
 #### `describe()` — Return the serializable assembly definition used by solve/inspect pipelines.
@@ -7422,7 +7825,7 @@ describe(): AssemblyDefinition
 
 A wrapper around an imported `Assembly` that provides kinematic access and convenient transform helpers.
 
-When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core#require) wraps it in an `ImportedAssembly`. This preserves the kinematic structure — you can call `solve()`, `sweepJoint()`, and `mergeInto()` — while also allowing convenience transforms that auto-solve at default values.
+When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core#require) wraps it in an `ImportedAssembly`. This preserves the kinematic structure — you can call `solve()` and `mergeInto()` — while also allowing convenience transforms that auto-solve at default values.
 
 **Kinematic access**
 
@@ -7451,7 +7854,7 @@ require("./arm.forge.js").mergeInto(robot, {
 });
 ```
 
-#### `assembly()` — The underlying Assembly — use for sweepJoint, addPart into parent, etc.
+#### `assembly()` — The underlying Assembly, for advanced composition and inspection.
 
 ```ts
 get assembly(): Assembly
@@ -7469,6 +7872,14 @@ solve(state?: JointState): SolvedAssembly
 part(name: string, state?: JointState): AssemblyPart
 ```
 
+#### `getPart()` — Return a specific named part positioned at the default solved pose.
+
+This mirrors `SolvedAssembly.getPart()` for imported assemblies. Use `solve(state).getPart(name)` when inspecting a non-default joint state.
+
+```ts
+getPart(partName: string): AssemblyPart
+```
+
 #### `toGroup()` — Convert all assembly parts to a ShapeGroup with named children. Use this for composition, transforms, or child lookup — not as a required render step for assemblies. Child names match the part names used in the assembly. Any stored placement offset and placement references are forwarded to the group.
 
 ```ts
@@ -7547,17 +7958,35 @@ color(hex: string): ShapeGroup
 child(name: string): Shape | Sketch | ShapeGroup
 ```
 
-#### `mergeInto()` — Flatten this sub-assembly's parts and joints into `parent` and wire a mount joint.
+#### `collisionReport()` — Detect overlapping part pairs at the default solved pose.
+
+This mirrors `SolvedAssembly.collisionReport()` for imported assemblies. Use `solve(state).collisionReport(options)` when inspecting a non-default joint state.
+
+```ts
+collisionReport(options?: CollisionOptions): CollisionFinding[]
+```
+
+`CollisionOptions`: `{ parts?: string[], ignorePairs?: Array<[ string, string ]>, minOverlapVolume?: number }`
+
+#### `minClearance()` — Compute the minimum gap between two parts at the default solved pose.
+
+This mirrors `SolvedAssembly.minClearance()` for imported assemblies. Use `solve(state).minClearance(partA, partB, searchLength)` when inspecting a non-default joint state.
+
+```ts
+minClearance(partA: string, partB: string, searchLength?: number): number
+```
+
+#### `mergeInto()` — Flatten this sub-assembly's parts and relationships into `parent` and wire a mount relationship.
 
-All part and joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions. After the merge, sub-assembly joints are driven from the parent using the prefixed names:
+All part, link, and legacy joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions. After the merge, controls are driven from the parent using the prefixed names:
 
 ```ts
-parent.solve({ "Left Arm.shoulder": 45, "Right Arm.shoulder": -20 })
+parent.solve({ "Left Arm.theta": 45, "Right Arm.theta": -20 })
 ```
 
-Joint couplings inside the sub-assembly are preserved and rewritten with the prefix. Ports from sub-assembly parts are forwarded with the prefix.
+Connectors from sub-assembly parts are forwarded with the prefix.
 
-The sub-assembly must have exactly one root part. If it has multiple roots, use `addFixed()` first to consolidate them before merging.
+The sub-assembly must have exactly one root part before it can be merged.
 
 ```ts
 const robot = assembly("Robot").addPart("Chassis", chassis);
@@ -7574,6 +8003,25 @@ require("./arm.forge.js").mergeInto(robot, {
 mergeInto(parent: Assembly, options: MergeIntoOptions): Assembly
 ```
 
+**`MergeIntoOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `prefix?` | `string` | Prefix applied to every part name and joint name from the sub-assembly. E.g. prefix "Left Arm" turns part "Base" into "Left Arm.Base". Strongly recommended to avoid name collisions when merging multiple instances. |
+| `mountParent` | `string` | Part name in the parent assembly to attach the sub-assembly root to. |
+| `mountJoint` | `string` | Name for the new mount joint in the parent graph. |
+| `mountType?` | `JointType` | Joint type for the mount connection (default: 'fixed'). |
+| `mountOptions?` | `JointOptions` | Frame, axis, limits, and other options for the mount joint. |
+
+**`JointOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `connectorRefs?` | `JointConnectorRefs` | Connector refs that define this joint contract. Usually set by `connect()` / `match()`. |
+| `frame?`, `origin?`, `axis?`, `min?`, `max?`, `default?`, `unit?`, `effort?`, `velocity?`, `damping?`, `friction?` | | — |
+
+`JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
+
 ### `SolvedAssembly`
 
 The result of solving an assembly at a specific joint state.
@@ -7582,7 +8030,7 @@ The result of solving an assembly at a specific joint state.
 
 **Validation**
 
-Call `collisionReport()` to detect overlapping parts, or `sweepJoint()` on the parent `Assembly` to check for interference across the joint's motion range.
+Call `collisionReport()` to detect overlapping parts at this solved pose.
 
 ```ts
 const solved = mech.solve({ shoulder: 45, elbow: -20 });
@@ -7628,6 +8076,30 @@ get mateDof(): number | null
 get mateConverged(): boolean | null
 ```
 
+#### `kinematics()` — Solved assembly-native kinematic or frame-edge overlay data, or null when no rig overlay data was declared.
+
+```ts
+get kinematics(): SolvedAssemblyKinematics | null
+```
+
+#### `getLinkPosition()` — Return the solved world position of a kinematic link.
+
+```ts
+getLinkPosition(linkName: string): Vec3
+```
+
+#### `getFrame()` — Return the solved world transform for a named rig frame.
+
+```ts
+getFrame(frameName: string): Transform
+```
+
+#### `frames()` — Return solved rig frames, including origin, axis, up, and transform.
+
+```ts
+get frames(): SolvedAssemblyFrameDef[]
+```
+
 #### `getTransform()` — Return the world-space [`Transform`](/docs/core#transform) for the named part at the solved pose.
 
 ```ts
@@ -8061,6 +8533,10 @@ const part = sheetMetal({ panel: { width: 100, height: 60 }, thickness: 1.5, ben
 flange(edge: SheetMetalEdge, options: SheetMetalFlangeOptions): SheetMetalPart
 ```
 
+**`SheetMetalFlangeOptions`**
+- `length: number` — Flange leg length in mm, measured from the outside of the bend to the tip.
+- `angleDeg?: number` — Bend angle in degrees (default: `90`). Only `90°` is supported in v1. Values other than 90 will be rejected at build time.
+
 #### `cutout()` — Subtract a 2D sketch cutout from a planar region of the sheet metal part.
 
 `region` must be `'panel'` or one of `'flange-top'`, `'flange-right'`, `'flange-bottom'`, `'flange-left'` (only available once the corresponding flange has been added). Cutouts inside bend regions are **not** supported in v1.
@@ -8080,6 +8556,11 @@ const part = sheetMetal({ panel: { width: 180, height: 110 }, thickness: 1.5, be
 cutout(region: SheetMetalPlanarRegionName, sketch: Sketch, options?: SheetMetalCutoutOptions): SheetMetalPart
 ```
 
+**`SheetMetalCutoutOptions`**
+- `u?: number` — Horizontal offset within the region, measured from the region centre (mm). Default: `0`.
+- `v?: number` — Vertical offset within the region, measured from the region centre (mm). Default: `0`.
+- `selfAnchor?: Anchor` — Anchor point on the sketch that aligns to `(u, v)`. Use `'center'` for most cases. For asymmetric profiles, verify orientation by placing one test cutout before committing to the final position. Default: `'center'`.
+
 #### `regionNames()` — Return all semantic region names currently available on this part.
 
 The returned list always includes `'panel'`. For every flange that has been added, the list also includes the corresponding `'flange-<edge>'` and `'bend-<edge>'` entries.
@@ -8349,7 +8830,7 @@ Call `robotExport()` alongside your assembly definition. The CLI commands `forge
 
 - Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
 - Separate collision meshes (convex hull by default — ~50–80% smaller)
-- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
+- Joint limits, effort/velocity/damping/friction metadata from assembly joints
 
 **Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
@@ -8365,7 +8846,7 @@ Call `robotExport()` alongside your assembly definition. The CLI commands `forge
 - Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
 - Prismatic distances are in mm in Forge; exported in meters.
 - `massKg` is preferred; `densityKgM3` is used when mass is unknown.
-- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
+- Compatibility coupling metadata, when present, maps only the primary term (largest ratio) to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```ts
 const rover = assembly("Scout")
@@ -8421,9 +8902,9 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 **`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `plugins: { diffDrive?: RobotDiffDrivePluginOptions; jointStatePublisher?: RobotJointStatePublisherOptions; }`, `world: RobotWorldOptions | null`
 
-`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
+**`AssemblyDefinition`**: `name: string`, `parts: AssemblyPartDef[]`, `joints: AssemblyJointDef[]`, `jointCouplings: AssemblyJointCouplingDef[]`, `kinematics: AssemblyKinematicGraphDef`, `frames: AssemblyFrameDef[]`, `frameJoints: AssemblyFrameJointDef[]`, `frameEdges: AssemblyFrameEdgeDef[]`
 
-`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
+**`AssemblyPartDef`**: `name: string`, `part: AssemblyPart`, `base: Transform`, `metadata?: PartMetadata`, `mates: AssemblyPartMateInput[]`, `bindToFrame?: string`
 
 **`PartMetadata`**
 
@@ -8432,6 +8913,11 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 | `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
 | `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
+**`AssemblyPartMateInput`**
+- `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
+- `toLink: string` — Name of the link this connector's origin is pinned to.
+- `aimLink?: string` — Optional second link to orient toward. When set, the part is rotated so the connector's **axis** aims from `toLink` toward `aimLink`, posing an oriented bone instead of only translating it. For full pose without relying on a connector axis, declare a second mate (two connectors → two links).
+
 **`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `connectorRefs?: JointConnectorRefs`
 
 `JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
@@ -8440,6 +8926,26 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
+**`AssemblyKinematicGraphDef`**: `links: AssemblyLinkDef[]`, `edges: AssemblyEdgeBetweenLinksDef[]`, `angles: AssemblyAngleBetweenLinksDef[]`, `derivedLinks: AssemblyDerivedLinkDef[]`
+
+`AssemblyLinkDef`: `{ name: string, at: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
+
+**`AssemblyEdgeBetweenLinksDef`**: `name: string`, `a: string`, `b: string`, `length: number | null`, `min?: number`, `max?: number`, `visualOnly: boolean`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
+`AssemblyKinematicControlOptions`: `{ min?: number, max?: number, default?: number, unit?: string }`
+
+**`AssemblyAngleBetweenLinksDef`**: `name: string`, `a?: string`, `b: string`, `c: string`, `reference?: AssemblyAngleReferenceDef`, `target?: number`, `min?: number`, `max?: number`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
+`AssemblyAngleReferenceDef`: `{ kind: "worldDirection", direction: Vec3 }`
+
+`AssemblyDerivedLinkDef`: `{ name: string, fromLink: string, referenceLink: string, distance: number, direction: AssemblyDerivedLinkDirection }`
+
+`AssemblyFrameDef`: `{ name: string, origin: Vec3, axis: Vec3, up: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
+
+**`AssemblyFrameJointDef`**: `name: string`, `type: AssemblyFrameJointType`, `parent: string`, `child: string`, `rest: Transform`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `control: boolean`, `metadata?: Record<string, unknown>`
+
+`AssemblyFrameEdgeDef`: `{ name: string, a: string, b: string, metadata?: Record<string, unknown> }`
+
 #### `dim()` — Add a dimension annotation between two points.
 
 Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
@@ -8587,18 +9093,24 @@ offsetBand(thickness: number): Sketch
 addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this
 ```
 
+`DriveWheelSpurTeethRegionOptions`: `{ name?: string, teethOnFullCircle: number, toothCount: number, firstTooth?: number, faceWidth?: number }`
+
 #### `addSolidArcBetween()` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
 
 ```ts
 addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this
 ```
 
+**`DriveWheelSolidArcRegionOptions`**: `name?: string`, `fromAngleDeg: number`, `toAngleDeg: number`, `innerRadius?: number`, `outerRadius: number`, `faceWidth?: number`, `segments?: number`
+
 #### `addShapeRegion()` — Add a fully custom region shape while preserving region metadata.
 
 ```ts
 addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this
 ```
 
+`DriveWheelShapeRegionOptions`: `{ fromAngleDeg?: number, toAngleDeg?: number, innerRadius?: number, outerRadius?: number }`
+
 #### `build()` — Build the final wheel shape with a bore connector and region metadata.
 
 ```ts
@@ -8615,7 +9127,7 @@ Pre-built parametric parts available in user scripts as `lib.*`.
 
 Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts. The catalog includes:
 
-**Fasteners and hardware patterns:** `bolt`, `nut`, `washer`, `fastenerSet`, `boltedServiceCover`, `datumEnclosureAssembly`, `snapLatchCoverAssembly`, `pinnedLeverAssembly`, `retainedShaftAssembly`, `capturedLinearSlide`, `capturedCartridgeGuideAssembly`, `livingHingeCoverAssembly`, `knuckledHingeAssembly`, `clevisPinJointAssembly`, `seatedBearingAssembly`, `cableGlandAnchorAssembly`, `hoseBarbPortAssembly`, `routedTubeClipAssembly`, `pcbTerminalBlockAssembly`, `thumbScrewClampAssembly`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern`
+**Fasteners and hardware patterns:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern`
 
 **Structure:** `tube`, `pipe`, `bracket`, `pipeRoute`, `elbow`, `tSlotProfile`, `tSlotExtrusion`, `profile2020BSlot6Profile`, `profile2020BSlot6`
 
@@ -8649,24 +9161,8 @@ Sizes outside the supported ranges will throw at runtime with a descriptive erro
 - `nut(diameter: number, options?: { pitch?: number; height?: number; acrossFlats?: number; segments?: number; }): Shape` — ISO-style hex nut with a threaded bore. **Details** Constructed from the intersection of three rotated slabs with a cylindrical bore subtracted. The nut is centered at the origin, height along Z. Default proportions follow ISO 4032 loosely: height ≈ 0.8×diameter, across-flats ≈ 1.6×diameter. The bore is a clearance bore (not modelled with helical threads) for rendering efficiency. For standard M-size nuts pre-configured for a complete joint, use { **Example** ```ts const n = lib.nut(5); // M5 nut ```
 - `washer(size: MetricSize, options?: { standard?: WasherStandard; segments?: number; }): Shape` — ISO metric flat washer (DIN 125-A). **Details** Returns a flat ring centered at the origin, thickness along Z. Dimensions are taken from { **Example** ```ts const w = lib.washer('M5'); // DIN 125-A M5 washer ```
 - `fastenerSet(size: MetricSize, boltLength: number, options?: FastenerSetOptions): FastenerSetResult` — Complete ISO metric fastener set — bolt, nut, optional washers, and matching hole cutters. **Details** Returns all geometry for one bolted joint: the bolt, nut, up to two washers, a clearance-hole cutter, and a tap-drill cutter. All shapes are returned **un-positioned** (each on the Z-axis). Place them with `.translate()`. Sizes outside M4–M10 are supported for the washer (M2–M10); unsupported combinations will throw. **Example** ```ts const hw = lib.fastenerSet('M5', 20); const topPlate = box(60, 40, 8).translate(0, 0, 12) .subtract(hw.clearanceHole.translate(15, 10, 12)); const botPlate = box(60, 40, 8) .subtract(hw.clearanceHole.translate(15, 10, 0)); return [ { name: 'Top Plate', shape: topPlate }, { name: 'Bot Plate', shape: botPlate }, { name: 'Bolt', shape: hw.bolt.translate(15, 10, 20) }, { name: 'Nut', shape: hw.nut.translate(15, 10, -4) }, ]; ```
-- `boltedServiceCover(options: BoltedServiceCoverOptions): BoltedServiceCoverResult` — Bolted service-cover interface with real seats, aligned holes, gasket, fused pull tabs, and installed screws. **Details** This is a higher-level mechanical pattern for the common "removable service cover" failure mode. It creates the parent ledge, cover, gasket, and screws from one shared bolt pattern so agents do not place decorative screw heads or floating pull tabs by eye. Coordinate convention: the parent frame sits from `z=0` to `parentThickness`, the gasket sits on the ledge, the cover sits above the gasket, and screw shafts run downward through the cover into the parent. All parts are centered on the XY origin. **Example** ```ts const cover = lib.boltedServiceCover({ width: 90, depth: 56, screwSize: 'M4', ledgeWidth: 10, boltInset: [6, 6], }); verify.equal('four retained cover screws', cover.screws.length, 4); return cover.parts; ```
-- `datumEnclosureAssembly(options: DatumEnclosureAssemblyOptions): DatumEnclosureAssemblyResult` — Datum-driven enclosure tray with shared wall, ledge, standoff, cover, gasket, port, and screw geometry. **Details** This pattern is for electronics boxes, thermostat backplates, service-stack housings, camera housings, and small fixtures where generated models often place panels, ribs, bosses, ports, and covers by eye. The tray, internal ledges, standoffs, ribs, service port, gasket, cover holes, and installed screws all come from one datum system. This keeps screw axes, boss locations, wall thickness, and service openings aligned instead of relying on independent magic numbers. Coordinate convention: X/Y are the enclosure footprint, Z is up. The base tray starts at `z=0` and rises to `height`; the gasket and cover sit above the top ledge with small explicit face clearances. **Example** ```ts const enclosure = lib.datumEnclosureAssembly({ width: 96, depth: 64, height: 18, }); verify.notColliding('cover clears enclosure gasket', enclosure.cover, enclosure.gasket); verify.inRange('cover stack has small seating clearance', enclosure.dims.faceClearance, 0.01, 0.08); return enclosure.parts; ```
-- `snapLatchCoverAssembly(options: SnapLatchCoverAssemblyOptions): SnapLatchCoverAssemblyResult` — Snap-retained cover with a receiver frame, latch windows, underside catch lands, and fused snap hooks. **Details** This pattern is for covers, cartridges, clasps, and small housings where agents often add decorative tabs without a catch. The receiver has a real service opening plus two clearance latch windows. The cover is one fused part with two flexible-looking snap fingers that pass through the windows and barb under the receiver underside. Nothing intersects in the final assembly; the hook geometry sits close enough to the catch lands to prove retention intent. Coordinate convention: the receiver frame sits from `z=0` to `parentThickness`; the cover is seated just above the receiver on +Z. Two snap hooks sit on the +/-Y ledges and tuck under the receiver. **Example** ```ts const snapCover = lib.snapLatchCoverAssembly({ width: 72, depth: 44, }); verify.notColliding('snap hooks clear receiver windows', snapCover.cover, snapCover.parent); verify.inRange('snap cover has small seating clearance', snapCover.dims.faceClearance, 0.01, 0.08); return snapCover.parts; ```
-- `pinnedLeverAssembly(options: PinnedLeverAssemblyOptions): PinnedLeverAssemblyResult` — Retained pinned lever stack with a fused hub/arm/grip, low stop land, pivot pin, bore cutters, and thrust washers. **Details** This pattern is for the common handle/lever failure mode where a visual arm, hub, washer, and pin are placed near each other but never form a credible mechanism. The lever body is one fused part, the pin runs through aligned bores, washers sit on both sides of the lever, and the support includes a bearing land plus an optional low stop land beside the lever path. Coordinate convention: pivot axis is +Z at the XY origin. The support starts at `z=0`, the lower washer sits on top of the support, the lever sits on the lower washer, the upper washer sits on the lever, and the retained pin spans the full stack. **Example** ```ts const lever = lib.pinnedLeverAssembly({ armLength: 54, armWidth: 10, pinDiameter: 5, }); verify.equal('lever stack has five retained parts', lever.parts.length, 5); return lever.parts; ```
-- `retainedShaftAssembly(options: RetainedShaftAssemblyOptions): RetainedShaftAssemblyResult` — Retained shaft, washer, knob, and support-cheek stack for trunnions, pivots, and adjustable clamps. **Details** This pattern replaces the common "pin, washers, and knob are near each other" visual shortcut with a mechanically accountable shaft stack. The two support cheeks get matching clearance bores, the through shaft spans the whole stack, washers and knobs share the same axis, and retaining heads keep the knobs from reading as loose floating cylinders. Coordinate convention: the shaft axis is +X through the world origin. Support cheeks are centered at `x = +/- supportSpacing / 2`. The supports are bored for clearance, so collision inspection should report no support/shaft overlap while the connectivity audit still sees one retained stack. **Example** ```ts const trunnion = lib.retainedShaftAssembly({ supportSpacing: 96, shaftDiameter: 8, supportHeight: 42, }); verify.equal('retained shaft stack has seven parts', trunnion.parts.length, 7); return trunnion.parts; ```
-- `capturedLinearSlide(options: CapturedLinearSlideOptions): CapturedLinearSlideResult` — Captured linear slide with a U-channel rail, return lips, end stops, and a carriage posed inside the guide. **Details** This pattern is for drawer-slide, quick-release plate, and guided-carriage models where agents often place rail details and a moving block near each other without a capture relationship. The rail is one fused part with side walls, inward lips, and end stops; the carriage is wider than the lip throat but narrower than the inner rail width, so it is mechanically captured while retaining explicit clearance. Coordinate convention: rail length is along X, width is along Y, and Z is up. The rail base starts at `z=0`; the carriage sits above the base and below the return lips. `travel=0` places the carriage at the negative-X end of travel, and `travel=maxTravel` places it at the positive-X end. **Example** ```ts const slide = lib.capturedLinearSlide({ length: 160, carriageLength: 52, travel: 42, }); verify.greaterThan('carriage is captured by return lips', slide.dims.carriageWidth, slide.dims.throatWidth); return slide.parts; ```
-- `capturedCartridgeGuideAssembly(options: CapturedCartridgeGuideAssemblyOptions): CapturedCartridgeGuideAssemblyResult` — Captured removable cartridge guide with return lips, rear stop, wide cartridge flange, and pull tab. **Details** This pattern is for pump cartridges, filter cassettes, skeg cassettes, battery cartridges, and slide-in service modules where generated models often place a tray and a loose block near each other. The guide is one fused part with side walls, inward return lips, and a rear stop. The cartridge has a wide lower flange captured under the lips and a narrower body that passes through the throat, so the model has a real retention contract without manual coordinate tuning. Coordinate convention: insertion travel is along +X. The open entry is at −X, the rear stop is at +X, the guide base starts at `z=0`, and `insertion=0` places the cartridge at the front travel limit. **Example** ```ts const cassette = lib.capturedCartridgeGuideAssembly({ length: 150, cartridgeLength: 72, }); verify.notColliding('cartridge clears guide rails', cassette.cartridge, cassette.guide); verify.greaterThan('cartridge flange is captured by lips', cassette.dims.cartridgeWidth, cassette.dims.throatWidth); return cassette.parts; ```
-- `livingHingeCoverAssembly(options: LivingHingeCoverAssemblyOptions): LivingHingeCoverAssemblyResult` — One-piece molded living-hinge cover strip with a fixed leaf, thin flexible web, cover leaf, pull lip, snap barb, and catch land. **Details** This pattern is for small polypropylene-style lids, battery doors, sample covers, blister latches, and molded service flaps where generated models often draw a decorative hinge strip between two disconnected plates. It returns one fused molded part in its as-molded flat state: fixed mounting leaf, thin hinge web, moving cover leaf, pull lip, raised snap barb, and catch land. The flexible web is intentionally much thinner than the rigid leaves and shares material with both leaves. Coordinate convention: X is hinge length/part width, Y runs from fixed leaf through hinge web to cover leaf, and Z is thickness. The hinge web is centered on `y=0`; the fixed leaf lies at −Y and the cover leaf at +Y. **Example** ```ts const livingCover = lib.livingHingeCoverAssembly({ width: 64, coverDepth: 42, }); verify.greaterThan('living hinge is much thinner than rigid leaves', livingCover.dims.flexRatio, 3); return livingCover.parts; ```
-- `knuckledHingeAssembly(options: KnuckledHingeAssemblyOptions): KnuckledHingeAssemblyResult` — Alternating knuckle hinge with two fused leaves and a retained pin. **Details** This pattern replaces hand-placed hinge barrels and pin ghosts with a mechanically accountable hinge. The fixed leaf owns every other knuckle, the moving leaf owns the alternating knuckles, all knuckles share one bore size, and the retained pin spans the full stack with heads outside the barrels. Coordinate convention: the hinge pin axis is +X through the world origin. The fixed leaf extends toward +Y. The moving leaf extends toward -Y and rotates about +X by `openAngleDeg`. **Example** ```ts const hinge = lib.knuckledHingeAssembly({ length: 70, leafLength: 28, openAngleDeg: 45, }); verify.equal('hinge has two leaves and one retained pin', hinge.parts.length, 3); return hinge.parts; ```
-- `clevisPinJointAssembly(options?: ClevisPinJointAssemblyOptions): ClevisPinJointAssemblyResult` — Clevis-style pin joint with bored yoke ears, a center link eye, and a retained pin. **Details** This pattern is for crank links, damper rod ends, pump crossheads, capo/cam pivots, and small mechanism joints where agents often place an eyelet and a pin near a bracket without modeling the captured load path. The clevis is one fused part with two bored ears and a rear bridge, the center link has a real eye and arm, and the retained pin spans the full stack with heads outside the ears. Coordinate convention: the pin axis is +Y through the world origin. The center link arm extends toward +X. The clevis bridge sits behind the eye on -X, leaving the link eye clear inside the yoke. **Example** ```ts const clevis = lib.clevisPinJointAssembly({ pinDiameter: 4, linkArmLength: 38, }); verify.equal('clevis joint has three retained parts', clevis.parts.length, 3); return clevis.parts; ```
-- `seatedBearingAssembly(options: SeatedBearingAssemblyOptions): SeatedBearingAssemblyResult` — Seated radial-bearing support with a real counterbore, shoulder, through shaft, and retaining collars. **Details** This pattern is for purchased bearings, rollers, burr-cartridge shafts, and small spindle supports where agents often place a ring and a shaft near a block without modelling the pocket that locates the bearing. The housing includes a through-bore and a larger counterbore that leaves a shoulder for the bearing outer race. The shaft is smaller than the bearing bore and carries collars outside the housing, so collision checks can distinguish intended clearance from impossible overlap. Coordinate convention: the shaft axis is +Z through the world origin. The housing block starts at `z=0`, the raised boss is on top of the block, the bearing is seated from the top counterbore, and the shaft extends above and below the housing. **Example** ```ts const bearingStack = lib.seatedBearingAssembly({ bearingOuterDiameter: 22, bearingInnerDiameter: 8, bearingWidth: 7, }); verify.greaterThan('housing has wall around bearing pocket', bearingStack.dims.bossOuterDiameter - bearingStack.dims.pocketDiameter, 4); return bearingStack.parts; ```
-- `cableGlandAnchorAssembly(options: CableGlandAnchorAssemblyOptions): CableGlandAnchorAssemblyResult` — Cable, wire, or tube gland anchor with a real panel hole, hollow gland body, compression nut, and routed cable. **Details** This pattern is for pumps, filters, electronics boxes, vents, monitors, and fixtures where generated models often leave hoses or cables terminating in space. It creates the receiving panel hole, a hollow gland body with a panel-side flange seated in a shallow pocket, a hollow compression nut, and a cable/tube that runs through the gland bore with explicit clearance. Coordinate convention: the cable axis is +X through the world origin. The panel is centered around `x=0` with thickness along X; the flange sits on the +X side of the panel and the compression nut sits on the −X side. The cable spans the full anchor. **Example** ```ts const anchor = lib.cableGlandAnchorAssembly({ cableDiameter: 6, panelThickness: 3, }); verify.notColliding('cable clears gland bore', anchor.cable, anchor.gland); verify.clearanceBetween('gland flange is seated at panel pocket', anchor.gland, anchor.panel, 0.01, 0.2); return anchor.parts; ```
-- `hoseBarbPortAssembly(options: HoseBarbPortAssemblyOptions): HoseBarbPortAssemblyResult` — Hose-barb pump/filter port with a bored receiver, shoulder, barb ridges, installed hose, and clamp band. **Details** This pattern is for pump heads, filters, vents, lab cartridges, and fluid fittings where generated models often leave tubes ending near a block. The receiver has a real through-port and raised boss, the fitting is hollow with a shoulder and multiple barb ridges, and the hose is modeled as an installed tube over the barb envelope with a clamp band. The hose bore is sized for the deformed installed hose, so collision checks distinguish the retained interface from impossible solid overlap. Coordinate convention: the fluid axis is +X through the world origin. The receiver block is centered around `x=0`; the raised boss and hose are on the +X side. **Example** ```ts const hosePort = lib.hoseBarbPortAssembly({ hoseInnerDiameter: 6, hoseOuterDiameter: 10, }); verify.notColliding('hose clears barb peaks', hosePort.hose, hosePort.fitting); verify.inRange('fitting shoulder seats near boss face', hosePort.dims.faceClearance, 0.01, 0.08); return hosePort.parts; ```
-- `routedTubeClipAssembly(options: RoutedTubeClipAssemblyOptions): RoutedTubeClipAssemblyResult` — Routed tube or cable retained by saddle clips with real bores, screw holes, and installed screws. **Details** This pattern is for hoses, wires, pump tubes, sensor leads, and appliance cable runs where generated models often draw a cylinder near a wall without clips or strain relief. The base panel has receiving screw envelopes, each saddle clip has a real through-bore around the tube and vertical screw clearances, and the installed screws share those positions. Coordinate convention: the routed tube runs along +X through the world origin. The base panel starts at `z=0`; clips sit on top of the panel, and the tube passes through their bores. **Example** ```ts const route = lib.routedTubeClipAssembly({ tubeDiameter: 6, clipCount: 3, }); verify.notColliding('tube clears clip bores', route.tube, union(...route.clips)); verify.notColliding('clip screws clear retained stack', union(...route.screws), union(route.panel, ...route.clips)); return route.parts; ```
-- `pcbTerminalBlockAssembly(options?: PcbTerminalBlockAssemblyOptions): PcbTerminalBlockAssemblyResult` — PCB terminal-block stack with a backplate, standoffs, mounting screws, pin holes, and a seated terminal block. **Details** This pattern is for thermostat backplates, appliance control panels, sensor boards, and small electronics where generated models often place a terminal block, screw heads, and holes as independent decorations. The PCB mounting holes, fused standoffs, installed screws, terminal pins, and PCB pin clearances all come from one shared datum system so the purchased block is mechanically seated and the board is actually mounted. Coordinate convention: X/Y are the board footprint, Z is up. The backplate starts at `z=0`, standoffs rise from the plate, the PCB rests on the standoffs, and the terminal block sits on top of the PCB near the front edge. **Example** ```ts const terminalStack = lib.pcbTerminalBlockAssembly({ terminalCount: 5, screwSize: 'M3', }); verify.notColliding('terminal pins clear PCB holes', terminalStack.terminalBlock, terminalStack.pcb); verify.notColliding('mounting screws clear PCB and standoff holes', union(...terminalStack.screws), union(terminalStack.pcb, terminalStack.backplate)); return terminalStack.parts; ```
-- `thumbScrewClampAssembly(options?: ThumbScrewClampAssemblyOptions): ThumbScrewClampAssemblyResult` — Thumb-screw clamp with a C-frame, threaded boss, captive pressure pad, knob, and clamped workpiece. **Details** This pattern is for bench clamps, monitor-arm desk clamps, small vise screws, capo pressure screws, fixture hold-downs, and service brackets where generated models often place a loose screw, knob, or pressure pad near a bracket. The helper creates a one-piece clamp frame with a fixed anvil pad, a bored threaded support and boss, an installed screw with a captive pressure pad and hand knob, and a representative clamped workpiece seated between the pads. Coordinate convention: the clamp screw runs along +X. The fixed anvil is on the -X side, the threaded support and knob are on the +X side, and Z is up from the base bridge. **Example** ```ts const clamp = lib.thumbScrewClampAssembly({ screwSize: 'M6', workpieceThickness: 20, }); verify.notColliding('thumb screw clears threaded boss', clamp.clampScrew, clamp.frame); verify.clearanceBetween('pressure pad is seated on workpiece', clamp.clampScrew, clamp.workpiece, -0.01, 0.05); return clamp.parts; ```
-- `pipeRoute(points: [ number, number, number ][], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. Each interior waypoint gets a torus-section bend. Straight segments connect them. Returns a single unioned Shape.
-- `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section (torus arc) for connecting two pipe directions. By default creates a bend in the XZ plane: incoming along +Z, outgoing rotated by `angle`. The bend starts at the origin, curving away from it.
+- `pipeRoute(points: [ number, number, number ][], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. This is a convenience recipe over `Curve.Route.fromPolyline()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route` directly when you need route metadata, named ports, or custom swept profiles.
+- `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section for connecting two pipe directions. This is a convenience recipe over `Curve.Arc()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route.fromPolyline()` directly when you need named route ports, segment metadata, or multi-bend pipe runs.
 - `beltDrive(options: BeltDriveOptions): BeltDriveResult` — Create a flat open-belt body around two pulley pitch circles. The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley. For more than two pulleys, the API intentionally asks for route intent before geometry is created. Use `route: "outer"` for the future outside-envelope mode, or an ordered route for future serpentine/idler layouts. ```ts const drive = lib.beltDrive({ pulleys: [ { name: "motor", center: [0, 0], pitchRadius: 12 }, { name: "output", center: [80, 0], pitchRadius: 28 }, ], beltWidth: 8, beltThickness: 2, }); return drive.belt; ```
 - `tangentLoop2d(circles: TangentCircle2D[], options?: TangentLoop2DOptions): TangentLoop2D` — Build a closed 2D route made from common tangent spans and pulley wrap arcs. Use this when you need reusable belt/chain route geometry before creating a solid body. The first implementation supports two circles. `mode: "open"` uses external tangents; `mode: "crossed"` uses internal tangents. ```ts const route = lib.tangentLoop2d([ { center: [0, 0], radius: 12 }, { center: [80, 0], radius: 28 }, ]); const belt = route.offsetBand(2).extrude(8); ```
 - `tSlotProfile(options?: TSlotProfileOptions): Sketch` — Build a 2D T-slot cross-section sketch. Default parameters describe a 20x20 B-type profile with slot 6. Use this when you want a drawing-ready profile sketch before extrusion.
@@ -8814,7 +9310,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `jointsView`, `compareWith`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `compareWith`, `cutPlane`, `mock`, `showLabels`, `highlight`
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -9001,7 +9497,7 @@ scene(options: SceneOptions): void
 
 #### `viewConfig()` — Configure viewport helper visuals for the current script execution.
 
-Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when `jointsView` is active. Multiple calls merge — later values override earlier ones per key.
+Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when joint controls are active. Multiple calls merge — later values override earlier ones per key.
 
 This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
 
@@ -9058,91 +9554,6 @@ explodeView(options?: ExplodeViewOptions): void
 - `direction?: ExplodeDirection` — Direction mode for this node
 - `axisLock?: ExplodeAxis` — Optional axis lock after direction is resolved
 
-#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
-
-Defines joints (revolute or prismatic), optional gear/rack couplings, and named animations. The viewport resolves transforms through the joint chain at display time — the script geometry is computed only once at rest pose.
-
-**Critical:** Solve the assembly at **rest pose** (all animated joints = 0). The viewport applies `jointsView` transforms on top of the returned scene. If geometry is already solved at non-zero angles, animation will double-rotate everything.
-
-```js
-// BAD — double rotation
-const solved = mech.solve({ shoulder: 45, elbow: 30 });
-jointsView({ joints: [{ name: 'shoulder', ... }] });
-return solved;
-
-// GOOD — rest pose, jointsView controls all posing
-const solved = mech.solve({ shoulder: 0, elbow: 0 });
-jointsView({
-  joints: [
-    { name: 'shoulder', child: 'Upper Arm', default: 45, ... },
-    { name: 'elbow', child: 'Forearm', parent: 'Upper Arm', default: 30, ... },
-  ],
-});
-return solved;
-```
-
-**Pivot coordinates** are world-space positions of each joint origin at rest pose. For `addRevolute('shoulder', 'Base', 'Link', { frame: Transform.identity().translate(0, 0, 20) })` where "Base" is at world origin, the pivot is `[0, 0, 20]`.
-
-**Fixed attachments** that must follow a parent during animation need a zero-angle revolute joint in the chain:
-
-```js
-{ name: 'EE_Follow', child: 'End Effector', parent: 'Last Link',
-  type: 'revolute', axis: [0, 0, 1], pivot: [linkLength, 0, 0],
-  min: 0, max: 0, default: 0 }
-```
-
-Animation values are interpolated linearly between keyframes. ForgeCAD does **not** auto-wrap revolute values across `-180/180`. Keep keyframe values continuous — a `-180 -> 171` jump spins the part the long way around. Use `-180 -> -189` instead. Author high-speed multi-turn joints as accumulating angles (`0, 360, 720, ...`) with `continuous: true`.
-
-**Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
-
-```js
-keyframes: [
-  { ticks: 3, values: { Shoulder: 20 } },  // slow segment (3x weight)
-  { ticks: 1, values: { Shoulder: -10 } }, // fast segment (1x weight)
-  { values: { Shoulder: 20 } },            // last keyframe; ticks ignored
-]
-// positions: 0, 0.75, 1.0
-```
-
-Mixing explicit `at` and omitted `at` in the same animation is not allowed.
-
-```js
-jointsView({
-  joints: [{
-    name: 'Shoulder', child: 'Upper Arm', parent: 'Base',
-    type: 'revolute', axis: [0, -1, 0], pivot: [0, 0, 46],
-    min: -30, max: 110, default: 15,
-  }],
-  animations: [{
-    name: 'Walk Cycle', duration: 1.6, loop: true,
-    keyframes: [
-      { values: { Shoulder: 20 } },
-      { values: { Shoulder: -10 } },
-      { values: { Shoulder: 20 } },
-    ],
-  }],
-});
-```
-
-```ts
-jointsView(options?: JointsViewOptions): void
-```
-
-**`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
-
-**`JointViewInput`**: `name: string`, `child: string`, `parent?: string`, `type?: JointViewType`, `axis?: JointViewAxis`, `pivot?: [ number, number, number ]`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `hidden?: boolean`
-
-`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
-
-`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
-
-`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
-
-**`JointViewAnimationKeyframeInput`**
-- `at?: number` — Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights.
-- `ticks?: number` — Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored.
-- Also: `values: Record<string, number>`
-
 #### `compareWith()` — Declare a reference model for comparison inspection.
 
 `compareWith()` lets a model carry its own comparison target for inspection workflows. `forgecad inspect compare overlay model.forge.js` uses this reference to render the same Difference Only comparison overlay as the live viewport. Amber marks candidate mismatch evidence, cyan marks reference mismatch evidence, and faint model context keeps the overlay readable. When the CLI can resolve the referenced file, the manifest also includes the same geometric score produced by `forgecad compare 3d`.
@@ -9475,6 +9886,30 @@ For deeper API coverage, load the relevant generated doc group from the skill so
 
 How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
 
+## Frame-Aware Connectors First
+
+If a part must rotate, slide, or point in a specific physical direction, define connectors and use `assembly().connect()`. A connector is a small coordinate frame on the part:
+
+- `origin` is the pivot, pin center, socket center, or contact point.
+- `axis` is the hinge line or slide direction.
+- `up` is the secondary direction that fixes the part's zero-angle twist.
+
+For a hip -> knee -> wheel chain, the upper leg should be a real part with a hip connector and a knee connector. The hip connector frame defines how the upper leg sits on the hip drum at rest; the knee connector frame defines where the next part attaches. `connect()` aligns those frames and derives the joint axis.
+
+Do not treat `up` as optional on hinges, wheels, levers, or keyed sliders. If `up` is omitted, ForgeCAD chooses a deterministic perpendicular vector, which keeps the model stable but may not match the intended mechanical rest pose.
+
+Use `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()` for solved point skeletons and closed-loop relationships. A link is a point, not a bone frame. `addPart(..., { mate: { connector, toLink } })` only moves a connector origin onto a solved link point; it does not rotate the part to aim along an edge.
+
+## Mirrored Revolute Axes
+
+Revolute joint values are physical values signed by the right-hand rule around the joint axis. If a bilateral mechanism mirrors a hinge axis, the same numeric joint value does not mean "same pose" on both sides.
+
+Example: a right ankle hinge with `axis: [1, 0, 0]` and a left ankle hinge with `axis: [-1, 0, 0]` are exact geometric mirrors at rest. But `+20` degrees around those two axes rotates the feet in opposite fore/aft senses. The mirrored pose uses `RightAnkle: 20` and `LeftAnkle: -20`.
+
+When you expose physical joint limits directly, mirror revolute limits as `[min, max] -> [-max, -min]`. Prismatic joints do not have this angle-handedness flip because their scalar value translates along the mirrored axis.
+
+For bilateral robots, legs, grippers, and suspension mechanisms, prefer a side-neutral control layer when possible: solve mirrored link positions with `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()`, then attach real parts to the solved skeleton. If you use connector-frame joints directly, make the sign mapping explicit in defaults, keyframes, and verification.
+
 ## The Cavity Rule
 
 Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.
@@ -9606,7 +10041,7 @@ stable; named scene views are still available through `--view`.
 The command tree is intentionally job-shaped:
 
 ```text
-inspect visual image|cutaway|depth|normals|objects
+inspect visual image|cutaway|depth|normals|rig|objects
 inspect surface zebra|roughness
 inspect physical components|floating|gaps
 inspect fit interference
@@ -9647,6 +10082,7 @@ Use targeted evidence commands for expensive analyses:
 ```bash
 forgecad inspect visual depth model.forge.js --camera iso
 forgecad inspect visual normals model.forge.js --camera iso
+forgecad inspect visual rig model.forge.js --camera iso
 forgecad inspect surface zebra model.forge.js --camera iso
 forgecad inspect surface roughness model.forge.js --camera iso
 forgecad inspect visual objects model.forge.js --camera iso
@@ -10132,12 +10568,33 @@ color(value: string | undefined): SdfShape
 material(props: ShapeMaterialProps): SdfShape
 ```
 
+**`ShapeMaterialProps`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
+| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
+| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
+| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
+| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
+| `wireframe?` | `boolean` | Render as wireframe. Default: false |
+| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
+| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
+| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
+| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
+| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
+| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
+| `specularColor?` | `string` | Specular highlight tint. |
+| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+
 #### `bounds()` — Set explicit preview/meshing bounds for this implicit leaf.
 
 ```ts
 bounds(bounds: SdfBounds | [ Vec3, Vec3 ]): SdfShape
 ```
 
+`SdfBounds`: `{ min: Vec3, max: Vec3 }`
+
 #### `at()` — Sculpt-style alias for translate().
 
 ```ts
@@ -10234,6 +10691,12 @@ fillWith(pattern: SdfShape): SdfShape
 fillWithGyroid(options: TpmsOptions): SdfShape
 ```
 
+**`TpmsOptions`**
+- `thickness?: number` — Dimensionless field threshold kept for compatibility. Prefer `wallThickness` for approximate millimeter units.
+- `wallThickness?: number` — Approximate physical wall thickness in millimeters.
+- `tpmsThicknessMode?: TpmsThicknessMode` — Override TPMS thickness interpretation. Defaults to metric when `wallThickness` is used, field-threshold when `thickness` is used.
+- Also: `cellSize: number`
+
 #### `fillWithSchwarzP()` — Keep only the Schwarz-P lattice inside this shape.
 
 ```ts
@@ -10384,6 +10847,10 @@ shape.surfaceDisplace((u, v) => -Math.sin(u * 2) * 0.3)
 surfaceDisplace(pattern: SurfacePattern | ((u: number, v: number) => number), options?: SurfaceDisplaceOptions): SdfShape
 ```
 
+**`SurfaceDisplaceOptions`**
+- `uv?: "auto" | "sphere" | "cylinder" | "torus" | "triplanar"` — Override auto-detected UV mode. Default: 'auto' (detects from SDF tree).
+- `triplanarSharpness?: number` — Triplanar blend sharpness — higher = crisper transitions. Default: 4. Only used in triplanar mode.
+
 #### `onion()` — Create concentric onion layers.
 
 ```ts