forgecad 0.9.13 → 0.9.15

package/dist-skill/library/forgecad-component-model/SKILL.md

@@ -26,9 +26,11 @@ A part is a function from props to `{ shape, connectors, metadata }`. It builds
 - A connector = origin + axis (outward from the part)
 - Connectors meet **face-to-face**: both axes point outward, system brings them together
 - For prismatic joints: axes point along the shared slide direction
+- Mirrored revolute axes need negated physical joint values for the same mirrored pose
 
 ### 3. Assembly Is Pure Composition
-- `addPart()` + `connect()` + `addJointCoupling()` — nothing else
+- Use `addPart()` + `connect()` for frame-aware serial assemblies
+- Use `link()` + `edgeBetweenLinks()` + `addAngleBetweenLinks()` for solved point skeletons
 - Zero `translate()` calls for structural parts
 - Zero coordinate math
 - The assembly passes props down and reads metadata up
@@ -60,6 +62,13 @@ mount.withConnectors({
 assembly.connect("Base.mount_face", "Mount.flange", { as: "mount-fix" });
 ```
 
+Revolute values are signed by the physical hinge axis. In a bilateral mechanism,
+`axis: [1, 0, 0]` on the right side and `axis: [-1, 0, 0]` on the left side are
+exact mirrors at rest, but the same `+theta` value rotates them in opposite
+fore/aft senses. Use `Right: +theta`, `Left: -theta`, and mirror physical limits
+as `[min, max] -> [-max, -min]`, or drive both sides from a side-neutral link
+graph/control layer.
+
 ## Part Return Shape
 
 Every part file returns a structured object:

package/dist-skill/library/forgecad-image-replicator/SKILL.md

@@ -114,10 +114,10 @@ node dist-cli/forgecad.js render 3d path/to/model.forge.js /tmp/<slug>-replicate
   --size 1000 --edges thin
 ```
 
-Build side-by-side boards with the bundled helper:
+Build side-by-side boards with the bundled helper. It is a self-contained `uv` script that installs Pillow on demand and does not require Chrome. The examples use the ForgeCAD source-checkout path; if the skill is installed elsewhere, resolve `scripts/compare_images.py` relative to the `forgecad-image-replicator` skill directory.
 
 ```bash
-node skills/forgecad-image-replicator/scripts/compare_images.mjs \
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py \
   /tmp/<slug>-replicate/refs/front.png \
   /tmp/<slug>-replicate/render-front.png \
   /tmp/<slug>-replicate/compare-front.png \
@@ -127,10 +127,10 @@ node skills/forgecad-image-replicator/scripts/compare_images.mjs \
 Common helper options:
 
 ```bash
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.jpg render.png compare.png --height 1200 --fit contain
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png --fit cover --labels "Target,Current"
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png --no-labels
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.jpg render.png compare.png --height 1200 --fit contain
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --fit cover --labels "Target,Current"
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --no-labels
 ```
 
 Use `--fit contain` by default. Use `--fit cover` only when both images already share the same crop and aspect.

package/dist-skill/library/forgecad-image-replicator/scripts/compare_images.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pillow>=10"]
+# ///
+
+"""Build a reference-vs-render PNG board for ForgeCAD image replication."""
+
+from __future__ import annotations
+
+import argparse
+from math import ceil
+from pathlib import Path
+
+from PIL import Image, ImageColor, ImageDraw, ImageFont, ImageOps
+
+
+def positive_int(raw: str) -> int:
+    value = int(raw)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return value
+
+
+def labels(raw: str) -> tuple[str, str]:
+    values = tuple(part.strip() for part in raw.split(",") if part.strip())
+    if len(values) != 2:
+        raise argparse.ArgumentTypeError("must contain two comma-separated labels")
+    return values
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a side-by-side comparison board from a reference image and ForgeCAD render.",
+    )
+    parser.add_argument("reference_image")
+    parser.add_argument("forgecad_render")
+    parser.add_argument("output_png")
+    parser.add_argument("--height", type=positive_int, default=900, help="Panel height in pixels.")
+    parser.add_argument("--panel-width", type=positive_int, default=None, help="Panel width in pixels.")
+    parser.add_argument("--gap", type=positive_int, default=16, help="Gap between panels in pixels.")
+    parser.add_argument("--padding", type=positive_int, default=16, help="Outer padding in pixels.")
+    parser.add_argument("--background", default="#111111", help="Canvas background color.")
+    parser.add_argument("--fit", choices=("contain", "cover"), default="contain", help="Image fit mode.")
+    parser.add_argument("--labels", type=labels, default=("Reference", "ForgeCAD"), help="Two comma-separated labels.")
+    parser.add_argument("--no-labels", action="store_true", help="Disable label band.")
+    parser.add_argument(
+        "--chrome-path",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    return parser.parse_args()
+
+
+def open_image(path_arg: str) -> Image.Image:
+    path = Path(path_arg).expanduser()
+    if not path.exists():
+        raise SystemExit(f"Image not found: {path}")
+    try:
+        image = Image.open(path)
+        return ImageOps.exif_transpose(image).convert("RGBA")
+    except Exception as exc:  # Pillow gives format-specific exceptions.
+        raise SystemExit(f"Failed to open image {path}: {exc}") from exc
+
+
+def parse_background(raw: str) -> tuple[int, int, int, int]:
+    try:
+        color = ImageColor.getcolor(raw, "RGBA")
+    except ValueError as exc:
+        raise SystemExit(f"Invalid background color {raw!r}: {exc}") from exc
+    return color
+
+
+def load_label_font() -> ImageFont.ImageFont:
+    candidates = [
+        "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+        "/System/Library/Fonts/Supplemental/Arial.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/truetype/liberation2/LiberationSans-Bold.ttf",
+    ]
+    for candidate in candidates:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), 18)
+    return ImageFont.load_default()
+
+
+def scaled_to_panel(image: Image.Image, panel_width: int, panel_height: int, fit: str) -> Image.Image:
+    width, height = image.size
+    if width <= 0 or height <= 0:
+        raise SystemExit("Image dimensions must be positive.")
+    scale = (
+        max(panel_width / width, panel_height / height)
+        if fit == "cover"
+        else min(panel_width / width, panel_height / height)
+    )
+    if fit == "cover":
+        scaled_size = (max(panel_width, ceil(width * scale)), max(panel_height, ceil(height * scale)))
+    else:
+        scaled_size = (min(panel_width, max(1, round(width * scale))), min(panel_height, max(1, round(height * scale))))
+    resized = image.resize(scaled_size, Image.Resampling.LANCZOS)
+    if fit != "cover":
+        return resized
+
+    left = max(0, (resized.width - panel_width) // 2)
+    top = max(0, (resized.height - panel_height) // 2)
+    return resized.crop((left, top, left + panel_width, top + panel_height))
+
+
+def paste_panel(
+    board: Image.Image,
+    image: Image.Image,
+    *,
+    x: int,
+    y: int,
+    panel_width: int,
+    panel_height: int,
+    fit: str,
+) -> None:
+    panel = Image.new("RGBA", (panel_width, panel_height), (0, 0, 0, 0))
+    fitted = scaled_to_panel(image, panel_width, panel_height, fit)
+    dx = (panel_width - fitted.width) // 2
+    dy = (panel_height - fitted.height) // 2
+    panel.alpha_composite(fitted, (dx, dy))
+    board.alpha_composite(panel, (x, y))
+
+
+def main() -> None:
+    args = parse_args()
+    reference = open_image(args.reference_image)
+    render = open_image(args.forgecad_render)
+
+    panel_height = args.height
+    max_aspect = max(reference.width / reference.height, render.width / render.height)
+    panel_width = args.panel_width or int(panel_height * max_aspect + 0.9999)
+    label_values = None if args.no_labels else args.labels
+    label_height = 34 if label_values else 0
+    canvas_width = args.padding * 2 + panel_width * 2 + args.gap
+    canvas_height = args.padding * 2 + label_height + panel_height
+
+    board = Image.new("RGBA", (canvas_width, canvas_height), parse_background(args.background))
+    draw = ImageDraw.Draw(board)
+    left_x = args.padding
+    right_x = args.padding + panel_width + args.gap
+    panel_y = args.padding + label_height
+
+    if label_values:
+        font = load_label_font()
+        for text, x in ((label_values[0], left_x), (label_values[1], right_x)):
+            draw.text((x, args.padding + 4), text, fill=(255, 255, 255, 230), font=font)
+
+    paste_panel(board, reference, x=left_x, y=panel_y, panel_width=panel_width, panel_height=panel_height, fit=args.fit)
+    paste_panel(board, render, x=right_x, y=panel_y, panel_width=panel_width, panel_height=panel_height, fit=args.fit)
+
+    outline = (255, 255, 255, 64)
+    draw.rectangle((left_x, panel_y, left_x + panel_width - 1, panel_y + panel_height - 1), outline=outline)
+    draw.rectangle((right_x, panel_y, right_x + panel_width - 1, panel_y + panel_height - 1), outline=outline)
+
+    output_path = Path(args.output_png).expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    board.save(output_path, "PNG")
+    print(f"Wrote {output_path} ({canvas_width}x{canvas_height})")
+
+
+if __name__ == "__main__":
+    main()

package/dist-skill/library/forgecad-make-a-model/SKILL.md

@@ -60,7 +60,7 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
    - Return the final geometry (single shape, array, or named objects array)
    - Treat `fillet(shape, r)` and `chamfer(shape, r)` as experimental edge treatments: Manifold can produce incorrect results and OCCT can be very slow. Prefer simpler primitive profiles, lower segment counts, targeted edge selectors, and inspection before relying on the result.
 4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
-5. Verify geometry — render a multi-angle visual evidence set before final delivery: whole-model context plus agent-chosen orthographic, oblique, underside, or hidden-object views that expose the relevant components and interfaces. Choose camera directions from the model's shape and likely failure modes, not from a fixed recipe. Use those views to look for internals that are accidentally visible, parts that visibly do not fit, floating details, blocked access, missing seats, and unexpected interference. Run `forgecad run --connectivity` when the model has multiple returned objects or visible attachments, run `forgecad debug assembly --fail-on warning` when the script uses `assembly()`, run `forgecad inspect mechanical-integrity <project-or-file> --collisions` before sharing generated mechanical work, and run the targeted `forgecad inspect <family> <mode>` commands that match the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`. Collision findings are model work, not FYI: remove unexpected overlaps before delivery.
+5. Verify geometry — render a multi-angle visual evidence set before final delivery: whole-model context plus agent-chosen orthographic, oblique, underside, or hidden-object views that expose the relevant components and interfaces. Choose camera directions from the model's shape and likely failure modes, not from a fixed recipe. Use those views to look for internals that are accidentally visible, parts that visibly do not fit, floating details, blocked access, missing seats, and unexpected interference. Run `forgecad inspect physical components` when the model has multiple returned objects or visible attachments, run `forgecad debug assembly --fail-on warning` when the script uses `assembly()`, run `forgecad inspect mechanical-integrity <project-or-file> --collisions` before sharing generated mechanical work, and run the targeted `forgecad inspect <family> <mode>` commands that match the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`. Collision findings are model work, not FYI: remove unexpected overlaps before delivery.
 6. Iterate from visual and inspection feedback — treat every render and inspection bundle as model evidence, not a checkbox. Read the normal PNGs, manifest, and evidence PNGs; convert each unexpected collision, thin region, missing section detail, wrong component count, floating body, distance gap, confusing object-color result, accidentally exposed internal structure, bad fit, or visually unsupported interface into a concrete model edit; then rerun the same targeted evidence pass until the result matches the intended physical component graph.
 
 ## Manufacturing Process Is Not Assumed
@@ -183,7 +183,7 @@ Before telling the user the model is done, prove both technical validity and vis
 1. State the intended physical component graph. Decide whether the final artifact should be one connected component, several intentionally separate components, or a selected assembly plus named ghosts. Then run:
 
    ```bash
-   forgecad run model.forge.js --connectivity
+   forgecad inspect physical components model.forge.js --camera iso
    ```
 
    The reported component count must match the design intent. Treat unexpected islands, accidental fusion, or bbox-only "touching" that does not make physical sense as model bugs.
@@ -292,7 +292,7 @@ For important components, collect both:
 - Context view — neighbors present, proving the part belongs in the final assembly.
 - Focus view — only the relevant objects visible, making small gaps, intersections, missing seats, and floating parts easy to see.
 
-Prefer CLI `--focus` / `--hide` filters, named views, or parameter-selected diagnostic modes over changing production geometry. Use the object names from `node dist-cli/forgecad.js run model.forge.js --quality live` when you are unsure what the filters should target.
+Prefer CLI `--focus` / `--hide` filters, named views, or parameter-selected diagnostic modes over changing production geometry. Use the object paths from `node dist-cli/forgecad.js ls model.forge.js --tree` when you are unsure what the filters should target.
 
 ### Structured inspection bundles
 

package/dist-skill/library/forgecad-model-grader/SKILL.md

@@ -59,7 +59,7 @@ This skill is an evaluator workflow. Do not edit the model unless the user expli
 
    ```bash
    node dist-cli/forgecad.js inspect fit interference path/to/model.forge.js /tmp/model-grade/collisions --camera iso --force --size 700
-   python skills/forgecad-render-inspect/summarize_manifest.py /tmp/model-grade/collisions
+   python agent-skill-library/forgecad-render-inspect/summarize_manifest.py /tmp/model-grade/collisions
    ```
 
    Read the manifest and inspect the relevant evidence PNGs. Treat unexpected collisions, thin regions, missing sections, wrong component counts, floating bodies, and confusing object colors as evidence, not as warnings to wave away.

package/dist-skill/library/forgecad-prepare-prompt/SKILL.md

@@ -176,7 +176,7 @@ By the end of this skill, there should be:
 
 9. If implementation continues immediately, hand off to `forgecad`.
    For moving mechanisms, load:
-   - `skills/forgecad/SKILL.md`
+   - `~/.agents/skills/forgecad/SKILL.md`
    - `docs/permanent/generated/assembly.md`
    - `docs/permanent/generated/output.md`
    - `docs/permanent/guides/joint-design.md`

package/dist-skill/library/forgecad-reconstruction-benchmark/SKILL.md

@@ -72,13 +72,13 @@ ForgeCAD commands.
    inference.
 
    ```bash
-   ./bin/forgecad run task/reference/<asset> --quality live --details
+   ./bin/forgecad ls task/reference/<asset> --quality live --long
    ./bin/forgecad render 3d task/reference/<asset> outputs/reference.png --camera iso --edges thin --size 900
    ./bin/forgecad inspect sections sample task/reference/<asset> outputs/reference-sections --count 5 --size 700
    ./bin/forgecad inspect section task/reference/<asset> --plane yz --offset 0 --ray width:-50,0:50,0 --size 700
    ```
 
-   For 3MF references, the `run --details` output includes a source structure
+   For 3MF references, the `forgecad run` output includes a source structure
    table with stable `3mf:build:...:object:...` refs, automatic item names,
    per-item bounding boxes, and triangle counts. Treat that table as part of
    the evidence: the final model may be one part or many parts, but you should
@@ -88,7 +88,7 @@ ForgeCAD commands.
    unique probe directory with `result.json`; later you can replay that probe
    against the candidate with `./bin/forgecad inspect replay <result.json>
    --source submission/main.forge.js`.
-   For 3MF references, the `run --details` output includes a source structure
+   For 3MF references, the `forgecad run` output includes a source structure
    table with stable `3mf:build:...:object:...` refs, automatic item names,
    per-item bounding boxes, and triangle counts. Treat that table as part of
    the evidence: the final model may be one part or many parts, but you should

package/dist-skill/library/forgecad-render-inspect/SKILL.md

@@ -62,7 +62,7 @@ Routing:
    Run the bundled helper:
 
    ```bash
-   python skills/forgecad-render-inspect/summarize_manifest.py /tmp/model-inspect
+   python agent-skill-library/forgecad-render-inspect/summarize_manifest.py /tmp/model-inspect
    ```
 
    Use `jq` for targeted follow-up when needed:
@@ -88,6 +88,7 @@ Routing:
 | Question | Evidence command |
 |----------|------------------|
 | Quick visual sanity | `inspect visual image` |
+| Kinematic rig, joints, axes, and links | `inspect visual rig` |
 | Object naming and identity | `inspect visual objects` |
 | Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
 | Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at|stack|sample` |
@@ -106,6 +107,7 @@ Explicit fast bundle:
 
 ```bash
 forgecad inspect visual objects model.forge.js --camera iso --size 700
+forgecad inspect visual rig model.forge.js --camera iso --size 700
 forgecad inspect sections at model.forge.js --plane yz --offset 12.5 --size 700
 forgecad inspect sections stack model.forge.js --plane yz --every 1 --size 700
 forgecad inspect sections sample model.forge.js --count 5 --size 700

package/examples/api/assembly-kinematics-foundation.forge.js

@@ -0,0 +1,65 @@
+// Assembly-owned point kinematics: return the rig, then let viewport controls
+// drive solve(state). Closed loops stay solver-backed instead of viewport-FK,
+// and the editor updates part transforms without rebuilding the marker meshes.
+//
+// This file deliberately keeps the skin as point markers. For physical bars
+// that orient from one solved link to another with two connector mates, see
+// assembly-kinematics-four-bar.forge.js.
+
+const DEFAULT_THETA = 42;
+const MAX_THETA = 95;
+
+const GROUND_A = [0, 0, 0];
+const GROUND_B = [90, 0, 0];
+const CRANK_TIP = [35, 0, 0];
+const ROCKER_TIP = [55, 42, 0];
+
+const crankLen = Points.distance(GROUND_A, CRANK_TIP);
+const couplerLen = Points.distance(CRANK_TIP, ROCKER_TIP);
+const rockerLen = Points.distance(GROUND_B, ROCKER_TIP);
+
+function linkMarker(color) {
+  return box(8, 8, 4)
+    .translate(0, 0, -2)
+    .color(color)
+    .withConnectors({
+      center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
+    });
+}
+
+const mechanism = assembly("Assembly Kinematics Foundation")
+  .link("groundA", { at: GROUND_A, fixed: true })
+  .link("groundB", { at: GROUND_B, fixed: true })
+  .link("crankTip", { at: CRANK_TIP })
+  .link("rockerTip", { at: ROCKER_TIP })
+  .edgeBetweenLinks("groundA", "crankTip", { name: "crank" })
+  .edgeBetweenLinks("crankTip", "rockerTip", { name: "coupler" })
+  .edgeBetweenLinks("groundB", "rockerTip", { name: "rocker" })
+  .addAngleBetweenLinks("groundB", "groundA", "crankTip", {
+    name: "theta",
+    // Past about 98 degrees this link set has no exact four-bar solution:
+    // the coupler and rocker are fully extended.
+    control: { min: 0, max: MAX_THETA, default: DEFAULT_THETA },
+  })
+  .addPart("Ground A marker", linkMarker("#4f5f67"), { mate: { connector: "center", toLink: "groundA" } })
+  .addPart("Ground B marker", linkMarker("#4f5f67"), { mate: { connector: "center", toLink: "groundB" } })
+  .addPart("Crank tip marker", linkMarker("#d55e5e"), { mate: { connector: "center", toLink: "crankTip" } })
+  .addPart("Rocker tip marker", linkMarker("#3d87c7"), { mate: { connector: "center", toLink: "rockerTip" } });
+
+const solved = mechanism.solve({ theta: DEFAULT_THETA });
+verify.equal("kinematic controls are preserved", solved.kinematics.controls.theta, DEFAULT_THETA, 0.000001);
+
+for (const theta of [0, DEFAULT_THETA, 70, MAX_THETA]) {
+  const pose = mechanism.solve({ theta });
+  const groundA = pose.getLinkPosition("groundA");
+  const groundB = pose.getLinkPosition("groundB");
+  const crankTip = pose.getLinkPosition("crankTip");
+  const rockerTip = pose.getLinkPosition("rockerTip");
+
+  verify.that(`closed loop converges at theta ${theta}`, () => pose.kinematics.converged);
+  verify.equal(`crank length holds at theta ${theta}`, Points.distance(groundA, crankTip), crankLen, 0.01);
+  verify.equal(`coupler length holds at theta ${theta}`, Points.distance(crankTip, rockerTip), couplerLen, 0.01);
+  verify.equal(`rocker length holds at theta ${theta}`, Points.distance(groundB, rockerTip), rockerLen, 0.01);
+}
+
+return mechanism;

package/examples/api/assembly-kinematics-four-bar.forge.js

@@ -0,0 +1,115 @@
+// Closed-loop four-bar linkage using the assembly kinematic graph.
+//
+// The links define the mechanism. The bars are ordinary local geometry with
+// two connector mates, so the editor slider re-solves the link graph and then
+// updates part transforms. The bar meshes are not rebuilt while theta changes.
+
+scene({
+  background: { top: "#e6ebef", bottom: "#7b858d" },
+  views: {
+    top: { camera: { position: [45, 25, 220], target: [45, 24, 0], up: [0, 1, 0], fov: 32 } },
+    iso: { camera: { position: [150, -135, 115], target: [45, 24, 0], up: [0, 0, 1], fov: 34 } },
+  },
+  lights: [
+    { type: "ambient", color: "#f4f7fa", intensity: 0.45 },
+    { type: "directional", position: [160, -140, 260], color: "#fff4dc", intensity: 2.0, castShadow: true },
+  ],
+});
+
+const DEFAULT_THETA = 42;
+
+const GROUND_A = [0, 0, 0];
+const GROUND_B = [90, 0, 0];
+const CRANK_TIP = [35, 0, 0];
+const ROCKER_TIP = [55, 42, 0];
+
+const groundLen = Points.distance(GROUND_A, GROUND_B);
+const crankLen = Points.distance(GROUND_A, CRANK_TIP);
+const couplerLen = Points.distance(CRANK_TIP, ROCKER_TIP);
+const rockerLen = Points.distance(GROUND_B, ROCKER_TIP);
+
+function bar(length, width, color) {
+  return box(length, width, 5)
+    .translate(length / 2, 0, 0)
+    .color(color)
+    .material({ metalness: 0.1, roughness: 0.55 })
+    .withConnectors({
+      near: connector({ origin: [0, 0, 0], axis: [1, 0, 0], up: [0, 0, 1] }),
+      far: connector({ origin: [length, 0, 0], axis: [1, 0, 0], up: [0, 0, 1] }),
+    });
+}
+
+function pivot(color) {
+  return cylinder(7, 5.5)
+    .translate(0, 0, -3.5)
+    .color(color)
+    .material({ metalness: 0.2, roughness: 0.45 })
+    .withConnectors({
+      center: connector({ origin: [0, 0, 0], axis: [0, 0, 1], up: [1, 0, 0] }),
+    });
+}
+
+const fourBar = assembly("Closed Loop Four Bar")
+  .link("groundA", { at: GROUND_A, fixed: true })
+  .link("groundB", { at: GROUND_B, fixed: true })
+  .link("crankTip", { at: CRANK_TIP })
+  .link("rockerTip", { at: ROCKER_TIP })
+  .edgeBetweenLinks("groundA", "crankTip", { name: "crank" })
+  .edgeBetweenLinks("crankTip", "rockerTip", { name: "coupler" })
+  .edgeBetweenLinks("groundB", "rockerTip", { name: "rocker" })
+  .addAngleBetweenLinks("groundB", "groundA", "crankTip", {
+    name: "theta",
+    control: { min: 0, max: 95, default: DEFAULT_THETA },
+  });
+
+fourBar.addPart("Ground", bar(groundLen, 10, "#56636b"), {
+  mate: [
+    { connector: "near", toLink: "groundA" },
+    { connector: "far", toLink: "groundB" },
+  ],
+});
+
+fourBar.addPart("Crank", bar(crankLen, 8, "#d95c4b"), {
+  mate: [
+    { connector: "near", toLink: "groundA" },
+    { connector: "far", toLink: "crankTip" },
+  ],
+});
+
+fourBar.addPart("Coupler", bar(couplerLen, 7, "#e5b84c"), {
+  mate: [
+    { connector: "near", toLink: "crankTip" },
+    { connector: "far", toLink: "rockerTip" },
+  ],
+});
+
+fourBar.addPart("Rocker", bar(rockerLen, 8, "#3b82c4"), {
+  mate: [
+    { connector: "near", toLink: "groundB" },
+    { connector: "far", toLink: "rockerTip" },
+  ],
+});
+
+for (const [name, link, color] of [
+  ["Ground A Pivot", "groundA", "#263238"],
+  ["Ground B Pivot", "groundB", "#263238"],
+  ["Crank Pin", "crankTip", "#8c2d25"],
+  ["Rocker Pin", "rockerTip", "#244b74"],
+]) {
+  fourBar.addPart(name, pivot(color), { mate: { connector: "center", toLink: link } });
+}
+
+for (const theta of [0, DEFAULT_THETA, 70, 95]) {
+  const solved = fourBar.solve({ theta });
+  const groundA = solved.getLinkPosition("groundA");
+  const groundB = solved.getLinkPosition("groundB");
+  const crankTip = solved.getLinkPosition("crankTip");
+  const rockerTip = solved.getLinkPosition("rockerTip");
+
+  verify.that(`closed loop converges at theta ${theta}`, () => solved.kinematics.converged);
+  verify.equal(`crank length holds at theta ${theta}`, Points.distance(groundA, crankTip), crankLen, 0.01);
+  verify.equal(`coupler length holds at theta ${theta}`, Points.distance(crankTip, rockerTip), couplerLen, 0.01);
+  verify.equal(`rocker length holds at theta ${theta}`, Points.distance(groundB, rockerTip), rockerLen, 0.01);
+}
+
+return fourBar;

package/examples/api/assembly-kinematics-limb.forge.js

@@ -0,0 +1,116 @@
+// Oriented serial-chain limb posed entirely by the assembly rig API.
+//
+// The motion skeleton is authored as kinematic LINKS in the limb's sagittal
+// (Y/Z) plane; EDGES hold the bone lengths; ANGLES drive the hip and knee.
+// Bone geometry is built once at the origin and attached with two-connector
+// MATES, so each bone ROTATES to span between its two solved links — it does
+// not merely translate. This is the oriented serial chain that position-only
+// link mates could not pose.
+
+scene({
+  background: { top: '#cdd3da', bottom: '#5d6770' },
+  views: {
+    // Look straight down +X so the Y/Z motion plane faces the camera.
+    side: { camera: { position: [320, -25, -35], target: [0, -25, -35], up: [0, 0, 1], fov: 34 } },
+    iso: { camera: { position: [240, -190, 90], target: [0, -25, -40], up: [0, 0, 1], fov: 34 } },
+  },
+  lights: [
+    { type: 'ambient', color: '#eef0f4', intensity: 0.4 },
+    { type: 'directional', position: [240, -200, 320], color: '#fff1dd', intensity: 2.2, castShadow: true },
+  ],
+});
+
+const r = 7;
+
+// A bone running from its `near` connector at the origin to `far` at [0, L, 0].
+// Its connector axis (+Y) is the bone's own length direction.
+function bone(L, color) {
+  return cylinder(L, r)
+    .pointAlong([0, 1, 0])
+    .color(color)
+    .material({ metalness: 0.1, roughness: 0.55 })
+    .withConnectors({
+      near: connector({ origin: [0, 0, 0], axis: [0, 1, 0] }),
+      far: connector({ origin: [0, L, 0], axis: [0, 1, 0] }),
+    });
+}
+
+// ── Skeleton geometry (all at x = 0 → the limb lives in the Y/Z plane) ───────
+const HIP = [0, 0, 0];
+const KNEE = [0, 20, -70]; // forward + down from the hip
+const ANKLE = [0, 50, -110]; // forward + down from the knee
+const HIP_REF = [0, -40, 0]; // a forward marker that fixes the hip's zero angle
+
+const thighLen = Points.distance(HIP, KNEE);
+const shinLen = Points.distance(KNEE, ANKLE);
+
+// Drivers: return the rig and the editor exposes these as solver-backed
+// assembly controls. Dragging them re-solves the link graph, then updates
+// part transforms; the bone meshes stay local and are reused.
+const DEFAULT_HIP_SWING = 18;
+const DEFAULT_KNEE_BEND = 38;
+
+const limb = assembly('Oriented Limb')
+  .link('hipRef', { at: HIP_REF, fixed: true })
+  .link('hip', { at: HIP, fixed: true })
+  .link('knee', { at: KNEE })
+  .link('ankle', { at: ANKLE })
+  .edgeBetweenLinks('hip', 'knee', { name: 'thigh' })
+  .edgeBetweenLinks('knee', 'ankle', { name: 'shin' })
+  // The control `default` is the live param value, so the editor sliders (and
+  // `--param` on the CLI) drive the pose directly.
+  .addAngleBetweenLinks('hipRef', 'hip', 'knee', {
+    name: 'hipSwing',
+    control: { min: -40, max: 60, default: DEFAULT_HIP_SWING },
+  })
+  .addAngleBetweenLinks('hip', 'knee', 'ankle', {
+    name: 'kneeBend',
+    control: { min: 0, max: 120, default: DEFAULT_KNEE_BEND },
+  });
+
+// ── Skin: bones span their links via two-connector mates ─────────────────────
+limb.addPart(
+  'HipHub',
+  sphere(11)
+    .color('#2c2f36')
+    .material({ metalness: 0.2, roughness: 0.5 })
+    .withConnectors({ center: connector({ origin: [0, 0, 0], axis: [1, 0, 0] }) }),
+  { mate: { connector: 'center', toLink: 'hip' } },
+);
+
+limb.addPart('Thigh', bone(thighLen, '#d24b4b'), {
+  mate: [
+    { connector: 'near', toLink: 'hip' },
+    { connector: 'far', toLink: 'knee' },
+  ],
+});
+
+limb.addPart('Shin', bone(shinLen, '#2f3338'), {
+  mate: [
+    { connector: 'near', toLink: 'knee' },
+    { connector: 'far', toLink: 'ankle' },
+  ],
+});
+
+// Wheel hub at the ankle — single mate, position-only is exactly right here
+// (a spin-symmetric wheel needs no orientation).
+limb.addPart(
+  'Wheel',
+  cylinder(13, 18)
+    .pointAlong([1, 0, 0])
+    .translate(-6.5, 0, 0)
+    .color('#b23b3b')
+    .material({ metalness: 0.1, roughness: 0.6 })
+    .withConnectors({ hub: connector({ origin: [0, 0, 0], axis: [1, 0, 0] }) }),
+  { mate: { connector: 'hub', toLink: 'ankle' } },
+);
+
+// ── Validation: the solved bones actually reach their joints ─────────────────
+const solved = limb.solve({ hipSwing: DEFAULT_HIP_SWING, kneeBend: DEFAULT_KNEE_BEND });
+const knee = solved.getLinkPosition('knee');
+const ankle = solved.getLinkPosition('ankle');
+verify.equal('thigh edge holds its length', Points.distance(solved.getLinkPosition('hip'), knee), thighLen, 0.01);
+verify.equal('shin edge holds its length', Points.distance(knee, ankle), shinLen, 0.01);
+verify.that('the limb stays in the Y/Z plane', () => Math.abs(knee[0]) < 1e-6 && Math.abs(ankle[0]) < 1e-6);
+
+return limb;