forgecad 0.1.0

package/examples/api/boolean-operations.forge.js

@@ -0,0 +1,48 @@
+// Boolean operations — union, difference, intersection.
+//
+// union(a, b)        → combined volume
+// difference(a, b)   → a minus b (subtract b from a)
+// intersection(a, b) → only the overlapping volume
+//
+// Method syntax also accepts multiple cutters/operands:
+// a.add(b, c), a.subtract(b, c), a.intersect(b, c)
+// and the helper functions also accept arrays:
+// difference([a, b, c]), union([a, b, c]), intersection([a, b, c])
+
+const size = param("Size", 30, { min: 15, max: 50, unit: "mm" });
+const overlap = param("Overlap", 15, { min: 0, max: 30, unit: "mm" });
+const spacing = 80;
+
+// Two overlapping shapes for each demo
+function makePair(offsetX) {
+  const a = box(size, size, size, true).translate(offsetX, 0, 0).color('#4488cc');
+  const b = sphere(size * 0.6).translate(offsetX + size - overlap, 0, 0).color('#cc4444');
+  return [a, b];
+}
+
+// 1. Union — combined
+const [u1, u2] = makePair(0);
+const unioned = union(u1, u2).color('#8866cc');
+
+// 2. Difference — box minus sphere and cross-bore
+const [d1, d2] = makePair(spacing);
+const d3 = cylinder(size * 1.2, size * 0.14, undefined, undefined, true)
+  .pointAlong([0, 1, 0])
+  .translate(spacing, 0, 0);
+const diffed = d1.subtract(d2, d3);
+
+// 3. Intersection — only overlap
+const [i1, i2] = makePair(2 * spacing);
+const intersected = intersection(i1, i2).color('#cc8844');
+
+// Show the original shapes (translucent-ish via separate objects) for reference
+const refA = box(size, size, size, true).translate(3 * spacing, 0, 0).color('#4488cc');
+const refB = sphere(size * 0.6).translate(3 * spacing + size - overlap, 0, 0).color('#cc4444');
+
+return [
+  { name: "Union", shape: unioned },
+  { name: "Difference (box - sphere - bore)", shape: diffed },
+  { name: "Intersection", shape: intersected },
+  { name: "Original Box", shape: refA },
+  { name: "Original Sphere", shape: refB },
+];

package/examples/api/bounding-box-visualizer.forge.js

@@ -0,0 +1,58 @@
+// Visualize bounding boxes — useful for debugging positioning.
+//
+// boundingBox() returns { min: [x,y,z], max: [x,y,z] }.
+// This example draws thin cylinders along the 12 edges of the bbox.
+
+const edgeR = 0.5; // wireframe edge radius
+
+function vizBBox(shape) {
+  const bb = shape.boundingBox();
+  const [x0, y0, z0] = bb.min;
+  const [x1, y1, z1] = bb.max;
+  const dx = x1 - x0, dy = y1 - y0, dz = z1 - z0;
+
+  const edges = [];
+  // 4 edges along X (at each combination of Y,Z corners)
+  for (const y of [y0, y1]) {
+    for (const z of [z0, z1]) {
+      edges.push(cylinder(dx, edgeR).pointAlong([1, 0, 0]).translate(x0, y, z));
+    }
+  }
+  // 4 edges along Y
+  for (const x of [x0, x1]) {
+    for (const z of [z0, z1]) {
+      edges.push(cylinder(dy, edgeR).pointAlong([0, 1, 0]).translate(x, y0, z));
+    }
+  }
+  // 4 edges along Z
+  for (const x of [x0, x1]) {
+    for (const y of [y0, y1]) {
+      edges.push(cylinder(dz, edgeR).translate(x, y, z0));
+    }
+  }
+  return union(...edges);
+}
+
+// --- Demo shapes ---
+
+// A rotated box — bbox is larger than the shape itself
+const angle = param("Rotation", 30, { min: 0, max: 90, unit: "°" });
+const rotBox = box(40, 30, 20, true).rotate(0, 0, angle).color('#4488cc');
+const rotBBox = vizBBox(rotBox).color('#cc4444');
+
+// A sphere — bbox is a perfect cube around it
+const sph = sphere(20).translate(80, 0, 0).color('#44cc44');
+const sphBBox = vizBBox(sph).color('#cc4444');
+
+// A tilted cylinder — bbox shows the extent
+const tiltCyl = cylinder(50, 10).rotate(30, 0, 0).translate(0, 80, 0).color('#cc88ff');
+const cylBBox = vizBBox(tiltCyl).color('#cc4444');
+
+return [
+  { name: "Rotated Box", shape: rotBox },
+  { name: "Box BBox", shape: rotBBox },
+  { name: "Sphere", shape: sph },
+  { name: "Sphere BBox", shape: sphBBox },
+  { name: "Tilted Cylinder", shape: tiltCyl },
+  { name: "Cylinder BBox", shape: cylBBox },
+];

package/examples/api/brep-exportable.forge.js

@@ -0,0 +1,19 @@
+// Exact-exportable subset demo for STEP/BREP.
+// Run: forgecad export step examples/api/brep-exportable.forge.js
+
+const plate = rect(120, 80, true).extrude(10).color('#748b99');
+const boss = cylinder(24, 18).translate(0, 0, 10).color('#b7c4cc');
+
+const leftHole = cylinder(18, 5).translate(-34, 0, -4);
+const rightHole = cylinder(18, 5).translate(34, 0, -4);
+const centerBore = cylinder(34, 8).translate(0, 0, 6);
+
+const exactPart = union(plate.toShape(), boss)
+  .subtract(leftHole)
+  .subtract(rightHole)
+  .subtract(centerBore)
+  .color('#9db1bd');
+
+return [
+  { name: 'Exact Export Demo', shape: exactPart },
+];

package/examples/api/center-true-vs-false.forge.js

@@ -0,0 +1,40 @@
+// center=true vs center=false — the #1 source of positioning confusion.
+//
+// box(w, d, h)        → corner at origin, extends into +X, +Y, +Z
+// box(w, d, h, true)  → centered at origin
+//
+// Same applies to cylinder(h, r) vs cylinder(h, r, r, undefined, true).
+
+const w = 40, d = 30, h = 20;
+
+// --- Side-by-side comparison ---
+
+// Left: center=false (default). Red sphere marks the origin [0,0,0].
+const cornerBox = box(w, d, h).color('#4488cc').translate(-60, 0, 0);
+const cornerOrigin = sphere(2).color('#cc0000').translate(-60, 0, 0);
+
+// Right: center=true. Red sphere marks the origin [0,0,0].
+const centeredBox = box(w, d, h, true).color('#44cc88').translate(60, 0, 0);
+const centeredOrigin = sphere(2).color('#cc0000').translate(60, 0, 0);
+
+// --- Practical impact: placing a cylinder on top of a base ---
+
+// With center=false: cylinder must go to (w/2, d/2, h)
+const base1 = box(w, d, h).color('#888888').translate(-60, 60, 0);
+const cyl1 = cylinder(15, 6).color('#cc8844').translate(-60 + w/2, 60 + d/2, h);
+
+// With center=true + attachTo: no math needed
+const base2 = box(w, d, h, true).color('#888888').translate(60, 60 + d/2, h/2);
+const cyl2 = cylinder(15, 6).color('#cc8844')
+  .attachTo(base2, 'top', 'bottom');
+
+return [
+  { name: "Corner Box (center=false)", shape: cornerBox },
+  { name: "Corner Origin ●", shape: cornerOrigin },
+  { name: "Centered Box (center=true)", shape: centeredBox },
+  { name: "Centered Origin ●", shape: centeredOrigin },
+  { name: "Base (corner)", shape: base1 },
+  { name: "Cylinder (manual math)", shape: cyl1 },
+  { name: "Base (centered)", shape: base2 },
+  { name: "Cylinder (attachTo)", shape: cyl2 },
+];

package/examples/api/clone-duplicate.forge.js

@@ -0,0 +1,41 @@
+// clone() / duplicate() — explicit copy helpers for Shape, TrackedShape, Sketch, and ShapeGroup.
+
+const spacing = param("Spacing", 90, { min: 40, max: 180, unit: "mm" });
+
+// --- Shape clone ---
+const block = box(36, 20, 12, true).color("#4a90e2");
+const blockL = block.clone().translate(-spacing / 2, 0, 0);
+const blockR = block.duplicate().translate(spacing / 2, 0, 0);
+
+// --- TrackedShape clone (topology preserved) ---
+const post = cylinder(36, 6).color("#49b675");
+const postCopy = post.clone().translate(0, 45, 0);
+
+// --- Sketch clone ---
+const slotProfile = slot(30, 10).color("#e98b39");
+const slotL = slotProfile.clone().translate(-spacing / 2, -35);
+const slotR = slotProfile.duplicate().translate(spacing / 2, -35);
+
+// --- ShapeGroup clone (with named children) ---
+const moduleGroup = group(
+  { name: "Block", shape: block },
+  { name: "Post", shape: post.attachTo(block, "top", "bottom") }
+);
+const moduleL = moduleGroup.clone().translate(-spacing / 2, 95, 0);
+const moduleR = moduleGroup.duplicate().translate(spacing / 2, 95, 0).color("#c85a54");
+
+return [
+  { name: "Shape clone/duplicate", group: [
+    { name: "Block L", shape: blockL },
+    { name: "Block R", shape: blockR },
+  ] },
+  { name: "TrackedShape clone", shape: postCopy },
+  { name: "Sketch clone/duplicate", group: [
+    { name: "Slot L", sketch: slotL },
+    { name: "Slot R", sketch: slotR },
+  ] },
+  { name: "ShapeGroup clone/duplicate", group: [
+    { name: "Module L", shape: moduleL },
+    { name: "Module R", shape: moduleR },
+  ] },
+];

package/examples/api/colors-union-vs-array.forge.js

@@ -0,0 +1,27 @@
+// Colors: union() vs returning separate objects.
+//
+// ❌ union() merges into one mesh → only the first shape's color survives.
+// ✅ Returning an array of {name, shape} → each keeps its own color.
+
+const size = 25;
+const gap = 5;
+
+// --- Three colored boxes ---
+const red   = box(size, size, size, true).color('#cc4444');
+const green = box(size, size, size, true).color('#44cc44').translate(size + gap, 0, 0);
+const blue  = box(size, size, size, true).color('#4444cc').translate(2 * (size + gap), 0, 0);
+
+// BAD: union kills individual colors — result is all red (first shape's color)
+const merged = union(red, green, blue).translate(-80, 0, 0);
+
+// GOOD: separate objects keep their colors
+const redSep   = box(size, size, size, true).color('#cc4444').translate(80, 0, 0);
+const greenSep = box(size, size, size, true).color('#44cc44').translate(80 + size + gap, 0, 0);
+const blueSep  = box(size, size, size, true).color('#4444cc').translate(80 + 2 * (size + gap), 0, 0);
+
+return [
+  { name: "❌ Union (all one color)", shape: merged },
+  { name: "✅ Red (separate)", shape: redSep },
+  { name: "✅ Green (separate)", shape: greenSep },
+  { name: "✅ Blue (separate)", shape: blueSep },
+];

package/examples/api/coordinate-system.forge.js

@@ -0,0 +1,54 @@
+// Coordinate system — ForgeCAD uses Z-up, right-handed.
+//   X = right (+X), left (-X)
+//   Y = forward (+Y), back (-Y)
+//   Z = up (+Z), down (-Z)
+//
+// "front" = -Y face (camera default looks from -Y toward +Y)
+// "back"  = +Y face
+
+const axisLen = 80;
+const shaftR = 2;
+const tipH = 10;
+const tipR = 5;
+
+// X axis — red, pointing right
+const xShaft = cylinder(axisLen, shaftR).pointAlong([1, 0, 0]).color('#cc4444');
+const xTip = cylinder(tipH, tipR, 0).pointAlong([1, 0, 0]).translate(axisLen, 0, 0).color('#cc4444');
+const xMark = sphere(4).translate(axisLen + tipH + 5, 0, 0).color('#cc4444');
+
+// Y axis — green, pointing forward
+const yShaft = cylinder(axisLen, shaftR).pointAlong([0, 1, 0]).color('#44cc44');
+const yTip = cylinder(tipH, tipR, 0).pointAlong([0, 1, 0]).translate(0, axisLen, 0).color('#44cc44');
+const yMark = box(7, 7, 7, true).translate(0, axisLen + tipH + 5, 0).color('#44cc44');
+
+// Z axis — blue, pointing up
+const zShaft = cylinder(axisLen, shaftR).color('#4444cc');
+const zTip = cylinder(tipH, tipR, 0).translate(0, 0, axisLen).color('#4444cc');
+const zMark = ngon(6, 4).extrude(4, { center: true }).translate(0, 0, axisLen + tipH + 5).color('#4444cc');
+
+// Origin
+const origin = sphere(3).color('#ffffff');
+
+// Reference box to show face names
+const ref = box(30, 20, 15, true).translate(40, 40, 0).color('#888888');
+// "front" face is at -Y, "right" face is at +X, "top" face is at +Z
+const frontDot = sphere(3).color('#ffaa00')
+  .attachTo(ref, 'front', 'center', [0, -5, 0]);
+const topDot = sphere(3).color('#ffaa00')
+  .attachTo(ref, 'top', 'center', [0, 0, 5]);
+
+return [
+  { name: "X shaft (right)", shape: xShaft },
+  { name: "X tip", shape: xTip },
+  { name: "X mark ●", shape: xMark },
+  { name: "Y shaft (forward)", shape: yShaft },
+  { name: "Y tip", shape: yTip },
+  { name: "Y mark ■", shape: yMark },
+  { name: "Z shaft (up)", shape: zShaft },
+  { name: "Z tip", shape: zTip },
+  { name: "Z mark ⬡", shape: zMark },
+  { name: "Origin", shape: origin },
+  { name: "Reference Box", shape: ref },
+  { name: "Front dot (−Y)", shape: frontDot },
+  { name: "Top dot (+Z)", shape: topDot },
+];

package/examples/api/curves-surfacing-basics.forge.js

@@ -0,0 +1,91 @@
+// Curves + Surfacing basics
+// Demonstrates reusable APIs for everyday products:
+// - spline2d() for smooth section sketches
+// - loft() for section-driven solids
+// - spline3d() + sweep() for curved tubes/handles/details
+
+const height = param("Bottle Height", 170, { min: 110, max: 260, unit: "mm" });
+const bodyW = param("Body Width", 72, { min: 45, max: 110, unit: "mm" });
+const bodyD = param("Body Depth", 48, { min: 30, max: 90, unit: "mm" });
+const neckW = param("Neck Width", 28, { min: 18, max: 45, unit: "mm" });
+const neckD = param("Neck Depth", 24, { min: 14, max: 40, unit: "mm" });
+const corner = param("Corner Round", 8, { min: 2, max: 20, unit: "mm" });
+
+const sectionAt = (w, d, pinch = 0) => spline2d([
+  [w * 0.5, 0],
+  [w * 0.42, d * 0.45],
+  [w * 0.2, d * 0.5 + pinch],
+  [0, d * 0.52 + pinch],
+  [-w * 0.2, d * 0.5 + pinch],
+  [-w * 0.42, d * 0.45],
+  [-w * 0.5, 0],
+  [-w * 0.42, -d * 0.45],
+  [-w * 0.2, -d * 0.5 + pinch],
+  [0, -d * 0.52 + pinch],
+  [w * 0.2, -d * 0.5 + pinch],
+  [w * 0.42, -d * 0.45],
+], {
+  closed: true,
+  samplesPerSegment: 10,
+  tension: 0.42,
+}).offset(corner * 0.08, 'Round');
+
+const z0 = 0;
+const z1 = height * 0.25;
+const z2 = height * 0.62;
+const z3 = height * 0.9;
+const z4 = height;
+
+const body = loft(
+  [
+    sectionAt(bodyW * 0.86, bodyD * 0.84, -2),
+    sectionAt(bodyW, bodyD, 0),
+    sectionAt(bodyW * 0.92, bodyD * 0.94, 1),
+    sectionAt(neckW * 1.25, neckD * 1.2, 0.5),
+    sectionAt(neckW, neckD, 0),
+  ],
+  [z0, z1, z2, z3, z4],
+  { edgeLength: 1.1 },
+);
+
+// Hollow interior by lofting smaller inner sections.
+const wall = 2.4;
+const inner = loft(
+  [
+    sectionAt(bodyW * 0.78, bodyD * 0.76, -2.2),
+    sectionAt(bodyW - wall * 2, bodyD - wall * 2, -0.6),
+    sectionAt(bodyW * 0.86 - wall * 2, bodyD * 0.88 - wall * 2, 0.2),
+    sectionAt(neckW * 1.06 - wall, neckD * 1.06 - wall, 0),
+    sectionAt(neckW - wall, neckD - wall, 0),
+  ],
+  [z0 + 3, z1, z2, z3, z4 + 2],
+  { edgeLength: 1.1 },
+);
+
+let bottle = body.subtract(inner);
+// Mild smoothing to reduce voxel-like artifacts on curved sections.
+bottle = bottle.smoothOut(70, 0.25).refine(2);
+
+// Curved spout/tube detail using sweep.
+const spoutPath = spline3d(
+  [
+    [0, 0, z4 - 8],
+    [12, 0, z4 + 8],
+    [26, 0, z4 + 24],
+    [36, 0, z4 + 16],
+  ],
+  { tension: 0.45 },
+);
+const spout = sweep(circle2d(2.8, 20), spoutPath, {
+  samples: 36,
+  edgeLength: 0.65,
+});
+
+const topCap = circle2d(Math.max(neckW, neckD) * 0.34, 40).extrude(9)
+  .translate(0, 0, z4 - 1.5);
+
+return [
+  { name: "Bottle Body", shape: bottle.color('#d8e5ec') },
+  { name: "Spout", shape: spout.color('#c0ccd4') },
+  { name: "Cap", shape: topCap.color('#4f5f70') },
+];

package/examples/api/dimensioned-bracket.forge.js

@@ -0,0 +1,19 @@
+// Dimensioned L-bracket — shows how to add dimension annotations
+
+const w = param("Width", 80, { min: 40, max: 150, unit: "mm" });
+const h = param("Height", 60, { min: 30, max: 100, unit: "mm" });
+const d = param("Depth", 40, { min: 20, max: 80, unit: "mm" });
+const t = param("Thickness", 5, { min: 2, max: 15, unit: "mm" });
+
+// Build the L-bracket
+const base = box(w, d, t);
+const wall = box(t, d, h).translate(0, 0, t);
+const bracket = union(base, wall);
+
+// Add dimensions — purely visual annotations
+dim([0, 0, 0], [w, 0, 0], { label: "Width" });
+dim([0, 0, 0], [0, d, 0], { label: "Depth", offset: 12 });
+dim([0, 0, 0], [0, 0, h + t], { label: "Height", offset: 15 });
+dim([0, 0, 0], [t, 0, 0], { label: "Wall", offset: -8, color: "#ffaa44" });
+
+return bracket;

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

@@ -0,0 +1,23 @@
+// Test lib.elbow() — pipe bend primitive
+const pipeR = param("Pipe Radius", 5, { min: 2, max: 15, unit: "mm" });
+const bendR = param("Bend Radius", 25, { min: 10, max: 60, unit: "mm" });
+const angle = param("Angle", 90, { min: 15, max: 180, unit: "°" });
+
+// Basic elbow at default orientation
+const basic = lib.elbow(pipeR, bendR, angle).color('#B87333');
+
+// Elbow with from/to directions
+const oriented = lib.elbow(pipeR, bendR, {
+  from: [0, 0, 1],
+  to: [1, 0, 0],
+}).translate(80, 0, 0).color('#4488cc');
+
+// Hollow elbow
+const hollow = lib.elbow(pipeR, bendR, angle, { wall: 1.5 })
+  .translate(0, 80, 0).color('#888888');
+
+return [
+  { name: "Basic 90° Elbow", shape: basic },
+  { name: "Oriented Elbow (Z→X)", shape: oriented },
+  { name: "Hollow Elbow", shape: hollow },
+];

package/examples/api/exploded-view.forge.js

@@ -0,0 +1,60 @@
+// Standard-library exploded view: staged offsets + per-part direction overrides.
+
+const explodeAmt = param("Explode", 0, { min: 0, max: 36, unit: "mm" });
+
+const base = box(120, 80, 10, true).color('#5f6d7a');
+const pedestal = box(70, 40, 20, true).translate(0, 0, 15).color('#6f7f8f');
+
+const motorBody = cylinder(55, 16, 16, 40, true)
+  .pointAlong([1, 0, 0])
+  .translate(0, 0, 32)
+  .color('#8f9eab');
+const shaft = cylinder(80, 4, 4, 24, true)
+  .pointAlong([1, 0, 0])
+  .translate(0, 0, 32)
+  .color('#d1d7de');
+const rotorCap = cylinder(8, 18, 18, 36, true)
+  .pointAlong([1, 0, 0])
+  .translate(31, 0, 32)
+  .color('#9eacb9');
+
+const boltTemplate = lib.bolt(6, 26).rotate(180, 0, 0).color('#d8dde3');
+const bolts = [
+  boltTemplate.translate(-45, -25, 10),
+  boltTemplate.translate(45, -25, 10),
+  boltTemplate.translate(-45, 25, 10),
+  boltTemplate.translate(45, 25, 10),
+];
+
+const explodedParts = [
+  { name: "Base", shape: base },
+  { name: "Pedestal", shape: pedestal, explode: { stage: 0.35, direction: [0, 0, 1] } },
+  {
+    name: "Drive",
+    group: [
+      { name: "Motor Body", shape: motorBody },
+      { name: "Rotor Cap", shape: rotorCap, explode: { stage: 1.1, direction: [1, 0, 0] } },
+      { name: "Shaft", shape: shaft },
+    ],
+  },
+  {
+    name: "Fasteners",
+    group: bolts.map((b, i) => ({
+      name: `Bolt ${i + 1}`,
+      shape: b,
+      explode: { stage: 0.9, direction: 'z' },
+    })),
+  },
+];
+
+cutPlane("Center Section", [0, 1, 0], 0);
+
+return lib.explode(explodedParts, {
+  amount: explodeAmt,
+  stages: [0.35, 0.7, 1.0],
+  mode: 'radial',
+  byName: {
+    "Shaft": { direction: [1, 0, 0], stage: 1.4 },
+    "Fasteners": { axisLock: 'z', stage: 0.45 },
+  },
+});

package/examples/api/extrude-options.forge.js

@@ -0,0 +1,44 @@
+// Extrude options — twist, taper, center.
+//
+// .extrude(height) is the basic form.
+// Options: { twist, divisions, scaleTop, center }
+
+const r = param("Radius", 20, { min: 10, max: 40, unit: "mm" });
+const h = param("Height", 60, { min: 20, max: 120, unit: "mm" });
+const twist = param("Twist", 90, { min: 0, max: 360, unit: "°" });
+const taper = param("Taper", 0.5, { min: 0.1, max: 1.0 });
+const spacing = 60;
+
+// 1. Plain extrude
+const plain = ngon(6, r).extrude(h)
+  .color('#4488cc');
+
+// 2. Twisted extrude — needs divisions for smooth twist
+const twisted = ngon(6, r).extrude(h, { twist: twist, divisions: 32 })
+  .translate(spacing, 0, 0)
+  .color('#cc8844');
+
+// 3. Tapered extrude — scaleTop shrinks the top face
+const tapered = circle2d(r).extrude(h, { scaleTop: taper })
+  .translate(2 * spacing, 0, 0)
+  .color('#44cc88');
+
+// 4. Centered extrude — shape is centered along Z instead of starting at Z=0
+const centered = rect(r * 1.5, r, true).extrude(h, { center: true })
+  .translate(3 * spacing, 0, 0)
+  .color('#cc44cc');
+
+// 5. Combined: twist + taper
+const combo = star(5, r, r * 0.5).extrude(h, {
+  twist: twist,
+  scaleTop: taper,
+  divisions: 32,
+}).translate(4 * spacing, 0, 0).color('#cccc44');
+
+return [
+  { name: "Plain", shape: plain },
+  { name: "Twisted", shape: twisted },
+  { name: "Tapered", shape: tapered },
+  { name: "Centered (Z)", shape: centered },
+  { name: "Twist + Taper", shape: combo },
+];

package/examples/api/face-gears.forge.js

@@ -0,0 +1,44 @@
+// Face gear demo: teeth on one face + perpendicular vertical spur gear.
+
+const moduleSize = param("Module", 1.25, { min: 0.6, max: 3.0, step: 0.05 });
+const faceTeeth = param("Face Teeth", 36, { min: 18, max: 84, integer: true });
+const verticalTeeth = param("Vertical Teeth", 12, { min: 8, max: 30, integer: true });
+const faceWidth = param("Face Width", 8, { min: 4, max: 18, unit: "mm" });
+const toothHeight = param("Face Tooth Height", 1.25, { min: 0.4, max: 3.5, step: 0.05, unit: "mm" });
+const backlash = param("Backlash", 0.04, { min: 0, max: 0.2, step: 0.01, unit: "mm" });
+const topFace = param("Top Face Teeth (1/0)", 1, { min: 0, max: 1, integer: true });
+
+const pair = lib.faceGearPair({
+  face: {
+    module: moduleSize,
+    teeth: faceTeeth,
+    pressureAngleDeg: 20,
+    faceWidth,
+    toothHeight,
+    side: topFace === 0 ? "bottom" : "top",
+    boreDiameter: moduleSize * 5,
+  },
+  vertical: {
+    module: moduleSize,
+    teeth: verticalTeeth,
+    pressureAngleDeg: 20,
+    faceWidth,
+    boreDiameter: moduleSize * 3,
+  },
+  backlash,
+});
+
+for (const d of pair.diagnostics) {
+  const tag = `[${d.level}] ${d.code}`;
+  if (d.level === "error") console.error(tag, d.message);
+  else if (d.level === "warn") console.warn(tag, d.message);
+  else console.info(tag, d.message);
+}
+
+const faceColor = pair.status === "error" ? "#bf4b4b" : "#8aa8c2";
+const verticalColor = pair.status === "error" ? "#c58b5d" : "#d5a15f";
+
+return [
+  { name: "Face Gear", shape: pair.face.color(faceColor) },
+  { name: "Vertical Gear", shape: pair.vertical.color(verticalColor) },
+];

package/examples/api/face-transformation-history.forge.js

@@ -0,0 +1,45 @@
+/**
+ * Face Transformation History Demo
+ *
+ * Shows how to trace the transformation chain for each surface.
+ */
+
+const base = box(100, 60, 20, true)
+  .translate(0, 0, 10)
+  .rotate(0, 0, 15);
+
+const withHole = base
+  .hole('top', { diameter: 12, depth: 8, u: 20, v: 10 });
+
+// Get the transformation history for the top face
+const topHistory = withHole.faceHistory('top');
+
+// Get history for the hole floor
+const floorHistory = withHole.faceHistory('floor');
+
+// Display the histories as dimensions for visibility
+dim([0, 0, 0], [10, 0, 0], {
+  label: `Top: ${topHistory.origin.operation} → ${topHistory.transformations.length} transforms`,
+});
+
+dim([0, 0, 0], [0, 10, 0], {
+  label: `Floor: ${floorHistory.origin.operation} → ${floorHistory.transformations.length} transforms`,
+});
+
+// Also log to console for CLI output
+console.log('=== Face Transformation History ===');
+console.log('\nTop Face:');
+console.log('  Origin:', topHistory.origin.operation);
+console.log('  Transformations:');
+topHistory.transformations.forEach((step, i) => {
+  console.log(`    ${i + 1}. ${step.description}`);
+});
+
+console.log('\nHole Floor Face:');
+console.log('  Origin:', floorHistory.origin.operation);
+console.log('  Transformations:');
+floorHistory.transformations.forEach((step, i) => {
+  console.log(`    ${i + 1}. ${step.description}`);
+});
+
+return withHole;

package/examples/api/feature-created-faces.forge.js

@@ -0,0 +1,47 @@
+const shellBase = roundedRect(90, 56, 6, true).extrude(28);
+const cup = shellBase.shell(2.5, { openFaces: ['top'] }).color('#6f7b86');
+const innerWallPad = roundedRect(16, 9, 1.8, true)
+  .onFace(cup, 'inner-side-right', { u: 0, v: -3, protrude: 0.05, selfAnchor: 'center' })
+  .extrude(1.4)
+  .toShape()
+  .color('#f2b16a');
+
+const holeBase = roundedRect(72, 44, 5, true).extrude(20);
+const drilled = holeBase.hole('top', { diameter: 8, u: 16, v: -8, depth: 10 }).color('#7a8792');
+const floorBoss = circle2d(3)
+  .onFace(drilled, 'floor', { u: 0, v: 0, protrude: 0.05, selfAnchor: 'center' })
+  .extrude(1.2)
+  .toShape()
+  .color('#d46452');
+
+const counterboreBase = roundedRect(72, 44, 5, true).extrude(20);
+const counterboreExitFace = counterboreBase.face('bottom');
+const counterbored = counterboreBase.hole('top', {
+  diameter: 6,
+  u: -14,
+  v: 10,
+  upToFace: counterboreExitFace,
+  counterbore: { diameter: 10, depth: 4 },
+}).color('#748498');
+const shoulderPad = rect(4, 3)
+  .onFace(counterbored, 'counterbore-floor', { u: 0, v: 0, protrude: 0.05, selfAnchor: 'center' })
+  .extrude(0.9)
+  .toShape()
+  .color('#f0c36c');
+
+const cutBase = roundedRect(78, 46, 5, true).extrude(22);
+const pocket = roundedRect(20, 12, 2, true)
+  .onFace(cutBase, 'front', { u: 0, v: 4, selfAnchor: 'center' });
+const cut = cutBase.cutout(pocket, { depth: 8 }).color('#64707d');
+const wallTab = rect(5, 4)
+  .onFace(cut, 'wall-right', { u: 0, v: 0, protrude: 0.05, selfAnchor: 'center' })
+  .extrude(1)
+  .toShape()
+  .color('#5ba6d6');
+
+return [
+  { name: 'Shell Inner Wall Pad', shape: union(cup, innerWallPad).translate(-165, 0, 0) },
+  { name: 'Blind Hole Floor Boss', shape: union(drilled, floorBoss).translate(-55, 0, 0) },
+  { name: 'Counterbore Shoulder Pad', shape: union(counterbored, shoulderPad).translate(55, 0, 0) },
+  { name: 'Cut Wall Tab', shape: union(cut, wallTab).translate(165, 0, 0) },
+];

package/examples/api/folded-service-panel-cover.forge.js

@@ -0,0 +1,3 @@
+import { buildFoldedServicePanelCoverScene } from './folded-service-panel-cover.js';
+
+return buildFoldedServicePanelCoverScene();