forgecad 0.9.16 → 0.10.0

package/dist-cli/forgecad.js

@@ -4,6 +4,7 @@ import {
   CLI_DEFAULT_BACKEND,
   COMPILER_REGRESSION_CORPUS,
   FILLET_EDGE_WORKFLOW_CODE,
+  Loft,
   MathUtils,
   OCCTUnsupportedError,
   Rectangle2D,
@@ -33,7 +34,6 @@ import {
   chamferTrackedEdge,
   circle2d,
   collectProjectFiles,
-  composeChain,
   constrainedSketch,
   cylinder,
   describeFaceQueryRef,
@@ -63,6 +63,7 @@ import {
   getLastSolveTrail,
   getShapeCompilePlan,
   getShapeDimensions,
+  getShapeLineageToken,
   getShapePrimaryQueryOwner,
   getShapeQueryOwners,
   getShapeRuntimeBackend,
@@ -126,7 +127,7 @@ import {
   union2d,
   updateConstraintValue,
   wrapOCCTShapeBackend
-} from "./chunk-SPZE3DUY.js";
+} from "./chunk-OAN5T4XD.js";
 
 // cli/forgecad.ts
 import { Command, Flags, Help, flush as flushOclif, handle as handleOclif, run as runOclif } from "@oclif/core";
@@ -234,6 +235,18 @@ function checkBooleanErrors() {
     /union2d\(\) argument 2: expected a Sketch, got undefined/
   );
 }
+function checkLoftFieldApiContract() {
+  const fieldLoft = Loft.field([circle2d(4, 32), roundedRect(8, 2, 0.5)], [0, 8], { edgeLength: 0.8, maxTriangles: 5e3 });
+  assert(fieldLoft.volume() > 0, "Loft.field() should build a positive-volume field loft");
+  assert.throws(
+    () => Loft.field([circle2d(4, 16), roundedRect(8, 2, 0.5)], [0, 8], { maxTriangles: 0.5 }),
+    /Loft\.field\(\) maxTriangles must be a positive integer/
+  );
+  assert.throws(
+    () => Loft.field([circle2d(4, 16), roundedRect(8, 2, 0.5)], [0, 8], { edgeLength: 1.2, maxTriangles: 1 }).volume(),
+    /above maxTriangles=1/
+  );
+}
 function checkEdgeFinishSubsetErrors() {
   const base = Rectangle2D.fromDimensions(-24, -16, 48, 32).extrude(18);
   const once2 = filletTrackedEdge(base, base.edge("vert-br"), 4, [-1, -1]);
@@ -340,7 +353,7 @@ function checkSculptApiContracts() {
     "Sculpt.tube() should return an SdfShape"
   );
   assert(
-    Sculpt.path(
+    Sculpt.tube(
       [
         [0, 0, 0, 2],
         [12, 0, 0, 5],
@@ -348,7 +361,7 @@ function checkSculptApiContracts() {
       ],
       { blend: 2 }
     ) instanceof SdfShape,
-    "Sculpt.path() should accept [x, y, z, radius] control points"
+    "Sculpt.tube() should accept [x, y, z, radius] control points"
   );
   assert(
     Sculpt.curve(
@@ -361,7 +374,7 @@ function checkSculptApiContracts() {
     ) instanceof SdfShape,
     "Sculpt.curve() should accept object control points and produce a smoothed variable sweep"
   );
-  assert(Sculpt.circle(8, 1.5) instanceof SdfShape, "Sculpt.circle() should return a thin circular SDF shape");
+  assert(Sculpt.disk(8, 1.5) instanceof SdfShape, "Sculpt.disk() should return a thin circular SDF shape");
   assert(
     Sculpt.blend([Sculpt.sphere(8), Sculpt.box(12, 8, 6, { radius: 2 })], { radius: 3 }).polish("ceramic") instanceof SdfShape,
     "Sculpt.blend([...], options).polish() should stay in SDF space"
@@ -379,7 +392,7 @@ scene(Sculpt.look('gallery'));
 return Sculpt
   .blend([
     Sculpt.curve([[0, 0, 0, 2], [8, 0, 6, 4], [16, 4, 0, 2]], { segments: 5 }),
-    Sculpt.box(10, 8, 6, { radius: 2 }).carve(Sculpt.circle(3, 8).tilt(90, 'x'), { radius: 1.2 }).at(8, 0, 0),
+    Sculpt.box(10, 8, 6, { radius: 2 }).carve(Sculpt.disk(3, 8).tilt(90, 'x'), { radius: 1.2 }).at(8, 0, 0),
   ], { radius: 3 })
   .polish('glass');
 `;
@@ -567,6 +580,7 @@ async function runCheckApiContractsCli() {
   checkTrackedShapeInterop();
   checkSketchBooleanForms();
   checkBooleanErrors();
+  checkLoftFieldApiContract();
   checkEdgeFinishSubsetErrors();
   checkSheetMetalApiContracts();
   checkSandboxBindings();
@@ -2085,7 +2099,7 @@ return [
   assert2.equal(facetedManifest.objects.length, 4, "Expected all segmented shapes to export as faceted objects");
   assert2.equal(facetedManifest.fallbacks.length, 4, "Expected faceted fallbacks for all segmented runtime-hint shapes");
 }
-function checkBroadNativeEdgeFinishesStayOutOfCadQueryExactSubset() {
+async function checkBroadNativeEdgeFinishesStayOutOfCadQueryExactSubset() {
   const files = {
     "main.forge.js": `
 const base = box(30, 20, 15);
@@ -2098,7 +2112,7 @@ return [
 `
   };
   const previousBackend = getActiveBackend();
-  setActiveBackend("truck");
+  await activateBackend("truck");
   let result = null;
   try {
     result = runScript(files["main.forge.js"], "main.forge.js", files);
@@ -2188,7 +2202,7 @@ async function runCheckBrepExportCli() {
   checkPlaneTrimAndSplitStayExactExportable();
   checkLoftAndSweepExportEndToEnd();
   checkSegmentedRuntimeHintsStayOutOfExactSubset();
-  checkBroadNativeEdgeFinishesStayOutOfCadQueryExactSubset();
+  await checkBroadNativeEdgeFinishesStayOutOfCadQueryExactSubset();
   console.log("\u2713 BREP export invariants passed");
 }
 runDirectCliMain(import.meta.url, "cli/check-brep-export.ts", () => runCheckBrepExportCli());
@@ -5387,6 +5401,10 @@ function applyViewportJointOverridesToResult(result, overrides) {
     objects: result.objects.map(transformObject)
   };
 }
+function formatJointNumber(value) {
+  const rounded = Number(value.toFixed(6));
+  return Object.is(rounded, -0) ? "0" : String(rounded);
+}
 
 // cli/joint-overrides.ts
 function parseJointFlags(argv) {
@@ -5414,6 +5432,57 @@ function applyCliJointOverrides(result, overrides) {
   return applyViewportJointOverridesToResult(result, overrides);
 }
 
+// cli/joint-sweep.ts
+var MAX_CLI_JOINT_SWEEP_SAMPLES = 101;
+var NUMBER_PATTERN = String.raw`[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?`;
+var SWEEP_PATTERN = new RegExp(String.raw`^\s*([^=]+?)\s*=\s*(${NUMBER_PATTERN})\s*\.\.\s*(${NUMBER_PATTERN})\s*:\s*(\d+)\s*$`);
+function normalizeSweepNumber(value) {
+  const rounded = Number(value.toPrecision(12));
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+function sampleCliJointSweepValues(start, end, samples) {
+  if (samples < 2) return [normalizeSweepNumber(start)];
+  return Array.from({ length: samples }, (_, index) => normalizeSweepNumber(start + (end - start) * index / (samples - 1)));
+}
+function parseCliJointSweep(raw, flag = "--joint-sweep") {
+  const match = SWEEP_PATTERN.exec(raw);
+  if (!match) {
+    throw new Error(`Invalid ${flag} format: "${raw}". Expected JointName=start..end:samples.`);
+  }
+  const joint2 = match[1].trim();
+  const start = Number(match[2]);
+  const end = Number(match[3]);
+  const samples = Number(match[4]);
+  if (!joint2) throw new Error(`${flag} joint name cannot be blank.`);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) throw new Error(`${flag} range values must be finite.`);
+  if (start === end) throw new Error(`${flag} range must span two different values.`);
+  if (!Number.isSafeInteger(samples) || samples < 2 || samples > MAX_CLI_JOINT_SWEEP_SAMPLES) {
+    throw new Error(`${flag} samples must be an integer between 2 and ${MAX_CLI_JOINT_SWEEP_SAMPLES}.`);
+  }
+  return {
+    raw,
+    joint: joint2,
+    start,
+    end,
+    samples,
+    values: sampleCliJointSweepValues(start, end, samples)
+  };
+}
+function describeCliJointSweep(sweep) {
+  return `${sweep.joint}=${formatJointNumber(sweep.start)}..${formatJointNumber(sweep.end)}:${sweep.samples}`;
+}
+function buildCliJointSweepPoses(sweep, baseOverrides = {}) {
+  return sweep.values.map((value, index) => ({
+    index: index + 1,
+    joint: sweep.joint,
+    value,
+    overrides: {
+      ...baseOverrides,
+      [sweep.joint]: value
+    }
+  }));
+}
+
 // cli/render-cli-inputs.ts
 import { existsSync as existsSync2, readFileSync as readFileSync4, statSync as statSync3 } from "fs";
 import { homedir } from "os";
@@ -5539,7 +5608,7 @@ function computeMeshInertia(mesh, massKg) {
 }
 
 // src/studio/project-files/importGraph.ts
-var FORGE_IMPORT_RE = /\b(?:importMesh|importStep|importSvgSketch|Import\.dxfSketch|compareWith)\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
+var FORGE_IMPORT_RE = /\b(?:importMesh|importStep|importSvgSketch|Import\.mesh|Import\.step|Import\.svgSketch|Import\.dxfSketch|compareWith)\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
 var REQUIRE_RE = /\brequire\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
 var ES_IMPORT_RE = /\bfrom\s+(?:"([^"]+)"|'([^']+)')/g;
 var VIRTUAL_MODULES = /* @__PURE__ */ new Set(["forgecad", "@forge/runtime", "@forgecad/runtime"]);
@@ -5556,6 +5625,9 @@ function extractImports(code) {
     importMesh: "forgeMesh",
     importStep: "forgeMesh",
     importSvgSketch: "forgeSvg",
+    "Import.mesh": "forgeMesh",
+    "Import.step": "forgeMesh",
+    "Import.svgSketch": "forgeSvg",
     "Import.dxfSketch": "forgeDxf",
     compareWith: "compareWith"
   };
@@ -5563,7 +5635,9 @@ function extractImports(code) {
   const forgeRe = new RegExp(FORGE_IMPORT_RE.source, FORGE_IMPORT_RE.flags);
   while ((m = forgeRe.exec(code)) !== null) {
     const path5 = m[1] ?? m[2];
-    const fn = m[0].match(/\b(importMesh|importStep|importSvgSketch|Import\.dxfSketch|compareWith)/)?.[1];
+    const fn = m[0].match(
+      /\b(importMesh|importStep|importSvgSketch|Import\.mesh|Import\.step|Import\.svgSketch|Import\.dxfSketch|compareWith)/
+    )?.[1];
     add2(path5, kindMap[fn] ?? "forgeMesh");
   }
   const reqRe = new RegExp(REQUIRE_RE.source, REQUIRE_RE.flags);
@@ -5673,7 +5747,7 @@ function replaceCliInputExtension(path5, newExt) {
   return path5 + newExt;
 }
 function buildDirectCadImportScript(fileName, kind) {
-  const importFn = kind === "step" ? "importStep" : "importMesh";
+  const importFn = kind === "step" ? "Import.step" : "Import.mesh";
   const importOptions = kind === "mesh" && extname(fileName).toLowerCase() === ".3mf" ? ", { separateObjects: true }" : "";
   const objectName = basename3(fileName);
   return [
@@ -7915,6 +7989,7 @@ Options:
   --param <Key=Value>             Override a script parameter value. Repeatable.
   -p <Key=Value>                  Shorthand for --param
   --joint <JointName=Value>        Override a Motion tab joint value. Repeatable.
+  --joint-sweep <Joint=-10..10:5>  Sweep one Motion tab joint for fit interference evidence.
   --size <px>                     Image size in pixels (default: ${DEFAULT_SIZE})
   --quality <default|live|high>   Mesh/render quality (default: default)
   --render-style <${RENDER_STYLE_LABEL}>
@@ -7992,6 +8067,7 @@ function parseInspectCli(argv, config = {}) {
   let cutawayPlaneSource = null;
   const paramOverrides = {};
   const jointOverrides = {};
+  let jointSweep = null;
   const setCutawayNormal = (normal, source) => {
     if (!cutaway) throw new Error(`${source} only works with cutaway inspection.`);
     if (cutawayPlaneSource) {
@@ -8012,6 +8088,12 @@ function parseInspectCli(argv, config = {}) {
       i += 1;
       continue;
     }
+    if (arg === "--joint-sweep") {
+      if (jointSweep) throw new Error("Pass --joint-sweep only once.");
+      jointSweep = parseCliJointSweep(readValue2(argv, i, arg), arg);
+      i += 1;
+      continue;
+    }
     if (arg === "--output" || arg === "--out") {
       flagOutputDir = readValue2(argv, i, arg);
       i += 1;
@@ -8301,6 +8383,12 @@ function parseInspectCli(argv, config = {}) {
   if (hasCompareOptions && !channels.includes("comparison")) {
     throw new Error("Comparison options only work with `forgecad inspect compare overlay`.");
   }
+  if (jointSweep && !channels.includes("collisions")) {
+    throw new Error("--joint-sweep only works with `forgecad inspect fit interference`.");
+  }
+  if (jointSweep && Object.prototype.hasOwnProperty.call(jointOverrides, jointSweep.joint)) {
+    throw new Error(`Pass either --joint ${jointSweep.joint}=... or --joint-sweep ${jointSweep.raw}, not both.`);
+  }
   if (sectionOptionsUsed && !channels.includes("section")) {
     throw new Error("Section options only work with `forgecad inspect sections`.");
   }
@@ -8375,6 +8463,7 @@ function parseInspectCli(argv, config = {}) {
     cutaway,
     paramOverrides,
     jointOverrides,
+    jointSweep,
     comparison: hasCompareOptions ? {
       compareWith,
       align: compareAlign,
@@ -8623,6 +8712,70 @@ function buildViewPathEntries(pathsByView) {
     ])
   );
 }
+function collisionSweepPoseKey(pose) {
+  return `pose-${String(pose.index).padStart(3, "0")}`;
+}
+function buildCollisionSweepSummary(options, poseResults) {
+  const sweep = options.jointSweep;
+  const poses = poseResults.map(({ pose, result }) => {
+    const collisions = result.collisions ?? {};
+    return {
+      index: pose.index,
+      joint: pose.joint,
+      value: pose.value,
+      overrides: pose.overrides,
+      collisionCount: collisions.collisionCount ?? 0,
+      candidatePairCount: collisions.candidatePairCount ?? 0,
+      testedPairCount: collisions.testedPairCount ?? 0,
+      skippedPairCount: collisions.skippedPairCount ?? 0,
+      warnings: collisions.warnings ?? [],
+      collisions: collisions.collisions ?? [],
+      views: collisions.views ?? {}
+    };
+  });
+  const worstCollisions = poses.flatMap(
+    (pose) => pose.collisions.map((collision) => ({
+      poseIndex: pose.index,
+      joint: pose.joint,
+      value: pose.value,
+      collision
+    }))
+  ).sort((a, b) => (b.collision.overlapVolume ?? 0) - (a.collision.overlapVolume ?? 0)).slice(0, 10);
+  const maxCollisionCount = poses.reduce((max, pose) => Math.max(max, pose.collisionCount), 0);
+  const maxOverlapVolume = worstCollisions[0]?.collision?.overlapVolume ?? 0;
+  return {
+    method: "cli-joint-sweep-v1",
+    status: maxCollisionCount > 0 ? "fail" : "pass",
+    expression: describeCliJointSweep(sweep),
+    rawExpression: sweep.raw,
+    joint: sweep.joint,
+    start: sweep.start,
+    end: sweep.end,
+    sampleCount: sweep.samples,
+    values: sweep.values,
+    baseOverrides: options.jointOverrides ?? {},
+    poseCount: poses.length,
+    collidingPoseCount: poses.filter((pose) => pose.collisionCount > 0).length,
+    maxCollisionCount,
+    maxOverlapVolume,
+    worstCollisions,
+    warnings: Array.from(new Set(poses.flatMap((pose) => pose.warnings))),
+    poses
+  };
+}
+function buildCollisionSweepManifest(sweep, emittedSweepPaths) {
+  if (!sweep) return null;
+  return {
+    ...sweep,
+    poses: sweep.poses.map((pose) => {
+      const { views: _rawViews, ...rest } = pose;
+      return {
+        ...rest,
+        views: buildViewPathEntries(emittedSweepPaths?.[collisionSweepPoseKey(pose)])
+      };
+    })
+  };
+}
 function collectInspectViewNames(emittedPaths) {
   const names = [];
   const add2 = (value) => {
@@ -8939,11 +9092,14 @@ function buildInspectManifest({ options, result, scriptPath, projectRoot, emitte
     };
   }
   if (emittedPaths.collisions) {
+    const jointSweep = buildCollisionSweepManifest(result.collisions?.jointSweep, emittedPaths.collisionSweep);
+    const collisionStatus = jointSweep ? (result.collisions?.collisionCount ?? 0) > 0 || jointSweep.status === "fail" ? "fail" : "pass" : null;
     evidence.collisions = {
       format: "png",
       encoding: "rgb8-collision-highlight",
       backgroundColor: [0, 0, 0],
       decode: "source objects are translucent ghost geometry; boolean intersection volumes use per-finding collisions[].color palette entries",
+      ...collisionStatus ? { status: collisionStatus } : {},
       method: result.collisions?.method,
       options: result.collisions?.options,
       broadphase: result.collisions?.broadphase,
@@ -8960,6 +9116,7 @@ function buildInspectManifest({ options, result, scriptPath, projectRoot, emitte
       objects: result.collisions?.objects ?? [],
       collisions: result.collisions?.collisions ?? [],
       warnings: result.collisions?.warnings ?? [],
+      ...jointSweep ? { jointSweep } : {},
       views: buildViewPathEntries(emittedPaths.collisions)
     };
   }
@@ -9493,81 +9650,85 @@ async function runInspectBundleCli(argv, config) {
       await page.goto(url, { waitUntil: "networkidle0", timeout: 15e3 });
       await page.waitForFunction("window.__forgeReady === true", { timeout: RENDER_READY_TIMEOUT_MS });
       await page.exposeFunction("__forgeInspectProgress", logInspectProgress);
-      const result = await page.evaluate(
-        (scriptCode, files, scriptName, renderOptions) => {
+      const baseRenderOptions = {
+        cameras: options.cameras,
+        size: options.size,
+        quality: options.quality,
+        binaryFiles,
+        activeBackend,
+        cameraSpec: options.cameraSpec || null,
+        viewName: options.viewName || null,
+        sceneSpec: options.sceneSpec || null,
+        background: options.background || null,
+        focus: options.focus || null,
+        hide: options.hide || null,
+        renderStyle: options.renderStyle,
+        edges: options.edges,
+        paramOverrides: options.paramOverrides
+      };
+      const renderInspectInBrowser = (renderOptions) => page.evaluate(
+        (scriptCode, files, scriptName, browserRenderOptions) => {
           return window.__forgeRender(scriptCode, {
-            cameras: renderOptions.cameras,
-            size: renderOptions.size,
-            quality: renderOptions.quality,
-            channels: renderOptions.channels,
+            cameras: browserRenderOptions.cameras,
+            size: browserRenderOptions.size,
+            quality: browserRenderOptions.quality,
+            channels: browserRenderOptions.channels,
             allFiles: files,
             fileName: scriptName,
-            binaryFiles: renderOptions.binaryFiles,
-            activeBackend: renderOptions.activeBackend,
-            cameraSpec: renderOptions.cameraSpec,
-            viewName: renderOptions.viewName,
-            sceneSpec: renderOptions.sceneSpec,
-            background: renderOptions.background,
-            focus: renderOptions.focus,
-            hide: renderOptions.hide,
-            thickness: renderOptions.thickness,
-            roughness: renderOptions.roughness,
-            sectionPlan: renderOptions.sectionPlan,
-            cutaway: renderOptions.cutaway,
-            comparison: renderOptions.comparison,
+            binaryFiles: browserRenderOptions.binaryFiles,
+            activeBackend: browserRenderOptions.activeBackend,
+            cameraSpec: browserRenderOptions.cameraSpec,
+            viewName: browserRenderOptions.viewName,
+            sceneSpec: browserRenderOptions.sceneSpec,
+            background: browserRenderOptions.background,
+            focus: browserRenderOptions.focus,
+            hide: browserRenderOptions.hide,
+            thickness: browserRenderOptions.thickness,
+            roughness: browserRenderOptions.roughness,
+            sectionPlan: browserRenderOptions.sectionPlan,
+            cutaway: browserRenderOptions.cutaway,
+            comparison: browserRenderOptions.comparison,
             progress: "inspect",
             renderMode: "solid",
-            edges: renderOptions.edges,
-            renderStyle: renderOptions.renderStyle,
+            edges: browserRenderOptions.edges,
+            renderStyle: browserRenderOptions.renderStyle,
             respectAuthoredSceneStyle: false,
-            paramOverrides: renderOptions.paramOverrides,
-            jointOverrides: renderOptions.jointOverrides
+            paramOverrides: browserRenderOptions.paramOverrides,
+            jointOverrides: browserRenderOptions.jointOverrides
           });
         },
         input.code,
         input.allFiles,
         input.fileName,
-        {
-          cameras: options.cameras,
-          size: options.size,
-          quality: options.quality,
-          channels: options.channels,
-          binaryFiles,
-          activeBackend,
-          cameraSpec: options.cameraSpec || null,
-          viewName: options.viewName || null,
-          sceneSpec: options.sceneSpec || null,
-          background: options.background || null,
-          focus: options.focus || null,
-          hide: options.hide || null,
-          thickness: options.thickness,
-          roughness: options.roughness,
-          sectionPlan: options.sectionPlan,
-          cutaway: options.cutaway,
-          renderStyle: options.renderStyle,
-          edges: options.edges,
-          paramOverrides: options.paramOverrides,
-          jointOverrides: options.jointOverrides,
-          comparison: comparisonInput ? {
-            code: comparisonInput.code,
-            allFiles: comparisonInput.allFiles,
-            fileName: comparisonInput.fileName,
-            binaryFiles: comparisonBinaryFiles,
-            activeBackend: comparisonActiveBackend,
-            displayPath: options.comparison.compareWith,
-            sourcePath: comparisonInput.sourcePath,
-            align: options.comparison.align,
-            view: options.comparison.view,
-            samples: options.comparison.samples,
-            toleranceMm: options.comparison.toleranceMm
-          } : options.comparison ? {
-            align: options.comparison.align,
-            view: options.comparison.view,
-            samples: options.comparison.samples,
-            toleranceMm: options.comparison.toleranceMm
-          } : null
-        }
+        renderOptions
       );
+      const result = await renderInspectInBrowser({
+        ...baseRenderOptions,
+        channels: options.channels,
+        thickness: options.thickness,
+        roughness: options.roughness,
+        sectionPlan: options.sectionPlan,
+        cutaway: options.cutaway,
+        jointOverrides: options.jointOverrides,
+        comparison: comparisonInput ? {
+          code: comparisonInput.code,
+          allFiles: comparisonInput.allFiles,
+          fileName: comparisonInput.fileName,
+          binaryFiles: comparisonBinaryFiles,
+          activeBackend: comparisonActiveBackend,
+          displayPath: options.comparison.compareWith,
+          sourcePath: comparisonInput.sourcePath,
+          align: options.comparison.align,
+          view: options.comparison.view,
+          samples: options.comparison.samples,
+          toleranceMm: options.comparison.toleranceMm
+        } : options.comparison ? {
+          align: options.comparison.align,
+          view: options.comparison.view,
+          samples: options.comparison.samples,
+          toleranceMm: options.comparison.toleranceMm
+        } : null
+      });
       if (!result.ok) {
         console.error("Script error:", result.error);
         process.exit(1);
@@ -9605,6 +9766,33 @@ async function runInspectBundleCli(argv, config) {
           }
         }
       }
+      if (options.jointSweep && requested.has("collisions")) {
+        const sweepPoses = buildCliJointSweepPoses(options.jointSweep, options.jointOverrides);
+        const poseResults = [];
+        console.log(`[inspect] Sweeping joint: ${describeCliJointSweep(options.jointSweep)}`);
+        for (const pose of sweepPoses) {
+          console.log(`[inspect] Sweep pose ${pose.index}/${sweepPoses.length}: ${pose.joint}=${pose.value}`);
+          const sweepResult = await renderInspectInBrowser({
+            ...baseRenderOptions,
+            channels: ["collisions"],
+            thickness: {},
+            roughness: {},
+            sectionPlan: null,
+            cutaway: null,
+            comparison: null,
+            jointOverrides: pose.overrides
+          });
+          if (!sweepResult.ok) {
+            console.error("Script error:", sweepResult.error);
+            process.exit(1);
+          }
+          poseResults.push({ pose, result: sweepResult });
+        }
+        result.collisions = {
+          ...result.collisions ?? {},
+          jointSweep: buildCollisionSweepSummary(options, poseResults)
+        };
+      }
       const emittedPaths = {};
       const writeViewChannel = async (channel, source, getPng = (entry) => entry) => {
         const label = displayInspectChannel(channel, options);
@@ -9678,6 +9866,25 @@ async function runInspectBundleCli(argv, config) {
       }
       if (requested.has("collisions")) {
         await writeViewChannel("collisions", result.collisions?.views);
+        if (result.collisions?.jointSweep) {
+          console.log("[inspect] Writing fit interference joint sweep files...");
+          emittedPaths.collisionSweep = {};
+          for (const pose of result.collisions.jointSweep.poses) {
+            const poseKey = collisionSweepPoseKey(pose);
+            emittedPaths.collisionSweep[poseKey] = {};
+            const usedFileStems = /* @__PURE__ */ new Set();
+            for (const [view, png] of Object.entries(pose.views ?? {})) {
+              if (!png) throw new Error(`Renderer did not emit required joint sweep collision view: ${poseKey}/${view}`);
+              const relPath = toPortablePath(
+                join4("evidence", "collisions", "sweep", poseKey, `${sanitizeViewFileStem(view, usedFileStems)}.png`)
+              );
+              await mkdir(dirname(join4(tempDir, relPath)), { recursive: true });
+              await writeFile(join4(tempDir, relPath), pngBufferFromDataUrl(png));
+              emittedPaths.collisionSweep[poseKey][view] = relPath;
+            }
+          }
+          console.log("[inspect] Wrote fit interference joint sweep files.");
+        }
       }
       if (requested.has("thickness")) {
         await writeViewChannel("thickness", result.thickness?.views);
@@ -9734,6 +9941,15 @@ async function runInspectBundleCli(argv, config) {
       printFramingWarnings(result.framing);
       console.log(`  Size:     ${sz[0]} \xD7 ${sz[1]} \xD7 ${sz[2]} mm`);
       console.log(`  Volume:   ${result.volume.toFixed(1)} mm\xB3`);
+      if (manifest.evidence?.collisions?.jointSweep) {
+        const sweep = manifest.evidence.collisions.jointSweep;
+        console.log(
+          `  Joint sweep: ${sweep.status} (${sweep.collidingPoseCount}/${sweep.poseCount} colliding pose(s), max ${sweep.maxCollisionCount} collision(s))`
+        );
+      }
+      if (options.jointSweep && manifest.evidence?.collisions?.status === "fail") {
+        process.exitCode = 1;
+      }
     } finally {
       await browser.close();
     }
@@ -9813,7 +10029,7 @@ function writeParentImportFixture(root, withManifest) {
     resolve9(root, "part/finger.forge.js"),
     `
 const pose = Param.choice("Static Pose", "open-display", ["open-display", "curl"]);
-const showStaticTendons = boolParam("Show Static Tendons", true);
+const showStaticTendons = Param.bool("Show Static Tendons", true);
 
 return box(pose === "curl" ? 8 : 10, showStaticTendons ? 6 : 4, 3);
 `,
@@ -12261,15 +12477,29 @@ function pairKey(a, b) {
 }
 function resolveIntentionalOverlaps(allowances, entries, findings) {
   const entryByShape = /* @__PURE__ */ new Map();
-  for (const entry of entries) entryByShape.set(entry.shape, entry);
+  const entriesByLineage = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    entryByShape.set(entry.shape, entry);
+    const token = getShapeLineageToken(entry.shape);
+    const lineageEntries = entriesByLineage.get(token) ?? [];
+    lineageEntries.push(entry);
+    entriesByLineage.set(token, lineageEntries);
+  }
   const findingByPair = /* @__PURE__ */ new Map();
   for (const finding2 of findings) {
     findingByPair.set(pairKey(finding2.sourceId, finding2.targetId), finding2);
   }
+  const resolveVisibleEntry = (shape) => {
+    const exact = entryByShape.get(shape);
+    if (exact) return exact;
+    if (!shape || typeof shape !== "object") return void 0;
+    const lineageEntries = entriesByLineage.get(getShapeLineageToken(shape)) ?? [];
+    return lineageEntries.length === 1 ? lineageEntries[0] : void 0;
+  };
   const allowedCollisionKeys = /* @__PURE__ */ new Set();
   const reports = allowances.map((allowance) => {
-    const source = entryByShape.get(allowance.a);
-    const target = entryByShape.get(allowance.b);
+    const source = resolveVisibleEntry(allowance.a);
+    const target = resolveVisibleEntry(allowance.b);
     const base = {
       label: allowance.label,
       reason: allowance.reason,
@@ -16737,7 +16967,51 @@ var SKILL_SUPPRESSED_RUNTIME_NAMES = /* @__PURE__ */ new Set([
   "nurbs3d",
   "spline3d",
   "transitionCurve",
-  "transitionSurface"
+  "transitionSurface",
+  // Lean-API sweep (2026-06): soft-deprecated globals (legacy.md) and
+  // hard-removed throwing stubs. Still reserved in human-authored scripts,
+  // never taught to agents.
+  "assemblyInstructions",
+  "assemblyPreview",
+  "bomToCsv",
+  "boolParam",
+  "chamferTrackedEdge",
+  "choiceParam",
+  "circle",
+  "combine",
+  "COMMON_KERFS",
+  "composeChain",
+  "Constraint",
+  "Counterbore",
+  "degrees",
+  "dimLine",
+  "filletCorners",
+  "filletTrackedEdge",
+  "fingerJoint",
+  "flatPanel",
+  "flatPart",
+  "formatInstructions",
+  "highlight",
+  "importMesh",
+  "importStep",
+  "importSvgSketch",
+  "jointsView",
+  "laserKit",
+  "line",
+  "listParam",
+  "lookupKerf",
+  "nurbsSurface",
+  "point",
+  "ProductHandleBuilder",
+  "ProductHandleFeature",
+  "ProductSpoutBuilder",
+  "radians",
+  "Ribs",
+  "Slot",
+  "star",
+  "surfacePatch",
+  "tabSlot",
+  "viewConfig"
 ]);
 function checkRuntimeNamesDoc(runtimeNames) {
   const collisionReservedNames = runtimeNames.filter((name) => name !== "showLabels");
@@ -21912,7 +22186,7 @@ function computeLinkFrameWorlds(assembly2, jointValues) {
   const visit = (partName, world) => {
     worlds.set(partName, world);
     (jointsByParent.get(partName) ?? []).forEach((joint2) => {
-      const childWorld = composeChain(motionTransform(joint2, jointValues[joint2.name] ?? joint2.defaultValue), joint2.frame, world);
+      const childWorld = Transform.compose(motionTransform(joint2, jointValues[joint2.name] ?? joint2.defaultValue), joint2.frame, world);
       visit(joint2.child, childWorld);
     });
   };
@@ -23667,7 +23941,7 @@ import http from "http";
 import path3 from "path";
 
 // server/importAnalysis.ts
-var FORGE_IMPORT_RE2 = /\b(?:importMesh|importStep|importSvgSketch|Import\.dxfSketch)\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
+var FORGE_IMPORT_RE2 = /\b(?:importMesh|importStep|importSvgSketch|Import\.mesh|Import\.step|Import\.svgSketch|Import\.dxfSketch)\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
 var REQUIRE_RE2 = /\brequire\s*\(\s*(?:"([^"]+)"|'([^']+)')/g;
 var ES_IMPORT_RE2 = /\bfrom\s+(?:"([^"]+)"|'([^']+)')/g;
 var VIRTUAL_MODULES2 = /* @__PURE__ */ new Set(["forgecad", "@forge/runtime", "@forgecad/runtime"]);
@@ -23684,13 +23958,16 @@ function extractImports2(code) {
     importMesh: "forgeMesh",
     importStep: "forgeMesh",
     importSvgSketch: "forgeSvg",
+    "Import.mesh": "forgeMesh",
+    "Import.step": "forgeMesh",
+    "Import.svgSketch": "forgeSvg",
     "Import.dxfSketch": "forgeDxf"
   };
   let m;
   const forgeRe = new RegExp(FORGE_IMPORT_RE2.source, FORGE_IMPORT_RE2.flags);
   while ((m = forgeRe.exec(code)) !== null) {
     const path5 = m[1] ?? m[2];
-    const fn = m[0].match(/\b(importMesh|importStep|importSvgSketch|Import\.dxfSketch)/)?.[1];
+    const fn = m[0].match(/\b(importMesh|importStep|importSvgSketch|Import\.mesh|Import\.step|Import\.svgSketch|Import\.dxfSketch)/)?.[1];
     add2(path5, kindMap[fn] ?? "forgeMesh");
   }
   const reqRe = new RegExp(REQUIRE_RE2.source, REQUIRE_RE2.flags);
@@ -24176,11 +24453,39 @@ function requireCliAuth() {
 }
 
 // cli/project.ts
-var SOURCE_EXTS = [".forge.js", ".js", ".svg", ".dxf"];
+var SOURCE_EXTS = [
+  ".forge.js",
+  ".sketch.js",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".json",
+  ".md",
+  ".txt",
+  ".svg",
+  ".dxf",
+  ".html",
+  ".css",
+  ".scss",
+  ".yml",
+  ".yaml",
+  ".toml",
+  ".xml",
+  ".csv",
+  ".ini"
+];
 var MESH_EXTS = [".stl", ".obj", ".3mf"];
 var ALL_EXTS = [...SOURCE_EXTS, ...MESH_EXTS];
+var SKIPPED_PROJECT_DIRECTORY_NAMES = /* @__PURE__ */ new Set([".next", ".turbo", "build", "coverage", "dist", "node_modules"]);
 function isSourceFile(name) {
-  return SOURCE_EXTS.some((ext) => name.endsWith(ext));
+  const lower2 = name.toLowerCase();
+  return SOURCE_EXTS.some((ext) => lower2.endsWith(ext));
+}
+function shouldSkipProjectDirectory(name) {
+  return name.startsWith(".") || SKIPPED_PROJECT_DIRECTORY_NAMES.has(name);
 }
 var MANIFEST_FILE2 = "forgecad.json";
 function manifestPath(projectDir) {
@@ -24219,8 +24524,9 @@ function scanLocalFiles(projectDir) {
       const rel = prefix ? `${prefix}/${item.name}` : item.name;
       const full = join10(dir, item.name);
       if (item.isDirectory()) {
+        if (shouldSkipProjectDirectory(item.name)) continue;
         walk(full, rel);
-      } else if (item.isFile() && isSourceFile(item.name)) {
+      } else if (item.isFile() && rel !== MANIFEST_FILE2 && isSourceFile(item.name)) {
         const content = readFileSync17(full, "utf-8");
         files.push({ path: rel, content, hash: contentHash(content) });
       }
@@ -24440,7 +24746,7 @@ import { existsSync as existsSync13, readdirSync as readdirSync8, statSync as st
 import { createServer as createServer2 } from "net";
 import { join as join11 } from "path";
 var startedComputeServer = null;
-var REQUIRED_ENGINE_VERSION = "native-occt-node-api-0.2.0";
+var REQUIRED_ENGINE_VERSION = "native-occt-node-api-0.3.0";
 var REQUIRED_PLAN_KINDS = [
   "box",
   "cylinder",
@@ -24461,7 +24767,11 @@ function npmCommand() {
   return process.platform === "win32" ? "npm.cmd" : "npm";
 }
 function isLocalComputeUrl(url) {
-  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  const hostname = listenHostForUrl(url);
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+function listenHostForUrl(url) {
+  return url.hostname.replace(/^\[|\]$/g, "");
 }
 async function isHealthy(computeUrl) {
   try {
@@ -24525,6 +24835,7 @@ function computeUrlWithPort(url, port) {
   return next.toString().replace(/\/$/, "");
 }
 async function pickComputeUrl(preferred) {
+  const listenHost = listenHostForUrl(preferred);
   const preferredPort = Number.parseInt(preferred.port || (preferred.protocol === "https:" ? "443" : "80"), 10);
   for (let port = preferredPort; port < preferredPort + 10; port += 1) {
     const candidate = computeUrlWithPort(preferred, port);
@@ -24533,7 +24844,7 @@ async function pickComputeUrl(preferred) {
       const server = await new Promise((resolve40, reject) => {
         const probe = createServer2();
         probe.once("error", reject);
-        probe.listen(port, preferred.hostname, () => resolve40(probe));
+        probe.listen(port, listenHost, () => resolve40(probe));
       });
       await new Promise((resolve40) => server.close(() => resolve40()));
       return candidate;
@@ -24574,10 +24885,11 @@ function startLocalNativeComputeServer(options) {
     const computeUrl = await pickComputeUrl(parsed);
     const selected = new URL(computeUrl);
     const port = selected.port || (selected.protocol === "https:" ? "443" : "80");
+    const host = listenHostForUrl(selected);
     console.log(`[compute] Starting native OCCT backend at ${computeUrl}`);
     const child = spawn3("npx", ["tsx", "apps/backend/src/server.ts"], {
       cwd: options.packageRoot,
-      env: { ...process.env, FORGE_BACKEND_PORT: port },
+      env: { ...process.env, FORGE_BACKEND_PORT: port, FORGE_BACKEND_HOST: host },
       stdio: ["ignore", "inherit", "inherit"]
     });
     await waitForHealthy(computeUrl, child);
@@ -24876,12 +25188,42 @@ function updateLocalAgentContextLatestBundle(projectRoot, filePath, latestBundle
 }
 
 // cli/forge-studio-server.ts
-var PROJECT_FILE_EXTS = [".forge.js", ".js", ".svg", ".dxf"];
-var isProjectFile = (name) => PROJECT_FILE_EXTS.some((ext) => name.endsWith(ext));
+var PROJECT_FILE_EXTS = [
+  ".forge.js",
+  ".sketch.js",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".json",
+  ".md",
+  ".txt",
+  ".svg",
+  ".dxf",
+  ".html",
+  ".css",
+  ".scss",
+  ".yml",
+  ".yaml",
+  ".toml",
+  ".xml",
+  ".csv",
+  ".ini"
+];
+var isProjectFile = (name) => {
+  const lower2 = name.toLowerCase();
+  return PROJECT_FILE_EXTS.some((ext) => lower2.endsWith(ext));
+};
 var MESH_FILE_EXTS = [".stl", ".obj", ".3mf"];
 var EXACT_IMPORT_FILE_EXTS = [".step", ".stp"];
 var BINARY_PROJECT_FILE_EXTS = [...MESH_FILE_EXTS, ...EXACT_IMPORT_FILE_EXTS];
 var isBinaryProjectFile = (name) => BINARY_PROJECT_FILE_EXTS.some((ext) => name.toLowerCase().endsWith(ext));
+var SKIPPED_PROJECT_DIRECTORY_NAMES2 = /* @__PURE__ */ new Set([".next", ".turbo", "build", "coverage", "dist", "node_modules"]);
+var shouldSkipProjectDirectory2 = (name) => name.startsWith(".") || SKIPPED_PROJECT_DIRECTORY_NAMES2.has(name);
+var LOCAL_PROJECT_MANIFEST_FILE = "forgecad.json";
+var isLocalProjectManifestPath = (rel) => rel.toLowerCase() === LOCAL_PROJECT_MANIFEST_FILE;
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -24965,9 +25307,10 @@ function scanProjectFiles(projectDir) {
       if (item.name.startsWith(".")) continue;
       const rel = prefix ? `${prefix}/${item.name}` : item.name;
       if (item.isDirectory()) {
+        if (shouldSkipProjectDirectory2(item.name)) continue;
         folderSet.add(rel);
         scan(path3.join(dir, item.name), rel);
-      } else if (item.isFile() && isProjectFile(item.name)) {
+      } else if (item.isFile() && !isLocalProjectManifestPath(rel) && isProjectFile(item.name)) {
         files[rel] = fs2.readFileSync(path3.join(dir, item.name), "utf-8");
       } else if (item.isFile() && isBinaryProjectFile(item.name)) {
         files[rel] = "";
@@ -24989,9 +25332,10 @@ function scanProjectFileListing(projectDir) {
       if (item.name.startsWith(".")) continue;
       const rel = prefix ? `${prefix}/${item.name}` : item.name;
       if (item.isDirectory()) {
+        if (shouldSkipProjectDirectory2(item.name)) continue;
         folders.push(rel);
         scan(path3.join(dir, item.name), rel);
-      } else if (item.isFile() && (isProjectFile(item.name) || isBinaryProjectFile(item.name))) {
+      } else if (item.isFile() && !isLocalProjectManifestPath(rel) && (isProjectFile(item.name) || isBinaryProjectFile(item.name))) {
         files.push(rel);
       }
     }
@@ -25012,6 +25356,7 @@ function resolveProjectFile(projectDir, filename, opts = {}) {
   if (rel.startsWith("..") || path3.isAbsolute(rel)) {
     throw new Error(`Path "${filename}" is outside the project root`);
   }
+  if (isLocalProjectManifestPath(rel.replace(/\\/g, "/"))) throw new Error("Project manifest is not editable");
   return { filePath, filename: rel.replace(/\\/g, "/") };
 }
 function resolveProjectDirectory(projectDir, dirPath) {
@@ -25025,17 +25370,6 @@ function resolveProjectDirectory(projectDir, dirPath) {
   }
   return { dirPath: resolved, dirname: rel.replace(/\\/g, "/") };
 }
-function directoryTreeContainsFile(dirPath) {
-  for (const item of fs2.readdirSync(dirPath, { withFileTypes: true })) {
-    const childPath2 = path3.join(dirPath, item.name);
-    if (item.isDirectory()) {
-      if (directoryTreeContainsFile(childPath2)) return true;
-    } else {
-      return true;
-    }
-  }
-  return false;
-}
 function serveStatic(distDir, req, res) {
   const absDistDir = path3.resolve(distDir);
   const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
@@ -25171,10 +25505,14 @@ data: ${JSON.stringify(data)}
   }
   for (const proj of projects) {
     const abs = path3.resolve(proj.dir);
-    const watcher = chokidar.watch(abs, { ignoreInitial: true, ignored: /(^|[/\\])\../ });
+    const watcher = chokidar.watch(abs, {
+      ignoreInitial: true,
+      ignored: (candidate) => path3.relative(abs, candidate).split(/[\\/]/).some(shouldSkipProjectDirectory2)
+    });
     watcherReadyPromises.push(waitForWatcherReady(watcher));
     watcher.on("add", (f2) => {
       const rel = path3.relative(abs, f2).replace(/\\/g, "/");
+      if (isLocalProjectManifestPath(rel)) return;
       if (isProjectFile(f2)) {
         try {
           broadcastToProject(proj.id, "change", { filename: rel, content: fs2.readFileSync(f2, "utf-8") });
@@ -25186,6 +25524,7 @@ data: ${JSON.stringify(data)}
     });
     watcher.on("change", (f2) => {
       const rel = path3.relative(abs, f2).replace(/\\/g, "/");
+      if (isLocalProjectManifestPath(rel)) return;
       if (isProjectFile(f2)) {
         try {
           broadcastToProject(proj.id, "change", { filename: rel, content: fs2.readFileSync(f2, "utf-8") });
@@ -25196,8 +25535,10 @@ data: ${JSON.stringify(data)}
       }
     });
     watcher.on("unlink", (f2) => {
+      const rel = path3.relative(abs, f2).replace(/\\/g, "/");
+      if (isLocalProjectManifestPath(rel)) return;
       if (!isProjectFile(f2) && !isBinaryProjectFile(f2)) return;
-      broadcastToProject(proj.id, "delete", { filename: path3.relative(abs, f2).replace(/\\/g, "/") });
+      broadcastToProject(proj.id, "delete", { filename: rel });
       broadcastProjectSnapshot(proj);
     });
     watcher.on("addDir", () => broadcastProjectSnapshot(proj));
@@ -25604,10 +25945,6 @@ data: ${JSON.stringify(data)}
             sendJson(res, 400, { error: "Path is not a directory" });
             return;
           }
-          if (directoryTreeContainsFile(resolved.dirPath)) {
-            sendJson(res, 409, { error: "Directory is not empty" });
-            return;
-          }
           fs2.rmSync(resolved.dirPath, { recursive: true, force: true });
           sendJson(res, 200, { success: true });
         }).catch((e) => sendJson(res, 500, { error: e.message }));
@@ -26428,7 +26765,7 @@ function computeLinkFrameWorlds2(assembly2, jointValues) {
   const visit = (partName, world) => {
     worlds.set(partName, world);
     (jointsByParent.get(partName) ?? []).forEach((joint2) => {
-      const childWorld = composeChain(motionTransform2(joint2, jointValues[joint2.name] ?? joint2.defaultValue), joint2.frame, world);
+      const childWorld = Transform.compose(motionTransform2(joint2, jointValues[joint2.name] ?? joint2.defaultValue), joint2.frame, world);
       visit(joint2.child, childWorld);
     });
   };
@@ -31469,6 +31806,23 @@ var RENDER_OPTIONS = [
   },
   { name: "--output", description: "Output file path", argument: "required", valueLabel: "<path>", valueKind: "png" }
 ];
+var RENDER_MODEL_OPTIONS = [
+  ...RENDER_OPTIONS,
+  {
+    name: "--quality",
+    description: "Mesh quality preset",
+    argument: "required",
+    valueLabel: "<default|live|high>",
+    values: QUALITY_VALUES
+  },
+  {
+    name: "--backend",
+    description: "Geometry backend (default: manifold; STEP inputs default to OCCT)",
+    argument: "required",
+    valueLabel: "<manifold|occt|truck>",
+    values: BACKEND_VALUES
+  }
+];
 var LS_OPTIONS = [
   { name: "--tree", description: "Print targets as a compact object tree" },
   { name: "--long", description: "Include geometry metrics such as bounds, volume, area, bodies, and triangle counts" },
@@ -31516,6 +31870,12 @@ var SHOW_OPTIONS = [
 ];
 var INSPECT_EVIDENCE_OPTIONS = [
   ...PARAM_OPTIONS,
+  {
+    name: "--joint-sweep",
+    description: "Sweep one Motion tab joint for fit interference evidence",
+    argument: "required",
+    valueLabel: "<JointName=start..end:samples>"
+  },
   {
     name: "--output",
     description: "Preferred output bundle directory; a non-colliding sibling is created if needed",
@@ -31707,6 +32067,9 @@ function inspectEvidenceOptions(definition) {
   if (definition.channel === "roughness") {
     names.add("--roughness-samples");
   }
+  if (definition.channel === "collisions") {
+    names.add("--joint-sweep");
+  }
   if (definition.channel === "comparison") {
     for (const name of ["--with", "--compare-with", "--compare-align", "--compare-view", "--compare-samples", "--compare-tolerance-mm"]) {
       names.add(name);
@@ -32591,23 +32954,16 @@ var commands = [
     group: "Modeling",
     path: ["run"],
     summary: "Execute a Forge script quickly and print the inner-loop build summary: build count, verification results, parameters, and timing.",
-    description: "The fast validation command. Runs your script with the real geometry kernel (no browser needed) and reports whether it built, how many objects came back, any `verify.*` results, parameter values, script logs, and elapsed script time. This is the command agents should run frequently while editing a model.\n\n**Fast by default** \u2014 a bare `forgecad run model.forge.js` does not compute per-object volumes, bounding boxes, construction history, feature tallies, or solver profiles. Those run diagnostics are useful, but they are no longer part of the hot path.\n\n**Opt-in diagnostics** \u2014 use `--details` for volume/bounding-box/object geometry summaries, `--history` for the construction tree, `--features` for feature tallies, or `--solver-profile` for constraint solver timing. Use `inspect fit interference`, `inspect physical gaps`, or `inspect mechanical-integrity --collisions` for spatial and collision evidence.\n\n**Verification results** \u2014 runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values. Verification failures remain non-fatal so the model can still render and be inspected.\n\n**Physical connectivity** \u2014 pass `--connectivity` to list physically connected components across visible objects. Overlapping bbox candidates are checked with exact geometry by default, while bbox-only contact is treated as evidence rather than proof of one connected component. This helps answer whether the model is one continuous assembly or several separate islands.\n\n**Quality preset** \u2014 pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.\n\n**Direct CAD inputs** \u2014 pass `.stl`, `.obj`, `.3mf`, `.step`, or `.stp` directly when you just want to inspect an external asset. Mesh files are imported with `importMesh(...)`; STEP/STP files are imported with `importStep(...)` and auto-select OCCT unless you pass `--backend`.\n\nFor deeper confidence gates, prefer `forgecad inspect mechanical-integrity`, `forgecad check print`, or targeted evidence commands such as `forgecad inspect fit interference` instead of turning `run` back into a catch-all audit command.",
+    description: "The fast validation command: runs the script with the real geometry kernel (no browser) and reports build status, object count, `verify.*` pass/fail with expected vs actual values (non-fatal \u2014 the model still renders), parameter values, script logs, and timing. Run it frequently while editing.\n\nA bare `forgecad run` skips expensive diagnostics. Opt in with `--details` (volumes/bounds), `--history` (construction tree), `--features` (feature tallies), `--solver-profile` (constraint solver timing), or `--connectivity` (physical connected components \u2014 bbox contact is evidence, exact geometry is checked by default). `--quality live|default|high` selects the same geometry quality profile as the editor and export tools; `live` is fastest for large models.\n\nDirect `.stl`/`.obj`/`.3mf`/`.step`/`.stp` inputs are imported automatically; STEP/STP auto-selects OCCT unless you pass `--backend`. For deeper confidence gates, prefer `inspect mechanical-integrity`, `check print`, or `inspect fit interference` instead of turning `run` into a catch-all audit command.",
     usage: [
       "forgecad run <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [--details] [--history] [--features] [--connectivity] [--connectivity-tolerance <mm>] [--focus [names]] [--hide names] [--journeys] [--journeys-json] [--param Key=Value] [--joint JointName=Value] [--debug-imports] [--verbose] [--backend manifold|occt|truck] [--quality live|default|high] [--solver-profile] [--solver-debug-out <dir>]"
     ],
     examples: [
-      "forgecad run examples/api/static-assembly-connectors.forge.js",
-      "forgecad run examples/api/static-assembly-connectors.forge.js --focus",
-      'forgecad run examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"',
-      'forgecad run examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"',
-      "forgecad run examples/api/static-assembly-connectors.forge.js --details --history",
-      "forgecad run examples/products/cup.forge.js --connectivity",
-      "forgecad run examples/products/cup.forge.js --journeys",
-      "forgecad run examples/products/cup.forge.js --backend occt",
-      "forgecad run examples/products/cup.forge.js --backend truck --quality live",
-      "forgecad run examples/products/cup.forge.js --debug-imports",
-      'forgecad run examples/products/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"',
-      "forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug"
+      "forgecad run model.forge.js",
+      "forgecad run model.forge.js --details --history",
+      'forgecad run model.forge.js --focus "Bench.Slat*"',
+      "forgecad run model.forge.js --connectivity --quality live",
+      'forgecad run model.forge.js -p "Wall Thickness=3" -p "Body Height=200"'
     ],
     completion: {
       options: [
@@ -32678,14 +33034,7 @@ var commands = [
     summary: "Render a Forge scene. Use a subcommand \u2014 `3d`, `views`, `section`, `wireframe`, `sketch`, or `hq`.",
     description: "`forgecad render` is a group of rendering subcommands. Pick one based on what you want:\n\n- `render 3d` \u2014 standard viewport PNG, the usual way to visually verify geometry\n- `render views` \u2014 list named cameras declared with `scene({ views })`\n- `render wireframe` \u2014 edges only, no shading\n- `render section` \u2014 2D cross-section cut by a plane (SVG or PNG)\n- `render sketch` \u2014 2D sketch script to PNG\n- `render hq` \u2014 path-traced via Blender Cycles, for documentation and marketing shots",
     usage: ["forgecad render <subcommand> <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [options]"],
-    examples: [
-      "forgecad render 3d examples/products/cup.forge.js",
-      "forgecad inspect fit interference examples/api/static-assembly-connectors.forge.js --camera iso",
-      "forgecad render views examples/products/cup.forge.js",
-      "forgecad render wireframe examples/products/cup.forge.js",
-      "forgecad render section examples/furniture/01-table.forge.js --plane XZ",
-      "forgecad render hq examples/products/cup.forge.js --preset dramatic"
-    ],
+    examples: ["forgecad render 3d model.forge.js", "forgecad render section model.forge.js --plane XZ"],
     run: async (_args) => {
       console.error("`forgecad render` requires a subcommand.");
       console.error("");
@@ -32705,28 +33054,19 @@ 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. Each render uses a private renderer server by default, so parallel renders do not compete for the same Vite port.\n\nThe input can be a `.forge.js` script or a direct `.stl`, `.obj`, `.3mf`, `.step`, or `.stp` asset. Direct STEP/STP rendering auto-selects OCCT unless you pass `--backend`.\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. Use `--camera-json <file>` or `--scene <file>` for exact reproducible viewport cameras without shell escaping. Filtered renders report any visible objects whose bounding boxes are partially or fully outside the camera frame; exact cameras fail when they frame none of the visible objects.\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 headless Chrome, 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; the input can be a `.forge.js` script or a direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` asset.\n\n`--camera` accepts built-in 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. `--view` selects a named camera declared in `scene({ views })`; `--camera-json <file>` or `--scene <file>` give exact reproducible cameras without shell escaping. `--focus`/`--hide` filter visible objects; `--edges=<off|thin|bold>` controls the edge overlay.\n\nThis is the standard way to visually verify geometry from the CLI or in agent workflows. For path-traced quality use `render hq`; for edges only use `render wireframe`.",
     usage: [
       "forgecad render 3d <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [output.png] [--param Key=Value] [--joint JointName=Value] [--focus [names]] [--hide names] [--edges off|thin|bold] [options]"
     ],
     examples: [
-      "forgecad render 3d examples/products/cup.forge.js",
-      "forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus",
-      'forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"',
-      'forgecad render 3d examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"',
-      "forgecad render 3d model.forge.js --view hero",
-      "forgecad render 3d model.forge.js --camera 45:30",
+      "forgecad render 3d model.forge.js",
+      "forgecad render 3d model.forge.js --camera front --camera side --edges bold",
+      'forgecad render 3d model.forge.js --focus "Bench.Slat*" -p "Wall Thickness=3"',
       '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-json camera.json",
-      "forgecad render 3d model.forge.js --scene scene.json",
-      "forgecad render 3d model.forge.js --camera front --camera side",
-      'forgecad render 3d model.forge.js -p "Wall Thickness=3"',
-      "forgecad render 3d model.forge.js --edges bold",
-      "forgecad render 3d model.forge.js --edges off",
       "forgecad render 3d bracket.3mf bracket.png"
     ],
     completion: {
-      options: RENDER_OPTIONS,
+      options: RENDER_MODEL_OPTIONS,
       positionals: [
         { description: "Forge script or CAD asset", valueKind: "renderable" },
         { description: "output PNG path", valueKind: "png" }
@@ -32747,7 +33087,7 @@ var commands = [
       "forgecad render wireframe examples/products/cup.forge.js --camera iso"
     ],
     completion: {
-      options: RENDER_OPTIONS,
+      options: RENDER_MODEL_OPTIONS,
       positionals: [
         { description: "Forge script or CAD asset", valueKind: "renderable" },
         { description: "output PNG path", valueKind: "png" }
@@ -32791,17 +33131,14 @@ var commands = [
     group: "Modeling",
     path: ["render", "hq"],
     summary: "High-quality render via Blender Cycles \u2014 path-traced, HDRI, material presets.",
-    description: "Exports the scene to Blender and renders with Cycles (path tracer). Requires Blender installed and on PATH.\n\nChoose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (high-contrast), `clay` (matte, no color), `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more. Control quality vs speed with `--samples` (default 256). Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` for still camera control, matching `render 3d`. Use `--transparent` for a transparent background (compositing-ready).\n\nOutput defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.",
+    description: "Exports the scene to Blender and renders with Cycles (path tracer); requires Blender on PATH. Output defaults to `<script-name>-hq.png`.\n\n`--preset` picks the look (`studio`, `dramatic`, `clay`, `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more); `--samples` (default 256) trades quality vs speed; `--transparent` gives a compositing-ready background. Camera control (`--view`, `--camera`, `--camera-json`, `--scene <file>`) matches `render 3d`.",
     usage: [
       "forgecad render hq <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [output.png] [--param Key=Value] [--joint JointName=Value] [options]"
     ],
     examples: [
-      "forgecad render hq examples/products/cup.forge.js",
-      "forgecad render hq examples/products/cup.forge.js hero.png --preset dramatic --samples 1024",
-      "forgecad render hq examples/products/cup.forge.js hero.png --view hero",
-      "forgecad render hq examples/products/cup.forge.js hero.png --camera-json camera.json",
-      "forgecad render hq examples/products/cup.forge.js --preset clay --size 2048",
-      "forgecad render hq examples/products/cup.forge.js --transparent --preset glass"
+      "forgecad render hq model.forge.js",
+      "forgecad render hq model.forge.js hero.png --preset dramatic --samples 1024",
+      "forgecad render hq model.forge.js --transparent --preset glass --size 2048"
     ],
     completion: {
       options: [
@@ -32908,17 +33245,14 @@ var commands = [
     group: "Modeling",
     path: ["capture", "gif"],
     summary: "Capture an animated GIF from a script via orbit, named joint playback, or section sweep.",
-    description: "Renders an animated sequence by either orbiting the camera around the model or playing back a named joint animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joint clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.",
+    description: "Renders an animated sequence: `--capture orbit` (default) for a turntable, `--capture animation --animation <name>` for a named joint clip, or `--capture section-sweep` to move a clipping plane through the model. `--cut-plane` keeps a static cross-section visible while animating; the orbit base or fixed camera comes from `--view`, `--camera`, `--camera-json`, or `--scene <file>`.",
     usage: [
       "forgecad capture gif <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [output.gif] [options] [--param Key=Value] [--joint JointName=Value]"
     ],
     examples: [
-      "forgecad capture gif examples/products/cup.forge.js",
-      'forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"',
-      'forgecad capture gif model.forge.js out/raw.gif --param "Output=raw-sdf"',
-      "forgecad capture gif model.forge.js out/front.gif --camera front",
-      "forgecad capture gif model.forge.js out/hero.gif --view hero",
-      "forgecad capture gif examples/3d-printer.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ"
+      "forgecad capture gif model.forge.js",
+      "forgecad capture gif model.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ",
+      'forgecad capture gif model.forge.js out/hero.gif --view hero --cut-plane "Front Section"'
     ],
     completion: {
       options: CAPTURE_COMMON_OPTIONS,
@@ -32938,12 +33272,8 @@ var commands = [
       "forgecad capture mp4 <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [output.mp4] [options] [--param Key=Value] [--joint JointName=Value]"
     ],
     examples: [
-      "forgecad capture mp4 examples/products/cup.forge.js",
-      "forgecad capture mp4 examples/api/assembly-kinematics-four-bar.forge.js out/four-bar.mp4 --view iso",
-      'forgecad capture mp4 model.forge.js out/raw.mp4 --param "Output=raw-sdf"',
-      "forgecad capture mp4 model.forge.js out/front.mp4 --camera front",
-      "forgecad capture mp4 model.forge.js out/hero.mp4 --view hero",
-      "forgecad capture mp4 examples/3d-printer.forge.js out/sweep.mp4 --capture section-sweep --sweep-plane YZ --sweep-frames 180"
+      "forgecad capture mp4 model.forge.js out/four-bar.mp4 --view iso",
+      "forgecad capture mp4 model.forge.js out/sweep.mp4 --capture section-sweep --sweep-plane YZ --sweep-frames 180"
     ],
     completion: {
       options: CAPTURE_COMMON_OPTIONS,
@@ -32958,15 +33288,14 @@ var commands = [
     group: "Modeling",
     path: ["render", "section"],
     summary: "Render a 2D cross-section of a 3D model (cut by a plane) to SVG or PNG.",
-    description: "Cuts all shapes in the scene with an axis-aligned plane and produces a 2D cross-section drawing. The default plane is XY at Z=0. Use `--plane XZ` or `--plane YZ` for other orientations, and `--offset` to shift the cut position.\n\nOutput format is determined by the file extension: `.svg` (default, vector) or `.png` (rasterized at `--size` pixels). Use `--edges=<off|thin|bold>` to control the outline stroke on cut shapes.\n\nUseful for verifying internal geometry, wall thicknesses, and fit checks that aren't visible in 3D renders.",
+    description: "Cuts all shapes with an axis-aligned plane (default XY at Z=0; `--plane XZ|YZ` reorients, `--offset` shifts the cut) and writes a 2D cross-section drawing. The file extension picks the format: `.svg` (default, vector) or `.png` (rasterized at `--size` pixels); `--edges=<off|thin|bold>` sets the outline stroke. Useful for verifying internal geometry, wall thicknesses, and fits that aren't visible in 3D renders.",
     usage: [
       "forgecad render section <model.forge.js|asset.stl|asset.obj|asset.3mf|asset.step|asset.stp> [output.svg|.png] [--param Key=Value] [--joint JointName=Value] [--plane XY|XZ|YZ] [--offset <number>] [--size <px>] [--edges off|thin|bold] [--background <color>]"
     ],
     examples: [
-      "forgecad render section examples/furniture/01-table.forge.js",
-      "forgecad render section examples/furniture/01-table.forge.js out/section.svg --plane XZ --offset 10",
-      "forgecad render section examples/furniture/01-table.forge.js out/section.png --size 2048",
-      "forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edges bold"
+      "forgecad render section model.forge.js",
+      "forgecad render section model.forge.js out/section.svg --plane XZ --offset 10",
+      "forgecad render section model.forge.js out/section.png --size 2048"
     ],
     completion: {
       options: [
@@ -34081,13 +34410,12 @@ var commands = [
     group: "Inspect",
     path: ["inspect", "sketch"],
     summary: "Inspect returned sketches and profile regions used by returned shapes.",
-    description: "Runs a model and reports inspectable 2D sketch/profile regions without requiring model code to register inspection hooks. The command inspects returned Sketch objects and profile-bearing shape compile plans such as extrude, cut, and revolve. Use `--seed x,y` to dry-run which region a point selector would consume, and `--operation extrude` to check extrusion compatibility.",
+    description: "External inspection: runs the model, then reads returned `Sketch`/`ConstraintSketch` objects and profile-bearing shape compile plans (extrude, cut, revolve) \u2014 model code never calls an inspection API. Reports filled selectable regions (sorted largest-first, run-local ids like `R0`) and excluded hole interiors. `--seed x,y` is the stable selection mechanism (not region ids): it dry-runs which region a point selector would consume, and seed failures exit nonzero (outside every region, on a boundary, inside a hole, ambiguous, or incompatible operation). `--operation extrude` checks only whether the selected filled region can be consumed by extrusion.",
     usage: [
       "forgecad inspect sketch <model.forge.js> [--json] [--object <name-or-path>] [--seed <x,y>] [--operation extrude] [--param Key=Value] [--joint JointName=Value] [--backend manifold|occt|truck] [--quality live|default|high]"
     ],
     examples: [
-      "forgecad inspect sketch examples/api/sketch-regions.forge.js",
-      'forgecad inspect sketch model.forge.js --object "Profile" --seed 45,15',
+      "forgecad inspect sketch model.forge.js",
       'forgecad inspect sketch model.forge.js --json --object "Body" --seed 45,15 --operation extrude'
     ],
     completion: {
@@ -34218,7 +34546,7 @@ var commands = [
     group: "Inspect",
     path: ["inspect", "mechanical-integrity"],
     summary: "Inspect generated ForgeCAD models for mechanical integrity failures.",
-    description: "Scans a Forge script or a folder of generated projects and runs a mechanical integrity inspection. The inspection flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, optional positive-volume object collisions, and excessive physical component counts when requested. Markdown details include suggested repair patterns such as connector-authored mates, bolted service covers, pinned levers, captured slides, hinges, clevis joints, retained shafts, and seated bearings. When `--collisions` is enabled, the Markdown details list the largest overlapping object pairs by volume so agents can repair the highest-risk interfaces first. Exact collision checks use a default 40-pair bbox-overlap budget and 30s exact-check time budget; exhausting either budget fails the file instead of silently passing a partial check. Script-authored `console.warn()` diagnostics are reported as warnings; use `verify.*` checks or `console.error()` for gate-failing contracts. Script-side joint sweeps use a separate validation step budget so the gate can keep default geometry quality while failing truncated validation explicitly.",
+    description: "Scans a Forge script or a folder of generated projects and flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, and (when requested) positive-volume collisions and excessive physical component counts. Details suggest concrete repair patterns. With `--collisions`, the largest overlapping object pairs are listed by volume so the highest-risk interfaces get repaired first; exhausting the exact-check pair or time budget fails the file instead of silently passing a partial check, and truncated script-side joint-sweep validation fails explicitly. Script `console.warn()` diagnostics are reported as warnings; use `verify.*` checks or `console.error()` for gate-failing contracts.",
     usage: [
       "forgecad inspect mechanical-integrity <script-or-dir> [--json] [--param Key=Value] [--joint JointName=Value] [--timeout-ms <ms>] [--jobs <n>] [--min-verifications <n>] [--max-components <n>] [--collisions] [--min-overlap-volume <mm3>] [--collision-pair-limit <n>] [--collision-time-budget-ms <ms>] [--sweep-joint-step-limit <n>] [--all-forge] [--backend manifold|occt|truck]"
     ],
@@ -34385,7 +34713,7 @@ var commands = [
         { name: "--update", description: "Regenerate compiler snapshots" }
       ]
     },
-    run: async (args) => (await import("./check-compiler-SYQ2PWOB.js")).runCheckCompilerCli(args)
+    run: async (args) => (await import("./check-compiler-JTVBITCR.js")).runCheckCompilerCli(args)
   },
   {
     group: "Checks",
@@ -34408,7 +34736,7 @@ var commands = [
         { name: "--update", description: "Regenerate query-propagation snapshots" }
       ]
     },
-    run: async (args) => (await import("./check-query-propagation-HIAGV62W.js")).runCheckQueryPropagationCli(args)
+    run: async (args) => (await import("./check-query-propagation-3FFLSMVN.js")).runCheckQueryPropagationCli(args)
   },
   {
     group: "Checks",