forgecad 0.9.2 → 0.9.3

package/dist-cli/forgecad.js

@@ -4172,11 +4172,11 @@ function extractEdgeSegments(mesh) {
       const revKey = useNumeric ? vb * MAX_NUMERIC + va : `${vb},${va}`;
       const adjTri = halfEdges.get(revKey);
       if (adjTri !== void 0) {
-        const dot8 = faceNx[t] * faceNx[adjTri] + faceNy[t] * faceNy[adjTri] + faceNz[t] * faceNz[adjTri];
-        if (dot8 <= EDGE_THRESHOLD_DOT) {
+        const dot9 = faceNx[t] * faceNx[adjTri] + faceNy[t] * faceNy[adjTri] + faceNz[t] * faceNz[adjTri];
+        if (dot9 <= EDGE_THRESHOLD_DOT) {
           const origVa = triVerts[t * 3 + e];
           const origVb = triVerts[t * 3 + (e + 1) % 3];
-          const seg = buildEdgeSegment(edgeIndex++, origVa, origVb, vertProperties, numProp, t, adjTri, faceNx, faceNy, faceNz, dot8, false);
+          const seg = buildEdgeSegment(edgeIndex++, origVa, origVb, vertProperties, numProp, t, adjTri, faceNx, faceNy, faceNz, dot9, false);
           edges.push(seg);
         }
         halfEdges.delete(revKey);
@@ -4206,7 +4206,7 @@ function extractEdgeSegments(mesh) {
   }
   return edges;
 }
-function buildEdgeSegment(index, origVa, origVb, vertProperties, numProp, triA, triB, faceNx, faceNy, faceNz, dot8, boundary) {
+function buildEdgeSegment(index, origVa, origVb, vertProperties, numProp, triA, triB, faceNx, faceNy, faceNz, dot9, boundary) {
   const sx = vertProperties[origVa * numProp];
   const sy = vertProperties[origVa * numProp + 1];
   const sz = vertProperties[origVa * numProp + 2];
@@ -4218,7 +4218,7 @@ function buildEdgeSegment(index, origVa, origVb, vertProperties, numProp, triA,
   const invLen = length5 > 1e-12 ? 1 / length5 : 0;
   const nA = [faceNx[triA], faceNy[triA], faceNz[triA]];
   const nB = [faceNx[triB], faceNy[triB], faceNz[triB]];
-  const clampedDot = Math.max(-1, Math.min(1, dot8));
+  const clampedDot = Math.max(-1, Math.min(1, dot9));
   const dihedralAngle = boundary ? 0 : 180 - Math.acos(clampedDot) * (180 / Math.PI);
   const crossX = nA[1] * nB[2] - nA[2] * nB[1];
   const crossY = nA[2] * nB[0] - nA[0] * nB[2];
@@ -5467,20 +5467,20 @@ function resolvePlaneOriginNormal(plane) {
 }
 function rotationToPlaneSpace(normal) {
   const n = normalize2(normal);
-  const dot8 = n[2];
-  if (dot8 > 1 - EPS4) {
+  const dot9 = n[2];
+  if (dot9 > 1 - EPS4) {
     return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
   }
   let axis;
   let angle;
-  if (dot8 < -1 + EPS4) {
+  if (dot9 < -1 + EPS4) {
     axis = [1, 0, 0];
     angle = Math.PI;
   } else {
     axis = [n[1], -n[0], 0];
     const axisLen = length(axis);
     axis = [axis[0] / axisLen, axis[1] / axisLen, axis[2] / axisLen];
-    angle = Math.acos(dot8);
+    angle = Math.acos(dot9);
   }
   const [x, y, z] = axis;
   const c = Math.cos(angle);
@@ -10560,8 +10560,8 @@ function isFlat(p0, pMid, p1, cosThreshold) {
   const len1sq = d1x * d1x + d1y * d1y + d1z * d1z;
   const len2sq = d2x * d2x + d2y * d2y + d2z * d2z;
   if (len1sq < 1e-20 || len2sq < 1e-20) return true;
-  const dot8 = d1x * d2x + d1y * d2y + d1z * d2z;
-  const cosAngle = dot8 / Math.sqrt(len1sq * len2sq);
+  const dot9 = d1x * d2x + d1y * d2y + d1z * d2z;
+  const cosAngle = dot9 / Math.sqrt(len1sq * len2sq);
   return cosAngle >= cosThreshold;
 }
 function extractBoundingBox(oc, shape) {
@@ -12535,8 +12535,8 @@ Faces on this shape (${allFaces.length}):`);
       lines.push(`  ... and ${allFaces.length - 10} more`);
     }
     if (query.normal) {
-      const dot8 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-      const sorted = [...allFaces].map((f3) => ({ face: f3, sim: dot8(f3.normal, query.normal) })).sort((a, b) => b.sim - a.sim).slice(0, 3);
+      const dot9 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+      const sorted = [...allFaces].map((f3) => ({ face: f3, sim: dot9(f3.normal, query.normal) })).sort((a, b) => b.sim - a.sim).slice(0, 3);
       if (sorted.length > 0 && sorted[0].sim < 0.9998) {
         lines.push(`
 Nearest normals to query:`);
@@ -18313,7 +18313,7 @@ function extractEdgesWithFaces(mesh, triCluster) {
   }
   return edges;
 }
-function buildEdgeWithFaces(index, origVa, origVb, vertProperties, numProp, triA, triB, faceNx, faceNy, faceNz, dot8, boundary, clusterA, clusterB) {
+function buildEdgeWithFaces(index, origVa, origVb, vertProperties, numProp, triA, triB, faceNx, faceNy, faceNz, dot9, boundary, clusterA, clusterB) {
   const sx = vertProperties[origVa * numProp];
   const sy = vertProperties[origVa * numProp + 1];
   const sz = vertProperties[origVa * numProp + 2];
@@ -18325,7 +18325,7 @@ function buildEdgeWithFaces(index, origVa, origVb, vertProperties, numProp, triA
   const invLen = length5 > 1e-12 ? 1 / length5 : 0;
   const nA = [faceNx[triA], faceNy[triA], faceNz[triA]];
   const nB = [faceNx[triB], faceNy[triB], faceNz[triB]];
-  const clampedDot = Math.max(-1, Math.min(1, dot8));
+  const clampedDot = Math.max(-1, Math.min(1, dot9));
   const dihedralAngle = boundary ? 0 : 180 - Math.acos(clampedDot) * (180 / Math.PI);
   const crossX = nA[1] * nB[2] - nA[2] * nB[1];
   const crossY = nA[2] * nB[0] - nA[0] * nB[2];
@@ -20162,6 +20162,7 @@ Fix: pass a path like [[0,0,0], [20,0,8,4], [40,0,0,2]].`
   const curveMode = shouldSmoothCurve(options, defaultCurve) && sourcePoints.length >= 3;
   const normalized = compactPathPoints(resampleCurve(sourcePoints, options, defaultCurve));
   const minRadius = Math.min(...normalized.map((point2) => point2.radius));
+  const hasExplicitBlend = options.blend !== void 0;
   const blendRadius = positiveFinite(options.blend, "Sculpt.tube() blend", Math.max(0.5, minRadius));
   let segmentCount = 0;
   for (let i = 0; i < normalized.length - 1; i += 1) {
@@ -20170,8 +20171,8 @@ Fix: pass a path like [[0,0,0], [20,0,8,4], [40,0,0,2]].`
   if (segmentCount === 0) {
     throw new Error("Sculpt.tube() points must include at least one non-zero-length segment.");
   }
-  const curveBlendRadius = curveMode ? Math.max(blendRadius, minRadius * 1.5) : Math.min(blendRadius, Math.max(0.1, minRadius * 0.8));
-  let out = polylineSweep(normalized, curveMode ? curveBlendRadius : blendRadius);
+  const effectiveBlendRadius = curveMode && !hasExplicitBlend ? Math.max(blendRadius, minRadius * 1.5) : blendRadius;
+  let out = polylineSweep(normalized, effectiveBlendRadius);
   if (options.polish !== void 0) out = out.polish(options.polish);
   return out;
 }
@@ -24422,6 +24423,11 @@ function jointsView(options = {}) {
 }
 
 // src/forge/assembly/assembly.ts
+var SWEEP_JOINT_DEFAULT_STEP_LIMIT = {
+  live: 1,
+  default: 4,
+  high: Number.POSITIVE_INFINITY
+};
 var collectedAssemblies = [];
 function resetCollectedAssemblies() {
   collectedAssemblies = [];
@@ -24465,6 +24471,33 @@ function collisionShape(part) {
   if (shapes.length === 1) return shapes[0];
   return union(...shapes);
 }
+function boundsOverlap(a, b) {
+  for (let axis = 0; axis < 3; axis++) {
+    if (a.max[axis] <= b.min[axis] || b.max[axis] <= a.min[axis]) return false;
+  }
+  return true;
+}
+function readAssemblyPerfEnv(name) {
+  return typeof process !== "undefined" ? process.env?.[name] : void 0;
+}
+function resolveSweepJointStepLimit() {
+  if (readAssemblyPerfEnv("FORGECAD_ALLOW_FULL_SWEEP_JOINT") === "1") return Number.POSITIVE_INFINITY;
+  const override = readAssemblyPerfEnv("FORGECAD_SWEEP_JOINT_STEP_LIMIT");
+  if (override != null && override.trim() !== "") {
+    const parsed = Number(override);
+    if (Number.isFinite(parsed) && parsed >= 1) return Math.floor(parsed);
+  }
+  return SWEEP_JOINT_DEFAULT_STEP_LIMIT[getForgeQualityPreset()];
+}
+function boundSweepJointSteps(jointName, requestedSteps) {
+  const limit = resolveSweepJointStepLimit();
+  if (!Number.isFinite(limit) || requestedSteps <= limit) return requestedSteps;
+  const bounded = Math.max(1, Math.floor(limit));
+  emitRuntimeWarning(
+    `sweepJoint("${jointName}") requested ${requestedSteps} step(s), exceeding the ${getForgeQualityPreset()} quality sweep limit (${bounded}). Using ${bounded} step(s) for responsiveness. Use high quality/export, set FORGECAD_SWEEP_JOINT_STEP_LIMIT, or set FORGECAD_ALLOW_FULL_SWEEP_JOINT=1 for the full sweep.`
+  );
+  return bounded;
+}
 var FASTENER_PATTERN = /\b(bolt|screw|nut|washer|pin|rivet|fastener|standoff|insert)\b/i;
 function isFastenerName(name) {
   return FASTENER_PATTERN.test(name);
@@ -24793,16 +24826,23 @@ var SolvedAssembly = class {
     const minOverlap = options.minOverlapVolume ?? 0.1;
     const ignore = new Set((options.ignorePairs ?? []).map(([a, b]) => [a, b].sort().join("|")));
     const findings = [];
-    for (let i = 0; i < names.length; i++) {
-      for (let j = i + 1; j < names.length; j++) {
-        const aName = names[i];
-        const bName = names[j];
+    const entries = [];
+    for (const name of names) {
+      const shape = collisionShape(this.getPart(name));
+      if (!shape) continue;
+      try {
+        entries.push({ name, shape, bounds: shape.boundingBox() });
+      } catch {
+      }
+    }
+    for (let i = 0; i < entries.length; i++) {
+      for (let j = i + 1; j < entries.length; j++) {
+        const aName = entries[i].name;
+        const bName = entries[j].name;
         if (ignore.has([aName, bName].sort().join("|"))) continue;
-        const a = collisionShape(this.getPart(aName));
-        const b = collisionShape(this.getPart(bName));
-        if (!a || !b) continue;
+        if (!boundsOverlap(entries[i].bounds, entries[j].bounds)) continue;
         try {
-          const hit = a.intersect(b);
+          const hit = entries[i].shape.intersect(entries[j].shape);
           if (hit.isEmpty()) continue;
           const vol = hit.volume();
           if (vol > minOverlap) {
@@ -25779,7 +25819,7 @@ var Assembly = class _Assembly {
     if (this.jointCouplings.has(jointName)) {
       throw new Error(`Cannot sweep coupled joint "${jointName}". Sweep one of its source joints instead.`);
     }
-    const n = Math.max(1, Math.floor(steps));
+    const n = boundSweepJointSteps(jointName, Math.max(1, Math.floor(steps)));
     const frames = [];
     for (let i = 0; i <= n; i++) {
       const t = n === 0 ? 0 : i / n;
@@ -29280,9 +29320,9 @@ var PathBuilder = class {
     const [d1x, d1y] = this.getSegDirAt(prev, "end");
     const [d2x, d2y] = this.getSegDirAt(curr, "start");
     const cross7 = d1x * d2y - d1y * d2x;
-    const dot8 = d1x * d2x + d1y * d2y;
+    const dot9 = d1x * d2x + d1y * d2y;
     if (Math.abs(cross7) < 1e-9) return { trimA: [cx, cy], trimB: [cx, cy], arcSeg: null };
-    const halfAngle = Math.atan2(Math.abs(cross7), dot8) / 2;
+    const halfAngle = Math.atan2(Math.abs(cross7), dot9) / 2;
     const trimDist = radius / Math.tan(halfAngle);
     const trimA = [cx - d1x * trimDist, cy - d1y * trimDist];
     const trimB = [cx + d2x * trimDist, cy + d2y * trimDist];
@@ -29419,8 +29459,8 @@ var PathBuilder = class {
     const reflect = (px, py) => {
       const dx = px - pivotX;
       const dy = py - pivotY;
-      const dot8 = dx * nx + dy * ny;
-      return [px - 2 * dot8 * nx, py - 2 * dot8 * ny];
+      const dot9 = dx * nx + dy * ny;
+      return [px - 2 * dot9 * nx, py - 2 * dot9 * ny];
     };
     const toMirror = this.segs.slice(1).reverse();
     for (const seg of toMirror) {
@@ -30533,8 +30573,8 @@ function resolveExplodeDirection(mode, center, originCenter, seed) {
   return [0, 0, 1];
 }
 function explodeProjectPerpendicular(vec, axis) {
-  const dot8 = explodeDot(vec, axis);
-  return [vec[0] - axis[0] * dot8, vec[1] - axis[1] * dot8, vec[2] - axis[2] * dot8];
+  const dot9 = explodeDot(vec, axis);
+  return [vec[0] - axis[0] * dot9, vec[1] - axis[1] * dot9, vec[2] - axis[2] * dot9];
 }
 function applyExplodeTreeBias(direction2, mode, inheritedDirection, seed) {
   if (!inheritedDirection || mode !== "radial") return direction2;
@@ -44520,6 +44560,132 @@ function shapeToGeometryFallback(shape) {
   return { solid, edges, hasSmoothNormals: false };
 }
 
+// src/forge/renderLabel.ts
+var _collected5 = [];
+var _nextId = 1;
+function resetRenderLabels() {
+  _collected5 = [];
+  _nextId = 1;
+}
+function getCollectedRenderLabels() {
+  return _collected5.map((label) => ({ ...label, at: [...label.at], offset: [...label.offset] }));
+}
+function requireFinite2(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`);
+  }
+  return value;
+}
+function requireVec3(value, label) {
+  if (!Array.isArray(value) || value.length !== 3) {
+    throw new Error(`${label} must be [x, y, z]`);
+  }
+  return [requireFinite2(value[0], `${label}[0]`), requireFinite2(value[1], `${label}[1]`), requireFinite2(value[2], `${label}[2]`)];
+}
+function optionalColor(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty CSS color string`);
+  }
+  return value.trim();
+}
+var VALID_ANCHORS = /* @__PURE__ */ new Set([
+  "center",
+  "top",
+  "bottom",
+  "left",
+  "right",
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right"
+]);
+function normalizeOptions(options) {
+  if (options === void 0) {
+    return { offset: [0, 0, 0], anchor: "center", alwaysOnTop: true };
+  }
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new Error("Viewport.label options must be an object");
+  }
+  const out = {
+    offset: [0, 0, 0],
+    anchor: "center",
+    alwaysOnTop: true
+  };
+  const color = optionalColor(options.color, "Viewport.label options.color");
+  if (color !== void 0) out.color = color;
+  const background = optionalColor(options.background, "Viewport.label options.background");
+  if (background !== void 0) out.background = background;
+  if (options.size !== void 0) {
+    out.size = requireFinite2(options.size, "Viewport.label options.size");
+    if (out.size <= 0) throw new Error("Viewport.label options.size must be positive");
+  }
+  if (options.offset !== void 0) out.offset = requireVec3(options.offset, "Viewport.label options.offset");
+  if (options.anchor !== void 0) {
+    if (!VALID_ANCHORS.has(options.anchor)) {
+      throw new Error(`Viewport.label options.anchor must be one of: ${Array.from(VALID_ANCHORS).join(", ")}`);
+    }
+    out.anchor = options.anchor;
+  }
+  if (options.alwaysOnTop !== void 0) {
+    if (typeof options.alwaysOnTop !== "boolean") throw new Error("Viewport.label options.alwaysOnTop must be a boolean");
+    out.alwaysOnTop = options.alwaysOnTop;
+  }
+  return out;
+}
+function collectRenderLabel(text, at, options) {
+  if (typeof text !== "string" || text.trim().length === 0) {
+    throw new Error("Viewport.label text must be a non-empty string");
+  }
+  const normalizedAt = requireVec3(at, "Viewport.label at");
+  const normalizedOptions = normalizeOptions(options);
+  _collected5.push({
+    id: `render-label-${_nextId++}`,
+    text: text.trim(),
+    at: normalizedAt,
+    ...normalizedOptions
+  });
+}
+var Viewport = {
+  /**
+   * Add a render-only viewport label at a world-space point.
+   *
+   * **Details**
+   *
+   * `Viewport.label()` is for explanatory text that helps a viewer understand
+   * the model. It does not create sketches, meshes, B-rep topology, exported
+   * text, or face labels, so it stays off the OCCT path. Use `text2d()` only
+   * when the letters should become manufactured geometry, such as raised
+   * lettering, engraved serial numbers, or exported nameplates.
+   *
+   * Labels are collected during script execution and rendered by the viewport
+   * as lightweight overlay annotations. They are ignored by exports and do not
+   * appear in `objects`.
+   *
+   * **Example**
+   *
+   * ```js
+   * Viewport.label('Bearing bore', [0, 0, 18], {
+   *   color: '#f8fafc',
+   *   background: '#0f172acc',
+   *   offset: [0, 0, 8],
+   *   anchor: 'bottom',
+   * });
+   *
+   * return box(40, 30, 12);
+   * ```
+   *
+   * @param text - Label text to display in the viewport
+   * @param at - World-space anchor point `[x, y, z]`
+   * @param options - Visual label options
+   * @returns void
+   * @category Viewport Labels
+  */
+  label(text, at, options) {
+    collectRenderLabel(text, at, options);
+  }
+};
+
 // src/forge/renderStyle.ts
 var RENDER_STYLE_OPTIONS = [
   {
@@ -44666,17 +44832,17 @@ var rail = {
 };
 
 // src/forge/scene/scene.ts
-function requireFinite2(value, label) {
+function requireFinite3(value, label) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     throw new Error(`${label} must be a finite number`);
   }
   return value;
 }
-function requireVec3(value, label) {
+function requireVec32(value, label) {
   if (!Array.isArray(value) || value.length !== 3) {
     throw new Error(`${label} must be [x, y, z]`);
   }
-  return [requireFinite2(value[0], `${label}[0]`), requireFinite2(value[1], `${label}[1]`), requireFinite2(value[2], `${label}[2]`)];
+  return [requireFinite3(value[0], `${label}[0]`), requireFinite3(value[1], `${label}[1]`), requireFinite3(value[2], `${label}[2]`)];
 }
 function requireColor(value, label) {
   if (typeof value !== "string" || !value.trim()) {
@@ -44700,11 +44866,11 @@ var VALID_ENVIRONMENT_PRESETS = /* @__PURE__ */ new Set([
 ]);
 function validateCamera(cam, label) {
   const out = {};
-  if (cam.position !== void 0) out.position = requireVec3(cam.position, `${label}.position`);
-  if (cam.target !== void 0) out.target = requireVec3(cam.target, `${label}.target`);
-  if (cam.up !== void 0) out.up = requireVec3(cam.up, `${label}.up`);
+  if (cam.position !== void 0) out.position = requireVec32(cam.position, `${label}.position`);
+  if (cam.target !== void 0) out.target = requireVec32(cam.target, `${label}.target`);
+  if (cam.up !== void 0) out.up = requireVec32(cam.up, `${label}.up`);
   if (cam.fov !== void 0) {
-    out.fov = requireFinite2(cam.fov, `${label}.fov`);
+    out.fov = requireFinite3(cam.fov, `${label}.fov`);
     if (out.fov <= 0 || out.fov >= 180) throw new Error(`${label}.fov must be between 0 and 180`);
   }
   if (cam.type !== void 0) {
@@ -44715,6 +44881,120 @@ function validateCamera(cam, label) {
   }
   return out;
 }
+function validateViewCamera(cam, label) {
+  const validated = validateCamera(cam, label);
+  if (!validated.position) {
+    throw new Error(`${label}.position is required for named render views`);
+  }
+  if (!validated.target) {
+    throw new Error(`${label}.target is required for named render views`);
+  }
+  return {
+    ...validated,
+    position: validated.position,
+    target: validated.target
+  };
+}
+function validateViews(views, label) {
+  if (!views || typeof views !== "object" || Array.isArray(views)) {
+    throw new Error(`${label} must be an object mapping view names to cameras`);
+  }
+  const out = {};
+  for (const [name, view] of Object.entries(views)) {
+    if (!name.trim()) {
+      throw new Error(`${label} names must be non-empty strings`);
+    }
+    const viewLabel = `${label}.${name}`;
+    if (!view || typeof view !== "object" || Array.isArray(view)) {
+      throw new Error(`${viewLabel} must be a camera object or an object with a camera property`);
+    }
+    const hasExplicitCamera = Object.prototype.hasOwnProperty.call(view, "camera");
+    if (hasExplicitCamera) {
+      const camera = view.camera;
+      if (!camera || typeof camera !== "object" || Array.isArray(camera)) {
+        throw new Error(`${viewLabel}.camera must be an object`);
+      }
+      out[name] = { camera: validateViewCamera(camera, `${viewLabel}.camera`) };
+      continue;
+    }
+    out[name] = { camera: validateViewCamera(view, viewLabel) };
+  }
+  return out;
+}
+function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function optionalString(value, label) {
+  if (value === void 0) return void 0;
+  return requireString(value, label);
+}
+function validateJourneyStep(step, label) {
+  if (!step || typeof step !== "object" || Array.isArray(step)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const out = {
+    id: requireString(step.id, `${label}.id`)
+  };
+  const title = optionalString(step.title, `${label}.title`);
+  if (title !== void 0) out.title = title;
+  const focus = optionalString(step.focus, `${label}.focus`);
+  if (focus !== void 0) out.focus = focus;
+  const caption = optionalString(step.caption, `${label}.caption`);
+  if (caption !== void 0) out.caption = caption;
+  if (step.camera !== void 0) {
+    if (!step.camera || typeof step.camera !== "object" || Array.isArray(step.camera)) {
+      throw new Error(`${label}.camera must be an object`);
+    }
+    out.camera = validateViewCamera(step.camera, `${label}.camera`);
+  }
+  return out;
+}
+function validateJourney(journey, label) {
+  if (!journey || typeof journey !== "object" || Array.isArray(journey)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (!Array.isArray(journey.steps) || journey.steps.length === 0) {
+    throw new Error(`${label}.steps must be a non-empty array`);
+  }
+  const out = {
+    steps: journey.steps.map((step, index) => validateJourneyStep(step, `${label}.steps[${index}]`))
+  };
+  const title = optionalString(journey.title, `${label}.title`);
+  if (title !== void 0) out.title = title;
+  const startsAt = optionalString(journey.startsAt, `${label}.startsAt`);
+  if (startsAt !== void 0) out.startsAt = startsAt;
+  if (journey.behavior !== void 0) {
+    if (journey.behavior !== "opt-in" && journey.behavior !== "auto") {
+      throw new Error(`${label}.behavior must be "opt-in" or "auto"`);
+    }
+    out.behavior = journey.behavior;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const step of out.steps) {
+    if (seen.has(step.id)) {
+      throw new Error(`${label}.steps contains duplicate step id "${step.id}"`);
+    }
+    seen.add(step.id);
+  }
+  if (out.startsAt && !seen.has(out.startsAt)) {
+    throw new Error(`${label}.startsAt "${out.startsAt}" does not match any step id`);
+  }
+  return out;
+}
+function validateJourneys(journeys, label) {
+  if (!journeys || typeof journeys !== "object" || Array.isArray(journeys)) {
+    throw new Error(`${label} must be an object mapping journey ids to journey configs`);
+  }
+  const out = {};
+  for (const [id, journey] of Object.entries(journeys)) {
+    const normalizedId = requireString(id, `${label} journey id`);
+    out[normalizedId] = validateJourney(journey, `${label}.${normalizedId}`);
+  }
+  return out;
+}
 function validateLight(light, label) {
   if (!light || typeof light !== "object") throw new Error(`${label} must be an object`);
   if (!VALID_LIGHT_TYPES.has(light.type)) {
@@ -44722,15 +45002,15 @@ function validateLight(light, label) {
   }
   const out = { type: light.type };
   if (light.color !== void 0) out.color = requireColor(light.color, `${label}.color`);
-  if (light.intensity !== void 0) out.intensity = requireFinite2(light.intensity, `${label}.intensity`);
-  if (light.position !== void 0) out.position = requireVec3(light.position, `${label}.position`);
-  if (light.target !== void 0) out.target = requireVec3(light.target, `${label}.target`);
+  if (light.intensity !== void 0) out.intensity = requireFinite3(light.intensity, `${label}.intensity`);
+  if (light.position !== void 0) out.position = requireVec32(light.position, `${label}.position`);
+  if (light.target !== void 0) out.target = requireVec32(light.target, `${label}.target`);
   if (light.groundColor !== void 0) out.groundColor = requireColor(light.groundColor, `${label}.groundColor`);
   if (light.skyColor !== void 0) out.skyColor = requireColor(light.skyColor, `${label}.skyColor`);
-  if (light.angle !== void 0) out.angle = requireFinite2(light.angle, `${label}.angle`);
-  if (light.penumbra !== void 0) out.penumbra = requireFinite2(light.penumbra, `${label}.penumbra`);
-  if (light.decay !== void 0) out.decay = requireFinite2(light.decay, `${label}.decay`);
-  if (light.distance !== void 0) out.distance = requireFinite2(light.distance, `${label}.distance`);
+  if (light.angle !== void 0) out.angle = requireFinite3(light.angle, `${label}.angle`);
+  if (light.penumbra !== void 0) out.penumbra = requireFinite3(light.penumbra, `${label}.penumbra`);
+  if (light.decay !== void 0) out.decay = requireFinite3(light.decay, `${label}.decay`);
+  if (light.distance !== void 0) out.distance = requireFinite3(light.distance, `${label}.distance`);
   if (light.castShadow !== void 0) {
     if (typeof light.castShadow !== "boolean") throw new Error(`${label}.castShadow must be a boolean`);
     out.castShadow = light.castShadow;
@@ -44745,7 +45025,7 @@ function validateEnvironment(env, label) {
     }
     out.preset = env.preset;
   }
-  if (env.intensity !== void 0) out.intensity = requireFinite2(env.intensity, `${label}.intensity`);
+  if (env.intensity !== void 0) out.intensity = requireFinite3(env.intensity, `${label}.intensity`);
   if (env.background !== void 0) {
     if (typeof env.background !== "boolean") throw new Error(`${label}.background must be a boolean`);
     out.background = env.background;
@@ -44755,9 +45035,9 @@ function validateEnvironment(env, label) {
 function validateFog(fog, label) {
   const out = {};
   if (fog.color !== void 0) out.color = requireColor(fog.color, `${label}.color`);
-  if (fog.near !== void 0) out.near = requireFinite2(fog.near, `${label}.near`);
-  if (fog.far !== void 0) out.far = requireFinite2(fog.far, `${label}.far`);
-  if (fog.density !== void 0) out.density = requireFinite2(fog.density, `${label}.density`);
+  if (fog.near !== void 0) out.near = requireFinite3(fog.near, `${label}.near`);
+  if (fog.far !== void 0) out.far = requireFinite3(fog.far, `${label}.far`);
+  if (fog.density !== void 0) out.density = requireFinite3(fog.density, `${label}.density`);
   return out;
 }
 function validatePostProcessing(pp, label) {
@@ -44765,23 +45045,23 @@ function validatePostProcessing(pp, label) {
   if (pp.bloom !== void 0) {
     if (!pp.bloom || typeof pp.bloom !== "object") throw new Error(`${label}.bloom must be an object`);
     out.bloom = {};
-    if (pp.bloom.intensity !== void 0) out.bloom.intensity = requireFinite2(pp.bloom.intensity, `${label}.bloom.intensity`);
-    if (pp.bloom.threshold !== void 0) out.bloom.threshold = requireFinite2(pp.bloom.threshold, `${label}.bloom.threshold`);
-    if (pp.bloom.radius !== void 0) out.bloom.radius = requireFinite2(pp.bloom.radius, `${label}.bloom.radius`);
+    if (pp.bloom.intensity !== void 0) out.bloom.intensity = requireFinite3(pp.bloom.intensity, `${label}.bloom.intensity`);
+    if (pp.bloom.threshold !== void 0) out.bloom.threshold = requireFinite3(pp.bloom.threshold, `${label}.bloom.threshold`);
+    if (pp.bloom.radius !== void 0) out.bloom.radius = requireFinite3(pp.bloom.radius, `${label}.bloom.radius`);
   }
   if (pp.vignette !== void 0) {
     if (!pp.vignette || typeof pp.vignette !== "object") throw new Error(`${label}.vignette must be an object`);
     out.vignette = {};
-    if (pp.vignette.darkness !== void 0) out.vignette.darkness = requireFinite2(pp.vignette.darkness, `${label}.vignette.darkness`);
-    if (pp.vignette.offset !== void 0) out.vignette.offset = requireFinite2(pp.vignette.offset, `${label}.vignette.offset`);
+    if (pp.vignette.darkness !== void 0) out.vignette.darkness = requireFinite3(pp.vignette.darkness, `${label}.vignette.darkness`);
+    if (pp.vignette.offset !== void 0) out.vignette.offset = requireFinite3(pp.vignette.offset, `${label}.vignette.offset`);
   }
   if (pp.grain !== void 0) {
     if (!pp.grain || typeof pp.grain !== "object") throw new Error(`${label}.grain must be an object`);
     out.grain = {};
-    if (pp.grain.intensity !== void 0) out.grain.intensity = requireFinite2(pp.grain.intensity, `${label}.grain.intensity`);
+    if (pp.grain.intensity !== void 0) out.grain.intensity = requireFinite3(pp.grain.intensity, `${label}.grain.intensity`);
   }
   if (pp.toneMappingExposure !== void 0) {
-    out.toneMappingExposure = requireFinite2(pp.toneMappingExposure, `${label}.toneMappingExposure`);
+    out.toneMappingExposure = requireFinite3(pp.toneMappingExposure, `${label}.toneMappingExposure`);
   }
   return out;
 }
@@ -44792,7 +45072,7 @@ function validateGround(ground, label) {
     out.visible = ground.visible;
   }
   if (ground.color !== void 0) out.color = requireColor(ground.color, `${label}.color`);
-  if (ground.offset !== void 0) out.offset = requireFinite2(ground.offset, `${label}.offset`);
+  if (ground.offset !== void 0) out.offset = requireFinite3(ground.offset, `${label}.offset`);
   if (ground.receiveShadow !== void 0) {
     if (typeof ground.receiveShadow !== "boolean") throw new Error(`${label}.receiveShadow must be a boolean`);
     out.receiveShadow = ground.receiveShadow;
@@ -44802,31 +45082,31 @@ function validateGround(ground, label) {
 function validateCapture(cap, label) {
   const out = {};
   if (cap.framesPerTurn !== void 0) {
-    out.framesPerTurn = requireFinite2(cap.framesPerTurn, `${label}.framesPerTurn`);
+    out.framesPerTurn = requireFinite3(cap.framesPerTurn, `${label}.framesPerTurn`);
     if (out.framesPerTurn < 12 || out.framesPerTurn > 720) {
       throw new Error(`${label}.framesPerTurn must be between 12 and 720`);
     }
   }
   if (cap.holdFrames !== void 0) {
-    out.holdFrames = requireFinite2(cap.holdFrames, `${label}.holdFrames`);
+    out.holdFrames = requireFinite3(cap.holdFrames, `${label}.holdFrames`);
     if (out.holdFrames < 0 || out.holdFrames > 300) {
       throw new Error(`${label}.holdFrames must be between 0 and 300`);
     }
   }
   if (cap.pitchDeg !== void 0) {
-    out.pitchDeg = requireFinite2(cap.pitchDeg, `${label}.pitchDeg`);
+    out.pitchDeg = requireFinite3(cap.pitchDeg, `${label}.pitchDeg`);
     if (out.pitchDeg < -80 || out.pitchDeg > 80) {
       throw new Error(`${label}.pitchDeg must be between -80 and 80`);
     }
   }
   if (cap.fps !== void 0) {
-    out.fps = requireFinite2(cap.fps, `${label}.fps`);
+    out.fps = requireFinite3(cap.fps, `${label}.fps`);
     if (out.fps < 1 || out.fps > 60) {
       throw new Error(`${label}.fps must be between 1 and 60`);
     }
   }
   if (cap.size !== void 0) {
-    out.size = requireFinite2(cap.size, `${label}.size`);
+    out.size = requireFinite3(cap.size, `${label}.size`);
     if (out.size < 1) {
       throw new Error(`${label}.size must be positive`);
     }
@@ -44847,18 +45127,29 @@ function validateBackground(bg, label) {
   }
   throw new Error(`${label} must be a color string or { top, bottom } gradient`);
 }
-var _collected5 = null;
+var _collected6 = null;
 function resetScene() {
-  _collected5 = null;
+  _collected6 = null;
 }
 function getCollectedScene() {
-  return _collected5 ? { ..._collected5 } : null;
+  return _collected6 ? { ..._collected6 } : null;
 }
 function scene(options) {
   if (!options || typeof options !== "object") {
     throw new Error("scene(options) expects an options object");
   }
-  const current = _collected5 ? { ..._collected5 } : { background: null, camera: null, lights: null, environment: null, fog: null, postProcessing: null, ground: null, capture: null };
+  const current = _collected6 ? { ..._collected6 } : {
+    background: null,
+    camera: null,
+    views: null,
+    journeys: null,
+    lights: null,
+    environment: null,
+    fog: null,
+    postProcessing: null,
+    ground: null,
+    capture: null
+  };
   if (options.background !== void 0) {
     current.background = validateBackground(options.background, "scene.background");
   }
@@ -44869,6 +45160,14 @@ function scene(options) {
     const validated = validateCamera(options.camera, "scene.camera");
     current.camera = current.camera ? { ...current.camera, ...validated } : validated;
   }
+  if (options.views !== void 0) {
+    const validated = validateViews(options.views, "scene.views");
+    current.views = current.views ? { ...current.views, ...validated } : validated;
+  }
+  if (options.journeys !== void 0) {
+    const validated = validateJourneys(options.journeys, "scene.journeys");
+    current.journeys = current.journeys ? { ...current.journeys, ...validated } : validated;
+  }
   if (options.lights !== void 0) {
     if (!Array.isArray(options.lights)) {
       throw new Error("scene.lights must be an array");
@@ -44907,7 +45206,74 @@ function scene(options) {
     const validated = validateCapture(options.capture, "scene.capture");
     current.capture = current.capture ? { ...current.capture, ...validated } : validated;
   }
-  _collected5 = current;
+  _collected6 = current;
+}
+var targetPath = (target) => {
+  const path4 = target.treePath?.filter((entry) => entry.trim());
+  return path4 && path4.length > 0 ? path4.join("/") : target.name;
+};
+var hasErrorDiagnostic = (diagnostics) => diagnostics.some((diagnostic) => diagnostic.level === "error");
+function resolveJourneyFocus(focus, targets) {
+  return targets.filter((target) => target.name === focus || targetPath(target) === focus);
+}
+function formatAvailableTargets(targets) {
+  return targets.map((target) => targetPath(target)).filter((value, index, values) => values.indexOf(value) === index).sort().slice(0, 8);
+}
+function resolveSceneJourneyTargets(config, targets) {
+  if (!config?.journeys) return config;
+  const journeys = {};
+  for (const [journeyId, journey] of Object.entries(config.journeys)) {
+    const journeyDiagnostics = [...journey.diagnostics ?? []];
+    const steps = journey.steps.map((step) => {
+      const stepDiagnostics = [...step.diagnostics ?? []];
+      let resolvedFocusId = null;
+      let resolvedFocusPath = null;
+      if (step.focus) {
+        const matches = resolveJourneyFocus(step.focus, targets);
+        if (matches.length === 1) {
+          resolvedFocusId = matches[0].id;
+          resolvedFocusPath = targetPath(matches[0]);
+        } else if (matches.length === 0) {
+          stepDiagnostics.push({
+            level: "error",
+            stepId: step.id,
+            message: `focus "${step.focus}" did not match any returned object by name or tree path.`,
+            suggestions: formatAvailableTargets(targets)
+          });
+        } else {
+          stepDiagnostics.push({
+            level: "error",
+            stepId: step.id,
+            message: `focus "${step.focus}" matched ${matches.length} objects. Use a slash-separated tree path.`,
+            suggestions: matches.map((match) => targetPath(match))
+          });
+        }
+      } else if (!step.camera) {
+        stepDiagnostics.push({
+          level: "warning",
+          stepId: step.id,
+          message: "step has no focus or explicit camera, so the viewer can show the caption but cannot move the camera."
+        });
+      }
+      journeyDiagnostics.push(...stepDiagnostics);
+      return {
+        ...step,
+        resolvedFocusId,
+        resolvedFocusPath,
+        diagnostics: stepDiagnostics.length > 0 ? stepDiagnostics : void 0
+      };
+    });
+    journeys[journeyId] = {
+      ...journey,
+      steps,
+      valid: !hasErrorDiagnostic(journeyDiagnostics),
+      diagnostics: journeyDiagnostics.length > 0 ? journeyDiagnostics : void 0
+    };
+  }
+  return {
+    ...config,
+    journeys
+  };
 }
 
 // src/forge/scene/viewConfig.ts
@@ -45065,25 +45431,25 @@ var DEFAULT_JOINT_OVERLAY_VIEW_CONFIG = {
 var DEFAULT_VIEW_CONFIG = {
   jointOverlay: cloneJointOverlay(DEFAULT_JOINT_OVERLAY_VIEW_CONFIG)
 };
-var _collected6 = null;
+var _collected7 = null;
 function resetViewConfig() {
-  _collected6 = null;
+  _collected7 = null;
 }
 function getCollectedViewConfig() {
-  return _collected6 ? cloneViewConfig(_collected6) : null;
+  return _collected7 ? cloneViewConfig(_collected7) : null;
 }
 function viewConfig(options = {}) {
   if (!options || typeof options !== "object") {
     throw new Error("viewConfig(options) expects an options object");
   }
-  const next = _collected6 ? cloneViewConfig(_collected6) : cloneViewConfig(DEFAULT_VIEW_CONFIG);
+  const next = _collected7 ? cloneViewConfig(_collected7) : cloneViewConfig(DEFAULT_VIEW_CONFIG);
   if (options.jointOverlay !== void 0) {
     if (!options.jointOverlay || typeof options.jointOverlay !== "object") {
       throw new Error("viewConfig.jointOverlay must be an object");
     }
     next.jointOverlay = patchJointOverlay(next.jointOverlay, options.jointOverlay, "viewConfig.jointOverlay");
   }
-  _collected6 = next;
+  _collected7 = next;
 }
 
 // src/forge/intent/compilerDiagnostics.ts
@@ -46239,7 +46605,7 @@ function hermiteTransitionG2(a, b) {
 }
 
 // src/forge/sketch/nurbsCurve.ts
-function requireFinite3(v, label) {
+function requireFinite4(v, label) {
   if (!Number.isFinite(v)) throw new Error(`nurbs3d: ${label} must be finite, got ${v}`);
 }
 var NurbsCurve3D = class {
@@ -46254,14 +46620,14 @@ var NurbsCurve3D = class {
     if (degree < 1) throw new Error("nurbs3d: degree must be \u2265 1");
     if (n < degree + 1) throw new Error(`nurbs3d: need at least ${degree + 1} control points for degree ${degree}, got ${n}`);
     for (let i = 0; i < n; i++) {
-      requireFinite3(points[i][0], `controlPoints[${i}][0]`);
-      requireFinite3(points[i][1], `controlPoints[${i}][1]`);
-      requireFinite3(points[i][2], `controlPoints[${i}][2]`);
+      requireFinite4(points[i][0], `controlPoints[${i}][0]`);
+      requireFinite4(points[i][1], `controlPoints[${i}][1]`);
+      requireFinite4(points[i][2], `controlPoints[${i}][2]`);
     }
     const weights = options.weights ?? new Array(n).fill(1);
     if (weights.length !== n) throw new Error(`nurbs3d: weights.length (${weights.length}) must equal controlPoints.length (${n})`);
     for (let i = 0; i < n; i++) {
-      requireFinite3(weights[i], `weights[${i}]`);
+      requireFinite4(weights[i], `weights[${i}]`);
       if (weights[i] <= 0) throw new Error(`nurbs3d: weights[${i}] must be > 0, got ${weights[i]}`);
     }
     const expectedKnotLength = n + degree + 1;
@@ -46270,7 +46636,7 @@ var NurbsCurve3D = class {
       throw new Error(`nurbs3d: knots.length (${knots.length}) must be controlPoints.length + degree + 1 (${expectedKnotLength})`);
     }
     for (let i = 0; i < knots.length; i++) {
-      requireFinite3(knots[i], `knots[${i}]`);
+      requireFinite4(knots[i], `knots[${i}]`);
       if (i > 0 && knots[i] < knots[i - 1]) {
         throw new Error(`nurbs3d: knot vector must be non-decreasing, but knots[${i - 1}]=${knots[i - 1]} > knots[${i}]=${knots[i]}`);
       }
@@ -46831,9 +47197,15 @@ function cross5(a, b) {
 function add4(a, b) {
   return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
 }
+function sub6(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
 function scale5(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
+function dot6(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
 function lerp2(a, b, t) {
   return a + (b - a) * t;
 }
@@ -46866,6 +47238,65 @@ function sideVectors(axis) {
 function cloneQuery(query) {
   return { side: query.side, u: query.u, v: query.v, offset: query.offset };
 }
+function normalizedSide(side) {
+  return side === "back" ? "rear" : side;
+}
+function profileExponent(station) {
+  if (station.profile.kind === "superEllipse") return station.profile.exponent ?? 3.2;
+  if (station.profile.kind === "roundedRect") return 4.5;
+  return 2;
+}
+function superEllipsePoint(rx, ry, exponent, angle) {
+  const cos4 = Math.cos(angle);
+  const sin4 = Math.sin(angle);
+  const x = rx * Math.sign(cos4) * Math.abs(cos4) ** (2 / exponent);
+  const y = ry * Math.sign(sin4) * Math.abs(sin4) ** (2 / exponent);
+  const nx = Math.sign(x) * Math.abs(x / Math.max(rx, EPS7)) ** Math.max(exponent - 1, 1e-3);
+  const ny = Math.sign(y) * Math.abs(y / Math.max(ry, EPS7)) ** Math.max(exponent - 1, 1e-3);
+  const nLen = Math.hypot(nx, ny);
+  return {
+    point: [x, y],
+    normal: nLen < EPS7 ? [Math.sign(cos4), Math.sign(sin4)] : [nx / nLen, ny / nLen]
+  };
+}
+function angleForSide(side, u) {
+  const t = clamp6(u, 0, 1);
+  if (side === "right") return -Math.PI / 2 + t * Math.PI;
+  if (side === "left") return Math.PI / 2 + t * Math.PI;
+  if (side === "top") return Math.PI - t * Math.PI;
+  if (side === "bottom") return Math.PI + t * Math.PI;
+  return null;
+}
+function sideSpan(side, width, depth) {
+  if (side === "left" || side === "right") return Math.max(depth, EPS7);
+  if (side === "top" || side === "bottom") return Math.max(width, EPS7);
+  return Math.max(width, depth, EPS7);
+}
+function interpolateQuery(a, b, t) {
+  const sideA = normalizedSide(a.side);
+  const sideB = normalizedSide(b.side);
+  if (sideA !== sideB) {
+    throw new Error(
+      `Product.ribbon().on(...) currently samples one skin side per ribbon; got '${a.side}' then '${b.side}'. Split this into separate ribbons at the side transition.`
+    );
+  }
+  return {
+    side: sideA,
+    u: lerp2(a.u ?? 0.5, b.u ?? 0.5, t),
+    v: lerp2(a.v ?? 0.5, b.v ?? 0.5, t),
+    offset: lerp2(a.offset ?? 0, b.offset ?? 0, t)
+  };
+}
+function resolvePathQueries(points) {
+  return points.map((point2) => point2 instanceof ProductSurfaceRef ? point2.querySpec() : cloneQuery(point2));
+}
+function orientGridToNormal(grid, desiredNormal) {
+  if (grid.length < 2 || grid[0].length < 2) return grid;
+  const widthEdge = sub6(grid[grid.length - 1][0], grid[0][0]);
+  const lengthEdge = sub6(grid[0][grid[0].length - 1], grid[0][0]);
+  const actual = norm2(cross5(widthEdge, lengthEdge));
+  return dot6(actual, desiredNormal) < 0 ? [...grid].reverse() : grid;
+}
 function isStationBuilder(input) {
   return typeof input.toSpec === "function";
 }
@@ -46967,6 +47398,15 @@ var ProductSkin = class {
   curveOnSurface(name, points) {
     return points.map((point2, index) => new ProductSurfaceRef(this, { u: 0.5, v: 0.5, ...point2 }, `${name}/${index}`));
   }
+  /**
+   * Create a fluent surface helper for refs and conformal features on one side of this skin.
+   *
+   * Use this when several refs or ribbons share the same skin side; side-local helpers keep
+   * path points concise and make it harder to mix sides accidentally.
+   */
+  surface(side) {
+    return new ProductSurfaceBuilder(this, side);
+  }
   /** Interpolate center, width, and depth at a normalized v or absolute axis value. */
   stationAt(vOrAxis) {
     const axisValue = vOrAxis >= 0 && vOrAxis <= 1 ? lerp2(this.axisMin, this.axisMax, vOrAxis) : clamp6(vOrAxis, this.axisMin, this.axisMax);
@@ -46985,7 +47425,9 @@ var ProductSkin = class {
         width: lerp2(a.profile.width, b.profile.width, t),
         depth: lerp2(a.profile.depth, b.profile.depth, t),
         dWidth: (b.profile.width - a.profile.width) / span,
-        dDepth: (b.profile.depth - a.profile.depth) / span
+        dDepth: (b.profile.depth - a.profile.depth) / span,
+        exponent: lerp2(profileExponent(a), profileExponent(b), t),
+        kind: a.profile.kind === b.profile.kind ? a.profile.kind : "custom"
       };
     }
     const last = sorted[sorted.length - 1];
@@ -46995,12 +47437,14 @@ var ProductSkin = class {
       width: last.profile.width,
       depth: last.profile.depth,
       dWidth: 0,
-      dDepth: 0
+      dDepth: 0,
+      exponent: profileExponent(last),
+      kind: last.profile.kind
     };
   }
   /** Build a local surface frame from a side/u/v query. */
   frame(query) {
-    const side = query.side === "back" ? "rear" : query.side;
+    const side = normalizedSide(query.side);
     const offset2 = query.offset ?? 0;
     const basis = sideVectors(this.axis);
     const isFrontCap = side === "front";
@@ -47024,11 +47468,31 @@ var ProductSkin = class {
     }
     const station = this.stationAt(query.v ?? 0.5);
     const u = clamp6(query.u ?? 0.5, 0, 1) - 0.5;
+    const sideAngle = angleForSide(side, query.u ?? 0.5);
     let crossA = 0;
     let crossB = 0;
     let normal = [0, 0, 1];
     let tangentU = basis.crossA;
-    if (side === "right") {
+    if (sideAngle != null) {
+      const section = superEllipsePoint(station.width / 2, station.depth / 2, station.exponent, sideAngle);
+      crossA = section.point[0];
+      crossB = section.point[1];
+      normal = norm2(add4(scale5(basis.crossA, section.normal[0]), scale5(basis.crossB, section.normal[1])));
+      const delta = 2e-3;
+      const prev = superEllipsePoint(
+        station.width / 2,
+        station.depth / 2,
+        station.exponent,
+        angleForSide(side, clamp6((query.u ?? 0.5) - delta, 0, 1)) ?? sideAngle
+      ).point;
+      const next = superEllipsePoint(
+        station.width / 2,
+        station.depth / 2,
+        station.exponent,
+        angleForSide(side, clamp6((query.u ?? 0.5) + delta, 0, 1)) ?? sideAngle
+      ).point;
+      tangentU = norm2(add4(scale5(basis.crossA, next[0] - prev[0]), scale5(basis.crossB, next[1] - prev[1])));
+    } else if (side === "right") {
       crossA = station.width / 2;
       crossB = u * station.depth;
       normal = basis.crossA;
@@ -47050,7 +47514,7 @@ var ProductSkin = class {
       tangentU = basis.crossA;
     }
     normal = norm2(normal);
-    tangentU = norm2(tangentU);
+    tangentU = norm2(sub6(tangentU, scale5(normal, dot6(tangentU, normal))));
     const tangentV = norm2(cross5(normal, tangentU));
     const point2 = add4(add4(station.center, add4(scale5(basis.crossA, crossA), scale5(basis.crossB, crossB))), scale5(normal, offset2));
     return {
@@ -47370,6 +47834,303 @@ var ProductHandleBuilder = class {
     return new ProductHandleFeature(grip, upperPad, lowerPad);
   }
 };
+var ProductSurfaceBuilder = class {
+  constructor(skin, side) {
+    this.skin = skin;
+    this.side = side;
+  }
+  /** Create a ref on this skin side. */
+  ref(u = 0.5, v = 0.5, offset2) {
+    return Product.ref(this.skin, {
+      side: this.side,
+      u,
+      v,
+      ...offset2 != null ? { offset: offset2 } : {}
+    });
+  }
+  /** Create a side/u/v query on this skin side. */
+  uv(u = 0.5, v = 0.5, offset2) {
+    return {
+      side: this.side,
+      u,
+      v,
+      ...offset2 != null ? { offset: offset2 } : {}
+    };
+  }
+  /**
+   * Start a conformal ribbon on this skin side.
+   *
+   * Path points use side-local `u`/`v` coordinates; this builder supplies the side.
+   * The returned ProductRibbonBuilder is already bound to the source skin and can be further
+   * configured before build(). Use `widthSamples` >= 3 when the ribbon must visibly wrap over
+   * curved product sections instead of behaving like a flat strip.
+   */
+  ribbon(name, points, options = {}) {
+    if (points.length < 2) throw new Error("Product.surface(...).ribbon(name, points) requires at least two path points");
+    const path4 = points.map((point2) => ({
+      side: this.side,
+      u: point2.u ?? 0.5,
+      v: point2.v ?? 0.5,
+      ...point2.offset != null ? { offset: point2.offset } : {}
+    }));
+    return new ProductRibbonBuilder(name).on(this.skin, path4, options);
+  }
+};
+var ProductRibbonBuilder = class {
+  constructor(name) {
+    this.name = name;
+    if (!name || !name.trim()) throw new Error("Product.ribbon(name) requires a non-empty name");
+  }
+  skinValue;
+  queryPath = [];
+  refPath = [];
+  widthValue = 6;
+  thicknessValue = 0.8;
+  offsetValue = 0.25;
+  samplesValue = 24;
+  widthSamplesValue = 5;
+  resolutionValue;
+  materialValue;
+  colorValue;
+  lastDiagnosticsValue;
+  /**
+   * Follow a ProductSkin with side/u/v path queries or refs.
+   *
+   * This is the highest-fidelity mode because every interpolated sample is resolved through
+   * ProductSkin.frame(), so the ribbon bends along the selected side as station width/depth changes.
+   * All query path points must stay on one side; split side transitions into separate ribbons.
+   */
+  on(skin, points, options = {}) {
+    if (points.length < 2) throw new Error("Product.ribbon().on(skin, points) requires at least two path points");
+    this.skinValue = skin;
+    this.queryPath = resolvePathQueries(points);
+    this.refPath = [];
+    return this.applyOptions(options);
+  }
+  /**
+   * Follow explicit surface refs.
+   *
+   * Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and
+   * interpolates between those frames; use on(skin, points) when you need full skin-side sampling
+   * between sparse control points.
+   */
+  fromRefs(points, options = {}) {
+    if (points.length < 2) throw new Error("Product.ribbon().fromRefs(points) requires at least two refs");
+    this.skinValue = void 0;
+    this.queryPath = [];
+    this.refPath = [...points];
+    return this.applyOptions(options);
+  }
+  /** Set ribbon width in millimeters. */
+  width(width) {
+    if (!Number.isFinite(width) || width <= 0) throw new Error("Product.ribbon().width(width) requires a positive finite number");
+    this.widthValue = width;
+    return this;
+  }
+  /** Set solid thickness outward from the source surface in millimeters. */
+  thickness(thickness) {
+    if (!Number.isFinite(thickness) || thickness <= 0)
+      throw new Error("Product.ribbon().thickness(thickness) requires a positive finite number");
+    this.thicknessValue = thickness;
+    return this;
+  }
+  /** Set positive clearance between the source surface and the ribbon's inner face. */
+  offset(offset2) {
+    if (!Number.isFinite(offset2)) throw new Error("Product.ribbon().offset(offset) requires a finite number");
+    this.offsetValue = offset2;
+    return this;
+  }
+  /** Set samples along the path. */
+  samples(samples) {
+    if (!Number.isFinite(samples) || samples < 2) throw new Error("Product.ribbon().samples(samples) requires a value >= 2");
+    this.samplesValue = Math.round(samples);
+    return this;
+  }
+  /** Set samples across the width. Use 3+ to bend over curved cross-sections. */
+  widthSamples(samples) {
+    if (!Number.isFinite(samples) || samples < 2) throw new Error("Product.ribbon().widthSamples(samples) requires a value >= 2");
+    this.widthSamplesValue = Math.round(samples);
+    return this;
+  }
+  /** Set NURBS tessellation resolution. */
+  resolution(resolution) {
+    if (!Number.isFinite(resolution) || resolution < 2) throw new Error("Product.ribbon().resolution(resolution) requires a value >= 2");
+    this.resolutionValue = Math.round(resolution);
+    return this;
+  }
+  /** Apply a product material preset. */
+  material(material) {
+    this.materialValue = material;
+    return this;
+  }
+  /** Apply a simple color override. */
+  color(color) {
+    this.colorValue = color;
+    return this;
+  }
+  /** Build a conformal ribbon as a thin NURBS surface solid. */
+  build(options = {}) {
+    return this.buildWithDiagnostics(options).shape;
+  }
+  /**
+   * Build a conformal ribbon and return surface-feature diagnostics.
+   *
+   * Use this while validating API usage or model fidelity; diagnostics report sampling counts,
+   * side-span clamping, lowering mode, and warnings that should be visible in reviews.
+   */
+  buildWithDiagnostics(options = {}) {
+    this.applyOptions(options);
+    const gridResult = this.skinValue ? this.buildSkinGrid(this.skinValue, this.queryPath) : this.buildRefGrid(this.refPath);
+    const desiredNormal = this.centerDesiredNormal();
+    let ribbon = nurbsSurface(orientGridToNormal(gridResult.grid, desiredNormal), {
+      degreeU: Math.min(3, this.widthSamplesValue - 1),
+      degreeV: Math.min(3, this.samplesValue - 1),
+      thickness: this.thicknessValue,
+      resolution: this.resolutionValue ?? Math.max(this.samplesValue, this.widthSamplesValue, 12),
+      approximate: true
+    }).as(this.name);
+    if (this.colorValue) ribbon = ribbon.color(this.colorValue);
+    const shape = applyMaterial(ribbon, this.materialValue);
+    this.lastDiagnosticsValue = gridResult.diagnostics;
+    return { shape, diagnostics: this.cloneDiagnostics(gridResult.diagnostics) };
+  }
+  /** Return diagnostics from the most recent build, if this builder has been built. */
+  diagnostics() {
+    return this.lastDiagnosticsValue ? this.cloneDiagnostics(this.lastDiagnosticsValue) : void 0;
+  }
+  applyOptions(options) {
+    if (options.width != null) this.width(options.width);
+    if (options.thickness != null) this.thickness(options.thickness);
+    if (options.offset != null) this.offset(options.offset);
+    if (options.samples != null) this.samples(options.samples);
+    if (options.widthSamples != null) this.widthSamples(options.widthSamples);
+    if (options.resolution != null) this.resolution(options.resolution);
+    if (options.material) this.material(options.material);
+    if (options.color) this.color(options.color);
+    return this;
+  }
+  centerDesiredNormal() {
+    if (this.skinValue && this.queryPath.length > 0) {
+      const mid = this.samplePathQuery(0.5);
+      return this.skinValue.frame({ ...mid, offset: (mid.offset ?? 0) + this.offsetValue }).normal;
+    }
+    if (this.refPath.length > 0) return this.refPath[Math.floor(this.refPath.length / 2)].frame({ offset: this.offsetValue }).normal;
+    return [0, 0, 1];
+  }
+  samplePathQuery(t) {
+    if (this.queryPath.length < 2) throw new Error("Product.ribbon().on(...) must be called before .build()");
+    const segmentCount = this.queryPath.length - 1;
+    const scaled = clamp6(t, 0, 1) * segmentCount;
+    const segment = Math.min(segmentCount - 1, Math.floor(scaled));
+    const localT = scaled - segment;
+    return interpolateQuery(this.queryPath[segment], this.queryPath[segment + 1], localT);
+  }
+  buildSkinGrid(skin, path4) {
+    if (path4.length < 2) throw new Error("Product.ribbon().on(skin, points) must be called before .build()");
+    const side = normalizedSide(path4[0].side);
+    if (side === "front" || side === "rear") {
+      throw new Error(
+        "Product.ribbon().on(...) supports side ribbons on left/right/top/bottom surfaces. Use Product.panel() for front/rear caps."
+      );
+    }
+    for (const point2 of path4) {
+      if (normalizedSide(point2.side) !== side) {
+        throw new Error("Product.ribbon().on(...) currently supports one side per ribbon. Split ribbons at side transitions.");
+      }
+    }
+    const rows = Array.from({ length: this.widthSamplesValue }, () => []);
+    let clampedUCount = 0;
+    let maxUClampDistance = 0;
+    for (let i = 0; i < this.samplesValue; i += 1) {
+      const along = this.samplesValue === 1 ? 0 : i / (this.samplesValue - 1);
+      const center = this.samplePathQuery(along);
+      const station = skin.stationAt(center.v ?? 0.5);
+      const span = sideSpan(side, station.width, station.depth);
+      for (let j = 0; j < this.widthSamplesValue; j += 1) {
+        const across = this.widthSamplesValue === 1 ? 0 : j / (this.widthSamplesValue - 1) - 0.5;
+        const rawU = (center.u ?? 0.5) + across * this.widthValue / span;
+        const u = clamp6(rawU, 0, 1);
+        const clampDistance = Math.abs(rawU - u) * span;
+        if (clampDistance > EPS7) {
+          clampedUCount += 1;
+          maxUClampDistance = Math.max(maxUClampDistance, clampDistance);
+        }
+        const query = {
+          ...center,
+          side,
+          u,
+          offset: (center.offset ?? 0) + this.offsetValue + this.thicknessValue
+        };
+        rows[j].push(skin.frame(query).point);
+      }
+    }
+    return {
+      grid: rows,
+      diagnostics: this.makeDiagnostics({
+        skin: skin.name,
+        side,
+        pathPointCount: path4.length,
+        clampedUCount,
+        maxUClampDistance
+      })
+    };
+  }
+  buildRefGrid(refs) {
+    if (refs.length < 2) throw new Error("Product.ribbon().fromRefs(points) must be called before .build()");
+    const frames = refs.map((ref) => ref.frame({ offset: this.offsetValue + this.thicknessValue }));
+    const rows = Array.from({ length: this.widthSamplesValue }, () => []);
+    for (const frame of frames) {
+      for (let j = 0; j < this.widthSamplesValue; j += 1) {
+        const across = this.widthSamplesValue === 1 ? 0 : j / (this.widthSamplesValue - 1) - 0.5;
+        rows[j].push(add4(frame.point, scale5(frame.tangentU, across * this.widthValue)));
+      }
+    }
+    this.samplesValue = refs.length;
+    return {
+      grid: rows,
+      diagnostics: this.makeDiagnostics({
+        pathPointCount: refs.length,
+        clampedUCount: 0,
+        maxUClampDistance: 0
+      })
+    };
+  }
+  makeDiagnostics(input) {
+    const resolution = this.resolutionValue ?? Math.max(this.samplesValue, this.widthSamplesValue, 12);
+    const warnings = [];
+    if (input.clampedUCount > 0) {
+      warnings.push(
+        `Ribbon '${this.name}' was clipped to the ${input.side ?? "surface"} UV bounds at ${input.clampedUCount} sampled point(s).`
+      );
+    }
+    if (this.samplesValue < 8) warnings.push(`Ribbon '${this.name}' uses low along-path sampling; increase samples() for smoother bends.`);
+    if (this.widthSamplesValue < 3)
+      warnings.push(`Ribbon '${this.name}' uses low width sampling; use widthSamples(3+) to show cross-surface curvature.`);
+    return {
+      name: this.name,
+      ...input.skin ? { skin: input.skin } : {},
+      ...input.side ? { side: input.side } : {},
+      pathPointCount: input.pathPointCount,
+      width: this.widthValue,
+      thickness: this.thicknessValue,
+      offset: this.offsetValue,
+      samples: this.samplesValue,
+      widthSamples: this.widthSamplesValue,
+      resolution,
+      lowering: "nurbsSurface",
+      expectedFidelity: "mixed",
+      clampedUCount: input.clampedUCount,
+      maxUClampDistance: input.maxUClampDistance,
+      warnings
+    };
+  }
+  cloneDiagnostics(diagnostics) {
+    return {
+      ...diagnostics,
+      warnings: [...diagnostics.warnings]
+    };
+  }
+};
 var Product = {
   /** Start a named product skin builder. */
   skin(name) {
@@ -47442,10 +48203,27 @@ var Product = {
   ref(skin, query) {
     return new ProductSurfaceRef(skin, query);
   },
+  /**
+   * Create a fluent surface helper for refs and conformal features on one side of a skin.
+   *
+   * Equivalent to skin.surface(side), useful when writing in Product.* namespace style.
+   */
+  surface(skin, side) {
+    return skin.surface(side);
+  },
   /** Start a panel feature builder. */
   panel(name) {
     return new ProductPanelBuilder(name);
   },
+  /**
+   * Start a conformal ribbon/trim builder for details that should bend with a ProductSkin.
+   *
+   * Call .on(skin, points) for side/u/v sampling or .fromRefs(points) for explicit surface refs,
+   * then configure width, thickness, offset, sampling, material, and color before build().
+   */
+  ribbon(name) {
+    return new ProductRibbonBuilder(name);
+  },
   /** Start a spout/nozzle feature builder. */
   spout(name) {
     return new ProductSpoutBuilder(name);
@@ -47615,8 +48393,8 @@ function buildNameLookup(objects) {
   const bySuffix = /* @__PURE__ */ new Map();
   objects.forEach((obj) => {
     pushLookup(byExact, obj.name, obj.id);
-    for (let dot8 = obj.name.indexOf("."); dot8 >= 0; dot8 = obj.name.indexOf(".", dot8 + 1)) {
-      pushLookup(bySuffix, obj.name.slice(dot8 + 1), obj.id);
+    for (let dot9 = obj.name.indexOf("."); dot9 >= 0; dot9 = obj.name.indexOf(".", dot9 + 1)) {
+      pushLookup(bySuffix, obj.name.slice(dot9 + 1), obj.id);
     }
   });
   return { byExact, bySuffix };
@@ -49904,7 +50682,7 @@ var Constraint = {
 };
 
 // src/forge/points.ts
-function requireVec32(v, label) {
+function requireVec33(v, label) {
   if (!Array.isArray(v) || v.length !== 3 || !Number.isFinite(v[0]) || !Number.isFinite(v[1]) || !Number.isFinite(v[2])) {
     throw new Error(`${label} must be a [number, number, number] with finite values, got ${JSON.stringify(v)}`);
   }
@@ -49917,24 +50695,24 @@ function requireFiniteNumber(n, label) {
   return n;
 }
 function distance(a, b) {
-  requireVec32(a, "a");
-  requireVec32(b, "b");
+  requireVec33(a, "a");
+  requireVec33(b, "b");
   return Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
 }
 function midpoint4(a, b) {
-  requireVec32(a, "a");
-  requireVec32(b, "b");
+  requireVec33(a, "a");
+  requireVec33(b, "b");
   return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2];
 }
 function lerp3(a, b, t) {
-  requireVec32(a, "a");
-  requireVec32(b, "b");
+  requireVec33(a, "a");
+  requireVec33(b, "b");
   requireFiniteNumber(t, "t");
   return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
 }
 function direction(a, b) {
-  requireVec32(a, "a");
-  requireVec32(b, "b");
+  requireVec33(a, "a");
+  requireVec33(b, "b");
   const dx = b[0] - a[0];
   const dy = b[1] - a[1];
   const dz = b[2] - a[2];
@@ -49945,8 +50723,8 @@ function direction(a, b) {
   return [dx / len2, dy / len2, dz / len2];
 }
 function offset(point2, dir, amount) {
-  requireVec32(point2, "point");
-  requireVec32(dir, "dir");
+  requireVec33(point2, "point");
+  requireVec33(dir, "dir");
   requireFiniteNumber(amount, "amount");
   return [point2[0] + dir[0] * amount, point2[1] + dir[1] * amount, point2[2] + dir[2] * amount];
 }
@@ -50055,14 +50833,14 @@ var WoodBoard = class _WoodBoard {
 };
 
 // src/forge/wood/joints.ts
-function requireFinite4(value, name) {
+function requireFinite5(value, name) {
   if (!Number.isFinite(value)) {
     throw new Error(`${name} must be a finite number, got ${value}`);
   }
   return value;
 }
 function requirePositive3(value, name) {
-  requireFinite4(value, name);
+  requireFinite5(value, name);
   if (value <= 0) {
     throw new Error(`${name} must be positive, got ${value}`);
   }
@@ -50097,10 +50875,10 @@ function dado(host, guest, opts) {
   }
   let fromBottom;
   if (opts.fromBottom != null) {
-    fromBottom = requireFinite4(opts.fromBottom, "fromBottom");
+    fromBottom = requireFinite5(opts.fromBottom, "fromBottom");
   } else {
     fromBottom = host.height - opts.fromTop - channelWidth;
-    requireFinite4(fromBottom, "computed fromBottom");
+    requireFinite5(fromBottom, "computed fromBottom");
   }
   let dadoLength = host.width;
   let xOffset = 0;
@@ -50157,7 +50935,7 @@ function mortiseAndTenon(mortiseBoard, tenonBoard, opts) {
   const style = o.style ?? "blind";
   const fit = o.fit ?? "snug";
   const clearance = clearanceForFit(fit);
-  const cornerRadius = o.cornerRadius != null ? requireFinite4(o.cornerRadius, "cornerRadius") : 0;
+  const cornerRadius = o.cornerRadius != null ? requireFinite5(o.cornerRadius, "cornerRadius") : 0;
   const tenonThickness = o.tenonThickness != null ? requirePositive3(o.tenonThickness, "tenonThickness") : tenonBoard.thickness / 3;
   const tenonWidth = o.tenonWidth != null ? requirePositive3(o.tenonWidth, "tenonWidth") : Math.min(tenonBoard.height * 0.6, mortiseBoard.height * 0.8);
   const tenonLength = o.tenonLength != null ? requirePositive3(o.tenonLength, "tenonLength") : style === "through" ? mortiseBoard.thickness : mortiseBoard.thickness * 2 / 3;
@@ -50170,10 +50948,10 @@ function mortiseAndTenon(mortiseBoard, tenonBoard, opts) {
       throw new Error("mortiseAndTenon: specify position.fromTop or position.fromBottom, not both");
     }
     if (o.position.fromTop != null) {
-      requireFinite4(o.position.fromTop, "position.fromTop");
+      requireFinite5(o.position.fromTop, "position.fromTop");
       mortiseCenterY = mortiseBoard.height / 2 - o.position.fromTop - mortiseH / 2;
     } else if (o.position.fromBottom != null) {
-      requireFinite4(o.position.fromBottom, "position.fromBottom");
+      requireFinite5(o.position.fromBottom, "position.fromBottom");
       mortiseCenterY = -mortiseBoard.height / 2 + o.position.fromBottom + mortiseH / 2;
     }
   }
@@ -50249,12 +51027,12 @@ var Wood = {
 };
 
 // src/forge/cameraTrajectory.ts
-var _collected7 = null;
+var _collected8 = null;
 function resetCameraTrajectory() {
-  _collected7 = null;
+  _collected8 = null;
 }
 function getCollectedCameraTrajectory() {
-  return _collected7;
+  return _collected8;
 }
 function isOrbitKeyframe(kf) {
   return "orbit" in kf;
@@ -50262,19 +51040,19 @@ function isOrbitKeyframe(kf) {
 function isCartesianKeyframe(kf) {
   return "position" in kf;
 }
-function requireFinite5(value, label) {
+function requireFinite6(value, label) {
   if (!Number.isFinite(value)) {
     throw new Error(`cameraTrajectory(): ${label} must be a finite number, got ${value}`);
   }
 }
 function validateOrbitKeyframe(kf, index) {
-  requireFinite5(kf.at, `keyframes[${index}].at`);
-  requireFinite5(kf.orbit.angle, `keyframes[${index}].orbit.angle`);
-  requireFinite5(kf.orbit.pitch, `keyframes[${index}].orbit.pitch`);
-  requireFinite5(kf.orbit.distance, `keyframes[${index}].orbit.distance`);
+  requireFinite6(kf.at, `keyframes[${index}].at`);
+  requireFinite6(kf.orbit.angle, `keyframes[${index}].orbit.angle`);
+  requireFinite6(kf.orbit.pitch, `keyframes[${index}].orbit.pitch`);
+  requireFinite6(kf.orbit.distance, `keyframes[${index}].orbit.distance`);
 }
 function validateCartesianKeyframe(kf, index) {
-  requireFinite5(kf.at, `keyframes[${index}].at`);
+  requireFinite6(kf.at, `keyframes[${index}].at`);
   if (!Array.isArray(kf.position) || kf.position.length !== 3) {
     throw new Error(`cameraTrajectory(): keyframes[${index}].position must be a 3-element array`);
   }
@@ -50282,8 +51060,8 @@ function validateCartesianKeyframe(kf, index) {
     throw new Error(`cameraTrajectory(): keyframes[${index}].target must be a 3-element array`);
   }
   for (let i = 0; i < 3; i++) {
-    requireFinite5(kf.position[i], `keyframes[${index}].position[${i}]`);
-    requireFinite5(kf.target[i], `keyframes[${index}].target[${i}]`);
+    requireFinite6(kf.position[i], `keyframes[${index}].position[${i}]`);
+    requireFinite6(kf.target[i], `keyframes[${index}].target[${i}]`);
   }
 }
 function validateKeyframeOrder(keyframes) {
@@ -50303,11 +51081,11 @@ function validateKeyframeOrder(keyframes) {
   }
 }
 function cameraTrajectory(defOrFn, options) {
-  if (_collected7 !== null) {
+  if (_collected8 !== null) {
     console.warn("cameraTrajectory() called more than once \u2014 overwriting previous trajectory.");
   }
   if (typeof defOrFn === "function") {
-    _collected7 = {
+    _collected8 = {
       kind: "parametric",
       parametricFn: defOrFn,
       duration: options?.duration,
@@ -50326,13 +51104,13 @@ function cameraTrajectory(defOrFn, options) {
     for (let i = 0; i < orbitKeyframes.length; i++) {
       validateOrbitKeyframe(orbitKeyframes[i], i);
     }
-    _collected7 = { kind: "orbit-keyframes", orbitKeyframes, duration, fps, easing };
+    _collected8 = { kind: "orbit-keyframes", orbitKeyframes, duration, fps, easing };
   } else if (isCartesianKeyframe(first)) {
     const cartesianKeyframes = keyframes;
     for (let i = 0; i < cartesianKeyframes.length; i++) {
       validateCartesianKeyframe(cartesianKeyframes[i], i);
     }
-    _collected7 = { kind: "cartesian-keyframes", cartesianKeyframes, duration, fps, easing };
+    _collected8 = { kind: "cartesian-keyframes", cartesianKeyframes, duration, fps, easing };
   } else {
     throw new Error('cameraTrajectory(): each keyframe must have either an "orbit" or "position" property');
   }
@@ -50360,6 +51138,76 @@ function isEdgeSegment(value) {
 function isEdgeReferenceLike(value) {
   return typeof value === "object" && value !== null && "edges" in value && typeof value.edges === "function";
 }
+var BROAD_EDGE_FEATURE_DEFAULT_BUDGET = {
+  live: 0,
+  default: 12,
+  high: Number.POSITIVE_INFINITY
+};
+var broadEdgeFeatureBudget = null;
+function readBroadEdgeFeatureEnv(name) {
+  return typeof process !== "undefined" ? process.env?.[name] : void 0;
+}
+function resolveBroadEdgeFeatureBudget() {
+  if (readBroadEdgeFeatureEnv("FORGECAD_ALLOW_BROAD_EDGE_FEATURES") === "1") return Number.POSITIVE_INFINITY;
+  const override = readBroadEdgeFeatureEnv("FORGECAD_BROAD_EDGE_FEATURE_BUDGET");
+  if (override != null && override.trim() !== "") {
+    const parsed = Number(override);
+    if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  }
+  return BROAD_EDGE_FEATURE_DEFAULT_BUDGET[getForgeQualityPreset()];
+}
+function resetBroadEdgeFeatureBudget() {
+  broadEdgeFeatureBudget = null;
+}
+function remainingBroadEdgeFeatureBudget() {
+  if (broadEdgeFeatureBudget === null) broadEdgeFeatureBudget = resolveBroadEdgeFeatureBudget();
+  return broadEdgeFeatureBudget;
+}
+function consumeBroadEdgeFeatureBudget(edgeCount) {
+  const remaining = remainingBroadEdgeFeatureBudget();
+  if (!Number.isFinite(remaining)) return true;
+  if (edgeCount > remaining) return false;
+  broadEdgeFeatureBudget = Math.max(0, remaining - edgeCount);
+  return true;
+}
+function shouldSkipBroadEdgeFeature(operation, edgeCount) {
+  if (consumeBroadEdgeFeatureBudget(edgeCount)) return false;
+  const remaining = Math.max(0, remainingBroadEdgeFeatureBudget());
+  emitRuntimeWarning(
+    `${operation}() without an edge selector matched ${edgeCount} edge(s), exceeding the remaining broad edge-feature budget (${remaining}). Skipped this cosmetic edge finish for responsiveness. Pass an explicit edge selector, use high quality/export, or set FORGECAD_BROAD_EDGE_FEATURE_BUDGET to opt into more broad edge finishing.`
+  );
+  return true;
+}
+function shouldSkipExhaustedBroadEdgeFeature(operation) {
+  const remaining = remainingBroadEdgeFeatureBudget();
+  if (!Number.isFinite(remaining) || remaining > 0) return false;
+  emitRuntimeWarning(
+    `${operation}() without an edge selector was skipped because the broad edge-feature budget is exhausted. Skipped this cosmetic edge finish for responsiveness. Pass an explicit edge selector, use high quality/export, or set FORGECAD_BROAD_EDGE_FEATURE_BUDGET to opt into more broad edge finishing.`
+  );
+  return true;
+}
+function estimateSelectorlessEdgeCount(plan) {
+  if (!plan) return null;
+  switch (plan.kind) {
+    case "box":
+      return 12;
+    case "queryOwner":
+    case "transform":
+      return estimateSelectorlessEdgeCount(plan.base);
+    default:
+      return null;
+  }
+}
+function shouldSkipUnestimatedBroadEdgeFeature(operation, target) {
+  const remaining = remainingBroadEdgeFeatureBudget();
+  if (!Number.isFinite(remaining)) return false;
+  const estimatedEdges = estimateSelectorlessEdgeCount(getShapeCompilePlan(target));
+  if (estimatedEdges !== null && estimatedEdges <= remaining) return false;
+  emitRuntimeWarning(
+    `${operation}() without an edge selector was skipped before broad edge enumeration because this shape is too complex for the remaining broad edge-feature budget (${Math.max(0, remaining)}). Skipped this cosmetic edge finish for responsiveness. Pass an explicit edge selector, use high quality/export, or set FORGECAD_BROAD_EDGE_FEATURE_BUDGET to opt into more broad edge finishing.`
+  );
+  return true;
+}
 function edgesToTargets(edges) {
   return edges.map((e) => ({
     midpoint: [e.midpoint[0], e.midpoint[1], e.midpoint[2]],
@@ -50373,10 +51221,13 @@ function fillet(shape, radius, edges, segments = 16) {
     throw new Error("fillet() requires a positive finite radius.");
   }
   const target = shape;
+  if (edges === void 0 && shouldSkipExhaustedBroadEdgeFeature("fillet")) return target;
+  if (edges === void 0 && shouldSkipUnestimatedBroadEdgeFeature("fillet", target)) return target;
   const resolvedEdges = resolveEdges(target, edges);
   if (resolvedEdges.length === 0) {
     throw new Error("fillet(): no edges match the given selection.");
   }
+  if (edges === void 0 && shouldSkipBroadEdgeFeature("fillet", resolvedEdges.length)) return target;
   const basePlan = getShapeCompilePlan(target);
   const plan = {
     kind: "filletEdges",
@@ -50396,10 +51247,13 @@ function chamfer(shape, size, edges) {
     throw new Error("chamfer() requires a positive finite size.");
   }
   const target = shape;
+  if (edges === void 0 && shouldSkipExhaustedBroadEdgeFeature("chamfer")) return target;
+  if (edges === void 0 && shouldSkipUnestimatedBroadEdgeFeature("chamfer", target)) return target;
   const resolvedEdges = resolveEdges(target, edges);
   if (resolvedEdges.length === 0) {
     throw new Error("chamfer(): no edges match the given selection.");
   }
+  if (edges === void 0 && shouldSkipBroadEdgeFeature("chamfer", resolvedEdges.length)) return target;
   const basePlan = getShapeCompilePlan(target);
   const plan = {
     kind: "chamferEdges",
@@ -50455,10 +51309,10 @@ function offsetSolid(shape, thickness) {
 
 // src/forge/projectionCompile.ts
 var EPS8 = 1e-6;
-function dot6(a, b) {
+function dot7(a, b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
-function sub6(a, b) {
+function sub7(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 function length2d(x, y) {
@@ -50583,14 +51437,14 @@ function mapProfileToPlane(profile, sourcePlacement, targetPlane) {
   const sourceU = sourceTransform.vector([1, 0, 0]);
   const sourceV = sourceTransform.vector([0, 1, 0]);
   const sourceNormal = sourceTransform.vector([0, 0, 1]);
-  const normalAlignment = Math.abs(dot6(normalize8(sourceNormal), targetPlane.normal));
+  const normalAlignment = Math.abs(dot7(normalize8(sourceNormal), targetPlane.normal));
   if (!nearlyEqual(normalAlignment, 1, 1e-5)) {
     return { reason: "projection replay currently requires the target plane to stay parallel to the source workplane." };
   }
-  const a = dot6(sourceU, targetPlane.u);
-  const b = dot6(sourceV, targetPlane.u);
-  const c = dot6(sourceU, targetPlane.v);
-  const d = dot6(sourceV, targetPlane.v);
+  const a = dot7(sourceU, targetPlane.u);
+  const b = dot7(sourceV, targetPlane.u);
+  const c = dot7(sourceU, targetPlane.v);
+  const d = dot7(sourceV, targetPlane.v);
   const sx = length2d(a, c);
   const sy = length2d(b, d);
   if (sx < EPS8 || sy < EPS8) {
@@ -50624,9 +51478,9 @@ function mapProfileToPlane(profile, sourcePlacement, targetPlane) {
       next = appendProfileCompileTransform(next, { kind: "rotate", degrees: angle });
     }
   }
-  const delta = sub6(sourceOrigin, targetPlane.origin);
-  const tx = dot6(delta, targetPlane.u);
-  const ty = dot6(delta, targetPlane.v);
+  const delta = sub7(sourceOrigin, targetPlane.origin);
+  const tx = dot7(delta, targetPlane.u);
+  const ty = dot7(delta, targetPlane.v);
   if (!nearlyEqual(tx, 0) || !nearlyEqual(ty, 0)) {
     next = appendProfileCompileTransform(next, { kind: "translate", x: tx, y: ty });
   }
@@ -56547,8 +57401,8 @@ function normalizeVector2(v) {
 function angleDegBetween(a, b) {
   const na = normalizeVector2(a);
   const nb = normalizeVector2(b);
-  const dot8 = Math.max(-1, Math.min(1, na[0] * nb[0] + na[1] * nb[1] + na[2] * nb[2]));
-  return Math.acos(dot8) * 180 / Math.PI;
+  const dot9 = Math.max(-1, Math.min(1, na[0] * nb[0] + na[1] * nb[1] + na[2] * nb[2]));
+  return Math.acos(dot9) * 180 / Math.PI;
 }
 function edgeEndpoint(edge, endpoint) {
   const source = endpoint === "start" ? edge.start : edge.end;
@@ -57466,9 +58320,9 @@ function sampleQuadratic2(p0, p1, p2, tolerance) {
   return out;
 }
 function vectorAngle(ux, uy, vx, vy) {
-  const dot8 = ux * vx + uy * vy;
+  const dot9 = ux * vx + uy * vy;
   const det = ux * vy - uy * vx;
-  return Math.atan2(det, dot8);
+  return Math.atan2(det, dot9);
 }
 function sampleArc2(x1, y1, rxInput, ryInput, xAxisRotation, largeArcFlag, sweepFlag, x2, y2, tolerance, arcSegmentsMin) {
   let rx = Math.abs(rxInput);
@@ -58567,8 +59421,8 @@ function fromSlicesImpl(slices, options = {}) {
       group2 = { normal: canonicalNormal(s.normal), slices: [] };
       groupMap.set(key, group2);
     }
-    const dot8 = s.normal[0] * group2.normal[0] + s.normal[1] * group2.normal[1] + s.normal[2] * group2.normal[2];
-    const sign = dot8 < 0 ? -1 : 1;
+    const dot9 = s.normal[0] * group2.normal[0] + s.normal[1] * group2.normal[1] + s.normal[2] * group2.normal[2];
+    const sign = dot9 < 0 ? -1 : 1;
     group2.slices.push({ offset: s.offset * sign, profile: s.profile });
   }
   const groups = [...groupMap.values()];
@@ -58933,14 +59787,14 @@ function sheetStock(width, height, description, opts) {
 }
 
 // src/forge/laserKit/joints.ts
-function requireFinite6(value, name) {
+function requireFinite7(value, name) {
   if (!Number.isFinite(value)) {
     throw new Error(`${name} must be a finite number, got ${value}`);
   }
   return value;
 }
 function requirePositive4(value, name) {
-  requireFinite6(value, name);
+  requireFinite7(value, name);
   if (value <= 0) {
     throw new Error(`${name} must be positive, got ${value}`);
   }
@@ -58955,8 +59809,8 @@ function requireOdd(value, name) {
 function fingerJointProfile(length5, thickness, options = {}) {
   requirePositive4(length5, "length");
   requirePositive4(thickness, "thickness");
-  const clearance = requireFinite6(options.clearance ?? 0, "clearance");
-  const kerf = requireFinite6(options.kerf ?? 0, "kerf");
+  const clearance = requireFinite7(options.clearance ?? 0, "clearance");
+  const kerf = requireFinite7(options.kerf ?? 0, "kerf");
   const endStyle = options.endStyle ?? "full";
   let fingers;
   if (options.fingers != null) {
@@ -59019,11 +59873,11 @@ function fingerJointProfile(length5, thickness, options = {}) {
 function tabSlotProfile(length5, thickness, options = {}) {
   requirePositive4(length5, "length");
   requirePositive4(thickness, "thickness");
-  const clearance = requireFinite6(options.clearance ?? 0, "clearance");
-  const kerf = requireFinite6(options.kerf ?? 0, "kerf");
+  const clearance = requireFinite7(options.clearance ?? 0, "clearance");
+  const kerf = requireFinite7(options.kerf ?? 0, "kerf");
   const inset = requirePositive4(options.inset ?? thickness, "inset");
   const tabWidth = requirePositive4(options.tabWidth ?? 2 * thickness, "tabWidth");
-  const tabCount = options.tabCount != null ? (requireFinite6(options.tabCount, "tabCount"), Math.max(1, Math.round(options.tabCount))) : Math.max(1, Math.round(length5 / (4 * thickness)));
+  const tabCount = options.tabCount != null ? (requireFinite7(options.tabCount, "tabCount"), Math.max(1, Math.round(options.tabCount))) : Math.max(1, Math.round(length5 / (4 * thickness)));
   const halfKerf = kerf / 2;
   const usableLength = length5 - 2 * inset;
   const spacing = tabCount > 1 ? usableLength / (tabCount - 1) : 0;
@@ -59112,14 +59966,14 @@ function lookupKerf(material, thickness, laserType) {
 }
 
 // src/forge/laserKit/flatPart.ts
-function requireFinite7(value, name) {
+function requireFinite8(value, name) {
   if (!Number.isFinite(value)) {
     throw new Error(`${name} must be a finite number, got ${value}`);
   }
   return value;
 }
 function requirePositive5(value, name) {
-  requireFinite7(value, name);
+  requireFinite8(value, name);
   if (value <= 0) {
     throw new Error(`${name} must be positive, got ${value}`);
   }
@@ -59219,9 +60073,9 @@ function positionAlongEdge(profile, edge, inward = false) {
   const angle = Math.atan2(-nx, ny) * (180 / Math.PI);
   const edx = (edge.end[0] - edge.start[0]) / edge.length;
   const edy = (edge.end[1] - edge.start[1]) / edge.length;
-  const dot8 = ny * edx + -nx * edy;
+  const dot9 = ny * edx + -nx * edy;
   const rotated = profile.rotateAround(angle, [0, 0]);
-  if (dot8 > 0) {
+  if (dot9 > 0) {
     return rotated.translate(edge.start[0], edge.start[1]);
   } else {
     return rotated.translate(edge.end[0], edge.end[1]);
@@ -60363,12 +61217,12 @@ function rotatePoint(p2, axis, angleDeg2, pivot) {
   const s = Math.sin(rad);
   const k = v3normalize(axis);
   const v = v3sub(p2, pivot);
-  const dot8 = v3dot(k, v);
+  const dot9 = v3dot(k, v);
   const cross7 = v3cross(k, v);
   const result = [
-    v[0] * c + cross7[0] * s + k[0] * dot8 * (1 - c),
-    v[1] * c + cross7[1] * s + k[1] * dot8 * (1 - c),
-    v[2] * c + cross7[2] * s + k[2] * dot8 * (1 - c)
+    v[0] * c + cross7[0] * s + k[0] * dot9 * (1 - c),
+    v[1] * c + cross7[1] * s + k[1] * dot9 * (1 - c),
+    v[2] * c + cross7[2] * s + k[2] * dot9 * (1 - c)
   ];
   return v3add(result, pivot);
 }
@@ -60943,14 +61797,14 @@ function spec(name, checkFn) {
   return {
     name,
     check(...args) {
-      const before = _collected8.length;
+      const before = _collected9.length;
       _activeGroup = name;
       try {
         checkFn(...args);
       } finally {
         _activeGroup = null;
       }
-      const added = _collected8.slice(before);
+      const added = _collected9.slice(before);
       return {
         name,
         passed: added.filter((r) => r.status === "pass").length,
@@ -60960,15 +61814,15 @@ function spec(name, checkFn) {
     }
   };
 }
-var _collected8 = [];
+var _collected9 = [];
 var _counter2 = 0;
 var _activeGroup = null;
 function resetVerifications() {
-  _collected8 = [];
+  _collected9 = [];
   _counter2 = 0;
 }
 function getCollectedVerifications() {
-  return _collected8.slice();
+  return _collected9.slice();
 }
 function nextId() {
   _counter2 += 1;
@@ -60993,7 +61847,7 @@ function captureSourceLine() {
 }
 function push(result) {
   if (_activeGroup) result.group = _activeGroup;
-  _collected8.push(result);
+  _collected9.push(result);
 }
 function roundNum(n, digits = 4) {
   return Number.isFinite(n) ? n.toFixed(digits).replace(/\.?0+$/, "") : String(n);
@@ -61196,14 +62050,14 @@ var verify = {
     try {
       const na = faceA.normal;
       const nb = faceB.normal;
-      const dot8 = vec3Dot3(na, nb);
+      const dot9 = vec3Dot3(na, nb);
       const lenA = vec3Len3(na);
       const lenB = vec3Len3(nb);
       if (lenA < 1e-9 || lenB < 1e-9) {
         push({ id: nextId(), label, status: "fail", message: "One or both faces have zero-length normals", line: line2 });
         return;
       }
-      const cosAngle = Math.abs(dot8) / (lenA * lenB);
+      const cosAngle = Math.abs(dot9) / (lenA * lenB);
       const angleDeg2 = Math.acos(Math.min(1, cosAngle)) * 180 / Math.PI;
       const passed = angleDeg2 <= toleranceDeg;
       push({
@@ -61227,14 +62081,14 @@ var verify = {
     try {
       const na = faceA.normal;
       const nb = faceB.normal;
-      const dot8 = vec3Dot3(na, nb);
+      const dot9 = vec3Dot3(na, nb);
       const lenA = vec3Len3(na);
       const lenB = vec3Len3(nb);
       if (lenA < 1e-9 || lenB < 1e-9) {
         push({ id: nextId(), label, status: "fail", message: "One or both faces have zero-length normals", line: line2 });
         return;
       }
-      const cosAngle = Math.abs(dot8) / (lenA * lenB);
+      const cosAngle = Math.abs(dot9) / (lenA * lenB);
       const angleDeg2 = 90 - Math.acos(Math.min(1, cosAngle)) * 180 / Math.PI;
       const passed = Math.abs(angleDeg2) <= toleranceDeg;
       push({
@@ -61328,18 +62182,18 @@ var verify = {
     try {
       const na = faceA.normal;
       const nb = faceB.normal;
-      const dot8 = vec3Dot3(na, nb);
+      const dot9 = vec3Dot3(na, nb);
       const lenA = vec3Len3(na);
       const lenB = vec3Len3(nb);
       if (lenA < 1e-9 || lenB < 1e-9) {
         push({ id: nextId(), label, status: "fail", message: "One or both faces have zero-length normals", line: line2 });
         return;
       }
-      if (dot8 <= 0) {
+      if (dot9 <= 0) {
         push({ id: nextId(), label, status: "fail", message: "Face normals point in opposite directions", line: line2 });
         return;
       }
-      const cosAngle = dot8 / (lenA * lenB);
+      const cosAngle = dot9 / (lenA * lenB);
       const angleDeg2 = Math.acos(Math.min(1, cosAngle)) * 180 / Math.PI;
       const passed = angleDeg2 <= toleranceDeg;
       push({
@@ -61556,6 +62410,7 @@ var verify = {
 // src/forge/script-runtime/executionSession.ts
 function resetExecutionSession(logs) {
   resetCollectedAssemblies();
+  resetBroadEdgeFeatureBudget();
   resetParams();
   resetShapeQueryOwnerIds();
   resetDimensions();
@@ -61564,6 +62419,7 @@ function resetExecutionSession(logs) {
   resetSheetStock();
   resetRobotExport();
   resetCutPlanes();
+  resetRenderLabels();
   resetCameraTrajectory();
   resetExplodeView();
   resetJointsView();
@@ -61627,6 +62483,7 @@ function collectSuccessfulExecutionSnapshot(args) {
     bom: getCollectedBom(),
     sheetStock: getCollectedSheetStock(),
     cutPlanes: getCollectedCutPlanes(),
+    renderLabels: getCollectedRenderLabels(),
     cameraTrajectory: getCollectedCameraTrajectory(),
     explodeView: getCollectedExplodeView(),
     jointsView: getCollectedJointsView(),
@@ -61650,6 +62507,7 @@ function collectFailedExecutionSnapshot(args) {
     bom: getCollectedBom(),
     sheetStock: getCollectedSheetStock(),
     cutPlanes: getCollectedCutPlanes(),
+    renderLabels: getCollectedRenderLabels(),
     cameraTrajectory: getCollectedCameraTrajectory(),
     explodeView: getCollectedExplodeView(),
     jointsView: getCollectedJointsView(),
@@ -61796,13 +62654,15 @@ function formatLogArg(value) {
     return `[Log serialization failed: ${formatLogError(error)}]`;
   }
 }
-function makeSandboxConsole(collectedLogs) {
+function makeSandboxConsole(collectedLogs, mirror) {
   const capture = (level) => (...args) => {
+    const formattedArgs = args.map(formatLogArg);
     collectedLogs.push({
       level,
-      args: args.map(formatLogArg),
+      args: formattedArgs,
       timestamp: Date.now()
     });
+    mirror?.(level, formattedArgs);
   };
   return { log: capture("log"), warn: capture("warn"), error: capture("error"), info: capture("info") };
 }
@@ -61966,6 +62826,18 @@ function buildFileIndex(allFiles) {
   }
   return fileIndex;
 }
+function hasPathExtension(path4) {
+  const fileName = path4.split("/").pop() ?? path4;
+  return /\.[^/.]+$/.test(fileName);
+}
+function explicitExtensionHint(requestedName, resolvedPath, fileIndex) {
+  if (!resolvedPath || hasPathExtension(resolvedPath)) return "";
+  const requestedBase = requestedName.trim();
+  const suggestions = [".forge.js", ".js"].map((ext) => ({ ext, resolved: `${resolvedPath}${ext}` })).filter(({ resolved }) => fileIndex.has(resolved)).map(({ ext }) => `"${requestedBase}${ext}"`);
+  if (suggestions.length === 0) return "";
+  const joined = suggestions.length === 1 ? suggestions[0] : suggestions.join(" or ");
+  return ` Did you mean ${joined}? ForgeCAD requires explicit file extensions in project imports.`;
+}
 function resolveImportSource(fromFile, requestedName, allFiles, options) {
   if (typeof requestedName !== "string" || requestedName.trim().length === 0) {
     throw new Error("Import path must be a non-empty string");
@@ -61974,7 +62846,8 @@ function resolveImportSource(fromFile, requestedName, allFiles, options) {
   const lookupKey = options.fileIndex.get(resolvedPath);
   if (!lookupKey) {
     const suffix = resolvedPath && resolvedPath !== requestedName ? ` (resolved to "${resolvedPath}" from "${fromFile}")` : ` (from "${fromFile}")`;
-    throw new Error(`File not found: "${requestedName}"${suffix}`);
+    const hint = explicitExtensionHint(requestedName, resolvedPath, options.fileIndex);
+    throw new Error(`File not found: "${requestedName}"${suffix}.${hint}`);
   }
   const source = allFiles[lookupKey];
   if (typeof source !== "string") {
@@ -62227,6 +63100,36 @@ function extractUnusedTopLevelVarNames(code) {
   }
   return declaredNames.filter((n) => topLevelNames.has(n) && (!usedByOthers.has(n) || explicitImplicitResultNames.has(n)));
 }
+function collectBindingNameLocations(node, sourceFile, names) {
+  if (ts.isIdentifier(node)) {
+    const { line: line2, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    names.push({ name: node.text, line: line2 + 1, column: character + 1 });
+    return;
+  }
+  for (const element of node.elements) {
+    if (ts.isBindingElement(element)) {
+      collectBindingNameLocations(element.name, sourceFile, names);
+    }
+  }
+}
+function findTopLevelRuntimeGlobalCollision(code, runtimeGlobalNames) {
+  const runtimeGlobals = new Set(runtimeGlobalNames);
+  const sourceFile = ts.createSourceFile("__runtime-globals.js", code, ts.ScriptTarget.ES2020, false, ts.ScriptKind.JS);
+  const declarations = [];
+  for (const statement of sourceFile.statements) {
+    if (ts.isVariableStatement(statement)) {
+      const isLexical = (statement.declarationList.flags & (ts.NodeFlags.Let | ts.NodeFlags.Const)) !== 0;
+      if (!isLexical) continue;
+      for (const decl of statement.declarationList.declarations) {
+        collectBindingNameLocations(decl.name, sourceFile, declarations);
+      }
+    } else if (ts.isClassDeclaration(statement) && statement.name) {
+      const { line: line2, character } = sourceFile.getLineAndCharacterOfPosition(statement.name.getStart(sourceFile));
+      declarations.push({ name: statement.name.text, line: line2 + 1, column: character + 1 });
+    }
+  }
+  return declarations.find((declaration) => runtimeGlobals.has(declaration.name)) ?? null;
+}
 function createForgeRuntimeModule(bindings) {
   const runtime = { ...bindings };
   Object.defineProperty(runtime, "__esModule", { value: true });
@@ -62768,6 +63671,11 @@ function withConstructorChainLockdown(fn) {
   }
 }
 function executeFile(code, fileName, allFiles, visited, scope = {}, options, executionMode = "script", moduleCacheEntry) {
+  options.debug?.("executeFile:start", {
+    fileName,
+    executionMode,
+    scope: scope.namePrefix ?? fileName
+  });
   const trackCircularImports = executionMode === "script";
   if (trackCircularImports) {
     if (visited.has(fileName)) {
@@ -62879,7 +63787,34 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       setShapeTopology(shape, topo);
       return shape;
     };
-    const sandboxConsole = makeSandboxConsole(_collectedLogs);
+    const sandboxConsole = makeSandboxConsole(_collectedLogs, options.debug ? (level, args) => options.debug?.("console", { level, args }) : void 0);
+    const runtimeVerify = options.debug ? {
+      ...verify,
+      that(label, check, message) {
+        options.debug?.("verify:that:start", { label });
+        const verifyStart = performance.now();
+        try {
+          return verify.that(label, check, message);
+        } finally {
+          options.debug?.("verify:that:end", {
+            label,
+            ms: Number((performance.now() - verifyStart).toFixed(1))
+          });
+        }
+      },
+      equal(label, actual, expected, tolerance = 0, message) {
+        options.debug?.("verify:equal:start", { label, actual, expected, tolerance });
+        const verifyStart = performance.now();
+        try {
+          return verify.equal(label, actual, expected, tolerance, message);
+        } finally {
+          options.debug?.("verify:equal:end", {
+            label,
+            ms: Number((performance.now() - verifyStart).toFixed(1))
+          });
+        }
+      }
+    } : verify;
     setShowLabelsHighlight(highlight);
     const runtimeBindings = {
       box: trackedBox,
@@ -63020,7 +63955,8 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       jointsView,
       viewConfig,
       scene,
-      verify,
+      Viewport,
+      verify: runtimeVerify,
       spec,
       mock,
       gcode,
@@ -63158,8 +64094,21 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
         throw error;
       }
     };
-    const compiled = compileScript(code, fileName, options);
     const bindingNames = Object.keys(runtimeBindings);
+    const collision = findTopLevelRuntimeGlobalCollision(code, bindingNames);
+    if (collision) {
+      throw new Error(
+        `Local declaration "${collision.name}" at ${fileName}:${collision.line}:${collision.column} collides with the built-in ForgeCAD runtime name "${collision.name}". Use the ForgeCAD API directly, or rename your local variable/import (for example, import the helper module object instead of destructuring "${collision.name}").`
+      );
+    }
+    options.debug?.("executeFile:compile:start", { fileName, executionMode });
+    const compileStart = performance.now();
+    const compiled = compileScript(code, fileName, options);
+    options.debug?.("executeFile:compile:end", {
+      fileName,
+      executionMode,
+      ms: Number((performance.now() - compileStart).toFixed(1))
+    });
     const bindingValues = bindingNames.map((name) => runtimeBindings[name]);
     let scriptCode = compiled.code;
     if (executionMode === "script") {
@@ -63185,12 +64134,20 @@ ${scriptCode}
       exports: executionMode === "module" && moduleCacheEntry ? moduleCacheEntry.exports : {}
     };
     const initialExportsRef = moduleValue.exports;
+    options.debug?.("executeFile:invoke:start", { fileName, executionMode });
+    const invokeStart = performance.now();
     const returnValue = withConstructorChainLockdown(
       () => runWithParamScope(
         scope,
         () => fn(moduleValue.exports, moduleValue, requireModule, fileName, dirnamePath(fileName), ...bindingValues)
       )
     );
+    options.debug?.("executeFile:invoke:end", {
+      fileName,
+      executionMode,
+      ms: Number((performance.now() - invokeStart).toFixed(1)),
+      returned: returnValue === void 0 ? "undefined" : returnValue === null ? "null" : typeof returnValue
+    });
     if (executionMode === "module") {
       const hasExports = hasExplicitModuleExports(moduleValue.exports, initialExportsRef);
       if (returnValue !== void 0 && hasExports) {
@@ -63229,6 +64186,7 @@ ${scriptCode}
     }
     return returnValue;
   } finally {
+    options.debug?.("executeFile:end", { fileName, executionMode });
     if (trackCircularImports) {
       visited.delete(fileName);
     }
@@ -63243,14 +64201,24 @@ function runScript(code, fileName = "main.forge.js", allFiles = {}, options = {}
     fileIndex: buildFileIndex(allFiles),
     compiledFiles: persistentCompiledFiles,
     moduleCache: /* @__PURE__ */ new Map(),
-    readBinaryFile: options.readBinaryFile
+    readBinaryFile: options.readBinaryFile,
+    debug: options.debug
   };
   const quality = resolveForgeQualityPreset(options.quality);
+  options.debug?.("runScript:start", { fileName, quality, fileCount: Object.keys(allFiles).length });
   try {
     return runWithForgeQuality(quality, () => {
+      options.debug?.("runScript:execute:start", { fileName });
+      const executeStart = performance.now();
       const result = executeFile(code, fileName, allFiles, /* @__PURE__ */ new Set(), {}, execOptions);
+      options.debug?.("runScript:execute:end", {
+        fileName,
+        ms: Number((performance.now() - executeStart).toFixed(1)),
+        resultType: result === void 0 ? "undefined" : result === null ? "null" : typeof result
+      });
       const highlights = getCollectedHighlights();
       const mocks = getCollectedMocks();
+      options.debug?.("runScript:map:start", { highlights: highlights.length, mocks: mocks.length });
       const mapped = mapScriptResultToScene({
         result,
         fileName,
@@ -63259,24 +64227,43 @@ function runScript(code, fileName = "main.forge.js", allFiles = {}, options = {}
         mocks,
         logs: _collectedLogs
       });
+      options.debug?.("runScript:map:end", {
+        objects: mapped.objects.length,
+        hasShape: Boolean(mapped.shape),
+        hasSketch: Boolean(mapped.sketch),
+        hasError: Boolean(mapped.error)
+      });
+      options.debug?.("runScript:explodeHints:start", { objects: mapped.objects.length });
       autoFillExplodeHints(mapped.objects);
+      options.debug?.("runScript:explodeHints:end");
+      options.debug?.("runScript:snapshot:start", { objects: mapped.objects.length });
+      const snapshot = collectSuccessfulExecutionSnapshot({
+        quality,
+        objects: mapped.objects,
+        logs: _collectedLogs,
+        extraDimensions: mapped.extraDimensions,
+        highlights,
+        mocks
+      });
+      options.debug?.("runScript:snapshot:end", {
+        params: snapshot.params.length,
+        cutPlanes: snapshot.cutPlanes.length,
+        verifications: snapshot.verifications.length
+      });
+      options.debug?.("runScript:sceneTargets:start");
+      snapshot.sceneConfig = resolveSceneJourneyTargets(snapshot.sceneConfig, mapped.objects);
+      options.debug?.("runScript:sceneTargets:end");
       return {
         shape: mapped.shape,
         sketch: mapped.sketch,
         objects: mapped.objects,
-        ...collectSuccessfulExecutionSnapshot({
-          quality,
-          objects: mapped.objects,
-          logs: _collectedLogs,
-          extraDimensions: mapped.extraDimensions,
-          highlights,
-          mocks
-        }),
+        ...snapshot,
         error: mapped.error,
         timeMs: performance.now() - t0
       };
     });
   } catch (e) {
+    options.debug?.("runScript:error", { error: e?.message || String(e) });
     const msg = e.message || String(e);
     const stack = e.stack || "";
     let lineInfo = "";
@@ -69319,6 +70306,7 @@ Options:
                                     With distance: azimuth:elevation:distance (e.g. 45:30:200)
                                     Full spec: proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45
                                   Default: iso
+  --view <name>                   Use a named camera view declared with scene({ views })
   --scene <json>                  Scene state JSON copied from the viewport
   --size <px>                     Image size in pixels (default: ${DEFAULT_SIZE})
   --focus [names]                  Focus: no arg hides mocks; comma-separated names shows only those
@@ -69343,6 +70331,7 @@ Examples:
   forgecad render model.forge.js --camera 45:30           # 45\xB0 azimuth, 30\xB0 elevation
   forgecad render model.forge.js --camera 45:30:200       # same, at 200mm distance
   forgecad render model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
+  forgecad render model.forge.js --view hero              # camera from scene({ views: { hero: ... } })
   forgecad render model.forge.js --camera front --camera side  # two views`;
 }
 function readValue(argv, idx, flag) {
@@ -69359,6 +70348,15 @@ function parseRenderStyle(value) {
   if (RENDER_STYLES.has(value)) return value;
   throw new Error(`--render-style must be 'classic', 'studio', 'fast', or 'glass' (got '${value}')`);
 }
+function sceneSpecHasCamera(sceneSpec) {
+  let parsed;
+  try {
+    parsed = JSON.parse(sceneSpec);
+  } catch (err2) {
+    throw new Error(`--scene must be valid JSON when used with --view: ${err2 instanceof Error ? err2.message : String(err2)}`);
+  }
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.prototype.hasOwnProperty.call(parsed, "camera");
+}
 function parseFocusArg(argv, idx) {
   const next = argv[idx + 1];
   if (!next || next.startsWith("--")) {
@@ -69394,6 +70392,7 @@ function parseRenderCliOptions(argv) {
   let port = DEFAULT_PORT;
   let chromePath = process.env.CHROME_PATH;
   let cameraSpec;
+  let viewName;
   let sceneSpec;
   let background;
   let focus = null;
@@ -69425,6 +70424,18 @@ function parseRenderCliOptions(argv) {
       i += 1;
       continue;
     }
+    if (arg === "--view") {
+      if (viewName) {
+        throw new Error("Pass --view only once.");
+      }
+      const val = readValue(argv, i, arg).trim();
+      if (!val) {
+        throw new Error("--view requires a non-empty view name.");
+      }
+      viewName = val;
+      i += 1;
+      continue;
+    }
     if (arg === "--angles") {
       const vals = readValue(argv, i, arg).split(",").map((s) => s.trim()).filter(Boolean);
       cameras.push(...vals);
@@ -69504,7 +70515,13 @@ function parseRenderCliOptions(argv) {
   if (!Number.isFinite(port) || port < 1 || port > 65535) {
     throw new Error(`--port must be between 1 and 65535 (got ${port})`);
   }
-  if (cameras.length === 0 && !cameraSpec && !sceneSpec) {
+  if (viewName && (cameras.length > 0 || cameraSpec)) {
+    throw new Error("Cannot use --view with --camera or --angles. Choose either a model-declared view or an explicit camera.");
+  }
+  if (viewName && sceneSpec && sceneSpecHasCamera(sceneSpec)) {
+    throw new Error("Cannot use --view with --scene JSON that includes camera. Remove the camera field from --scene or use --camera.");
+  }
+  if (cameras.length === 0 && !cameraSpec && !sceneSpec && !viewName) {
     cameras.push("iso");
   }
   if (focus && hide) {
@@ -69518,6 +70535,7 @@ function parseRenderCliOptions(argv) {
     port,
     chromePath: resolveChromePath(chromePath),
     cameraSpec,
+    viewName,
     sceneSpec,
     background,
     focus,
@@ -69668,7 +70686,9 @@ function parseInspectCli(argv) {
     throw new Error("Missing input .forge.js path");
   }
   if (!channels) {
-    throw new Error("Missing required --channels. Choose explicit channels, for example --channels rgb,mask or --channels rgb,mask,collisions.");
+    throw new Error(
+      "Missing required --channels. Choose explicit channels, for example --channels rgb,mask or --channels rgb,mask,collisions."
+    );
   }
   if (flagOutputDir && positionalOutputDir) {
     throw new Error("Pass either positional output-dir or --output, not both.");
@@ -70279,6 +71299,7 @@ async function runRenderCli(argv = process.argv.slice(2)) {
             allFiles: files,
             fileName: scriptName,
             cameraSpec: renderOptions.cameraSpec,
+            viewName: renderOptions.viewName,
             sceneSpec: renderOptions.sceneSpec,
             background: renderOptions.background,
             focus: renderOptions.focus,
@@ -70295,6 +71316,7 @@ async function runRenderCli(argv = process.argv.slice(2)) {
           cameras: options.cameras,
           size: options.size,
           cameraSpec: options.cameraSpec || null,
+          viewName: options.viewName || null,
           sceneSpec: options.sceneSpec || null,
           background: options.background || null,
           focus: options.focus || null,
@@ -74816,7 +75838,7 @@ function inBounds(p2, min2, max3, pad = 1e-4) {
 function clamp13(v, lo, hi) {
   return Math.max(lo, Math.min(hi, v));
 }
-function dot7(a, b) {
+function dot8(a, b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
 function cross6(a, b) {
@@ -74830,7 +75852,7 @@ function norm4(v) {
 function mul(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
-function sub7(a, b) {
+function sub8(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 function makeViewFrame2(view) {
@@ -74847,12 +75869,12 @@ function makeViewFrame2(view) {
   return { id: view, right, up, forward };
 }
 function isDimensionVisibleInView2(dim2, frame, toleranceDeg) {
-  const dir = sub7(dim2.to, dim2.from);
+  const dir = sub8(dim2.to, dim2.from);
   const len2 = Math.hypot(dir[0], dir[1], dir[2]);
   if (len2 < 1e-9) return false;
   const d = [dir[0] / len2, dir[1] / len2, dir[2] / len2];
-  const alignRight = clamp13(Math.abs(dot7(d, frame.right)), 0, 1);
-  const alignUp = clamp13(Math.abs(dot7(d, frame.up)), 0, 1);
+  const alignRight = clamp13(Math.abs(dot8(d, frame.right)), 0, 1);
+  const alignUp = clamp13(Math.abs(dot8(d, frame.up)), 0, 1);
   const angleRight = Math.acos(alignRight) * 180 / Math.PI;
   const angleUp = Math.acos(alignUp) * 180 / Math.PI;
   const minAngle = Math.min(angleRight, angleUp);
@@ -75367,6 +76389,9 @@ var DEFAULTS = {
   crf: parseIntEnv(["FORGE_CAPTURE_CRF"], 18),
   port: parseIntEnv(["FORGE_PORT"], 5173)
 };
+var PUPPETEER_PROTOCOL_TIMEOUT_MS2 = parseIntEnv(["FORGE_CAPTURE_PROTOCOL_TIMEOUT_MS"], 10 * 60 * 1e3);
+var CAPTURE_DEBUG = parseBooleanEnv(["FORGE_CAPTURE_DEBUG", "FORGE_CAPTURE_TRACE"], false);
+var CAPTURE_DEBUG_ALL_BROWSER = parseBooleanEnv(["FORGE_CAPTURE_DEBUG_ALL_BROWSER"], false);
 var repoRoot = packageRootFrom(import.meta.url);
 function parseIntEnv(names, fallback) {
   for (const name of names) {
@@ -75395,10 +76420,24 @@ function parseOptionalFloatEnv(names) {
   }
   return void 0;
 }
+function parseBooleanEnv(names, fallback) {
+  for (const name of names) {
+    const raw = process.env[name];
+    if (raw == null) continue;
+    const normalized = raw.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) return true;
+    if (["0", "false", "no", "off"].includes(normalized)) return false;
+  }
+  return fallback;
+}
 function parseQualityEnv(raw) {
   if (raw === "default" || raw === "live" || raw === "high") return raw;
   return null;
 }
+function debugLog(message) {
+  if (!CAPTURE_DEBUG) return;
+  console.log(`[forge-capture:debug] ${message}`);
+}
 function parseSweepPlaneEnv(raw) {
   if (!raw) return null;
   const normalized = raw.toUpperCase();
@@ -76355,7 +77394,8 @@ async function captureAndEncode(page, options, framePlan, encoderMode, ffmpegPat
           imageFormat: ffmpegInputMode === "jpeg" ? "jpeg" : "png",
           jpegQuality: 0.9,
           showEdges: process.env.FORGE_CAPTURE_SHOW_EDGES !== "0",
-          profile
+          profile,
+          debug: CAPTURE_DEBUG
         }
       );
       timings.browserFrameMs += Date.now() - browserStart;
@@ -76580,10 +77620,26 @@ async function runCaptureCli(config, argv = process.argv.slice(2)) {
     }
     browser = await puppeteer2.launch({
       headless: true,
+      protocolTimeout: PUPPETEER_PROTOCOL_TIMEOUT_MS2,
       executablePath: chromePath,
       args: chromeArgs
     });
     const page = await browser.newPage();
+    if (CAPTURE_DEBUG) {
+      page.on("console", (message) => {
+        const text = message.text();
+        if (text.includes("[forge-capture:debug]") || CAPTURE_DEBUG_ALL_BROWSER) {
+          console.log(text.includes("[forge-capture:debug]") ? text : `[browser:${message.type()}] ${text}`);
+        }
+      });
+      page.on("pageerror", (error) => {
+        console.log(`[forge-capture:debug] browser page error: ${error.message}`);
+      });
+      page.on("requestfailed", (request) => {
+        console.log(`[forge-capture:debug] browser request failed: ${request.url()} ${request.failure()?.errorText ?? ""}`.trim());
+      });
+    }
+    debugLog(`loading capture runtime on :${activePort}`);
     let captureRuntimeReady = await loadCaptureRuntime(page, activePort, options.capture);
     if (!captureRuntimeReady && !viteProc) {
       const fallbackPort = await findFreePort(activePort + 1);
@@ -76597,6 +77653,8 @@ async function runCaptureCli(config, argv = process.argv.slice(2)) {
     if (!captureRuntimeReady) {
       throw new Error("Capture runtime did not initialize. Restart the Forge dev server and try again.");
     }
+    debugLog(`capture runtime ready; starting browser init for ${basename4(input)}`);
+    const initStart = Date.now();
     const init2 = await page.evaluate(
       (payload) => {
         return window.__forgeCaptureInit(payload.code, payload.options);
@@ -76617,6 +77675,7 @@ async function runCaptureCli(config, argv = process.argv.slice(2)) {
           paramOverrides: options.paramOverrides,
           animationName: options.animationName ?? null,
           capture: options.capture,
+          debug: CAPTURE_DEBUG,
           sweep: options.capture === "section-sweep" ? {
             plane: options.sweepPlane,
             normal: options.sweepNormal ?? null,
@@ -76629,6 +77688,7 @@ async function runCaptureCli(config, argv = process.argv.slice(2)) {
         }
       }
     );
+    debugLog(`browser init returned in ${Date.now() - initStart}ms`);
     if (!init2?.ok) {
       throw new Error(init2?.error || "Script failed to initialize in renderer");
     }
@@ -82355,29 +83415,39 @@ import { homedir as homedir7 } from "os";
 import { join as join12 } from "path";
 var VALID_TIERS = /* @__PURE__ */ new Set(["free", "pro", "team"]);
 var PRO_COMMANDS = /* @__PURE__ */ new Set([
-  // Exact CAD interchange formats
-  "export step",
-  "export brep",
   // Advanced rendering
   "render hq",
   // Animations
   "capture gif",
-  "capture mp4",
-  // Manufacturing outputs
-  "cut-list",
-  "export gcode",
-  "export report",
-  "export cutting-layout",
-  // Robotics exports
-  "export sdf",
-  "export urdf",
-  // Sketch PDF export
-  "export sketch-pdf"
+  "capture mp4"
 ]);
 function requiredTierForCommand(commandPath) {
   const key = commandPath.join(" ");
   return PRO_COMMANDS.has(key) ? "pro" : "free";
 }
+var PRODUCTION_OUTPUT_COMMANDS = /* @__PURE__ */ new Map([
+  ["cut-list", "sheet cut list"],
+  ["export sketch-pdf", "dimensioned sketch PDF"],
+  ["export step", "STEP exact CAD exchange"],
+  ["export brep", "BREP exact geometry"],
+  ["export gcode", "G-code toolpath"],
+  ["export sdf", "SDF robotics package"],
+  ["export urdf", "URDF robotics package"],
+  ["export report", "model report PDF"],
+  ["export cutting-layout", "sheet cutting layout PDF"]
+]);
+function productionOutputNoticeForCommand(commandPath) {
+  const key = commandPath.join(" ");
+  const label = PRODUCTION_OUTPUT_COMMANDS.get(key);
+  if (!label) return null;
+  return {
+    label,
+    message: "Free to run. For client, employer, sale, funded product, or closed commercial IP work, ForgeCAD Pro covers commercial use and support."
+  };
+}
+function productionOutputBadgeForCommand(commandPath) {
+  return productionOutputNoticeForCommand(commandPath) ? "Production" : null;
+}
 function tierSatisfies(userTier, required) {
   if (required === "free") return true;
   return userTier === "pro" || userTier === "team";
@@ -82645,6 +83715,17 @@ function enforceFeatureGate(commandPath) {
   }
   process.exit(1);
 }
+function printProductionOutputNotice(commandPath) {
+  const notice = productionOutputNoticeForCommand(commandPath);
+  if (!notice) return;
+  const license = getCurrentLicense();
+  if (license.valid && tierSatisfies(license.tier, "pro")) return;
+  const commandName = `forgecad ${commandPath.join(" ")}`;
+  console.error(`\x1B[36mProduction output:\x1B[0m ${commandName} creates a ${notice.label}.`);
+  console.error(`  ${notice.message}`);
+  console.error("  Upgrade: https://forgecad.io/pricing");
+  console.error("");
+}
 
 // cli/forge-project.ts
 function slugify(name) {
@@ -85292,6 +86373,64 @@ async function writeSolverDebugIndex(root, scriptPath, bundles) {
 }
 
 // cli/test-run.ts
+var DEFAULT_EXACT_SPATIAL_OBJECT_LIMIT = 250;
+function parseSpatialMode(argv) {
+  const consumed = /* @__PURE__ */ new Set();
+  const idx = argv.indexOf("--spatial");
+  if (idx === -1) return { mode: "bounded", consumed };
+  consumed.add(idx);
+  const raw = argv[idx + 1];
+  if (!raw || raw.startsWith("-")) {
+    console.error("Missing value for --spatial. Expected bounded, exact, or off.");
+    process.exit(1);
+  }
+  consumed.add(idx + 1);
+  if (raw === "bounded" || raw === "exact" || raw === "off") return { mode: raw, consumed };
+  console.error(`Invalid --spatial value: ${raw}. Expected bounded, exact, or off.`);
+  process.exit(1);
+}
+function buildJourneyInspection(journeys) {
+  return {
+    journeys: Object.entries(journeys ?? {}).map(([id, journey]) => ({
+      id,
+      title: journey.title ?? id,
+      startsAt: journey.startsAt ?? journey.steps[0]?.id ?? null,
+      behavior: journey.behavior ?? "opt-in",
+      valid: journey.valid !== false,
+      diagnostics: journey.diagnostics ?? [],
+      steps: journey.steps.map((step) => ({
+        id: step.id,
+        title: step.title ?? step.id,
+        focus: step.focus ?? null,
+        resolvedFocusId: step.resolvedFocusId ?? null,
+        resolvedFocusPath: step.resolvedFocusPath ?? null,
+        caption: step.caption ?? null,
+        camera: step.camera ?? null,
+        diagnostics: step.diagnostics ?? []
+      }))
+    }))
+  };
+}
+function printJourneySummary(journeys) {
+  const inspected = buildJourneyInspection(journeys).journeys;
+  console.log(`\u2713 Journeys: ${inspected.length}`);
+  for (const journey of inspected) {
+    const status = journey.valid ? "ok" : "has errors";
+    console.log(`  ${journey.id}: ${journey.title} (${journey.steps.length} step${journey.steps.length === 1 ? "" : "s"}, ${status})`);
+    for (const diagnostic of journey.diagnostics) {
+      const icon = diagnostic.level === "error" ? "\u2717" : "!";
+      const stepTag = diagnostic.stepId ? `${diagnostic.stepId}: ` : "";
+      console.log(`    ${icon} ${stepTag}${diagnostic.message}`);
+      if (diagnostic.suggestions && diagnostic.suggestions.length > 0) {
+        console.log(`      suggestions: ${diagnostic.suggestions.join(", ")}`);
+      }
+    }
+    for (const [index, step] of journey.steps.entries()) {
+      const target = step.resolvedFocusPath ?? step.focus ?? (step.camera ? "camera" : "no target");
+      console.log(`    ${index + 1}. ${step.id} -> ${target}`);
+    }
+  }
+}
 function tallyFeatures(plan) {
   const counts = /* @__PURE__ */ new Map();
   function inc(key) {
@@ -85390,7 +86529,7 @@ function formatFeatureSummary(counts) {
 function bboxOverlap2(a, b) {
   return [0, 1, 2].every((k) => a.min[k] < b.max[k] + 0.1 && a.max[k] > b.min[k] - 0.1);
 }
-function analyzeSpatial(entries) {
+function analyzeSpatial(entries, mode) {
   const lines = [];
   const _axisLabel = ["X", "Y", "Z"];
   const dirLabels = {
@@ -85408,12 +86547,20 @@ function analyzeSpatial(entries) {
   }
   const sceneSize = Math.max(...allMax.map((v, i) => v - allMin[i]));
   const proximityThreshold = sceneSize * 0.15;
+  const exactCollisionChecksEnabled = mode === "exact" || entries.length <= DEFAULT_EXACT_SPATIAL_OBJECT_LIMIT;
+  let bboxOverlapPairs = 0;
+  let skippedExactCollisionPairs = 0;
   for (let i = 0; i < entries.length; i++) {
     for (let j = i + 1; j < entries.length; j++) {
       const a = entries[i], b = entries[j];
       if (a.groupName && a.groupName === b.groupName) continue;
       if (a.mock && b.mock) continue;
       if (!bboxOverlap2(a, b)) continue;
+      bboxOverlapPairs++;
+      if (!exactCollisionChecksEnabled) {
+        skippedExactCollisionPairs++;
+        continue;
+      }
       try {
         const hit = a.shape.intersect(b.shape);
         if (!hit.isEmpty()) {
@@ -85426,6 +86573,13 @@ function analyzeSpatial(entries) {
       }
     }
   }
+  if (skippedExactCollisionPairs > 0) {
+    lines.push(
+      `  Exact collision checks skipped for ${skippedExactCollisionPairs} bbox-overlapping pair(s) in this ${entries.length}-object scene. Re-run with --spatial exact for exhaustive pairwise intersections.`
+    );
+  } else if (bboxOverlapPairs > 0 && exactCollisionChecksEnabled) {
+    lines.push(`  Exact collision checks: ${bboxOverlapPairs} bbox-overlapping pair(s) tested.`);
+  }
   for (let i = 0; i < entries.length; i++) {
     const a = entries[i];
     const nearest = Array.from({ length: 6 }, () => ({ idx: -1, gap: Infinity }));
@@ -85538,7 +86692,7 @@ function parseParamFlags(argv) {
 }
 function usage15() {
   console.error(
-    "Usage: forgecad run <script.forge.js> [--connectivity] [--connectivity-tolerance <mm>] [--param Key=Value] [--debug-imports] [--verbose] [--backend manifold|occt] [--solver-debug-out <dir>]"
+    "Usage: forgecad run <script.forge.js> [--connectivity] [--connectivity-tolerance <mm>] [--spatial bounded|exact|off] [--param Key=Value] [--debug-imports] [--verbose] [--backend manifold|occt] [--solver-debug-out <dir>]"
   );
   process.exit(1);
 }
@@ -85648,11 +86802,14 @@ async function runScriptCli(argv = process.argv.slice(2)) {
     consumed: connectivityConsumed
   } = parsePhysicalConnectivityFlags(argv);
   const debugImports = argv.includes("--debug-imports");
+  const printJourneys = argv.includes("--journeys");
+  const printJourneysJson = argv.includes("--journeys-json");
   const verbose = argv.includes("--verbose") || argv.includes("-v");
   const backend = parseBackendArg(argv);
   const solverDebugOut = parseRequiredArg(argv, "--solver-debug-out");
+  const { mode: spatialMode, consumed: spatialConsumed } = parseSpatialMode(argv);
   const positional = argv.filter(
-    (arg, i) => !paramConsumed.has(i) && !focusConsumed.has(i) && !connectivityConsumed.has(i) && arg !== "--debug-imports" && arg !== "--backend" && argv[i - 1] !== "--backend" && arg !== "--solver-debug-out" && argv[i - 1] !== "--solver-debug-out"
+    (arg, i) => !paramConsumed.has(i) && !focusConsumed.has(i) && !connectivityConsumed.has(i) && !spatialConsumed.has(i) && arg !== "--debug-imports" && arg !== "--journeys" && arg !== "--journeys-json" && arg !== "--backend" && argv[i - 1] !== "--backend" && arg !== "--solver-debug-out" && argv[i - 1] !== "--solver-debug-out"
   );
   const scriptPath = positional[0];
   if (!scriptPath) usage15();
@@ -85681,6 +86838,10 @@ async function runScriptCli(argv = process.argv.slice(2)) {
       }
       process.exit(1);
     }
+    if (printJourneysJson) {
+      console.log(JSON.stringify(buildJourneyInspection(result.sceneConfig?.journeys), null, 2));
+      return;
+    }
     const { visible: visibleObjects, summary: focusSummary } = applyFocusFilter(result.objects, focusFilter);
     let totalBodies = 0;
     for (const obj of visibleObjects) {
@@ -85741,6 +86902,10 @@ async function runScriptCli(argv = process.argv.slice(2)) {
         }
       }
     }
+    if (printJourneys) {
+      console.log();
+      printJourneySummary(result.sceneConfig?.journeys);
+    }
     for (const obj of result.objects) {
       if (!obj.shape) continue;
       const plan = getShapeCompilePlan(obj.shape);
@@ -85826,14 +86991,17 @@ async function runScriptCli(argv = process.argv.slice(2)) {
       const connectivity = analyzePhysicalConnectivity2(entries, connectivityOptions);
       for (const line2 of formatPhysicalConnectivity(connectivity)) console.log(line2);
     }
-    if (entries.length > 1) {
+    if (entries.length > 1 && spatialMode !== "off") {
       console.log(`
 \u2713 Spatial analysis:`);
-      const spatialLines = analyzeSpatial(entries);
+      const spatialLines = analyzeSpatial(entries, spatialMode);
       for (const line2 of spatialLines) console.log(line2);
       if (spatialLines.length === 0) {
         console.log(`  (no collisions, all objects well-separated)`);
       }
+    } else if (entries.length > 1 && spatialMode === "off") {
+      console.log(`
+\u2713 Spatial analysis: skipped (--spatial off)`);
     }
     console.log(
       `\u2713 Params: ${result.params.map((p2) => {
@@ -86300,6 +87468,12 @@ var RENDER_OPTIONS = [
     valueLabel: "<front|back|side|right|top|iso|az:el|az:el:dist|spec>",
     values: RENDER_ANGLE_VALUES
   },
+  {
+    name: "--view",
+    description: "Named camera view declared by the model with scene({ views })",
+    argument: "required",
+    valueLabel: "<name>"
+  },
   { name: "--size", description: "Image size in pixels", argument: "required", valueLabel: "<px>" },
   { name: "--scene", description: "Viewport scene state JSON", argument: "required", valueLabel: "<json>" },
   { name: "--background", description: "Canvas background override", argument: "required", valueLabel: "<color>" },
@@ -86472,27 +87646,27 @@ var CAPTURE_COMMON_OPTIONS = [
 var commands = [
   {
     group: "Studio",
-    path: ["dev"],
-    summary: "Start the Vite dev server with live reload. No build step required \u2014 the preferred way to run ForgeCAD during active development.",
-    usage: ["forgecad dev <project-path> [project-path ...]"],
-    examples: ["forgecad dev ~/cad/gearbox", "forgecad dev ~/cad/gearbox ~/cad/fixture", "forgecad dev ~/cad/gearbox --port 4173"],
+    path: ["studio"],
+    summary: "Open the installed local editor around one or more project folders.",
+    usage: ["forgecad studio <project-path> [project-path ...]"],
+    examples: ["forgecad studio ~/cad/gearbox", "forgecad studio ~/cad/gearbox ~/cad/fixture", "forgecad studio ~/cad/gearbox --port 4173"],
     completion: {
       options: STUDIO_OPTIONS,
       positionals: [{ description: "project path", valueKind: "directory", repeatable: true }]
     },
-    run: runDevCli
+    run: runStudioCli
   },
   {
     group: "Studio",
-    path: ["studio"],
-    summary: "Serve the production build of the studio (requires dist/ \u2014 run `npm run build` first).",
-    usage: ["forgecad studio <project-path> [project-path ...]"],
-    examples: ["forgecad studio ~/cad/gearbox", "forgecad studio ~/cad/gearbox ~/cad/fixture", "forgecad studio ~/cad/gearbox --port 4173"],
+    path: ["dev"],
+    summary: "Start the Vite dev server for ForgeCAD source development.",
+    usage: ["forgecad dev <project-path> [project-path ...]"],
+    examples: ["forgecad dev ~/cad/gearbox", "forgecad dev ~/cad/gearbox ~/cad/fixture", "forgecad dev ~/cad/gearbox --port 4173"],
     completion: {
       options: STUDIO_OPTIONS,
       positionals: [{ description: "project path", valueKind: "directory", repeatable: true }]
     },
-    run: runStudioCli
+    run: runDevCli
   },
   {
     group: "Studio",
@@ -86606,9 +87780,9 @@ var commands = [
     group: "Modeling",
     path: ["run"],
     summary: "Execute a Forge script and print full geometry diagnostics \u2014 object summary, collision detection, spatial analysis, verification results, and solver profiling.",
-    description: "The primary validation command. Runs your script with the real geometry kernel (no browser needed) and prints a comprehensive report:\n\n**Object summary** \u2014 lists every named shape with its volume, bounding box, and body count. For constrained sketches, shows solver status (FULLY / UNDER / OVER constrained), DOF, and error residuals. Problematic constraints (conflicting, redundant, or high-residual) are flagged individually.\n\n**Construction history** \u2014 shows the build sequence for each shape (primitives, operations, modifications) so you can verify the modeling intent.\n\n**Feature summary** \u2014 tallies geometry features across all objects (e.g. `3 extrude, 2 fillet, 1 chamfer`).\n\n**Verification results** \u2014 runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values.\n\n**Automatic collision detection** \u2014 performs an all-pairs collision check on every named shape. For each pair whose bounding boxes overlap, computes the boolean intersection and reports overlap above 0.1 mm\xB3:\n\n```\n\u26A0 COLLISION: bolt \u2229 base (shared vol: 42.3mm\xB3)\n```\n\nIntra-group pairs (same assembly group) and mock-to-mock pairs are skipped. If a part passes through a boolean-subtracted hole, no collision is reported \u2014 the material is gone.\n\n**Spatial analysis** \u2014 reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). When no issues are found: `(no collisions, all objects well-separated)`.\n\n**Physical connectivity** \u2014 pass `--connectivity` to list physically connected components across visible objects. Overlapping or touching bboxes are joined within `--connectivity-tolerance` (default `0.05` model units); use collision inspection for exact positive-volume overlaps. This helps answer whether the model is one continuous assembly or several separate islands.\n\n**Parameters** \u2014 lists all declared parameters with their current values. Overridden values are marked with `*`.\n\n**Solver profiling** \u2014 when constraint solving occurs, shows timing breakdown (clone, solve, redundancy detection, surface building) and solver internals.",
+    description: "The primary validation command. Runs your script with the real geometry kernel (no browser needed) and prints a comprehensive report:\n\n**Object summary** \u2014 lists every named shape with its volume, bounding box, and body count. For constrained sketches, shows solver status (FULLY / UNDER / OVER constrained), DOF, and error residuals. Problematic constraints (conflicting, redundant, or high-residual) are flagged individually.\n\n**Construction history** \u2014 shows the build sequence for each shape (primitives, operations, modifications) so you can verify the modeling intent.\n\n**Feature summary** \u2014 tallies geometry features across all objects (e.g. `3 extrude, 2 fillet, 1 chamfer`).\n\n**Verification results** \u2014 runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values.\n\n**Automatic collision detection** \u2014 performs an all-pairs collision check on every named shape. For each pair whose bounding boxes overlap, computes the boolean intersection and reports overlap above 0.1 mm\xB3:\n\n```\n\u26A0 COLLISION: bolt \u2229 base (shared vol: 42.3mm\xB3)\n```\n\nIntra-group pairs (same assembly group) and mock-to-mock pairs are skipped. If a part passes through a boolean-subtracted hole, no collision is reported \u2014 the material is gone.\n\n**Spatial analysis** \u2014 reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). Exact pairwise collision intersections run by default only for bounded scenes; use `--spatial exact` for exhaustive collision checks or `--spatial off` to skip this section.\n\n**Physical connectivity** \u2014 pass `--connectivity` to list physically connected components across visible objects. Overlapping or touching bboxes are joined within `--connectivity-tolerance` (default `0.05` model units); use collision inspection for exact positive-volume overlaps. This helps answer whether the model is one continuous assembly or several separate islands.\n\n**Parameters** \u2014 lists all declared parameters with their current values. Overridden values are marked with `*`.\n\n**Solver profiling** \u2014 when constraint solving occurs, shows timing breakdown (clone, solve, redundancy detection, surface building) and solver internals.",
     usage: [
-      "forgecad run <script.forge.js> [--connectivity] [--connectivity-tolerance <mm>] [--focus [names]] [--hide names] [--param Key=Value] [--debug-imports] [--backend manifold|occt] [--solver-debug-out <dir>]"
+      "forgecad run <script.forge.js> [--connectivity] [--connectivity-tolerance <mm>] [--spatial bounded|exact|off] [--focus [names]] [--hide names] [--journeys] [--journeys-json] [--param Key=Value] [--debug-imports] [--backend manifold|occt] [--solver-debug-out <dir>]"
     ],
     examples: [
       "forgecad run examples/cup.forge.js",
@@ -86616,6 +87790,7 @@ var commands = [
       "forgecad run examples/cup.forge.js --focus bracket,hinge",
       'forgecad run examples/cup.forge.js --hide "wall,bolt"',
       "forgecad run examples/cup.forge.js --connectivity",
+      "forgecad run examples/cup.forge.js --journeys",
       "forgecad run examples/cup.forge.js --backend occt",
       "forgecad run examples/cup.forge.js --debug-imports",
       'forgecad run examples/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"',
@@ -86637,7 +87812,20 @@ var commands = [
           argument: "required",
           valueLabel: "<mm>"
         },
+        {
+          name: "--spatial",
+          description: "Spatial diagnostics mode",
+          argument: "required",
+          valueLabel: "<bounded|exact|off>",
+          values: [
+            { value: "bounded", description: "Default: exact checks only for bounded scene sizes" },
+            { value: "exact", description: "Exhaustive pairwise exact collision intersections" },
+            { value: "off", description: "Skip spatial diagnostics" }
+          ]
+        },
         { name: "--debug-imports", description: "Print the import trace" },
+        { name: "--journeys", description: "Print model journey summaries declared with scene({ journeys })" },
+        { name: "--journeys-json", description: "Emit machine-readable journey metadata and diagnostics only" },
         {
           name: "--solver-debug-out",
           description: "Write constructive transcripts and SVG snapshots to a directory",
@@ -86704,13 +87892,14 @@ var commands = [
     group: "Modeling",
     path: ["render", "3d"],
     summary: "Render a Forge scene to PNG using the real viewport renderer.",
-    description: "Launches a headless Chrome instance, renders the scene with the same WebGL viewport as the editor, and saves a PNG. The output path defaults to `<script-name>.png` next to the input file.\n\nUse `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--camera` flag accepts named views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec \u2014 pass it multiple times to render several viewpoints in one run.\n\nUse `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.\n\nThis is the standard way to visually verify geometry from the CLI or in agent workflows. For higher quality (path-traced, materials, HDRI lighting), use `render hq` instead.",
+    description: "Launches a headless Chrome instance, renders the scene with the same WebGL viewport as the editor, and saves a PNG. The output path defaults to `<script-name>.png` next to the input file.\n\nUse `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--view` flag selects a named camera declared in `scene({ views })`. The `--camera` flag accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec \u2014 pass `--camera` multiple times to render several viewpoints in one run.\n\nUse `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.\n\nThis is the standard way to visually verify geometry from the CLI or in agent workflows. For higher quality (path-traced, materials, HDRI lighting), use `render hq` instead.",
     usage: ["forgecad render 3d <script.forge.js> [output.png] [--focus [names]] [--hide names] [--edges off|thin|bold] [options]"],
     examples: [
       "forgecad render 3d examples/cup.forge.js",
       "forgecad render 3d examples/cup.forge.js --focus",
       "forgecad render 3d examples/cup.forge.js --focus bracket",
       'forgecad render 3d examples/cup.forge.js --hide "wall,bolt"',
+      "forgecad render 3d model.forge.js --view hero",
       "forgecad render 3d model.forge.js --camera 45:30",
       'forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"',
       "forgecad render 3d model.forge.js --camera front --camera side",
@@ -88124,7 +89313,8 @@ Commands:`);
 ${group2}`);
     visibleCommands.filter((command) => command.group === group2).forEach((command) => {
       const tier = requiredTierForCommand(command.path);
-      const badge = tier === "pro" ? " \x1B[33m[Pro]\x1B[0m" : "";
+      const productionBadge = productionOutputBadgeForCommand(command.path);
+      const badge = tier === "pro" ? " \x1B[33m[Pro]\x1B[0m" : productionBadge ? ` \x1B[36m[${productionBadge}]\x1B[0m` : "";
       console.log(`  ${padRight2(commandLabel(command), width + 2)}${command.summary}${badge}`);
     });
   }
@@ -88306,6 +89496,7 @@ async function runForgeCadCli(argv = process.argv.slice(2)) {
   }
   if (!shouldRequireAuth) {
     enforceFeatureGate(match.command.path);
+    if (match.args.length > 0) printProductionOutputNotice(match.command.path);
     await match.command.run(match.args);
     return;
   }
@@ -88313,6 +89504,7 @@ async function runForgeCadCli(argv = process.argv.slice(2)) {
   const requiredTier = requiredTierForCommand(match.command.path);
   if (isLongRunningCommand(match.command.path)) {
     enforceFeatureGate(match.command.path);
+    if (match.args.length > 0) printProductionOutputNotice(match.command.path);
     await recordCliCommandEvent({
       commandPath: match.command.path,
       args: match.args,
@@ -88328,6 +89520,7 @@ async function runForgeCadCli(argv = process.argv.slice(2)) {
   try {
     capturedExitCode = await runWithExitCapture(async () => {
       enforceFeatureGate(match.command.path);
+      if (match.args.length > 0) printProductionOutputNotice(match.command.path);
       await match.command.run(match.args);
     });
     await recordCliCommandEvent({
@@ -88364,6 +89557,7 @@ if (isDirectCliRun(import.meta.url)) {
 export {
   commandRequiresCliAuth,
   commands,
+  productionOutputBadgeForCommand,
   requiredTierForCommand,
   runForgeCadCli
 };