forgecad 0.9.14 → 0.9.15

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

@@ -7,13 +7,13 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 - **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(76 functions)*
 - **[C2: Boolean Combination](#c2-boolean-combination)** — Combine same-dimension geometry using CSG set operations. *(6 functions)*
 - **[C3: Rigid Transform](#c3-rigid-transform)** — Reposition or reorient geometry without changing its shape. *(3 functions)*
-- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(50 functions)*
+- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(52 functions)*
 - **[C5: Topology Query](#c5-topology-query)** — Select or inspect named faces and edges on a shape. *(3 functions)*
 - **[C6: Edge Feature](#c6-edge-feature)** — Modify edges of a solid — fillets, chamfers, draft, offset. *(7 functions)*
 - **[C7: Pattern Replication](#c7-pattern-replication)** — Duplicate geometry in regular arrangements (linear, circular, mirror). *(6 functions)*
 - **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(17 functions)*
 - **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(6 functions)*
-- **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(4 functions)*
+- **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(3 functions)*
 - **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(7 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(5 functions)*
@@ -1002,10 +1002,182 @@ composeChain(...steps: TransformInput[]): Transform
 
 Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
 
-#### `Helix.path()` — Create a metadata-bearing helical centerline around the Z axis.
+#### `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
+Curve.Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D
+```
+
+**`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.
+
+#### `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
+Curve.BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D
+```
+
+
+**`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
+- `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
+
+#### `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
+Curve.Arc(options: CurveArcOptions): NurbsCurve3D
+```
+
+**`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
+Curve.Line(start: Vec3, end: Vec3): NurbsCurve3D
+```
+
+#### `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
+Curve.Polyline(points: Vec3[]): Vec3[]
+```
+
+#### `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
+Curve.Spline(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.
+
+#### `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
-Helix.path(options: HelixOptions): HelixCurve
+Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
+```
+
+**`NurbsCurve3DOptions`**
+
+| 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
+Curve.Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D
+```
+
+**`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.
+
+#### `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
+Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>
+```
+
+#### `Curve.Reverse()` — 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.
+
+```ts
+Curve.Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>
+```
+
+#### `Curve.Route()` — 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.
+
+```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
+```
+
+#### `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
+Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }
 ```
 
 **`HelixOptions`**
@@ -1020,18 +1192,8 @@ 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.
-
-Overloads:
-
-- `Helix.coil(options: HelixCoilOptions): Shape`
-- `Helix.coil(profile: Sketch, options: HelixCoilOptions): Shape`
-
 
-**`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.
+`CurveHelixPath`: `{ radius: number, pitch: number, turns: number, height: number, startAngle: number, clockwise: boolean }`
 
 #### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
 
@@ -1397,37 +1559,6 @@ Surface.Match(shape: Shape, options: { edge: "u0" | "u1" | "v0" | "v1"; target:
 Surface.MatchEdge(shape: Shape, options: { edge: "u0" | "u1" | "v0" | "v1"; target: EdgeRef; continuity?: SurfaceContinuity; }): Shape
 ```
 
-#### `nurbs3d()` — Create a NURBS curve from control points.
-
-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.
-
-```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);
-```
-
-```js
-// Rational quadratic — exact circular arc
-const arc = nurbs3d(
-  [[10,0,0], [10,10,0], [0,10,0]],
-  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
-);
-```
-
-```ts
-nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
-```
-
-**`NurbsCurve3DOptions`**
-
-| 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). |
-
 #### `nurbsSurface()` — Create a NURBS surface from a grid of control points.
 
 The control grid is indexed as `controlGrid[u][v]` — each row is a curve in the V direction, and columns trace curves in the U direction.
@@ -1449,73 +1580,6 @@ const surface = nurbsSurface(grid, { thickness: 2 });
 nurbsSurface(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape
 ```
 
-#### `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` | | — |
-
-**`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.
-
-**`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. |
-
-**`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. |
-
-#### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
-
-The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
-
-```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
-```
-
-**`QuinticHermiteCurveEndpoint`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `point` | `Vec3` | Position |
-| `tangent` | `Vec3` | Tangent direction (will be normalized internally) |
-| `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
-| `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
-
 #### `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.
@@ -1526,41 +1590,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. |
-
-#### `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.
-
 #### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
 
 The four curves form the boundary of a quadrilateral patch:
@@ -1620,54 +1649,6 @@ variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?:
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
 | `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
-#### `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.
-
-#### `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
-```
-
 ---
 
 ## C5: Topology Query
@@ -1732,9 +1713,9 @@ selectEdge(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 }`
 
@@ -2332,31 +2313,43 @@ Points.polar(length: number, angleDeg: number, from?: [ number, number ]): [ num
 
 Compose parts with joints for kinematic simulation.
 
-#### `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.** 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.
+**Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
 
-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.
+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.
 
-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.
+`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.
 
-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.
+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.
+
+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()` 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; // auto-solved at defaults, renders all parts
+return mech;
 ```
 
 ```ts
@@ -2380,28 +2373,15 @@ 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?` | | — |
 
-#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
+<!-- forgecad-skill:exclude-start symbol="jointsView" reason="Compatibility-only viewport FK API. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model." -->
+#### `jointsView()` — Register legacy viewport-only mechanism controls that animate returned objects without re-running the script.
 
-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.
-
-```ts
-const arm = joint("Shoulder", armShape, [0, 0, 20], {
-  axis: [0, 1, 0],
-  min: -30, max: 120, default: 25,
-});
-return arm;
-```
-
-```ts
-joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
-```
-
-`RevoluteJointOpts`: `{ axis?: [ number, number, number ], min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
-
-#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
+> **Not included in ForgeCAD AI skill context yet.** This API remains visible in human docs, but is intentionally omitted from shipped agent skills until it is ready for agent-first use. Compatibility-only viewport FK API. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model.
 
 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.
 
+For `Assembly` mechanisms, prefer returning the `Assembly` directly. Returned assemblies expose solver-backed controls automatically, so link/edge closed loops move through the real assembly solver instead of this viewport-only FK layer.
+
 **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
@@ -2433,6 +2413,8 @@ return solved;
 
 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`.
 
+**Mirrored revolute axes:** `default` values and animation keyframes are physical joint values, signed by the joint axis. In a bilateral mechanism, mirrored hinge axes such as `[1, 0, 0]` and `[-1, 0, 0]` need opposite physical values for the same mirrored pose. Negate the mirrored revolute track and mirror physical limits as `[min, max] -> [-max, -min]`. Prismatic tracks do not have this handedness flip.
+
 **Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
 
 ```js
@@ -2482,6 +2464,7 @@ jointsView(options?: JointsViewOptions): void
 - `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>`
+<!-- forgecad-skill:exclude-end -->
 
 ---
 
@@ -2736,7 +2719,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`):
 
@@ -2752,7 +2735,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")
@@ -2808,9 +2791,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`
 
-`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata, mates: AssemblyPartMateInput[] }`
 
 **`PartMetadata`**
 
@@ -2819,6 +2802,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 }`
@@ -2827,6 +2815,16 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
+`AssemblyKinematicGraphDef`: `{ links: AssemblyLinkDef[], edges: AssemblyEdgeBetweenLinksDef[], angles: AssemblyAngleBetweenLinksDef[] }`
+
+`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`, `target?: number`, `min?: number`, `max?: number`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
 #### `sheetMetal()` — Create a parametric sheet metal part with flanges, bend allowances, and flat-pattern unfolding.
 
 `sheetMetal()` keeps one semantic model and derives both a folded 3D solid and an accurate flat pattern from it. The K-factor bend allowance is applied during unfolding. This is a strict v1 subset — it does not infer sheet metal from arbitrary solids.
@@ -3424,7 +3422,7 @@ showLabels(shape: Shape): Shape
 
 #### `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.