forgecad 0.9.13 → 0.9.15

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

@@ -5,12 +5,12 @@ skill-order: 100
 
 # 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)
@@ -36,96 +36,121 @@ 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.** 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.
 
-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.
+If no link in a connected kinematic component is fixed, ForgeCAD chooses a deterministic gauge link for solving and reports a floating-component warning.
 
-```ts
-const mech = assembly("Arm")
-  .addPart("base", box(80, 80, 20).translate(0, 0, -10), {
-    metadata: { material: "PETG", process: "FDM", qty: 1 },
-  })
-  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
-  .addRevolute("shoulder", "base", "link", {
-    axis: [0, 1, 0],
-    min: -30, max: 120, default: 25,
-    frame: Transform.identity().translate(0, 0, 20),
-  });
+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.
 
-return mech; // auto-solved at defaults, renders all parts
-```
-
-```ts
-assembly(name?: string): Assembly
-```
+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.
 
-#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
+**Point-link example**
 
-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.
+This snippet mates a marker to the solved `tip` point. It does not orient a bar along `ground -> tip`.
 
 ```ts
-const arm = joint("Shoulder", armShape, [0, 0, 20], {
-  axis: [0, 1, 0],
-  min: -30, max: 120, default: 25,
+const marker = box(8, 8, 4).withConnectors({
+  center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
 });
-return arm;
+
+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;
 ```
 
 ```ts
-joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
+assembly(name?: string): Assembly
 ```
 
-`RevoluteJointOpts`: `{ axis?: [ number, number, number ], min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
-
 ---
 
 ## Classes
 
 ### `Assembly`
 
-Container for a kinematic mechanism made up of named parts and joints.
-
-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.
+Container for a kinematic mechanism made up of links, relationships, and parts.
 
-Each joint carries a `frame` transform (from the parent part frame to the joint's zero-state frame) and a motion formula:
+Assembly has two related but different motion tools:
 
-```
-childWorld = parentWorld × frame × motion(value) × childBase
-```
+- **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.
 
-Three joint types are supported:
+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.
 
-- **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`
+**Point-link quick start**
 
-**Quick start**
+This attaches a marker to a solved point. It is intentionally not a bone or oriented part example.
 
 ```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),
+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
+return mech;
 ```
 
-Returning an unsolved `Assembly` auto-solves at default joint values. Return a `SolvedAssembly` directly for a specific pose:
+Returning an unsolved `Assembly` keeps the graph available to the runtime. Return a `SolvedAssembly` directly for a specific control state:
 
 ```ts
-return mech.solve({ shoulder: 60 });
+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**
@@ -141,6 +166,90 @@ return mech.solve({ shoulder: 60 });
 |----------|------|-------------|
 | `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 }`
+
+#### `describeKinematics()` — Return the assembly-native kinematic graph definition.
+
+```ts
+describeKinematics(): AssemblyKinematicGraphDef
+```
+
+**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.
+
+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
+```
+
+`PartOptions`: `{ transform?: TransformInput, metadata?: PartMetadata, mate?: AssemblyPartMateInput | AssemblyPartMateInput[] }`
+
+**`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).
+
+#### `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
+```
+
 **Connectors**
 
 #### `usedConnectorRefs()` — Connector refs (e.g. "PartName.connectorName") consumed by connect/match calls.
@@ -159,6 +268,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
@@ -175,23 +288,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)
@@ -203,6 +328,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.
@@ -225,13 +360,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.
@@ -240,186 +377,81 @@ match(childPartName: string, parentPartName: string, pairs: Record<string, strin
 withReferences(refs: Pick<PlacementReferenceInput, "points">): Assembly
 ```
 
-**Solving**
-
-#### `solve()` — Solve the assembly at the given joint state and return positioned parts.
-
-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()`).
-
-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.
-
-**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.
-
-This pitfall only applies when `toJointsView()` is active. If you only want a static posed result, return the solved assembly directly and skip `toJointsView()`.
-
-**Example — static posed output (no `toJointsView()`)**
-
-```ts
-return mech.solve({ shoulder: 45, elbow: -20 });
-```
-
-```ts
-solve(state?: JointState): SolvedAssembly
-```
-
-**Other**
-
-#### `mate()` — Register mate constraints between parts. Constraints are solved during `solve()` to derive part positions and explode hints. Part references use "partName:featureName" format.
-
-```ts
-mate(fn: (m: MateBuilder) => void): Assembly
-```
-
-#### `addFrame()` — Add a virtual reference frame (no geometry) to the assembly graph.
+**`PlacementReferenceInput`**: `points?: Record<string, [ number, number, number ]>`, `edges?: Record<string, PlacementEdgeRef>`, `surfaces?: Record<string, PlacementSurfaceRef>`, `objects?: Record<string, PlacementObjectInput>`
 
-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);
-```
+`PlacementEdgeRef`: `{ start: Vec3, end: Vec3 }`
 
-```ts
-addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
-```
+`PlacementSurfaceRef`: `{ center: Vec3, normal: Vec3 }`
 
-#### `addJoint()` — Add a kinematic joint between a parent and child part.
+**Solving**
 
-`frame` is a transform from the **parent part frame** to the **joint frame at zero state**. The child's world position is computed as:
+#### `solve()` — Solve the assembly at the given control state and return positioned parts.
 
-```
-childWorld = parentWorld × frame × motion(value) × childBase
-```
+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.
 
-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.
+Connector mates declared on `addPart(..., { mate })` attach geometry to solved links while preserving part and connector identity:
 
-```ts
-addJoint(name: string, type: JointType, parent: string, child: string, options?: JointOptions): Assembly
-```
+- 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.
 
-#### `addRevolute()` — Shorthand for `addJoint(name, 'revolute', parent, child, options)`.
+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
-addRevolute(name: string, parent: string, child: string, options?: JointOptions): Assembly
+return mech.solve({ theta: 45 });
 ```
 
-#### `addPrismatic()` — Shorthand for `addJoint(name, 'prismatic', parent, child, options)`.
-
 ```ts
-addPrismatic(name: string, parent: string, child: string, options?: JointOptions): Assembly
+solve(state?: JointState): SolvedAssembly
 ```
 
-#### `addFixed()` — Shorthand for `addJoint(name, 'fixed', parent, child, options)`.
+<!-- forgecad-skill:exclude-start symbol="Assembly.Compatibility methods" reason="Compatibility-only viewport FK adapter. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model." -->
+**Compatibility**
+<!-- forgecad-skill:exclude-end -->
 
-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.
+<!-- forgecad-skill:exclude-start symbol="Assembly.toJointsView" reason="Compatibility-only viewport FK adapter. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model." -->
+#### `toJointsView()` — Deprecated adapter that derives viewport-only FK controls from the assembly graph.
 
-```ts
-addFixed(name: string, parent: string, child: string, options?: JointOptions): Assembly
-```
+> **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 adapter. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model.
 
-#### `addJointCoupling()` — Link a joint's value to a linear combination of other joint values.
+Prefer returning the `Assembly` itself. The runtime now exposes returned assembly controls automatically and re-evaluates the assembly with `solve(state)` when a control changes. That path is the source of truth for link/edge kinematics, handles closed-loop mechanisms through the real solver, and avoids stacking a viewport transform on top of already-solved geometry.
 
-The driven joint's value is computed as:
+`toJointsView()` remains for legacy scripts that intentionally want the old viewport-only FK behavior.
 
-```
-driven = offset + Σ(ratio_i × source_i)
-```
+**Legacy mirrored revolute tracks:** Viewport defaults and animation keyframes use physical joint values. If two mirrored revolute joints have opposite axes, equal keyframe values are not a mirrored pose; negate the mirrored side's values, or prefer returned-assembly controls so the solver owns the side-neutral state.
 
-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.
+**Preferred**
 
 ```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 },
-    ],
-  });
+return mech; // editor controls call mech.solve(state)
 ```
 
 ```ts
-addJointCoupling(jointName: string, options: JointCouplingOptions): Assembly
-```
-
-#### `addGearCoupling()` — Link two revolute joints via a gear ratio.
-
-Choose exactly one ratio source:
-
-- `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 });
-```
-
-```ts
-addGearCoupling(drivenJointName: string, driverJointName: string, options?: GearCouplingOptions): Assembly
-```
-
-#### `sweepJoint()` — Sample a joint through its motion range, collecting collision data at each step.
-
-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.
-
-You cannot sweep a coupled joint — sweep one of its source joints instead.
-
-```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`);
+toJointsView(options?: ToJointsViewOptions): void
 ```
 
-```ts
-sweepJoint(jointName: string, from: number, to: number, steps: number, baseState?: JointState, collisionOptions?: CollisionOptions): JointSweepFrame[]
-```
+**`ToJointsViewOptions`**: `defaults?: Record<string, number>`, `overrides?: Record<string, Partial<JointViewInput>>`, `animations?: JointViewAnimationInput[]`, `couplings?: JointViewCouplingInput[]`, `defaultAnimation?: string`, `enabled?: boolean`
 
-#### `toJointsView()` — Derive viewport joint controls from the assembly graph and register them.
+**`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`
 
-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.
+`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
 
-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()`.
+**`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>`
 
-**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.
+`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
 
-Do not solve at a non-zero angle when using `toJointsView()` — the viewport will apply the same rotation again, double-rotating the part.
+`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
+<!-- forgecad-skill:exclude-end -->
 
-```ts
-mech.toJointsView({
-  defaults: { J1: 30 },
-  animations: [{
-    name: "Swing", duration: 2, loop: true,
-    keyframes: [{ values: { J1: -45 } }, { values: { J1: 45 } }, { values: { J1: -45 } }],
-  }],
-});
+**Other**
 
-// Solve at REST — viewport handles posing
-return mech.solve();
-```
+#### `mate()` — Register mate constraints between parts. Constraints are solved during `solve()` to derive part positions and explode hints. Part references use "partName:featureName" format.
 
 ```ts
-toJointsView(options?: ToJointsViewOptions): void
+mate(fn: (m: MateBuilder) => void): Assembly
 ```
 
 #### `describe()` — Return the serializable assembly definition used by solve/inspect pipelines.
@@ -439,7 +471,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**
 
@@ -468,7 +500,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
@@ -486,6 +518,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
@@ -564,17 +604,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.
 
-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:
+This mirrors `SolvedAssembly.collisionReport()` for imported assemblies. Use `solve(state).collisionReport(options)` when inspecting a non-default joint state.
 
 ```ts
-parent.solve({ "Left Arm.shoulder": 45, "Right Arm.shoulder": -20 })
+collisionReport(options?: CollisionOptions): CollisionFinding[]
 ```
 
-Joint couplings inside the sub-assembly are preserved and rewritten with the prefix. Ports from sub-assembly parts are forwarded with the prefix.
+`CollisionOptions`: `{ parts?: string[], ignorePairs?: Array<[ string, string ]>, minOverlapVolume?: number }`
 
-The sub-assembly must have exactly one root part. If it has multiple roots, use `addFixed()` first to consolidate them before merging.
+#### `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, 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.theta": 45, "Right Arm.theta": -20 })
+```
+
+Connectors from sub-assembly parts are forwarded with the prefix.
+
+The sub-assembly must have exactly one root part before it can be merged.
 
 ```ts
 const robot = assembly("Robot").addPart("Chassis", chassis);
@@ -591,6 +649,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.
@@ -599,7 +676,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 });
@@ -645,6 +722,18 @@ get mateDof(): number | null
 get mateConverged(): boolean | null
 ```
 
+#### `kinematics()` — Solved assembly-native kinematic graph, or null when no links were declared.
+
+```ts
+get kinematics(): SolvedAssemblyKinematics | null
+```
+
+#### `getLinkPosition()` — Return the solved world position of a kinematic link.
+
+```ts
+getLinkPosition(linkName: string): Vec3
+```
+
 #### `getTransform()` — Return the world-space [`Transform`](/docs/core#transform) for the named part at the solved pose.
 
 ```ts