forgecad 0.9.2 → 0.9.3

package/dist/assets/{sectionPlaneMath-DXJ_TdIW.js → sectionPlaneMath-BxfokaJE.js}

@@ -7310,7 +7310,7 @@ function add$3(a, b) {
 function scale$4(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
-function sub$4(a, b) {
+function sub$5(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 function cross$4(a, b) {
@@ -7349,8 +7349,8 @@ function buildSurfaceSheetTopology(boundaries, options = {}) {
   const [v1Start, v1End] = boundaries.v1;
   const corners = [u0Start, u0End, u1Start, u1End];
   const center = options.center ?? average$1(corners);
-  const uAxis = normalizeAxis$1(sub$4(midpoint$3(u1Start, u1End), midpoint$3(u0Start, u0End)));
-  const vAxis = normalizeAxis$1(sub$4(midpoint$3(v1Start, v1End), midpoint$3(v0Start, v0End)));
+  const uAxis = normalizeAxis$1(sub$5(midpoint$3(u1Start, u1End), midpoint$3(u0Start, u0End)));
+  const vAxis = normalizeAxis$1(sub$5(midpoint$3(v1Start, v1End), midpoint$3(v0Start, v0End)));
   const normal = normalizeAxis$1(options.normal ?? cross$4(uAxis, vAxis));
   const faces = /* @__PURE__ */ new Map();
   faces.set(faceName, {
@@ -7382,7 +7382,7 @@ function attachSurfaceSheetTopology(shape, boundaries, options = {}) {
   });
   return shape;
 }
-function requireFinite$6(v, label) {
+function requireFinite$7(v, label) {
   if (!Number.isFinite(v)) throw new Error(`nurbsSurface: ${label} must be finite, got ${v}`);
 }
 class NurbsSurface {
@@ -7408,16 +7408,16 @@ class NurbsSurface {
     for (let i = 0; i < nU; i++) {
       if (controlGrid[i].length !== nV) throw new Error(`nurbsSurface: row ${i} has ${controlGrid[i].length} points, expected ${nV}`);
       for (let j = 0; j < nV; j++) {
-        requireFinite$6(controlGrid[i][j][0], `controlGrid[${i}][${j}][0]`);
-        requireFinite$6(controlGrid[i][j][1], `controlGrid[${i}][${j}][1]`);
-        requireFinite$6(controlGrid[i][j][2], `controlGrid[${i}][${j}][2]`);
+        requireFinite$7(controlGrid[i][j][0], `controlGrid[${i}][${j}][0]`);
+        requireFinite$7(controlGrid[i][j][1], `controlGrid[${i}][${j}][1]`);
+        requireFinite$7(controlGrid[i][j][2], `controlGrid[${i}][${j}][2]`);
       }
     }
     const weightsGrid = options.weights ?? controlGrid.map((row) => row.map(() => 1));
     for (let i = 0; i < nU; i++) {
       if (weightsGrid[i].length !== nV) throw new Error(`nurbsSurface: weights row ${i} length mismatch`);
       for (let j = 0; j < nV; j++) {
-        requireFinite$6(weightsGrid[i][j], `weights[${i}][${j}]`);
+        requireFinite$7(weightsGrid[i][j], `weights[${i}][${j}]`);
         if (weightsGrid[i][j] <= 0) throw new Error(`nurbsSurface: weights[${i}][${j}] must be > 0`);
       }
     }
@@ -8825,7 +8825,7 @@ async function initManifoldWasm() {
   if (_wasm) return _wasm;
   performance.mark("manifold:start");
   const Module = (await __vitePreload(async () => {
-    const { default: __vite_default__ } = await import("./manifold-DbyILno4.js");
+    const { default: __vite_default__ } = await import("./manifold-CYWZMfjB.js");
     return { default: __vite_default__ };
   }, true ? [] : void 0)).default;
   performance.mark("manifold:imported");
@@ -9048,7 +9048,7 @@ function sweepStitched(profilePolygons, pathPoints, up, wasm) {
 function computeParallelTransportFrames(path2, preferredUp) {
   const n = path2.length;
   const frames = [];
-  const firstTangent = normalize$6(sub$3(path2[1], path2[0]));
+  const firstTangent = normalize$6(sub$4(path2[1], path2[0]));
   if (!firstTangent) return null;
   let x = normalize$6(cross$3(preferredUp, firstTangent));
   if (!x || length(x) < 1e-8) {
@@ -9062,18 +9062,18 @@ function computeParallelTransportFrames(path2, preferredUp) {
     const prevT = frames[i - 1].t;
     let nextT;
     if (i < n - 1) {
-      const t1 = normalize$6(sub$3(path2[i], path2[i - 1]));
-      const t2 = normalize$6(sub$3(path2[i + 1], path2[i]));
+      const t1 = normalize$6(sub$4(path2[i], path2[i - 1]));
+      const t2 = normalize$6(sub$4(path2[i + 1], path2[i]));
       if (!t1 || !t2) return null;
       nextT = normalize$6(add$2(t1, t2)) || t1;
     } else {
-      const nt = normalize$6(sub$3(path2[i], path2[i - 1]));
+      const nt = normalize$6(sub$4(path2[i], path2[i - 1]));
       if (!nt) return null;
       nextT = nt;
     }
     const v = cross$3(prevT, nextT);
     const vLen = length(v);
-    const c = dot$4(prevT, nextT);
+    const c = dot$5(prevT, nextT);
     if (vLen > 1e-10) {
       const axis = scale$3(v, 1 / vLen);
       x = rotateVector(frames[i - 1].x, axis, c, vLen);
@@ -9147,7 +9147,7 @@ function signedArea$5(loop) {
   }
   return area2 * 0.5;
 }
-function sub$3(a, b) {
+function sub$4(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 function add$2(a, b) {
@@ -9156,7 +9156,7 @@ function add$2(a, b) {
 function scale$3(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
-function dot$4(a, b) {
+function dot$5(a, b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
 function cross$3(a, b) {
@@ -9175,7 +9175,7 @@ function normalize$6(v) {
   return [v[0] / len2, v[1] / len2, v[2] / len2];
 }
 function rotateVector(v, axis, c, s) {
-  const kDotV = dot$4(axis, v);
+  const kDotV = dot$5(axis, v);
   const kCrossV = cross$3(axis, v);
   return [
     v[0] * c + kCrossV[0] * s + axis[0] * kDotV * (1 - c),
@@ -12876,7 +12876,7 @@ function normalizeFaceSelector(selector) {
 function cross$2(a, b) {
   return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
 }
-function dot$3(a, b) {
+function dot$4(a, b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
 function normVec3(v) {
@@ -12911,11 +12911,11 @@ function clusterMeshFaces(shape) {
     if (!normal) continue;
     const crossLen = Math.sqrt(rawCross[0] * rawCross[0] + rawCross[1] * rawCross[1] + rawCross[2] * rawCross[2]);
     const triArea = crossLen / 2;
-    const planeOffset = dot$3(normal, v0);
+    const planeOffset = dot$4(normal, v0);
     const triCentroid = [(v0[0] + v1[0] + v2[0]) / 3, (v0[1] + v1[1] + v2[1]) / 3, (v0[2] + v1[2] + v2[2]) / 3];
     let merged = false;
     for (const c of clusters) {
-      if (dot$3(c.normal, normal) > NORMAL_COS_EPS$1 && Math.abs(c.planeOffset - planeOffset) < PLANE_OFFSET_EPS$1) {
+      if (dot$4(c.normal, normal) > NORMAL_COS_EPS$1 && Math.abs(c.planeOffset - planeOffset) < PLANE_OFFSET_EPS$1) {
         c.centroidSum[0] += triCentroid[0];
         c.centroidSum[1] += triCentroid[1];
         c.centroidSum[2] += triCentroid[2];
@@ -12957,7 +12957,7 @@ function queryMeshFaces(shape, query) {
   let clusters = clusterMeshFaces(shape);
   if (query.normal) {
     const qn = query.normal;
-    clusters = clusters.filter((c) => dot$3(c.normal, qn) > NORMAL_COS_EPS$1);
+    clusters = clusters.filter((c) => dot$4(c.normal, qn) > NORMAL_COS_EPS$1);
   }
   if (query.planar !== false) {
     clusters = clusters.filter((c) => c.normal !== null);
@@ -12973,7 +12973,7 @@ function queryMeshFace(shape, query) {
   let clusters = clusterMeshFaces(shape);
   if (query.normal) {
     const qn = query.normal;
-    clusters = clusters.filter((c) => dot$3(c.normal, qn) > NORMAL_COS_EPS$1);
+    clusters = clusters.filter((c) => dot$4(c.normal, qn) > NORMAL_COS_EPS$1);
   }
   if (query.planar !== false) {
     clusters = clusters.filter((c) => c.normal !== null);
@@ -19925,6 +19925,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$1(options.blend, "Sculpt.tube() blend", Math.max(0.5, minRadius));
   let segmentCount = 0;
   for (let i = 0; i < normalized.length - 1; i += 1) {
@@ -19933,8 +19934,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;
 }
@@ -22326,7 +22327,7 @@ function intersection(...inputs) {
     nextPlan
   );
 }
-var define_process_env_default = {};
+var define_process_env_default$2 = {};
 let _wasm_solve = null;
 let _wasm_get_profile = null;
 let _solverMemory = null;
@@ -22361,7 +22362,7 @@ function readInitialConsoleDebug() {
   return false;
 }
 function readEnvFlag(name) {
-  const value = typeof process !== "undefined" ? define_process_env_default == null ? void 0 : define_process_env_default[name] : void 0;
+  const value = typeof process !== "undefined" ? define_process_env_default$2 == null ? void 0 : define_process_env_default$2[name] : void 0;
   if (typeof value !== "string") return false;
   return ["1", "true", "yes", "on"].includes(value.toLowerCase());
 }
@@ -23648,7 +23649,7 @@ class MateBuilder {
     return this.constraints.reduce((sum, c) => sum + (CONSTRAINT_EQUATIONS[c.type] ?? 0), 0);
   }
 }
-let _collected$7 = null;
+let _collected$8 = null;
 const isAxis = (value) => value === "x" || value === "y" || value === "z";
 const normalizeDirection = (value, label) => {
   if (value === "radial" || isAxis(value)) return value;
@@ -23707,16 +23708,16 @@ const mergeDirective = (target, patch, label) => {
   return out;
 };
 function resetExplodeView() {
-  _collected$7 = null;
+  _collected$8 = null;
 }
 function getCollectedExplodeView() {
-  return _collected$7 ? cloneOptions(_collected$7) : null;
+  return _collected$8 ? cloneOptions(_collected$8) : null;
 }
 function explodeView(options = {}) {
   if (!options || typeof options !== "object") {
     throw new Error("explodeView(options) expects an options object");
   }
-  const next = _collected$7 ? cloneOptions(_collected$7) : {};
+  const next = _collected$8 ? cloneOptions(_collected$8) : {};
   if (options.enabled !== void 0) {
     if (typeof options.enabled !== "boolean") throw new Error("explodeView.enabled must be a boolean");
     next.enabled = options.enabled;
@@ -23764,9 +23765,9 @@ function explodeView(options = {}) {
     });
     next.byPath = byPath;
   }
-  _collected$7 = next;
+  _collected$8 = next;
 }
-let _collected$6 = null;
+let _collected$7 = null;
 const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 const isVec3$1 = (value) => Array.isArray(value) && value.length === 3 && isFiniteNumber(value[0]) && isFiniteNumber(value[1]) && isFiniteNumber(value[2]);
 const normalizeAxis = (axis) => {
@@ -24099,22 +24100,22 @@ const cloneCollected = (value) => ({
   defaultAnimation: value.defaultAnimation
 });
 function resetJointsView() {
-  _collected$6 = null;
+  _collected$7 = null;
 }
 function getCollectedJointsView() {
-  return _collected$6 ? cloneCollected(_collected$6) : null;
+  return _collected$7 ? cloneCollected(_collected$7) : null;
 }
 function saveJointsView() {
-  return _collected$6 ? cloneCollected(_collected$6) : null;
+  return _collected$7 ? cloneCollected(_collected$7) : null;
 }
 function restoreJointsView(state) {
-  _collected$6 = state;
+  _collected$7 = state;
 }
 function jointsView(options = {}) {
   if (!options || typeof options !== "object") {
     throw new Error("jointsView(options) expects an options object");
   }
-  const next = _collected$6 ? cloneCollected(_collected$6) : { joints: [], couplings: [], animations: [] };
+  const next = _collected$7 ? cloneCollected(_collected$7) : { joints: [], couplings: [], animations: [] };
   if (options.enabled !== void 0) {
     if (typeof options.enabled !== "boolean") {
       throw new Error("jointsView.enabled must be a boolean");
@@ -24169,8 +24170,14 @@ function jointsView(options = {}) {
   if (next.defaultAnimation && !next.animations.some((animation) => animation.name === next.defaultAnimation)) {
     throw new Error(`jointsView defaultAnimation "${next.defaultAnimation}" does not exist in animations`);
   }
-  _collected$6 = next;
+  _collected$7 = next;
 }
+var define_process_env_default$1 = {};
+const SWEEP_JOINT_DEFAULT_STEP_LIMIT = {
+  live: 1,
+  default: 4,
+  high: Number.POSITIVE_INFINITY
+};
 let collectedAssemblies = [];
 function resetCollectedAssemblies() {
   collectedAssemblies = [];
@@ -24211,6 +24218,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" ? define_process_env_default$1 == null ? void 0 : define_process_env_default$1[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;
+}
 const FASTENER_PATTERN = /\b(bolt|screw|nut|washer|pin|rivet|fastener|standoff|insert)\b/i;
 function isFastenerName(name) {
   return FASTENER_PATTERN.test(name);
@@ -24543,16 +24577,23 @@ class SolvedAssembly {
     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) {
@@ -25529,7 +25570,7 @@ 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;
@@ -25945,12 +25986,12 @@ function bom(quantity, description, opts) {
     metadata
   });
 }
-let _collected$5 = [];
+let _collected$6 = [];
 function resetCutPlanes() {
-  _collected$5 = [];
+  _collected$6 = [];
 }
 function getCollectedCutPlanes() {
-  return _collected$5.slice();
+  return _collected$6.slice();
 }
 function normalizeExcludedObjectNames(input) {
   if (input === void 0) return void 0;
@@ -25966,16 +26007,16 @@ function cutPlane(name, normal, offsetOrOptions = 0, maybeOptions = {}) {
   const offset2 = Number.isFinite(rawOffset) ? rawOffset : 0;
   const options = usingOffsetArg ? maybeOptions : offsetOrOptions;
   const excludeObjectNames = normalizeExcludedObjectNames(options.exclude);
-  _collected$5.push({ name, normal, offset: offset2, excludeObjectNames });
+  _collected$6.push({ name, normal, offset: offset2, excludeObjectNames });
 }
-let _collected$4 = [];
+let _collected$5 = [];
 let _counter$1 = 0;
 function resetMocks() {
-  _collected$4 = [];
+  _collected$5 = [];
   _counter$1 = 0;
 }
 function getCollectedMocks() {
-  return _collected$4.slice();
+  return _collected$5.slice();
 }
 function mock(shape, name) {
   if (!shape || typeof shape !== "object") {
@@ -25983,7 +26024,7 @@ function mock(shape, name) {
   }
   _counter$1 += 1;
   const displayName = name && typeof name === "string" && name.trim().length > 0 ? name.trim() : `Mock ${_counter$1}`;
-  _collected$4.push({
+  _collected$5.push({
     id: `mock-${_counter$1}`,
     name: displayName,
     shape
@@ -30185,7 +30226,7 @@ function shapeToBounds(shape) {
     max: [bb.max[0], bb.max[1], bb.max[2]]
   };
 }
-function sub$2(a, b) {
+function sub$3(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 function addVec(a, b) {
@@ -30194,7 +30235,7 @@ function addVec(a, b) {
 function scale$2(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
-function dot$2(a, b) {
+function dot$3(a, b) {
   return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
 function cross$1(a, b) {
@@ -30218,9 +30259,9 @@ function pipeRoute(points, radius, options) {
   const bends = new Array(points.length).fill(null);
   for (let i = 1; i < points.length - 1; i++) {
     const prev = points[i - 1], cur = points[i], next = points[i + 1];
-    const dIn = normalize$3(sub$2(cur, prev));
-    const dOut = normalize$3(sub$2(next, cur));
-    const dotVal = clampDot(dot$2(dIn, dOut));
+    const dIn = normalize$3(sub$3(cur, prev));
+    const dOut = normalize$3(sub$3(next, cur));
+    const dotVal = clampDot(dot$3(dIn, dOut));
     const bendAngle = Math.acos(dotVal);
     if (bendAngle < 1e-6) {
       continue;
@@ -30239,7 +30280,7 @@ function pipeRoute(points, radius, options) {
   }
   const parts = [];
   const makeSeg = (a, b) => {
-    const d = sub$2(b, a);
+    const d = sub$3(b, a);
     const len2 = vecLen(d);
     if (len2 < 0.01) return null;
     const dir = normalize$3(d);
@@ -30284,7 +30325,7 @@ function pipeRoute(points, radius, options) {
       const innerBend = buildShapeFromCompilePlan(innerPlan);
       bendShape = bendShape.subtract(innerBend);
     }
-    const radialDir = normalize$3(sub$2(info.startPt, info.center));
+    const radialDir = normalize$3(sub$3(info.startPt, info.center));
     const tangentDir = cross$1(info.axis, radialDir);
     const c = info.center;
     bendShape = bendShape.transform([
@@ -30345,7 +30386,7 @@ function elbow(pipeRadius, bendRadius, angle, options) {
   if (fromDir && toDir) {
     const nFrom = normalize$3(fromDir);
     const nTo = normalize$3(toDir);
-    const d = clampDot(dot$2(nFrom, nTo));
+    const d = clampDot(dot$3(nFrom, nTo));
     angleDeg = Math.acos(d) * 180 / Math.PI;
   }
   if (angleDeg < 0.01) throw new Error("elbow: angle too small");
@@ -30416,20 +30457,20 @@ function assertFinitePositive(apiName, name, value) {
 function add$1(a, b) {
   return [a[0] + b[0], a[1] + b[1]];
 }
-function sub$1(a, b) {
+function sub$2(a, b) {
   return [a[0] - b[0], a[1] - b[1]];
 }
 function scale$1(v, s) {
   return [v[0] * s, v[1] * s];
 }
-function dot$1(a, b) {
+function dot$2(a, b) {
   return a[0] * b[0] + a[1] * b[1];
 }
 function len(v) {
   return Math.hypot(v[0], v[1]);
 }
 function dist$2(a, b) {
-  return len(sub$1(b, a));
+  return len(sub$2(b, a));
 }
 function norm$1(v) {
   const l = len(v);
@@ -30454,7 +30495,7 @@ function chooseSweepDeg(center, start, end, incomingDir) {
   const endAngle = angleOf(center, end);
   const cwTangent = tangentAt(startAngle, true);
   const ccwTangent = tangentAt(startAngle, false);
-  const clockwise = dot$1(cwTangent, incomingDir) >= dot$1(ccwTangent, incomingDir);
+  const clockwise = dot$2(cwTangent, incomingDir) >= dot$2(ccwTangent, incomingDir);
   const sweep2 = clockwise ? -normalizePositiveRadians(startAngle - endAngle) : normalizePositiveRadians(endAngle - startAngle);
   return sweep2 * 180 / Math.PI;
 }
@@ -30497,8 +30538,8 @@ function normalizePulleyAsCircle(pulley, index, radiusOverride) {
   );
 }
 function commonTangents(a, b, mode) {
-  const delta = sub$1(b.center, a.center);
-  const z = dot$1(delta, delta);
+  const delta = sub$2(b.center, a.center);
+  const z = dot$2(delta, delta);
   if (z < EPS$5) {
     throw new Error(`beltDrive: pulleys "${a.name}" and "${b.name}" have the same center.`);
   }
@@ -30528,8 +30569,8 @@ function commonTangents(a, b, mode) {
   });
 }
 function buildSegmentsForTangentOrder(a, b, t0, t1) {
-  const span0Dir = norm$1(sub$1(t0.b, t0.a));
-  const span1Dir = norm$1(sub$1(t1.a, t1.b));
+  const span0Dir = norm$1(sub$2(t0.b, t0.a));
+  const span1Dir = norm$1(sub$2(t1.a, t1.b));
   const bSweepDeg = chooseSweepDeg(b.center, t0.b, t1.b, span0Dir);
   const aSweepDeg = chooseSweepDeg(a.center, t1.a, t0.a, span1Dir);
   const span0 = {
@@ -73204,6 +73245,130 @@ function shapeToGeometryFallback(shape) {
   const edges = new EdgesGeometry(solid, 1);
   return { solid, edges, hasSmoothNormals: false };
 }
+let _collected$4 = [];
+let _nextId = 1;
+function resetRenderLabels() {
+  _collected$4 = [];
+  _nextId = 1;
+}
+function getCollectedRenderLabels() {
+  return _collected$4.map((label) => ({ ...label, at: [...label.at], offset: [...label.offset] }));
+}
+function requireFinite$6(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`);
+  }
+  return value;
+}
+function requireVec3$2(value, label) {
+  if (!Array.isArray(value) || value.length !== 3) {
+    throw new Error(`${label} must be [x, y, z]`);
+  }
+  return [requireFinite$6(value[0], `${label}[0]`), requireFinite$6(value[1], `${label}[1]`), requireFinite$6(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();
+}
+const 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 = requireFinite$6(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$2(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$2(at, "Viewport.label at");
+  const normalizedOptions = normalizeOptions(options);
+  _collected$4.push({
+    id: `render-label-${_nextId++}`,
+    text: text.trim(),
+    at: normalizedAt,
+    ...normalizedOptions
+  });
+}
+const 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);
+  }
+};
 const DEFAULT_RENDER_STYLE = "classic";
 const RENDER_STYLE_OPTIONS = [
   {
@@ -73614,6 +73779,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 seen2 = /* @__PURE__ */ new Set();
+  for (const step of out.steps) {
+    if (seen2.has(step.id)) {
+      throw new Error(`${label}.steps contains duplicate step id "${step.id}"`);
+    }
+    seen2.add(step.id);
+  }
+  if (out.startsAt && !seen2.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)) {
@@ -73757,7 +74036,18 @@ function scene(options) {
   if (!options || typeof options !== "object") {
     throw new Error("scene(options) expects an options object");
   }
-  const current = _collected$3 ? { ..._collected$3 } : { background: null, camera: null, lights: null, environment: null, fog: null, postProcessing: null, ground: null, capture: null };
+  const current = _collected$3 ? { ..._collected$3 } : {
+    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");
   }
@@ -73768,6 +74058,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");
@@ -73808,6 +74106,74 @@ function scene(options) {
   }
   _collected$3 = current;
 }
+const targetPath = (target) => {
+  var _a3;
+  const path2 = (_a3 = target.treePath) == null ? void 0 : _a3.filter((entry) => entry.trim());
+  return path2 && path2.length > 0 ? path2.join("/") : target.name;
+};
+const 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 == null ? void 0 : 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
+  };
+}
 const validateColor = (value, label) => {
   if (typeof value !== "string") throw new Error(`${label} must be a string`);
   const trimmed = value.trim();
@@ -75053,9 +75419,15 @@ function cross(a, b) {
 function add(a, b) {
   return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
 }
+function sub$1(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
 function scale(v, s) {
   return [v[0] * s, v[1] * s, v[2] * s];
 }
+function dot$1(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
 function lerp$1(a, b, t) {
   return a + (b - a) * t;
 }
@@ -75088,6 +75460,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 cos2 = Math.cos(angle);
+  const sin2 = Math.sin(angle);
+  const x = rx * Math.sign(cos2) * Math.abs(cos2) ** (2 / exponent);
+  const y = ry * Math.sign(sin2) * Math.abs(sin2) ** (2 / exponent);
+  const nx = Math.sign(x) * Math.abs(x / Math.max(rx, EPS$4)) ** Math.max(exponent - 1, 1e-3);
+  const ny = Math.sign(y) * Math.abs(y / Math.max(ry, EPS$4)) ** Math.max(exponent - 1, 1e-3);
+  const nLen = Math.hypot(nx, ny);
+  return {
+    point: [x, y],
+    normal: nLen < EPS$4 ? [Math.sign(cos2), Math.sign(sin2)] : [nx / nLen, ny / nLen]
+  };
+}
+function angleForSide(side, u) {
+  const t = clamp$4(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, EPS$4);
+  if (side === "top" || side === "bottom") return Math.max(width, EPS$4);
+  return Math.max(width, depth, EPS$4);
+}
+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: lerp$1(a.u ?? 0.5, b.u ?? 0.5, t),
+    v: lerp$1(a.v ?? 0.5, b.v ?? 0.5, t),
+    offset: lerp$1(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 = sub$1(grid[grid.length - 1][0], grid[0][0]);
+  const lengthEdge = sub$1(grid[0][grid[0].length - 1], grid[0][0]);
+  const actual = norm(cross(widthEdge, lengthEdge));
+  return dot$1(actual, desiredNormal) < 0 ? [...grid].reverse() : grid;
+}
 function isStationBuilder(input) {
   return typeof input.toSpec === "function";
 }
@@ -75189,6 +75620,15 @@ class ProductSkin {
   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 ? lerp$1(this.axisMin, this.axisMax, vOrAxis) : clamp$4(vOrAxis, this.axisMin, this.axisMax);
@@ -75207,7 +75647,9 @@ class ProductSkin {
         width: lerp$1(a.profile.width, b.profile.width, t),
         depth: lerp$1(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: lerp$1(profileExponent(a), profileExponent(b), t),
+        kind: a.profile.kind === b.profile.kind ? a.profile.kind : "custom"
       };
     }
     const last = sorted[sorted.length - 1];
@@ -75217,12 +75659,14 @@ class ProductSkin {
       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";
@@ -75246,11 +75690,31 @@ class ProductSkin {
     }
     const station = this.stationAt(query.v ?? 0.5);
     const u = clamp$4(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 = norm(add(scale(basis.crossA, section.normal[0]), scale(basis.crossB, section.normal[1])));
+      const delta = 2e-3;
+      const prev = superEllipsePoint(
+        station.width / 2,
+        station.depth / 2,
+        station.exponent,
+        angleForSide(side, clamp$4((query.u ?? 0.5) - delta, 0, 1)) ?? sideAngle
+      ).point;
+      const next = superEllipsePoint(
+        station.width / 2,
+        station.depth / 2,
+        station.exponent,
+        angleForSide(side, clamp$4((query.u ?? 0.5) + delta, 0, 1)) ?? sideAngle
+      ).point;
+      tangentU = norm(add(scale(basis.crossA, next[0] - prev[0]), scale(basis.crossB, next[1] - prev[1])));
+    } else if (side === "right") {
       crossA = station.width / 2;
       crossB = u * station.depth;
       normal = basis.crossA;
@@ -75272,7 +75736,7 @@ class ProductSkin {
       tangentU = basis.crossA;
     }
     normal = norm(normal);
-    tangentU = norm(tangentU);
+    tangentU = norm(sub$1(tangentU, scale(normal, dot$1(tangentU, normal))));
     const tangentV = norm(cross(normal, tangentU));
     const point2 = add(add(station.center, add(scale(basis.crossA, crossA), scale(basis.crossB, crossB))), scale(normal, offset2));
     return {
@@ -75592,6 +76056,303 @@ class ProductHandleBuilder {
     return new ProductHandleFeature(grip, upperPad, lowerPad);
   }
 }
+class ProductSurfaceBuilder {
+  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 path2 = 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, path2, options);
+  }
+}
+class ProductRibbonBuilder {
+  constructor(name) {
+    __publicField(this, "skinValue");
+    __publicField(this, "queryPath", []);
+    __publicField(this, "refPath", []);
+    __publicField(this, "widthValue", 6);
+    __publicField(this, "thicknessValue", 0.8);
+    __publicField(this, "offsetValue", 0.25);
+    __publicField(this, "samplesValue", 24);
+    __publicField(this, "widthSamplesValue", 5);
+    __publicField(this, "resolutionValue");
+    __publicField(this, "materialValue");
+    __publicField(this, "colorValue");
+    __publicField(this, "lastDiagnosticsValue");
+    this.name = name;
+    if (!name || !name.trim()) throw new Error("Product.ribbon(name) requires a non-empty name");
+  }
+  /**
+   * 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 = clamp$4(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, path2) {
+    if (path2.length < 2) throw new Error("Product.ribbon().on(skin, points) must be called before .build()");
+    const side = normalizedSide(path2[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 path2) {
+      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 = clamp$4(rawU, 0, 1);
+        const clampDistance = Math.abs(rawU - u) * span;
+        if (clampDistance > EPS$4) {
+          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: path2.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(add(frame.point, scale(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]
+    };
+  }
+}
 const Product = {
   /** Start a named product skin builder. */
   skin(name) {
@@ -75664,10 +76425,27 @@ const 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);
@@ -76810,6 +77588,7 @@ function cameraTrajectory(defOrFn, options) {
     throw new Error('cameraTrajectory(): each keyframe must have either an "orbit" or "position" property');
   }
 }
+var define_process_env_default = {};
 function resolveEdges(shape, edges) {
   if (!edges) {
     return selectEdges(shape);
@@ -76831,6 +77610,76 @@ function isEdgeSegment(value) {
 function isEdgeReferenceLike(value) {
   return typeof value === "object" && value !== null && "edges" in value && typeof value.edges === "function";
 }
+const BROAD_EDGE_FEATURE_DEFAULT_BUDGET = {
+  live: 0,
+  default: 12,
+  high: Number.POSITIVE_INFINITY
+};
+let broadEdgeFeatureBudget = null;
+function readBroadEdgeFeatureEnv(name) {
+  return typeof process !== "undefined" ? define_process_env_default == null ? void 0 : define_process_env_default[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]],
@@ -76844,10 +77693,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",
@@ -76867,10 +77719,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",
@@ -100016,6 +100871,7 @@ const verify = {
 };
 function resetExecutionSession(logs) {
   resetCollectedAssemblies();
+  resetBroadEdgeFeatureBudget();
   resetParams();
   resetShapeQueryOwnerIds();
   resetDimensions();
@@ -100024,6 +100880,7 @@ function resetExecutionSession(logs) {
   resetSheetStock();
   resetRobotExport();
   resetCutPlanes();
+  resetRenderLabels();
   resetCameraTrajectory();
   resetExplodeView();
   resetJointsView();
@@ -100087,6 +100944,7 @@ function collectSuccessfulExecutionSnapshot(args) {
     bom: getCollectedBom(),
     sheetStock: getCollectedSheetStock(),
     cutPlanes: getCollectedCutPlanes(),
+    renderLabels: getCollectedRenderLabels(),
     cameraTrajectory: getCollectedCameraTrajectory(),
     explodeView: getCollectedExplodeView(),
     jointsView: getCollectedJointsView(),
@@ -100110,6 +100968,7 @@ function collectFailedExecutionSnapshot(args) {
     bom: getCollectedBom(),
     sheetStock: getCollectedSheetStock(),
     cutPlanes: getCollectedCutPlanes(),
+    renderLabels: getCollectedRenderLabels(),
     cameraTrajectory: getCollectedCameraTrajectory(),
     explodeView: getCollectedExplodeView(),
     jointsView: getCollectedJointsView(),
@@ -100255,13 +101114,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 == null ? void 0 : mirror(level, formattedArgs);
   };
   return { log: capture("log"), warn: capture("warn"), error: capture("error"), info: capture("info") };
 }
@@ -100423,6 +101284,18 @@ function buildFileIndex(allFiles) {
   }
   return fileIndex;
 }
+function hasPathExtension(path2) {
+  const fileName = path2.split("/").pop() ?? path2;
+  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");
@@ -100431,7 +101304,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") {
@@ -154712,7 +155586,7 @@ ${lanes.join("\n")}
         }
         const normalizedSourcePaths = getPathsRelativeToRootDirs(sourceDirectory, rootDirs, getCanonicalFileName);
         const relativePaths = flatMap(normalizedSourcePaths, (sourcePath) => {
-          return map(normalizedTargetPaths, (targetPath) => ensurePathIsNonModuleName(getRelativePathFromDirectory(sourcePath, targetPath, getCanonicalFileName)));
+          return map(normalizedTargetPaths, (targetPath2) => ensurePathIsNonModuleName(getRelativePathFromDirectory(sourcePath, targetPath2, getCanonicalFileName)));
         });
         const shortest = min2(relativePaths, compareNumberOfDirectorySeparators);
         if (!shortest) {
@@ -311282,6 +312156,36 @@ function extractUnusedTopLevelVarNames(code) {
   }
   return declaredNames.filter((n) => topLevelNames.has(n) && (!usedByOthers.has(n) || explicitImplicitResultNames.has(n)));
 }
+function collectBindingNameLocations(node, sourceFile, names) {
+  if (typescriptExports.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 (typescriptExports.isBindingElement(element)) {
+      collectBindingNameLocations(element.name, sourceFile, names);
+    }
+  }
+}
+function findTopLevelRuntimeGlobalCollision(code, runtimeGlobalNames) {
+  const runtimeGlobals = new Set(runtimeGlobalNames);
+  const sourceFile = typescriptExports.createSourceFile("__runtime-globals.js", code, typescriptExports.ScriptTarget.ES2020, false, typescriptExports.ScriptKind.JS);
+  const declarations = [];
+  for (const statement of sourceFile.statements) {
+    if (typescriptExports.isVariableStatement(statement)) {
+      const isLexical = (statement.declarationList.flags & (typescriptExports.NodeFlags.Let | typescriptExports.NodeFlags.Const)) !== 0;
+      if (!isLexical) continue;
+      for (const decl of statement.declarationList.declarations) {
+        collectBindingNameLocations(decl.name, sourceFile, declarations);
+      }
+    } else if (typescriptExports.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 });
@@ -312437,6 +313341,12 @@ function withConstructorChainLockdown(fn) {
   }
 }
 function executeFile(code, fileName, allFiles, visited, scope = {}, options, executionMode = "script", moduleCacheEntry) {
+  var _a3, _b3, _c2, _d2, _e2, _f;
+  (_a3 = options.debug) == null ? void 0 : _a3.call(options, "executeFile:start", {
+    fileName,
+    executionMode,
+    scope: scope.namePrefix ?? fileName
+  });
   const trackCircularImports = executionMode === "script";
   if (trackCircularImports) {
     if (visited.has(fileName)) {
@@ -312514,13 +313424,13 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       });
     };
     const importStep = (name) => {
-      var _a3;
+      var _a4;
       if (typeof name !== "string" || name.trim().length === 0) {
         throw new Error("importStep() requires a non-empty file path string");
       }
       const resolvedPath = resolveImportPath(fileName, name.trim());
       rejectPathTraversal("importStep", name, resolvedPath);
-      const ext = ((_a3 = resolvedPath.split(".").pop()) == null ? void 0 : _a3.toLowerCase()) ?? "";
+      const ext = ((_a4 = resolvedPath.split(".").pop()) == null ? void 0 : _a4.toLowerCase()) ?? "";
       if (ext !== "step" && ext !== "stp") {
         throw new Error(`importStep("${name}"): unsupported extension ".${ext}". Expected .step or .stp`);
       }
@@ -312549,7 +313459,39 @@ 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) => {
+      var _a4;
+      return (_a4 = options.debug) == null ? void 0 : _a4.call(options, "console", { level, args });
+    } : void 0);
+    const runtimeVerify = options.debug ? {
+      ...verify,
+      that(label, check2, message) {
+        var _a4, _b4;
+        (_a4 = options.debug) == null ? void 0 : _a4.call(options, "verify:that:start", { label });
+        const verifyStart = performance.now();
+        try {
+          return verify.that(label, check2, message);
+        } finally {
+          (_b4 = options.debug) == null ? void 0 : _b4.call(options, "verify:that:end", {
+            label,
+            ms: Number((performance.now() - verifyStart).toFixed(1))
+          });
+        }
+      },
+      equal(label, actual, expected, tolerance = 0, message) {
+        var _a4, _b4;
+        (_a4 = options.debug) == null ? void 0 : _a4.call(options, "verify:equal:start", { label, actual, expected, tolerance });
+        const verifyStart = performance.now();
+        try {
+          return verify.equal(label, actual, expected, tolerance, message);
+        } finally {
+          (_b4 = options.debug) == null ? void 0 : _b4.call(options, "verify:equal:end", {
+            label,
+            ms: Number((performance.now() - verifyStart).toFixed(1))
+          });
+        }
+      }
+    } : verify;
     setShowLabelsHighlight(highlight);
     const runtimeBindings = {
       box: trackedBox,
@@ -312690,7 +313632,8 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       jointsView,
       viewConfig,
       scene,
-      verify,
+      Viewport,
+      verify: runtimeVerify,
       spec,
       mock,
       gcode,
@@ -312828,8 +313771,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}").`
+      );
+    }
+    (_b3 = options.debug) == null ? void 0 : _b3.call(options, "executeFile:compile:start", { fileName, executionMode });
+    const compileStart = performance.now();
+    const compiled = compileScript(code, fileName, options);
+    (_c2 = options.debug) == null ? void 0 : _c2.call(options, "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") {
@@ -312855,12 +313811,20 @@ ${scriptCode}
       exports: executionMode === "module" && moduleCacheEntry ? moduleCacheEntry.exports : {}
     };
     const initialExportsRef = moduleValue.exports;
+    (_d2 = options.debug) == null ? void 0 : _d2.call(options, "executeFile:invoke:start", { fileName, executionMode });
+    const invokeStart = performance.now();
     const returnValue = withConstructorChainLockdown(
       () => runWithParamScope(
         scope,
         () => fn(moduleValue.exports, moduleValue, requireModule, fileName, dirnamePath(fileName), ...bindingValues)
       )
     );
+    (_e2 = options.debug) == null ? void 0 : _e2.call(options, "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) {
@@ -312899,12 +313863,14 @@ ${scriptCode}
     }
     return returnValue;
   } finally {
+    (_f = options.debug) == null ? void 0 : _f.call(options, "executeFile:end", { fileName, executionMode });
     if (trackCircularImports) {
       visited.delete(fileName);
     }
   }
 }
 function runScript(code, fileName = "main.forge.js", allFiles = {}, options = {}) {
+  var _a3, _b3;
   _collectedLogs = [];
   resetExecutionSession(_collectedLogs);
   const t0 = performance.now();
@@ -312913,14 +313879,25 @@ 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);
+  (_a3 = options.debug) == null ? void 0 : _a3.call(options, "runScript:start", { fileName, quality, fileCount: Object.keys(allFiles).length });
   try {
     return runWithForgeQuality(quality, () => {
+      var _a4, _b4, _c2, _d2, _e2, _f, _g, _h, _i, _j;
+      (_a4 = options.debug) == null ? void 0 : _a4.call(options, "runScript:execute:start", { fileName });
+      const executeStart = performance.now();
       const result = executeFile(code, fileName, allFiles, /* @__PURE__ */ new Set(), {}, execOptions);
+      (_b4 = options.debug) == null ? void 0 : _b4.call(options, "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();
+      (_c2 = options.debug) == null ? void 0 : _c2.call(options, "runScript:map:start", { highlights: highlights.length, mocks: mocks.length });
       const mapped = mapScriptResultToScene({
         result,
         fileName,
@@ -312929,24 +313906,43 @@ function runScript(code, fileName = "main.forge.js", allFiles = {}, options = {}
         mocks,
         logs: _collectedLogs
       });
+      (_d2 = options.debug) == null ? void 0 : _d2.call(options, "runScript:map:end", {
+        objects: mapped.objects.length,
+        hasShape: Boolean(mapped.shape),
+        hasSketch: Boolean(mapped.sketch),
+        hasError: Boolean(mapped.error)
+      });
+      (_e2 = options.debug) == null ? void 0 : _e2.call(options, "runScript:explodeHints:start", { objects: mapped.objects.length });
       autoFillExplodeHints(mapped.objects);
+      (_f = options.debug) == null ? void 0 : _f.call(options, "runScript:explodeHints:end");
+      (_g = options.debug) == null ? void 0 : _g.call(options, "runScript:snapshot:start", { objects: mapped.objects.length });
+      const snapshot = collectSuccessfulExecutionSnapshot({
+        quality,
+        objects: mapped.objects,
+        logs: _collectedLogs,
+        extraDimensions: mapped.extraDimensions,
+        highlights,
+        mocks
+      });
+      (_h = options.debug) == null ? void 0 : _h.call(options, "runScript:snapshot:end", {
+        params: snapshot.params.length,
+        cutPlanes: snapshot.cutPlanes.length,
+        verifications: snapshot.verifications.length
+      });
+      (_i = options.debug) == null ? void 0 : _i.call(options, "runScript:sceneTargets:start");
+      snapshot.sceneConfig = resolveSceneJourneyTargets(snapshot.sceneConfig, mapped.objects);
+      (_j = options.debug) == null ? void 0 : _j.call(options, "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) {
+    (_b3 = options.debug) == null ? void 0 : _b3.call(options, "runScript:error", { error: (e == null ? void 0 : e.message) || String(e) });
     const msg = e.message || String(e);
     const stack = e.stack || "";
     let lineInfo = "";