forgecad 0.9.14 → 0.9.16

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;

package/examples/api/connector-frame-rig-chain.forge.js

@@ -0,0 +1,102 @@
+// Connector-frame rig chain: serial articulated parts need full connector frames.
+//
+// Use link() graphs for solved point skeletons and closed loops. Use connect()
+// when real geometry must inherit orientation from a joint frame. Here the upper
+// leg's local +X axis is locked by connector up vectors, so the part points from
+// the hip pivot toward the knee pivot at every solved pose. Return the Assembly
+// itself so editor controls call solve(state) instead of stacking viewport FK.
+
+const DEFAULT_POSE = { hip: 22, knee: -42, wheel: 0 };
+
+const upperLength = 68;
+const lowerLength = 58;
+const legWidth = 10;
+const legThickness = 8;
+const hubRadius = 9;
+const wheelRadius = 16;
+const wheelThickness = 8;
+
+function hingeConnector(origin, axis, up, type = "planar-hinge") {
+  return connector(type, { origin, axis, up, kind: "revolute" });
+}
+
+function legSegment(length, colorHex) {
+  const body = box(length, legWidth, legThickness).translate(length / 2, 0, -legThickness / 2);
+  const nearHub = cylinder(legThickness, hubRadius).translate(0, 0, -legThickness / 2);
+  const farHub = cylinder(legThickness, hubRadius).translate(length, 0, -legThickness / 2);
+
+  return group(
+    { name: "Body", shape: body },
+    { name: "Near hub", shape: nearHub },
+    { name: "Far hub", shape: farHub },
+  ).color(colorHex);
+}
+
+const hipDrum = group({
+  name: "Drum",
+  shape: cylinder(18, 14).translate(0, 0, -9).color("#495057"),
+}).withConnectors({
+  hip: hingeConnector([0, 0, 0], [0, 0, 1], [1, 0, 0]),
+});
+
+const upperLeg = legSegment(upperLength, "#d55e5e").withConnectors({
+  hip: hingeConnector([0, 0, 0], [0, 0, -1], [1, 0, 0]),
+  knee: hingeConnector([upperLength, 0, 0], [0, 0, 1], [1, 0, 0]),
+});
+
+const lowerLeg = legSegment(lowerLength, "#3d87c7").withConnectors({
+  knee: hingeConnector([0, 0, 0], [0, 0, -1], [1, 0, 0]),
+  axle: hingeConnector([lowerLength, 0, 0], [0, 1, 0], [1, 0, 0], "wheel-axle"),
+});
+
+const wheel = group({
+  name: "Wheel",
+  shape: cylinder(wheelThickness, wheelRadius)
+    .pointAlong([0, 1, 0])
+    .translate(0, -wheelThickness / 2, 0)
+    .color("#212529"),
+}).withConnectors({
+  axle: hingeConnector([0, 0, 0], [0, -1, 0], [1, 0, 0], "wheel-axle"),
+});
+
+const rig = assembly("Connector Frame Rig Chain")
+  .addPart("Hip Drum", hipDrum)
+  .addPart("Upper Leg", upperLeg)
+  .addPart("Lower Leg", lowerLeg)
+  .addPart("Wheel", wheel)
+  .connect("Hip Drum.hip", "Upper Leg.hip", { as: "hip", min: -35, max: 55, default: DEFAULT_POSE.hip })
+  .connect("Upper Leg.knee", "Lower Leg.knee", { as: "knee", min: -90, max: 20, default: DEFAULT_POSE.knee })
+  .connect("Lower Leg.axle", "Wheel.axle", { as: "wheel", min: -180, max: 180, default: DEFAULT_POSE.wheel });
+
+const solved = rig.solve(DEFAULT_POSE);
+
+const upper = solved.getTransform("Upper Leg");
+const lower = solved.getTransform("Lower Leg");
+const wheelTx = solved.getTransform("Wheel");
+
+const hip = upper.point([0, 0, 0]);
+const kneeFromUpper = upper.point([upperLength, 0, 0]);
+const kneeFromLower = lower.point([0, 0, 0]);
+const axleFromLower = lower.point([lowerLength, 0, 0]);
+const axleFromWheel = wheelTx.point([0, 0, 0]);
+
+const upperLocalX = upper.vector([1, 0, 0]);
+const hipToKnee = Points.direction(hip, kneeFromUpper);
+
+verify.equal("knee connector origins coincide", Points.distance(kneeFromUpper, kneeFromLower), 0, 0.001);
+verify.equal("wheel axle connector origins coincide", Points.distance(axleFromLower, axleFromWheel), 0, 0.001);
+verify.equal("upper leg local +X points hip to knee", Points.distance(upperLocalX, hipToKnee), 0, 0.001);
+
+scene({
+  background: { top: "#edf2f7", bottom: "#ffffff" },
+  camera: { position: [115, -190, 120], target: [45, 12, 0], fov: 34 },
+  environment: { preset: "studio", intensity: 0.45 },
+  lights: [
+    { type: "ambient", color: "#e8edf5", intensity: 0.25 },
+    { type: "directional", position: [120, -140, 180], target: [35, 5, 0], color: "#fff5e6", intensity: 1.6, castShadow: true },
+    { type: "directional", position: [-80, 100, 120], target: [40, 15, 0], color: "#c9ddff", intensity: 0.7 },
+  ],
+  ground: { visible: true, color: "#f6f8fa", height: -wheelRadius, receiveShadow: true },
+});
+
+return rig;

package/examples/api/exact-sheet-shell-assembly.forge.js

@@ -1,5 +1,3 @@
-if (getActiveBackend() === 'manifold') setActiveBackend('truck');
-
 const width = param('Width', 112);
 const depth = param('Depth', 78);
 const height = param('Height', 44);

package/examples/api/exact-surface-studio.forge.js

@@ -1,5 +1,3 @@
-if (getActiveBackend() === 'manifold') setActiveBackend('truck');
-
 const span = param('Span', 128);
 const depth = param('Depth', 88);
 const crown = param('Crown', 26);
@@ -41,7 +39,7 @@ const canopySheet = Surface.Nurbs(
 const canopySolid = canopySheet.thicken(wall).translate(-span * 0.82, 0, 0).color('#9fd3ff');
 const canopyGhost = canopySheet.translate(-span * 0.82, 0, wall * 2.4).color('#d9f0ff');
 
-const archFront = nurbs3d(
+const archFront = Curve.Nurbs(
   [
     [-halfSpan * 0.55, -halfDepth * 0.58, 2],
     [-halfSpan * 0.18, -halfDepth * 0.58, crown * 0.95],
@@ -50,7 +48,7 @@ const archFront = nurbs3d(
   ],
   { degree: 3 },
 );
-const archBack = nurbs3d(
+const archBack = Curve.Nurbs(
   [
     [-halfSpan * 0.48, halfDepth * 0.52, 0],
     [-halfSpan * 0.14, halfDepth * 0.52, crown * 0.68],
@@ -65,7 +63,7 @@ const ruledRibbon = Surface.Ruled(archFront, archBack)
 
 const boundaryPatch = Surface.Patch(
   {
-    bottom: nurbs3d(
+    bottom: Curve.Nurbs(
       [
         [-halfSpan * 0.48, -halfDepth * 0.42, -2],
         [-halfSpan * 0.16, -halfDepth * 0.46, crown * 0.35],
@@ -74,7 +72,7 @@ const boundaryPatch = Surface.Patch(
       ],
       { degree: 3 },
     ),
-    top: nurbs3d(
+    top: Curve.Nurbs(
       [
         [-halfSpan * 0.48, halfDepth * 0.4, 1],
         [-halfSpan * 0.16, halfDepth * 0.43, crown * 0.62],
@@ -83,7 +81,7 @@ const boundaryPatch = Surface.Patch(
       ],
       { degree: 3 },
     ),
-    left: nurbs3d(
+    left: Curve.Nurbs(
       [
         [-halfSpan * 0.48, -halfDepth * 0.42, -2],
         [-halfSpan * 0.58, -halfDepth * 0.12, crown * 0.22],
@@ -92,7 +90,7 @@ const boundaryPatch = Surface.Patch(
       ],
       { degree: 3 },
     ),
-    right: nurbs3d(
+    right: Curve.Nurbs(
       [
         [halfSpan * 0.48, -halfDepth * 0.42, -2],
         [halfSpan * 0.58, -halfDepth * 0.12, crown * 0.22],

package/examples/api/helix-basics.forge.js

@@ -1,14 +1,14 @@
-// Helix API basics.
+// Curve.Helix API basics.
 //
-// Helix.path() is the reusable centerline primitive.
-// Helix.coil() turns the same helix definition into a solid helix-oriented coil.
+// Curve.Helix.path() is the reusable centerline primitive.
+// Curve.Helix.coil() turns the same helix definition into a solid helix-oriented coil.
 
 const radius = Param.number("Radius", 18, { min: 8, max: 32, step: 1, unit: "mm" });
 const pitch = Param.number("Pitch", 6, { min: 2, max: 12, step: 0.5, unit: "mm" });
 const turns = Param.number("Turns", 4, { min: 1, max: 7, step: 0.25 });
 const wireRadius = Param.number("Wire Radius", 1, { min: 0.25, max: 2.5, step: 0.25, unit: "mm" });
 
-const guide = Helix.path({
+const guide = Curve.Helix.path({
   radius,
   pitch,
   turns,
@@ -16,7 +16,7 @@ const guide = Helix.path({
   samplesPerTurn: 48,
 });
 
-const circularWireCoil = Helix.coil({
+const circularWireCoil = Curve.Helix.coil({
   radius,
   pitch,
   turns,
@@ -26,7 +26,7 @@ const circularWireCoil = Helix.coil({
 }).translate(-70, 0, 0);
 
 const rectangularProfile = rect(wireRadius * 2.4, wireRadius * 1.1);
-const rectangularWireCoil = Helix.coil(rectangularProfile, {
+const rectangularWireCoil = Curve.Helix.coil(rectangularProfile, {
   radius,
   height: guide.height,
   turns,
@@ -49,8 +49,8 @@ const sampledPathMarkers = union(
   ...guide.sample(9).map(([x, y, z]) => sphere(wireRadius * 0.5).translate(x + 120, y, z)),
 );
 
-console.info(`Helix height: ${guide.height.toFixed(2)}`);
-console.info(`Helix centerline length: ${guide.length().toFixed(2)}`);
+console.info(`Curve.Helix height: ${guide.height.toFixed(2)}`);
+console.info(`Curve.Helix centerline length: ${guide.length().toFixed(2)}`);
 
 return [
   { name: "Circular wire coil", shape: circularWireCoil },

package/examples/api/lean-foundations/README.md

@@ -0,0 +1,12 @@
+# Selected Lean Foundations Examples
+
+This pack contains only the currently selected lean API buckets: Curve / Route and route endpoint canonicalization. Surface, standalone Frame, FaceRef, and topology-selector expansion examples were intentionally left out of this split.
+
+Run these with `node dist-cli/forgecad.js run <file>`:
+
+- `curve-blend-exact.forge.js` - `Curve.Blend` and `Curve.BlendG2` as exact reference rails that also feed `sweep`.
+- `curve-fit-interpolation.forge.js` - `Curve.Fit` interpolation with residual validation.
+- `curve-helix-canonicalization.forge.js` - `Curve.Helix` path and coil canonicalization.
+- `curve-route-canonicalization.forge.js` - `Curve.Route.fromPolyline()` segment and port preservation.
+- `curve-trim-reverse.forge.js` - exact trim and reverse operations.
+- `exact-curve-arc.forge.js` - exact `Curve.Arc` construction and sweep use.

package/examples/api/lean-foundations/curve-blend-exact.forge.js

@@ -0,0 +1,22 @@
+const g1Rail = Curve.Blend(
+  { point: [0, 0, 0], tangent: [1, 0, 0], weight: 0.7 },
+  { point: [48, 22, 10], tangent: [0, 1, 0], weight: 0.65 },
+);
+
+const g2Rail = Curve.BlendG2(
+  { point: [0, 18, 0], tangent: [1, 0, 0], curvature: [0, 0.01, 0], weight: 0.55 },
+  { point: [48, 42, 10], tangent: [0, 1, 0], curvature: [-0.01, 0, 0], weight: 0.55 },
+);
+
+const g1Tube = sweep(circle2d(1.6), g1Rail);
+const g2Tube = sweep(circle2d(1.2), g2Rail).color("#5a8f7b");
+
+const close3d = (a, b, tolerance = 1e-6) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) <= tolerance;
+
+verify.equal("Curve.Blend returns a cubic NURBS", g1Rail.degree, 3);
+verify.equal("Curve.BlendG2 returns a quintic NURBS", g2Rail.degree, 5);
+verify.that("Curve.Blend hits directed endpoints", () => close3d(g1Rail.pointAt(0), [0, 0, 0]) && close3d(g1Rail.pointAt(1), [48, 22, 10]));
+verify.that("Curve.BlendG2 hits directed endpoints", () => close3d(g2Rail.pointAt(0), [0, 18, 0]) && close3d(g2Rail.pointAt(1), [48, 42, 10]));
+verify.greaterThan("Blend rails are usable as sweep paths", g1Tube.boundingBox().max[0], 45);
+
+return group(g1Tube, g2Tube);

package/examples/api/lean-foundations/curve-fit-interpolation.forge.js

@@ -0,0 +1,18 @@
+const fittedRail = Curve.Fit(
+  [
+    [0, 0, 0],
+    [16, 8, 10],
+    [36, -6, 18],
+    [58, 10, 12],
+    [78, 0, 0],
+  ],
+  { degree: 3, tolerance: 0.001 },
+);
+
+const tube = sweep(circle2d(2), fittedRail);
+
+verify.equal('Curve.Fit returns a cubic NURBS for this rail', fittedRail.degree, 3);
+verify.equal('Curve.Fit keeps one control point per interpolated point', fittedRail.controlPoints.length, 5);
+verify.greaterThan('Curve.Fit rail has positive length', fittedRail.length(), 0);
+
+return tube;

package/examples/api/lean-foundations/curve-helix-canonicalization.forge.js

@@ -0,0 +1,27 @@
+const guide = Curve.Helix.path({
+  radius: 14,
+  pitch: 5,
+  turns: 3,
+  samplesPerTurn: 30,
+});
+
+const roundCoil = Curve.Helix.coil({
+  radius: 14,
+  pitch: 5,
+  turns: 3,
+  wireRadius: 0.8,
+  profileSegments: 16,
+  divisionsPerTurn: 100,
+});
+
+const rectangularCoil = Curve.Helix.coil(rect(1.2, 0.8), {
+  radius: 20,
+  height: 15,
+  turns: 3,
+  divisionsPerTurn: 18,
+}).translate(50, 0, 0);
+
+verify.equal('Curve.Helix guide derives height from pitch and turns', guide.height, 15);
+verify.greaterThan('Curve.Helix guide has positive centerline length', guide.length(), 0);
+
+return union(roundCoil, rectangularCoil);

package/examples/api/lean-foundations/curve-route-canonicalization.forge.js

@@ -0,0 +1,16 @@
+const route = Curve.Route.fromPolyline(
+  [
+    [0, 0, 0],
+    [0, 0, 48],
+    [36, 0, 48],
+    [36, 24, 72],
+  ],
+  { cornerRadius: 10, startPort: 'inlet', endPort: 'outlet' },
+);
+
+const tube = sweep(difference2d(circle2d(5), circle2d(3.5)), route);
+verify.equal('Curve.Route keeps line-arc-line-arc-line route intent', route.segments.length, 5);
+verify.equal('Curve.Route exposes named ports', Object.keys(route.ports).length, 2);
+verify.greaterThan('Curve.Route remains usable as a sweep path', tube.boundingBox().max[2], 70);
+
+return route;

package/examples/api/lean-foundations/curve-trim-reverse.forge.js

@@ -0,0 +1,24 @@
+const rail = Curve.Fit(
+  [
+    [0, 0, 0],
+    [24, 10, 8],
+    [54, -8, 12],
+    [84, 0, 0],
+  ],
+  { degree: 3 },
+);
+
+const middle = Curve.Trim(rail, 0.2, 0.8);
+const reversed = Curve.Reverse(middle);
+
+const middleTube = sweep(circle2d(1.2), middle).color("#5f8cc0");
+const reversedTube = sweep(circle2d(0.8), reversed).translate(0, 18, 0).color("#c06f5f");
+
+const close3d = (a, b, tolerance = 1e-6) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) <= tolerance;
+
+verify.that("Curve.Trim starts at the source subdomain", () => close3d(middle.pointAt(0), rail.pointAt(0.2)));
+verify.that("Curve.Trim ends at the source subdomain", () => close3d(middle.pointAt(1), rail.pointAt(0.8)));
+verify.that("Curve.Reverse preserves geometry with opposite parameter direction", () => close3d(reversed.pointAt(0), middle.pointAt(1)));
+verify.greaterThan("Trimmed curves feed exact sweep rails", middleTube.boundingBox().max[0], 60);
+
+return group(middleTube, reversedTube);

package/examples/api/lean-foundations/exact-curve-arc.forge.js

@@ -0,0 +1,36 @@
+const lower = Curve.Arc({
+  start: [36, 0, 0],
+  end: [0, 36, 0],
+  tangent: [0, 1, 0],
+});
+const upper = Curve.Arc({
+  start: [36, 0, 10],
+  end: [0, 36, 10],
+  tangent: [0, 1, 0],
+});
+const half = Curve.Arc({
+  start: [12, 0, 18],
+  end: [-12, 0, 18],
+  tangent: [0, 1, 0],
+});
+
+const tube = sweep(circle2d(0.8), lower);
+const upperTube = sweep(circle2d(0.5), upper).color("#5a8f7b");
+
+const close3d = (a, b, tolerance = 1e-6) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) <= tolerance;
+
+verify.that("Curve.Arc hits start, midpoint, and end exactly", () =>
+  close3d(lower.pointAt(0), [36, 0, 0]) &&
+  close3d(lower.pointAt(0.5), [36 * Math.SQRT1_2, 36 * Math.SQRT1_2, 0]) &&
+  close3d(lower.pointAt(1), [0, 36, 0]));
+
+verify.that("Curve.Arc emits stable rational spans for half circles", () =>
+  half.controlPoints.length === 5 && close3d(half.pointAt(0.5), [0, 12, 18]));
+
+verify.that("Curve.Arc feeds sweep as an exact NURBS rail", () =>
+  tube.geometryInfo().backend !== "unknown" && tube.boundingBox().max[0] > 30 && tube.boundingBox().max[1] > 30);
+
+verify.that("Multiple Curve.Arc rails remain reusable sweep inputs", () =>
+  upperTube.boundingBox().max[2] > 10 && upperTube.boundingBox().max[0] > 30);
+
+return group(tube, upperTube);

package/examples/api/mixed-edge-finishes-proof.forge.js

@@ -27,17 +27,14 @@ const body = plate.subtract(cutout);
 const bodyEdges = selectEdges(body);
 const raw = body.color('#7b8490');
 const chamfered = chamfer(body, 0.75, bodyEdges).color('#d3a33a');
-const shapes = [
+// Native Truck fillet now produces analytic rolling-ball geometry (cylinders,
+// spheres, and toroidal corner blends) that exports to STEP canonically
+// identical to OpenCascade. See:
+//   forgecad export step examples/api/mixed-edge-finishes-proof.forge.js --backend truck
+const filleted = fillet(body, 0.75, bodyEdges).color('#4e8fd6');
+
+return [
   { name: 'Raw', shape: raw.translate(-80, 0, 0) },
   { name: 'Chamfered', shape: chamfered.translate(30, 0, 0) },
+  { name: 'Filleted', shape: filleted.translate(140, 0, 0) },
 ];
-
-try {
-  const filleted = fillet(body, 0.75, bodyEdges).color('#4e8fd6');
-  filleted.volume();
-  shapes.push({ name: 'Filleted', shape: filleted.translate(140, 0, 0) });
-} catch (error) {
-  console.log(`Filleted: unsupported in native Truck (${error instanceof Error ? error.message : String(error)})`);
-}
-
-return shapes;

package/examples/api/route3d-elbow.forge.js

@@ -0,0 +1,71 @@
+// Curve.Route elbow - demonstrates virtual 3D route corners, named route ports,
+// and sweeping an annular profile without hand-computing tangent points.
+
+const route = Curve.Route.fromPolyline(
+  [
+    [0, 0, 0],
+    [0, 0, 203.2],
+    [203.2, 0, 203.2],
+  ],
+  { cornerRadius: 114.3, startPort: 'inlet', endPort: 'outlet' },
+);
+
+const outerRadius = 44.45;
+const innerRadius = 38.96;
+const flangeRadius = 89.0;
+const boltCircleRadius = 72.3;
+const boltRadius = 5.3;
+const flangeThickness = 17.8;
+const neckLength = 26.645;
+const neckRadius = 55.6;
+
+const tubeProfile = difference2d(circle2d(outerRadius, 80), circle2d(innerRadius, 80));
+
+const pipe = sweep(tubeProfile, route, { samples: 72 });
+
+return pipe;
+
+function placeAtPort(shape, port, offset) {
+  return shape.pointAlong(port.axis).translate(
+    port.origin[0] + port.axis[0] * offset,
+    port.origin[1] + port.axis[1] * offset,
+    port.origin[2] + port.axis[2] * offset,
+  );
+}
+
+function flangePlate() {
+  const bore = cylinder(flangeThickness + 2, innerRadius, undefined, 80).translate(0, 0, -1);
+  const firstBolt = cylinder(flangeThickness + 2, boltRadius, undefined, 24).translate(boltCircleRadius, 0, -1);
+  const bolts = circularPattern(firstBolt, 5);
+  return cylinder(flangeThickness, flangeRadius, undefined, 96).subtract(bore, bolts);
+}
+
+function neck() {
+  const bore = cylinder(neckLength + 2, innerRadius, undefined, 80).translate(0, 0, -1);
+  return cylinder(neckLength, neckRadius, undefined, 80).subtract(bore);
+}
+
+const inlet = route.port('inlet');
+const outlet = route.port('outlet');
+const body = union(
+  pipe,
+  placeAtPort(neck(), inlet, -4.445),
+  placeAtPort(flangePlate(), inlet, 20.0),
+  placeAtPort(neck(), outlet, -4.445),
+  placeAtPort(flangePlate(), outlet, 20.0),
+).color('#b9c0c8');
+
+const bbox = body.boundingBox();
+const bboxSize = [bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2]];
+
+verify.equal('Curve.Route elbow keeps line-arc-line route intent', route.segments.length, 3);
+verify.equal('Curve.Route elbow exposes inlet and outlet ports', Object.keys(route.ports).length, 2);
+verify.boundingBoxSize('Curve.Route elbow preserves BenchCAD-scale envelope', body, [337, 178, 330], 18);
+verify.that(
+  'Curve.Route elbow bbox stays in expected quadrants',
+  () => bbox.min[0] < -40 && bbox.max[0] > 235 && bbox.min[2] < -35 && bbox.max[2] > 245 && bboxSize[1] > 175,
+  `bbox was ${JSON.stringify(bbox)}`,
+);
+verify.physicalComponentCount('Curve.Route elbow is one connected component', 1);
+
+return body;