forgecad 0.1.0

package/examples/ac-unit.forge.js

@@ -0,0 +1,126 @@
+// Home AC Unit — Indoor and Outdoor on opposite sides of a wall
+// Strategy: build each part at origin, then attachTo() its parent.
+
+// === Parameters ===
+const wallW = param("Wall Width", 400, { min: 200, max: 600, unit: "mm" });
+const wallH = param("Wall Height", 300, { min: 200, max: 500, unit: "mm" });
+const wallT = param("Wall Thickness", 20, { min: 10, max: 50, unit: "mm" });
+
+const inW = param("Indoor Width", 200, { min: 100, max: 400, unit: "mm" });
+const inH = param("Indoor Height", 80, { min: 40, max: 150, unit: "mm" });
+const inD = param("Indoor Depth", 25, { min: 15, max: 60, unit: "mm" });
+
+const outW = param("Outdoor Width", 180, { min: 100, max: 400, unit: "mm" });
+const outH = param("Outdoor Height", 150, { min: 80, max: 300, unit: "mm" });
+const outD = param("Outdoor Depth", 50, { min: 30, max: 100, unit: "mm" });
+
+// === Colors ===
+const C_WALL = '#D4C4A8';
+const C_INDOOR = '#FFFFFF';
+const C_ACCENT = '#E8E8E8';
+const C_OUTDOOR = '#F5F5F5';
+const C_GRILL = '#404040';
+const C_PIPE = '#A0A0A0';
+
+// === Wall (centered at origin) ===
+const wall = box(wallW, wallT, wallH, true).color(C_WALL);
+
+// === Indoor Unit ===
+// Sits on the front face of the wall (-Y side), near the ceiling.
+// Build at origin, then attach: indoor's back face → wall's front face, then offset up and out.
+const indoorBody = box(inW, inD, inH, true).color(C_INDOOR)
+  .attachTo(wall, 'top-front', 'top-back', [0, -5, -20]);
+  // back of indoor touches front of wall, shifted 5mm away from wall, 20mm below ceiling
+
+// Vent slats — protrude from the FRONT face of the indoor unit
+const slatCount = 4;
+const slats = [];
+for (let i = 0; i < slatCount; i++) {
+  const slat = box(inW - 30, 8, 3, true).color(C_ACCENT)
+    .attachTo(indoorBody, 'bottom-front', 'bottom-back', [0, -1, 8 + i * 12]);
+    // back of slat on front of indoor, 1mm gap, stacked upward from bottom
+  slats.push(slat);
+}
+
+// Control panel — sticks out from front-right area
+const panel = box(35, 4, 18, true).color('#1A1A1A')
+  .attachTo(indoorBody, 'top-front-right', 'top-back-right', [5, -1, -15]);
+
+// LED
+const led = sphere(2.5).color('#00FF00')
+  .attachTo(panel, 'front', 'center', [5, -2, -5]);
+
+// === Outdoor Unit ===
+// Sits on the back face of the wall (+Y side), near the ground.
+const outdoorBody = box(outW, outD, outH, true).color(C_OUTDOOR)
+  .attachTo(wall, 'bottom-back', 'bottom-front', [0, 10, 30]);
+  // front of outdoor touches back of wall, 10mm standoff, 30mm above ground
+
+// Fan grille — on the back face (+Y) of outdoor unit, centered
+const grilleR = Math.min(outW, outH) * 0.35;
+const fanRim = cylinder(4, grilleR).color(C_GRILL)
+  .pointAlong([0, 1, 0]) // lay along +Y
+  .attachTo(outdoorBody, 'back', 'front', [0, 2, 0]);
+
+const fanCenter = cylinder(2, grilleR * 0.4).color('#505050')
+  .pointAlong([0, 1, 0])
+  .attachTo(outdoorBody, 'back', 'front', [0, 3, 0]);
+
+// Cooling fins — protrude from left and right sides
+const finCount = 8;
+const fins = [];
+const outdoorBB = outdoorBody.boundingBox();
+const finSpacing = (outH - 40) / finCount;
+for (let i = 0; i < finCount; i++) {
+  const zOff = -outH / 2 + 20 + i * finSpacing;
+  // Left fin: right face of fin on left face of outdoor
+  const leftFin = box(5, 12, 3, true).color(C_GRILL)
+    .attachTo(outdoorBody, 'left', 'right', [0, -10, zOff]);
+  // Right fin: left face of fin on right face of outdoor
+  const rightFin = box(5, 12, 3, true).color(C_GRILL)
+    .attachTo(outdoorBody, 'right', 'left', [0, -10, zOff]);
+  fins.push(leftFin, rightFin);
+}
+
+// === Refrigerant Pipes ===
+// Connect from back of indoor unit through wall to front of outdoor unit.
+// Pipe runs along Y axis.
+const indoorBB = indoorBody.boundingBox();
+const pipeStartY = indoorBB.max[1]; // back of indoor (wall side)
+const pipeEndY = outdoorBB.min[1];  // front of outdoor (wall side)
+const pipeLen = pipeEndY - pipeStartY;
+const pipeZ = indoorBB.min[2] + 15; // near bottom of indoor unit
+const pipeX = 40;
+
+// cylinder after pointAlong([0,1,0]) spans Y=0..pipeLen, so translate to pipeStartY
+const liquidPipe = cylinder(pipeLen, 3.5).color(C_PIPE)
+  .pointAlong([0, 1, 0])
+  .translate(pipeX, pipeStartY, pipeZ);
+
+const gasPipe = cylinder(pipeLen, 5).color(C_PIPE)
+  .pointAlong([0, 1, 0])
+  .translate(pipeX + 15, pipeStartY, pipeZ);
+
+// Insulation at outdoor connection
+const insLiquid = cylinder(12, 7).color('#333333')
+  .pointAlong([0, 1, 0])
+  .translate(pipeX, pipeEndY - 12, pipeZ);
+
+const insGas = cylinder(12, 10).color('#333333')
+  .pointAlong([0, 1, 0])
+  .translate(pipeX + 15, pipeEndY - 12, pipeZ);
+
+// === Return ===
+return [
+  { name: "Wall", shape: wall },
+  { name: "Indoor Unit", shape: indoorBody },
+  { name: "Vent Slats", shape: union(...slats) },
+  { name: "Control Panel", shape: panel },
+  { name: "LED", shape: led },
+  { name: "Outdoor Unit", shape: outdoorBody },
+  { name: "Fan Grille", shape: union(fanRim, fanCenter) },
+  { name: "Cooling Fins", shape: union(...fins) },
+  { name: "Liquid Pipe", shape: liquidPipe },
+  { name: "Gas Pipe", shape: gasPipe },
+  { name: "Pipe Insulation", shape: union(insLiquid, insGas) },
+];

package/examples/adjustable-table.forge.js

@@ -0,0 +1,191 @@
+// Adjustable Height Table — manual crank mechanism
+// Shows real construction details: telescoping legs, cross braces,
+// crank shaft, and tabletop.
+//
+// BUILD NOTES (at bottom of file):
+// Materials, dimensions, and assembly instructions for actually building this.
+
+const topW = param("Top Width", 120, { min: 80, max: 200, unit: "cm" });
+const topD = param("Top Depth", 60, { min: 40, max: 100, unit: "cm" });
+const topThick = param("Top Thickness", 3, { min: 2, max: 5, unit: "cm" });
+const minH = param("Min Height", 72, { min: 60, max: 80, unit: "cm" });
+const maxH = param("Max Height", 120, { min: 100, max: 140, unit: "cm" });
+const heightPct = param("Height %", 30, { min: 0, max: 100, unit: "%" });
+const outerLeg = param("Outer Leg", 6, { min: 4, max: 10, unit: "cm" });
+const innerLeg = param("Inner Leg", 4, { min: 3, max: 8, unit: "cm" });
+const legWall = param("Leg Wall", 0.3, { min: 0.2, max: 0.5, unit: "cm" });
+const inset = param("Leg Inset", 5, { min: 2, max: 15, unit: "cm" });
+const braceW = param("Brace Width", 3, { min: 2, max: 5, unit: "cm" });
+const braceH = param("Brace Height", 1.5, { min: 1, max: 3, unit: "cm" });
+const crankR = param("Crank Radius", 8, { min: 5, max: 15, unit: "cm" });
+
+// Current height based on slider
+const currentH = minH + (maxH - minH) * heightPct / 100;
+const legH = currentH - topThick;
+const extensionH = legH - minH + topThick; // how much inner leg extends
+
+// --- Tabletop ---
+const top = box(topW, topD, topThick).translate(0, 0, legH);
+
+// --- Outer legs (fixed, bolted to frame under tabletop) ---
+// These are square tubes — outer shell minus inner hollow
+const outerLegH = minH - topThick; // fixed portion height
+
+const makeOuterLeg = (x, y) => {
+  const outer = box(outerLeg, outerLeg, outerLegH).translate(x, y, legH - outerLegH);
+  const inner = box(outerLeg - legWall * 2, outerLeg - legWall * 2, outerLegH + 1)
+    .translate(x + legWall, y + legWall, legH - outerLegH - 0.5);
+  return outer.subtract(inner);
+};
+
+// --- Inner legs (slide inside outer, extend downward) ---
+const makeInnerLeg = (x, y) => {
+  const legOffset = (outerLeg - innerLeg) / 2;
+  const inner = box(innerLeg, innerLeg, legH)
+    .translate(x + legOffset, y + legOffset, 0);
+  const hollow = box(innerLeg - legWall * 2, innerLeg - legWall * 2, legH + 1)
+    .translate(x + legOffset + legWall, y + legOffset + legWall, -0.5);
+  return inner.subtract(hollow);
+};
+
+// Leg positions
+const legPositions = [
+  [inset, inset],
+  [topW - inset - outerLeg, inset],
+  [inset, topD - inset - outerLeg],
+  [topW - inset - outerLeg, topD - inset - outerLeg],
+];
+
+const outerLegs = union(...legPositions.map(([x, y]) => makeOuterLeg(x, y)));
+const innerLegs = union(...legPositions.map(([x, y]) => makeInnerLeg(x, y)));
+
+// --- Locking pin holes (show where pins go through both tubes) ---
+// Holes at multiple heights for discrete height adjustment
+const pinHoleR = 0.4;
+const pinSpacing = 5; // every 5cm
+const pinHoles = [];
+const numPins = Math.floor((maxH - minH) / pinSpacing);
+
+for (const [lx, ly] of legPositions) {
+  const legCenterX = lx + outerLeg / 2;
+  const legCenterY = ly + outerLeg / 2;
+  for (let i = 0; i <= numPins; i++) {
+    const pz = legH - outerLegH + 5 + i * pinSpacing;
+    if (pz > 0 && pz < legH) {
+      // Through-hole in Y direction
+      pinHoles.push(
+        cylinder(outerLeg + 2, pinHoleR)
+          .rotate(90, 0, 0)
+          .translate(legCenterX, ly - 1, pz)
+      );
+    }
+  }
+}
+
+// --- Cross braces (connect legs for rigidity) ---
+// Front brace
+const frontBraceLen = topW - 2 * inset - 2 * outerLeg;
+const frontBrace = box(frontBraceLen, braceW, braceH)
+  .translate(inset + outerLeg, inset + outerLeg / 2 - braceW / 2, legH - outerLegH + 10);
+
+// Back brace
+const backBrace = box(frontBraceLen, braceW, braceH)
+  .translate(inset + outerLeg, topD - inset - outerLeg / 2 - braceW / 2, legH - outerLegH + 10);
+
+// Side braces
+const sideBraceLen = topD - 2 * inset - 2 * outerLeg;
+const leftBrace = box(braceW, sideBraceLen, braceH)
+  .translate(inset + outerLeg / 2 - braceW / 2, inset + outerLeg, legH - outerLegH + 10);
+const rightBrace = box(braceW, sideBraceLen, braceH)
+  .translate(topW - inset - outerLeg / 2 - braceW / 2, inset + outerLeg, legH - outerLegH + 10);
+
+// --- Crank mechanism (side-mounted, visual representation) ---
+// Crank shaft runs between front legs
+const shaftY = inset + outerLeg / 2;
+const shaftZ = legH - outerLegH + 25;
+const shaftLen = topW - 2 * inset;
+const shaft = cylinder(shaftLen, 0.8)
+  .rotate(0, 90, 0)
+  .translate(inset, shaftY, shaftZ);
+
+// Crank handle (on the right side)
+const handleX = topW - inset + 2;
+const crankArm = cylinder(crankR, 0.5)
+  .translate(handleX, shaftY, shaftZ);
+const crankKnob = sphere(1.2)
+  .translate(handleX, shaftY, shaftZ + crankR);
+
+// --- Foot pads (rubber feet at bottom of inner legs) ---
+const footPads = union(
+  ...legPositions.map(([lx, ly]) => {
+    const cx = lx + outerLeg / 2;
+    const cy = ly + outerLeg / 2;
+    return cylinder(0.5, innerLeg / 2 + 0.5)
+      .translate(cx, cy, 0);
+  })
+);
+
+// --- Assembly ---
+let structure = union(outerLegs, innerLegs, frontBrace, backBrace, leftBrace, rightBrace);
+if (pinHoles.length > 0) {
+  structure = structure.subtract(union(...pinHoles));
+}
+
+return [
+  { name: "Tabletop", shape: top, color: "#8B7355" },
+  { name: "Leg Structure", shape: structure, color: "#888888" },
+  { name: "Crank Shaft", shape: shaft, color: "#666666" },
+  { name: "Crank Arm", shape: crankArm, color: "#555555" },
+  { name: "Crank Knob", shape: crankKnob, color: "#444444" },
+  { name: "Foot Pads", shape: footPads, color: "#333333" },
+];
+
+// ============================================================
+// BUILD NOTES — How to actually build this table
+// ============================================================
+//
+// MATERIALS:
+// - Tabletop: 18mm plywood or solid wood panel (120×60cm)
+// - Outer legs: 60×60mm square steel tube, 2mm wall (×4, cut to ~69cm)
+// - Inner legs: 40×40mm square steel tube, 2mm wall (×4, cut to ~120cm)
+// - Cross braces: 30×15mm steel flat bar (×4)
+// - Crank shaft: 16mm steel rod, threaded ends
+// - Locking pins: 8mm spring pins or clevis pins
+// - Foot pads: rubber furniture feet (40mm)
+// - Hardware: M8 bolts for frame, M6 for braces
+//
+// ASSEMBLY:
+// 1. Cut all steel tubes to length. Deburr edges.
+// 2. Weld or bolt cross braces to outer leg tubes at 10cm from top.
+// 3. Slide inner legs into outer legs from below.
+// 4. Drill pin holes through both tubes at 5cm intervals.
+//    Use a drill press for alignment. Start from bottom.
+// 5. Mount outer leg assembly to underside of tabletop with
+//    L-brackets and M8 bolts (4 per leg).
+// 6. Thread crank shaft through front legs. Add bearing blocks
+//    or bushings at each leg pass-through.
+// 7. Attach crank handle to shaft end.
+// 8. For the crank-to-leg connection: weld a small gear or
+//    threaded collar to the shaft at each inner leg position.
+//    The inner leg needs a matching rack or threaded insert.
+//    SIMPLER ALTERNATIVE: Skip the crank, use spring pins only
+//    for discrete height positions (every 5cm).
+// 9. Press-fit rubber feet onto inner leg bottoms.
+// 10. Sand and paint/powder-coat all steel parts.
+//
+// TOOLS NEEDED:
+// - Angle grinder or chop saw (cutting tubes)
+// - Drill press (pin holes — alignment critical)
+// - Welder (MIG preferred) OR bolt-together with brackets
+// - Socket set, Allen keys
+// - Level, tape measure, square
+//
+// COST ESTIMATE (EU prices, 2026):
+// - Steel tubes: ~€40-60
+// - Plywood top: ~€25-40
+// - Hardware + feet: ~€15-20
+// - Paint/finish: ~€10-15
+// - Total: ~€90-135
+//
+// WEIGHT CAPACITY: ~80kg evenly distributed (depends on pin strength)
+// Upgrade: use 2 pins per leg for more stability.

package/examples/api/assembly-gear-coupling.forge.js

@@ -0,0 +1,32 @@
+// Assembly + gear coupling demo
+// Uses addGearCoupling(...) so the driven joint follows pinion motion automatically.
+
+const pinionDeg = param("Pinion Angle", 20, { min: -180, max: 180, step: 1, unit: "°" });
+
+const pair = lib.gearPair({
+  pinion: { module: 1.25, teeth: 14, faceWidth: 8, boreDiameter: 5 },
+  gear: { module: 1.25, teeth: 42, faceWidth: 8, boreDiameter: 8 },
+  backlash: 0.05,
+  place: false,
+});
+
+const mech = assembly("Gear Coupling Demo")
+  .addFrame("Base")
+  .addPart("Pinion", pair.pinion.color("#d5a15f"))
+  .addPart("Driven", pair.gear.color("#9ab3ca"), {
+    transform: Transform.identity().translate(pair.centerDistance, 0, 0),
+  })
+  .addRevolute("Pinion", "Base", "Pinion", {
+    axis: [0, 0, 1],
+    min: -720,
+    max: 720,
+  })
+  .addRevolute("Driven", "Base", "Driven", {
+    axis: [0, 0, 1],
+    min: -720,
+    max: 720,
+  })
+  .addGearCoupling("Driven", "Pinion", { pair });
+
+const solved = mech.solve({ Pinion: pinionDeg });
+return solved.toScene();

package/examples/api/assembly-mechanism.forge.js

@@ -0,0 +1,111 @@
+// Assembly + mechanism demo
+// Shows Transform composition, assembly joints, BOM metadata, and collision checks.
+
+const baseYaw = param("Base Yaw", 20, { min: -170, max: 170, unit: "°" });
+const shoulder = param("Shoulder", 30, { min: -30, max: 110, unit: "°" });
+const elbow = param("Elbow", 45, { min: -20, max: 135, unit: "°" });
+const open = param("Gripper Open", 28, { min: 0, max: 55, unit: "mm" });
+
+const upperLen = 180;
+const foreLen = 160;
+
+const basePlate = box(180, 140, 10, true).translate(0, 0, 5);
+const tower = cylinder(20, 36).translate(0, 0, 10);
+
+const m4 = lib.fastenerHole({ size: "M4", fit: "normal", depth: 14, counterbore: { depth: 4 } });
+const mountHoles = [
+  m4.translate(55, 40, 7),
+  m4.translate(-55, 40, 7),
+  m4.translate(55, -40, 7),
+  m4.translate(-55, -40, 7),
+];
+
+const base = difference(union(basePlate, tower), ...mountHoles).color("#6e7b88");
+
+const upperArm = box(upperLen, 28, 28)
+  .translate(0, -14, -14)
+  .subtract(cylinder(32, 8).pointAlong([0, 1, 0]).translate(0, 0, 0))
+  .color("#5f87c6");
+
+const forearm = box(foreLen, 24, 24)
+  .translate(0, -12, -12)
+  .subtract(cylinder(28, 7).pointAlong([0, 1, 0]).translate(0, 0, 0))
+  .color("#6fa2d6");
+
+const wristHub = cylinder(26, 10).pointAlong([1, 0, 0]).translate(0, 0, 0);
+const palm = box(34, 44, 16, true).translate(16, 0, 0);
+const toolBody = union(wristHub, palm).color("#b8c5d3");
+
+const fingerLen = 50;
+const finger = box(fingerLen, 8, 10).translate(8, -4, -5).color("#414952");
+const fingerLeft = finger.translate(18, 8 + open * 0.5, 0);
+const fingerRight = finger.translate(18, -8 - open * 0.5, 0);
+const gripper = group(
+  { name: "Tool Body", shape: toolBody },
+  { name: "Left Finger", shape: fingerLeft },
+  { name: "Right Finger", shape: fingerRight },
+);
+
+const mech = assembly("Robot Arm Demo")
+  .addPart("Base", base, {
+    metadata: { material: "PETG", process: "FDM", tolerance: "+/-0.2mm", qty: 1 },
+  })
+  .addPart("Upper Arm", upperArm, {
+    metadata: { material: "PETG-CF", process: "FDM", qty: 1 },
+  })
+  .addPart("Forearm", forearm, {
+    metadata: { material: "PETG-CF", process: "FDM", qty: 1 },
+  })
+  .addPart("Gripper", gripper, {
+    metadata: { material: "PETG", process: "FDM", notes: "Print fingers in TPU for compliance", qty: 1 },
+  })
+  .addJoint("baseYaw", "revolute", "Base", "Upper Arm", {
+    axis: [0, 0, 1],
+    min: -170,
+    max: 170,
+    frame: Transform.identity().translate(0, 0, 46),
+  })
+  .addJoint("shoulder", "revolute", "Upper Arm", "Forearm", {
+    axis: [0, -1, 0],
+    min: -30,
+    max: 110,
+    frame: Transform.identity().translate(upperLen + 8, 0, 0),
+  })
+  .addJoint("elbow", "revolute", "Forearm", "Gripper", {
+    axis: [0, -1, 0],
+    min: -20,
+    max: 135,
+    frame: Transform.identity().translate(foreLen + 12, 0, 0),
+  });
+
+const solved = mech.solve({
+  baseYaw,
+  shoulder,
+  elbow,
+});
+
+const collisions = solved.collisionReport({
+  minOverlapVolume: 0.5,
+  ignorePairs: [
+    ["Upper Arm", "Forearm"],
+    ["Forearm", "Gripper"],
+  ],
+});
+
+if (collisions.length > 0) {
+  console.warn("Assembly collisions:", collisions);
+}
+
+const elbowSweep = mech.sweepJoint("elbow", -20, 135, 16, {
+  baseYaw,
+  shoulder,
+});
+const sweptCollisions = elbowSweep.filter(step => step.collisions.length > 0).length;
+if (sweptCollisions > 0) {
+  console.info(`Elbow sweep has collisions in ${sweptCollisions}/${elbowSweep.length} steps`);
+}
+
+console.log("BOM", solved.bom());
+console.log("BOM CSV\n" + solved.bomCsv());
+
+return solved.toScene();

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

@@ -0,0 +1,45 @@
+// attachTo() — the primary way to position parts relative to each other.
+//
+// Mental model: child.attachTo(parent, parentAnchor, selfAnchor, offset)
+//   "Put my [selfAnchor] at the parent's [parentAnchor], then shift by [offset]"
+//
+// Anchor names:
+//   1 word  = face center:  'top', 'bottom', 'front', 'back', 'left', 'right'
+//   2 words = edge midpoint: 'top-front', 'back-left', etc.
+//   3 words = corner:        'top-front-left', 'bottom-back-right', etc.
+
+const baseW = param("Base Width", 100, { min: 50, max: 200, unit: "mm" });
+const baseD = param("Base Depth", 80, { min: 40, max: 150, unit: "mm" });
+const baseH = param("Base Height", 10, { min: 5, max: 30, unit: "mm" });
+
+const base = box(baseW, baseD, baseH, true).color('#888888');
+
+// Stack on top: column's bottom face meets base's top face
+const column = cylinder(40, 8).color('#4488cc')
+  .attachTo(base, 'top', 'bottom');
+
+// Protrude from front: button's back face meets base's front face
+const button = box(20, 6, 10, true).color('#cc4444')
+  .attachTo(base, 'front', 'back');
+
+// Hang below: bracket's top face meets base's bottom face
+const bracket = box(30, 30, 5, true).color('#44cc44')
+  .attachTo(base, 'bottom', 'top');
+
+// Attach to side with offset: panel's left face meets base's right face,
+// then shift 0mm on X, 0mm on Y, 10mm up on Z
+const sidePanel = box(4, 40, 25, true).color('#cc8844')
+  .attachTo(base, 'right', 'left', [0, 0, 10]);
+
+// Corner alignment: small cube at top-front-right corner of base
+const corner = box(8, 8, 8, true).color('#8844cc')
+  .attachTo(base, 'top-front-right', 'bottom-back-left');
+
+return [
+  { name: "Base", shape: base },
+  { name: "Column (top→bottom)", shape: column },
+  { name: "Button (front→back)", shape: button },
+  { name: "Bracket (bottom→top)", shape: bracket },
+  { name: "Side Panel (right→left, +10Z)", shape: sidePanel },
+  { name: "Corner Cube", shape: corner },
+];

package/examples/api/benchy-style-hull.forge.js

@@ -0,0 +1,89 @@
+// Benchy-style hull concept using reusable curve/surface APIs.
+// Not an exact #3DBenchy clone; this shows the modeling workflow:
+// sections -> loft hull, sweep rails/chimney, simple superstructure.
+
+const length = param("Length", 92, { min: 60, max: 150, unit: "mm" });
+const beam = param("Beam", 42, { min: 24, max: 70, unit: "mm" });
+const hullH = param("Hull Height", 34, { min: 18, max: 60, unit: "mm" });
+const deckDrop = param("Deck Drop", 6, { min: 2, max: 12, unit: "mm" });
+
+const mkSection = (w, h, keel = 0, chine = 0) => spline2d([
+  [w * 0.5, 0],
+  [w * 0.45, h * 0.28 + chine],
+  [w * 0.25, h * 0.5 + chine],
+  [0, h * 0.58 + keel],
+  [-w * 0.25, h * 0.5 + chine],
+  [-w * 0.45, h * 0.28 + chine],
+  [-w * 0.5, 0],
+  [-w * 0.45, -h * 0.18],
+  [-w * 0.23, -h * 0.32],
+  [0, -h * 0.36 - deckDrop],
+  [w * 0.23, -h * 0.32],
+  [w * 0.45, -h * 0.18],
+], {
+  closed: true,
+  samplesPerSegment: 10,
+  tension: 0.45,
+});
+
+const z0 = 0;
+const z1 = length * 0.22;
+const z2 = length * 0.56;
+const z3 = length * 0.88;
+const z4 = length;
+
+let hull = loft(
+  [
+    mkSection(beam * 0.52, hullH * 0.72, 2, 1), // stern
+    mkSection(beam * 0.94, hullH * 0.95, 3, 1.5),
+    mkSection(beam, hullH, 3.5, 1.2),           // max beam
+    mkSection(beam * 0.58, hullH * 0.82, 1.5, 0.5),
+    mkSection(beam * 0.18, hullH * 0.35, 0, 0), // bow tip
+  ],
+  [z0, z1, z2, z3, z4],
+  { edgeLength: 0.95 },
+);
+hull = hull.smoothOut(72, 0.28).refine(2);
+
+// Orient hull so length goes along X, beam along Y, height along Z.
+hull = hull
+  .rotate(0, 90, 0) // Z (loft stations) -> X
+  .rotate(90, 0, 0) // Y (section height) -> Z
+  .translate(-length * 0.5, 0, hullH * 0.58);
+
+// Deckhouse and cabin
+const houseW = beam * 0.48;
+const houseD = length * 0.26;
+const houseH = hullH * 0.62;
+const house = roundedRect(houseW, houseD, 4, true).extrude(houseH)
+  .translate(length * 0.04, 0, hullH * 0.82);
+
+const cabinCut = roundedRect(houseW * 0.68, houseD * 0.56, 2.2, true).extrude(houseH * 0.7)
+  .translate(length * 0.04, 0, hullH * 1.08);
+
+// Chimney via sweep
+const stackPath = spline3d(
+  [
+    [length * 0.02, 0, hullH * 1.45],
+    [length * 0.02, 0, hullH * 1.72],
+    [length * 0.08, 0, hullH * 1.84],
+  ],
+  { tension: 0.5 },
+);
+const stack = sweep(circle2d(3.8), stackPath, {
+  samples: 28,
+  edgeLength: 0.55,
+});
+const stackInner = sweep(circle2d(2.2), stackPath, {
+  samples: 28,
+  edgeLength: 0.55,
+});
+
+const cabin = house.subtract(cabinCut);
+const chimney = stack.subtract(stackInner);
+
+return [
+  { name: "Hull", shape: hull.color('#ce6f4e') },
+  { name: "Cabin", shape: cabin.color('#f0eee9') },
+  { name: "Chimney", shape: chimney.color('#3d4854') },
+];

package/examples/api/bill-of-materials.forge.js

@@ -0,0 +1,46 @@
+// API demo: script-declared bill of materials that gets auto-summed in report export
+
+const frameWidth = param('Frame Width', 900, { min: 300, max: 1800, unit: 'mm' });
+const frameDepth = param('Frame Depth', 500, { min: 200, max: 1200, unit: 'mm' });
+const legHeight = param('Leg Height', 720, { min: 300, max: 1200, unit: 'mm' });
+const tubeW = param('Tube Width', 30, { min: 15, max: 80, unit: 'mm' });
+const tubeH = param('Tube Height', 20, { min: 10, max: 80, unit: 'mm' });
+
+const frontBolts = param('Front Bolts', 8, { min: 0, max: 64, integer: true });
+const rearBolts = param('Rear Bolts', 8, { min: 0, max: 64, integer: true });
+const boltLength = param('Bolt Length', 16, { min: 6, max: 60, unit: 'mm' });
+
+const wall = 2;
+const longTubeMm = frameWidth * 2;
+const shortTubeMm = frameDepth * 2;
+const legTubeMm = legHeight * 4;
+const totalTubeMm = longTubeMm + shortTubeMm + legTubeMm;
+
+// Physical materials are authored by code, not inferred from mesh primitives.
+bom(totalTubeMm, `iron tube with dimensions ${tubeW} x ${tubeH}`, { unit: 'mm' });
+
+// These two lines intentionally share the same descriptor so report export sums them.
+bom(frontBolts, `M4 bolt of ${boltLength} mm length`, { unit: 'pieces' });
+bom(rearBolts, `M4 bolt of ${boltLength} mm length`, { unit: 'pieces' });
+
+const railFront = box(frameWidth, tubeW, tubeH).color('#778da9');
+const railBack = box(frameWidth, tubeW, tubeH).translate(0, frameDepth - tubeW, 0).color('#778da9');
+const railLeft = box(tubeW, frameDepth, tubeH).color('#778da9');
+const railRight = box(tubeW, frameDepth, tubeH).translate(frameWidth - tubeW, 0, 0).color('#778da9');
+
+const legSize = Math.min(tubeW, tubeH);
+const legA = box(legSize, legSize, legHeight).translate(0, 0, tubeH).color('#415a77');
+const legB = box(legSize, legSize, legHeight).translate(frameWidth - legSize, 0, tubeH).color('#415a77');
+const legC = box(legSize, legSize, legHeight).translate(0, frameDepth - legSize, tubeH).color('#415a77');
+const legD = box(legSize, legSize, legHeight).translate(frameWidth - legSize, frameDepth - legSize, tubeH).color('#415a77');
+
+return [
+  { name: 'Front Rail', shape: railFront },
+  { name: 'Back Rail', shape: railBack },
+  { name: 'Left Rail', shape: railLeft },
+  { name: 'Right Rail', shape: railRight },
+  { name: 'Leg A', shape: legA },
+  { name: 'Leg B', shape: legB },
+  { name: 'Leg C', shape: legC },
+  { name: 'Leg D', shape: legD },
+];