partforge 0.62.1 → 0.64.0

package/src/framework/imports.js

@@ -0,0 +1,84 @@
+// Resolve a part's declared `imports` ({ name: source }) to bytes + a SHA-256
+// content digest + a detected format, before the synchronous build — the
+// import-asset sibling of fonts.js: same source grammar and identity-
+// memoization rule (import sources are content-stable for a session), built on
+// the shared resolution core in asset-resolve.js. DOM-free and node:-free;
+// crypto.subtle exists in workers and Node.
+import { makeAssetResolver, resolveDecl } from "./asset-resolve.js";
+import { parseStl } from "./geometry/stl-parse.js";
+import { parse3MF } from "./geometry/threemf-parse.js";
+
+const EXT = { step: "step", stp: "step", stl: "stl", "3mf": "3mf" };
+
+export function detectFormat(source, bytes) {
+  const path = source instanceof URL ? source.pathname : typeof source === "string" ? source.split("?")[0] : null;
+  const ext = path?.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase();
+  if (ext && EXT[ext]) return EXT[ext];
+  const u8 = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+  if (u8 && u8.length > 0) {
+    const head = String.fromCharCode(...u8.slice(0, 64));
+    if (head.startsWith("ISO-10303-21")) return "step";
+    if (u8[0] === 0x50 && u8[1] === 0x4b) return "3mf"; // zip signature
+    return "stl"; // ascii "solid …" and binary STL both land here
+  }
+  throw new Error(`unrecognized import format${path ? ` for "${path}"` : ""} — use a .step/.stl/.3mf extension or non-empty bytes`);
+}
+
+async function sha256Hex(bytes) {
+  const d = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const cache = new Map(); // source → Promise<{bytes, digest, format}>
+const resolveOne = makeAssetResolver(
+  cache,
+  async (bytes, v, source) => {
+    const format = detectFormat(source instanceof URL || typeof source === "string" ? source : v, bytes);
+    return { bytes, digest: await sha256Hex(bytes), format };
+  },
+  "resolveImports: an import source must be bytes, a URL, or a thunk returning one",
+);
+
+export async function resolveImports(importsDecl) {
+  return resolveDecl(importsDecl, resolveOne);
+}
+
+// Register a part's imports on a booted kernel (idempotent per digest). The
+// framework calls this in the async phase before every job's synchronous
+// build — worker (jobs.js) and Node boots (src/testing/) alike.
+//
+// Registration is total; errors are lazy (see the spec section of that name):
+// every declared import registers on whichever kernel runs the job, and a
+// format this kernel cannot use registers as an {error} entry that k.import
+// throws at call time. That is what keeps a mixed-format declaration from
+// poisoning unrelated jobs — the OCCT worker's tessellate-imports service
+// job, or a per-backend generate group that never touches the unusable
+// import. STEP on a mesh backend needs pre-tessellated triangles in
+// `importMeshes`; absent, the entry carries code NEEDS_IMPORT_MESH and the
+// first build to call k.import on it makes the host arrange tessellation
+// (mount's needs-import-mesh flow in the browser, worker_threads in Node).
+export async function ensureImports(kernel, importsDecl, importMeshes = null) {
+  if (!importsDecl || typeof kernel._registerImport !== "function") return;
+  const resolved = await resolveImports(importsDecl);
+  for (const [name, a] of resolved) {
+    if (kernel._importDigest?.(name) === a.digest) continue; // error entries answer undefined → always retried
+    if (a.format === "step") {
+      if (kernel._acceptsStep) { await kernel._registerImport({ name, digest: a.digest, step: a.bytes }); continue; }
+      const m = importMeshes?.get?.(name);
+      if (m && m.digest === a.digest) {
+        await kernel._registerImport({ name, digest: a.digest, positions: m.positions, indices: m.indices });
+      } else {
+        const e = new Error(`import "${name}": STEP needs tessellation for the Manifold backend`);
+        e.code = "NEEDS_IMPORT_MESH";
+        await kernel._registerImport({ name, digest: a.digest, error: e });
+      }
+    } else if (kernel._acceptsMesh) {
+      const { positions, indices } = a.format === "3mf" ? parse3MF(a.bytes) : parseStl(a.bytes);
+      await kernel._registerImport({ name, digest: a.digest, positions, indices });
+    } else {
+      // No parse for a kernel that can't take the mesh — error entry directly.
+      await kernel._registerImport({ name, digest: a.digest, error: new Error(
+        `import "${name}": STL/3MF imports need the Manifold backend — this build routes to OCCT (shell or meta.backend, or a fillet/chamfer rerouted for an unsupported edge class); use the mesh import from a Manifold-routed build`) });
+    }
+  }
+}

package/src/framework/jobs.js

@@ -5,6 +5,7 @@
 import { meshTo3MF } from "./geometry/threemf.js";
 import { exportablePartNames } from "./export-select.js";
 import { resolveFonts } from "./fonts.js";
+import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
 import { measure } from "./oracle/measure.js";
@@ -105,6 +106,11 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const bufs = await resolveFonts(part.fonts);
       for (const [name, buf] of bufs) if (!kernel._fonts.has(name)) kernel._fonts.set(name, opentype.parse(buf));
     }
+    // Register this part's declared imports on the kernel running this job — the
+    // import-asset sibling of the fonts preload above. See ensureImports for the
+    // lazy-error policy that keeps a STEP import inert until a build actually
+    // calls k.import on it.
+    if (part.imports) await ensureImports(kernel, part.imports, opts.importMeshes ?? null);
     // Inside the try so a throwing derive posts an error the UI can show,
     // instead of killing the worker turn silently (an endless spinner).
     const { p, d } = resolveParams(part, msg.params);
@@ -196,6 +202,18 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);
       post({ type: "download", data, filename: `${fileBase}.3mf`, mime: "model/3mf", jobId: msg.jobId }, [bufferOf(data)]);
+    } else if (msg.type === "tessellate-imports") {
+      // OCCT-worker service job for the STEP-on-Manifold crossover: answer with
+      // print-quality triangle meshes for every STEP import, transferable.
+      const resolved = await resolveImports(part.imports ?? {});
+      const meshes = {};
+      for (const [name, a] of resolved) {
+        if (a.format !== "step") continue;
+        const { positions, indices } = kernel.import(name).toIndexedMesh({ quality: "print" });
+        meshes[name] = { digest: a.digest, positions, indices };
+      }
+      post({ type: "import-meshes", jobId: msg.jobId, meshes },
+           Object.values(meshes).flatMap((m) => [m.positions.buffer, m.indices.buffer]));
     } else if (msg.type === "inspect") {
       // Full geometric oracle for the current view: solid facts (volume/genus/
       // watertight), mesh facts, overlaps, and gap distances, plus the part's
@@ -246,7 +264,8 @@ export async function handle(kernel, part, msg, post, opts = {}) {
   } catch (err) {
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the
     // failed job covered, so only those latch to OCCT — not the whole part.
-    if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId, subparts: msg.subparts });
+    if (err?.code === "NEEDS_IMPORT_MESH") post({ type: "needs-import-mesh", jobId: msg.jobId, subparts: msg.subparts });
+    else if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId, subparts: msg.subparts });
     else post({ type: "error", message: String(err?.message || err), jobId: msg.jobId });
   } finally {
     kernel.cleanup?.();

package/src/framework/lint/index.js

@@ -15,8 +15,9 @@ import { BUILD_RULES } from "./rules-build.js";
 import { VERIFY_RULES, resolveExpect } from "./rules-verify.js";
 import { ANIMATION_RULES } from "./rules-animations.js";
 import { PLACE_RULES } from "./rules-place.js";
+import { IMPORT_RULES } from "./rules-imports.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES];
 
 // Every rule runs inside a guard. lintPart is called on a user-facing hosted path
 // (partforge-cloud's sandbox), and a linter that takes down the preview it exists to

package/src/framework/lint/rules-imports.js

@@ -0,0 +1,115 @@
+// Group 5 — geometry-import well-formedness. Each condition here is a static
+// early-catch for something that otherwise throws only later: `k.import()` on
+// an undeclared name throws mid-build (kernel.js), a declared mesh import
+// under an OCCT-routed part throws lazily from the `{error}` registration
+// entry the first time `k.import` reads it (imports.js), an unknown
+// `reference` breaks the deviation gate silently (measure.js just reports no
+// deviation), and a `ref*` verify metric with no `reference` always reports
+// status "skip" (verify-metrics.js) rather than the gate the author intended.
+//
+// `import-mesh-on-occt` is deliberately conservative: only extension-detectable
+// sources (a `URL` or a string path) are checked. Bytes and thunks carry no
+// format information without actually resolving them, which lint — geometry-
+// free and synchronous — cannot do; those cases (and any per-sub-part routing
+// split a whole-part `detectBackend` can't see) still fail correctly at build
+// time via imports.js's lazy `{error}` entry. This rule exists to catch the
+// common case early, not to replace that runtime authority.
+import { err, warn } from "./finding.js";
+import { detectBackend } from "../backend-select.js";
+import { SUBPART_METRICS } from "../verify-metrics.js";
+
+const MESH_EXT = /\.(stl|3mf)$/i;
+
+const REF_METRICS = new Set(Object.keys(SUBPART_METRICS).filter((k) => k.startsWith("ref")));
+
+const declaredImports = (part) => Object.keys(part?.imports ?? {});
+
+// Only URL/string sources carry a statically-visible extension; a thunk or raw
+// bytes source is skipped (see file header).
+const meshDeclared = (part) => Object.entries(part?.imports ?? {}).filter(([, src]) => {
+  const path = src instanceof URL ? src.pathname : typeof src === "string" ? src.split("?")[0] : null;
+  return path != null && MESH_EXT.test(path);
+});
+
+export const IMPORT_RULES = [
+  {
+    id: "import-unknown-name",
+    run: ({ part, probe }) => {
+      const known = new Set(declaredImports(part));
+      const seen = new Set();
+      const out = [];
+      for (const call of probe().calls) {
+        if (call.scope !== "kernel" || call.op !== "import") continue;
+        let name;
+        try { name = JSON.parse(call.args[0]); } catch { name = null; }
+        if (typeof name !== "string" || known.has(name) || seen.has(name)) continue;
+        seen.add(name);
+        out.push(err("import-unknown-name",
+          `build calls k.import with name "${name}", which the part's imports field does not declare: ${[...known].join(", ") || "(nothing)"}`,
+          "Declare the file under imports: { name: source }, or fix the name to match an existing entry.",
+          "imports"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "import-mesh-on-occt",
+    run: ({ part, p }) => {
+      const mesh = meshDeclared(part);
+      if (mesh.length === 0 || detectBackend(part, p) !== "occt") return [];
+      const cause = part?.meta?.backend === "occt"
+        ? "meta.backend forces OCCT"
+        : "a shell op routes this part to OCCT"; // post-contract-v3, fillet/chamfer no longer probe-route
+      return mesh.map(([name]) => err("import-mesh-on-occt",
+        `import "${name}" is a mesh (STL/3MF) but ${cause} — mesh imports need the Manifold backend`,
+        // detectBackend (this rule's own gate) is the whole-part max over every
+        // sub-part, same as lint/measure/single-worker export — so putting the
+        // import on a nominally Manifold sub-part does not clear this error
+        // while any OTHER sub-part routes to OCCT; that coexistence only works
+        // for the browser preview's per-sub-part routing. Say so explicitly —
+        // see ERROR-PATTERNS.md#import-mesh-on-occt for the long version.
+        "Split the mesh-importing sub-part into its own separate part (per-sub-part Manifold/OCCT coexistence is preview-only), replace it with a STEP source, or drop the CAD-only op / meta.backend pin so the whole part routes to Manifold.",
+        "imports"));
+    },
+  },
+  {
+    id: "reference-unknown",
+    run: ({ part }) => {
+      const known = new Set(declaredImports(part));
+      return Object.entries(part?.parts ?? {})
+        .filter(([, sp]) => sp?.reference && !known.has(sp.reference))
+        .map(([name, sp]) => err("reference-unknown",
+          `sub-part "${name}" declares reference: "${sp.reference}" but no such import exists`,
+          "reference must name a key of the part's imports field.",
+          `parts.${name}.reference`));
+    },
+  },
+  {
+    id: "ref-metric-without-reference",
+    // Deliberately resolves function-form `verify.expect` via `resolveExpectOnce()`
+    // (same memoized, try/caught call the Group 4 verify rules share) rather than
+    // skipping it — the plan's anchor guarded with a bare `typeof expect ===
+    // "object"` check on the assumption a function-form `expect` "can't be
+    // inspected statically", but `resolveExpectOnce()` already does exactly that
+    // inspection safely (a throw is reported separately by `verify-expect-throws`
+    // and short-circuits here via `!expect`). A ref* metric surfaced from a
+    // function-form expect with no `reference` is just as real a finding as one
+    // from the static-object form, so skipping it would be a false negative, not
+    // caution.
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const names = new Set(Object.keys(part?.parts ?? {}));
+      return Object.entries(expect)
+        // `sub` must name a real sub-part — a typo'd name is already reported by
+        // `verify-unknown-subpart`; skip it here so the two rules don't double-report
+        // the same typo under two different ids.
+        .filter(([sub, metrics]) => sub !== "_view" && names.has(sub) && metrics && typeof metrics === "object" &&
+          Object.keys(metrics).some((k) => REF_METRICS.has(k)) && !part?.parts?.[sub]?.reference)
+        .map(([sub]) => warn("ref-metric-without-reference",
+          `verify.expect.${sub} uses a ref* metric but sub-part "${sub}" declares no reference`,
+          `Add reference: "<import name>" to sub-part "${sub}", or the ref* checks always report status "skip".`,
+          `verify.expect.${sub}`));
+    },
+  },
+];

package/src/framework/mount.js

@@ -37,6 +37,17 @@ const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {}
 // Same no-op-default stance as attachTooltips/setHostPane below, for a
 // makeHandle caller (or a direct test) that doesn't wire measure mode.
 const NOOP_MEASURE = { isEnabled: () => false, setEnabled: () => {}, clearPins: () => {}, pinCount: () => 0 };
+// The STEP-on-Manifold import crossover's broken-state message (a second
+// needs-import-mesh after the mesh is already primed — see the "needs-import-mesh"
+// case below). One shared string so the status line, onBuild, and the ready
+// rejection can never drift apart.
+const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy the import — see console";
+// The crossover's OTHER failure mode: the tessellate-imports request itself
+// throws (malformed STEP, etc.) rather than delivering a mesh to prime. Distinct
+// from IMPORT_MESH_BROKEN_MESSAGE above (that one names a digest mismatch AFTER
+// a successful tessellation) — this one names the tessellation failure and
+// carries the worker's own error text. See the correlated "error" case below.
+const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
 export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure }) {
   return {
@@ -261,6 +272,30 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     if (forcedBackend !== "occt" && forcedBackend !== "manifold") forcedBackend = null;
     const backendPolicy = createBackendPolicy(part, { forced: forcedBackend });
     const backendFor = () => backendPolicy.backendFor(params);
+    // STEP-on-Manifold import crossover (spec 2026-08-16): null → "requested" →
+    // "primed", tracking the one tessellate-imports round trip this mount instance
+    // ever needs (a worker-lifetime prime, per Task 8). One mount() call handles
+    // exactly one part for its whole lifetime — there is no rebind point to reset
+    // this at — so declaring it here beside backendPolicy is its only reset.
+    let importMeshState = null;
+    // jobId of the outstanding tessellate-imports request (mount-generated —
+    // jobs.js's tessellate-imports branch echoes it back on both its
+    // "import-meshes" reply and, via the shared catch, on a thrown "error").
+    // Lets the "error" case below tell a correlated tessellation failure apart
+    // from an unrelated build error sharing the same message type, so it can
+    // reset the latch instead of stranding it at "requested" forever.
+    // String-namespaced ("tess-N"), mirroring capture-build.js's "cap-N" —
+    // this request shares the OCCT worker's message space with
+    // export-controller's PLAIN NUMERIC jobIds (both start counting at 1), and
+    // exportCtl.handleMessage (called before mount's own switch, below) does a
+    // raw pending.get(m.jobId) before checking type. A bare numeric id here
+    // could collide with a pending STEP export's jobId, so the export
+    // controller would wrongly claim this reply — rejecting an unrelated
+    // export with the tessellation failure text AND leaving importMeshState
+    // stranded at "requested" (mount's own switch, which would have reset it,
+    // never runs). The string namespace makes that collision impossible.
+    let importTessellateJobId = null;
+    let importTessellateJobSeq = 0;
 
     // ?debug shows the cache debug overlay; ?debug&nocache starts with caching off.
     const qs = new URLSearchParams(location.search);
@@ -582,7 +617,64 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           loop.buildDone();
           loop.kick();
           break;
-        case "error":
+        case "needs-import-mesh":
+          // STEP import on the Manifold worker: an unprimed import threw
+          // NEEDS_IMPORT_MESH (Task 8). Settle this build the same way
+          // needs-occt does — buildDone() only, no kick() here: the retry can't
+          // succeed until priming completes, and kicking now would just repeat
+          // the same failure before the mesh exists. The "import-meshes" case
+          // below is what kicks, once the prime has actually landed.
+          loop.buildDone();
+          if (importMeshState === "primed") {
+            // Tessellation already delivered a mesh but Manifold still can't
+            // satisfy the import — the digest didn't match. A genuinely broken
+            // state, not a retry loop: surface it like any other build error
+            // rather than re-requesting tessellation forever.
+            ui.hideBusy();
+            refreshView();
+            ui.setStatus(`failed: ${IMPORT_MESH_BROKEN_MESSAGE}`, true);
+            onBuild?.({ status: "error", error: IMPORT_MESH_BROKEN_MESSAGE });
+            if (!readySettled) { readySettled = true; rejectReady(new Error(IMPORT_MESH_BROKEN_MESSAGE)); }
+          } else if (importMeshState !== "requested") {
+            importMeshState = "requested";
+            importTessellateJobId = `tess-${++importTessellateJobSeq}`;
+            service.send({ type: "tessellate-imports", jobId: importTessellateJobId }, "occt");
+          }
+          break;
+        case "import-meshes":
+          // The OCCT worker answered tessellate-imports: prime the Manifold
+          // worker's import cache (worker-lifetime, per Task 8) with transferable
+          // mesh buffers, then kick the loop — the needs-import-mesh case above
+          // already settled the failed build (buildDone), so this kick is the
+          // other half of the same buildDone()/kick() pairing needs-occt does in
+          // one step, split across the two crossover replies here.
+          importMeshState = "primed";
+          importTessellateJobId = null; // the request this jobId correlated is answered — nothing to match against it anymore
+          service.send({ type: "prime-imports", meshes: data.meshes }, "manifold",
+            Object.values(data.meshes).flatMap((m) => [m.positions.buffer, m.indices.buffer]));
+          loop.kick();
+          break;
+        case "error": {
+          // A correlated tessellate-imports failure (malformed STEP, etc.) must
+          // not fall through the generic handling below: that request was
+          // dispatched directly via service.send (see needs-import-mesh above),
+          // never through loop.send, so loop.buildDone() has no matching pending
+          // count to release for it — calling it here would mis-credit an
+          // unrelated in-flight generate job. Reset the latch instead of leaving
+          // it stuck at "requested" forever (which would silently swallow every
+          // later needs-import-mesh via the `!== "requested"` guard above) — the
+          // next kick (param/view change) retries tessellation fresh.
+          if (data.jobId != null && data.jobId === importTessellateJobId) {
+            importMeshState = null;
+            importTessellateJobId = null;
+            ui.hideBusy();
+            refreshView();
+            const tessellateMessage = importTessellateFailedMessage(data.message);
+            ui.setStatus(`failed: ${tessellateMessage}`, true);
+            onBuild?.({ status: "error", error: tessellateMessage });
+            if (!readySettled) { readySettled = true; rejectReady(new Error(tessellateMessage)); }
+            break;
+          }
           loop.buildDone();
           ui.hideBusy();
           // refreshView FIRST: its all-current branch clears the status line,
@@ -592,6 +684,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           onBuild?.({ status: "error", error: data.message });
           if (!readySettled) { readySettled = true; rejectReady(new Error(data.message)); }
           break;
+        }
       }
     }
 

package/src/framework/oracle/measure.js

@@ -15,7 +15,11 @@ const unionBounds = (list) => list.reduce(
 // solid facts (volume/genus/emptiness) and mesh facts (bbox/area/triangles), plus
 // the assembly overlap check plus pair gap distances (near misses are reported,
 // never folded into `ok`). All solid facts are read BEFORE assemblyOverlaps,
-// which frees the shared kernel's objects at its end.
+// which frees the shared kernel's objects at its end. A sub-part that declares
+// `reference: "<import name>"` also gets a `deviation` fact — the posed solid's
+// symmetric-difference volume, volume delta %, and bbox-corner drift against
+// that import — for the `ref*` gate metrics (verify-metrics.js); every other
+// sub-part gets `deviation: null`.
 //   → { part, view, measuredMinWall, subparts[], aggregate, overlaps[], gaps[],
 //       nearMisses[], ok }
 export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}, opts = {}) {
@@ -43,16 +47,38 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     // Resolved lazily and only when asked for: without min-wall, a single-sub-part
     // view (no meshGaps) must still build no index at all.
     const mw = opts.minWall ? minWall(mesh, { bvh: cachedBVH(mesh, bvhCache) }) : null;
+    const vol = solid.volume();
+    // Deviation-from-reference: only for a sub-part that declares `reference:
+    // "<import name>"` (Task 12 — the gate that holds a parametric rebuild to
+    // its imported reference), and only when this kernel can import at all (a
+    // bare/third-party kernel may lack `import`). Read here, alongside every
+    // other solid fact, so it is captured before assemblyOverlaps/cleanup below
+    // frees the shared kernel's objects.
+    const refName = part.parts[name]?.reference;
+    let deviation = null;
+    if (refName && typeof kernel.import === "function") {
+      const ref = kernel.import(refName);
+      const refVol = ref.volume();
+      const rb = ref.boundingBox();
+      const inter = solid.intersect(ref).volume();
+      deviation = {
+        ref: refName,
+        xorVolume: vol + refVol - 2 * inter, // symmetric difference, one boolean
+        volumeDeltaPct: refVol > 1e-9 ? (100 * Math.abs(vol - refVol)) / refVol : null,
+        bboxDelta: [0, 1, 2].map((i) => Math.max(Math.abs(b.min[i] - rb.min[i]), Math.abs(b.max[i] - rb.max[i]))),
+      };
+    }
     return {
       name,
       bbox: size(b),
       bounds: { min: b.min, max: b.max },
       centerOfMass: meshCentroid(mesh.positions, mesh.indices),
-      volume: solid.volume(),
+      volume: vol,
       surfaceArea: meshArea(mesh.positions, mesh.indices),
       triangleCount: mesh.triangles,
       watertight: typeof solid.isEmpty === "function" ? !solid.isEmpty() : null,
       holes: typeof solid.genus === "function" ? solid.genus() : null,
+      deviation,
       minWall: mw?.value ?? null,
       minWallAt: mw?.location ?? null,
       // Sampling accounting, so a report can tell a guaranteed minimum from an

package/src/framework/verify-metrics.js

@@ -46,6 +46,16 @@ export const SUBPART_METRICS = {
         ? `no reading from the ${sampled} of ${total} triangles sampled — not a clean bill of health; a thin spot may exist between samples`
         : `sampled ${sampled} of ${total} triangles — an upper bound; a thinner spot may exist between samples`;
     } },
+  // `s.deviation` (measure.js) exists only for a sub-part declaring `reference:
+  // "<import name>"`; on every other sub-part `extract` returns null, which
+  // `check()` already reports as status "skip" rather than a fail — the
+  // no-reference path needs nothing here.
+  refXorVolume: { kind: "gate", extract: (s) => s.deviation?.xorVolume ?? null,
+    hint: "the rebuild's symmetric difference vs its reference import is too large — compare the ghost overlay, then adjust the governing dimensions toward the measured reference" },
+  refVolumeDeltaPct: { kind: "gate", extract: (s) => s.deviation?.volumeDeltaPct ?? null,
+    hint: "rebuild volume differs from the reference import by more than the allowed percentage — a feature is missing, doubled, or mis-scaled vs the reference" },
+  refBboxDelta: { kind: "gate", extract: (s) => s.deviation?.bboxDelta ?? null,
+    hint: "the rebuild's bounding-box corners drift from the reference import — check overall dimensions and that the rebuild is aligned to the reference's coordinates" },
 };
 export const VIEW_METRICS = {
   bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,

package/src/framework/worker.js

@@ -45,6 +45,7 @@ export function runWorker(part) {
   let epoch = 0;      // bumped per incoming generate and per setPart
   const queue = [];   // { data, part, epoch } — jobs run against the part current at arrival
   let pumping = false;
+  const importMeshes = new Map(); // name → {digest, positions, indices} — primed by the host for STEP-on-manifold
 
   // Manifold is cheap to boot — bring it up eagerly and signal readiness.
   if (backend === "manifold") {
@@ -98,7 +99,7 @@ export function runWorker(part) {
           const kernel = await kernelFor(job.data);
           // handle() declares each message's transferables (the big binary buffers).
           const post = (m, transfer = []) => postMessage(m, transfer);
-          if (job.epoch === null) { await handle(kernel, job.part, job.data, post); continue; }
+          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes }); continue; }
           const isStale = () => job.epoch !== epoch;
           // Post gate. The boundary check cannot catch a generate that goes stale during
           // its FINAL sub-part — there is no boundary after it — nor a single-sub-part
@@ -107,7 +108,7 @@ export function runWorker(part) {
           // contract simple: a `meshes` post is current as of the moment it is posted.
           const gated = (m, transfer = []) =>
             (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
-          await handle(kernel, job.part, job.data, gated, { isStale });
+          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes });
         } catch (err) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
           // Carry the job's jobId when it has one (capture/export are correlated by it):
@@ -123,6 +124,14 @@ export function runWorker(part) {
   }
 
   self.onmessage = (e) => {
+    // STEP-on-Manifold crossover: the host primes this worker's importMeshes before
+    // (or interleaved with) a generate, so a build's k.import(name) that needs
+    // pre-tessellated triangles finds them without touching the kernel — no queueing,
+    // no epoch bump, answered on the worker's own turn like the lint intercept below.
+    if (e.data?.type === "prime-imports") {
+      for (const [name, m] of Object.entries(e.data.meshes)) importMeshes.set(name, m);
+      return;
+    }
     // Lint is geometry-free by construction, so answer it before touching — or
     // booting — a kernel. handle() in jobs.js takes an already-booted kernel, and
     // the pump awaits that boot, so routing lint through the queue would drag in

package/src/import-demo-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/import-demo.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/parts/assets/import-demo-scan.stl

@@ -0,0 +1,86 @@
+solid import-demo-scan
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 20 14 0
+      vertex 20 0 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 0 14 0
+      vertex 20 14 0
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 8
+      vertex 20 0 8
+      vertex 20 14 8
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 8
+      vertex 20 14 8
+      vertex 0 14 8
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 0 0 0
+      vertex 20 0 0
+      vertex 20 0 8
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 0 0 0
+      vertex 20 0 8
+      vertex 0 0 8
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 0 14 0
+      vertex 0 14 8
+      vertex 20 14 8
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 0 14 0
+      vertex 20 14 8
+      vertex 20 14 0
+    endloop
+  endfacet
+  facet normal -1 0 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 0 8
+      vertex 0 14 8
+    endloop
+  endfacet
+  facet normal -1 0 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 14 8
+      vertex 0 14 0
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 20 0 0
+      vertex 20 14 0
+      vertex 20 14 8
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 20 0 0
+      vertex 20 14 8
+      vertex 20 0 8
+    endloop
+  endfacet
+endsolid import-demo-scan