partforge 0.63.0 → 0.64.0

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

package/src/parts/import-demo.js

@@ -0,0 +1,134 @@
+// Reference part for docs/AUTHORING-PARTS.md's "Importing geometry" section —
+// the worked example for BOTH import uses in one part:
+//   • reference — `ref` is a translucent ghost of the imported scan (never
+//     exported); `body` is a parametric rebuild of the same block, bound to
+//     the scan via `reference: "scan"` and held to it by the three ref*
+//     deviation metrics in `verify.expect.body`.
+//   • component — `mount` uses the import as a real boolean tool: a plate
+//     with a through-socket cut to the scan's own shape (scaled up by `fit`
+//     for clearance), exported like any other sub-part.
+// `src/parts/assets/import-demo-scan.stl` is a small hand-written ascii STL —
+// a 20×14×8 mm block, origin-cornered, outward-wound. `body`'s defaults
+// reproduce those dimensions exactly, so the deviation gate passes with real
+// margin. Open /import-demo.html after `npm run dev`.
+export default {
+  meta: { title: "Import demo", units: "mm", background: 0x15181d },
+  imports: {
+    scan: new URL("./assets/import-demo-scan.stl", import.meta.url),
+  },
+  parameters: [
+    {
+      id: "scan",
+      title: "Scan",
+      description: "Dimensions of the parametric rebuild (`body`). Defaults match the imported reference block exactly — drag one and watch the deviation gate in `partforge measure` react.",
+      advanced: [
+        { key: "scanW", label: "Width", unit: "mm", min: 10, max: 40, step: 0.5,
+          description: "Rebuild width (X). Matches the scan's width at the default." },
+        { key: "scanD", label: "Depth", unit: "mm", min: 10, max: 40, step: 0.5,
+          description: "Rebuild depth (Y). Matches the scan's depth at the default." },
+        { key: "scanH", label: "Height", unit: "mm", min: 4, max: 20, step: 0.5,
+          description: "Rebuild height (Z). Matches the scan's height at the default." },
+      ],
+    },
+    {
+      id: "mount",
+      title: "Mount",
+      description: "A plate with a through-socket cut to the scan's own shape — the import used as a real boolean component, not just a reference.",
+      advanced: [
+        { key: "fit", label: "Socket clearance", unit: "×", min: 1, max: 1.2, step: 0.01,
+          description: "Uniform scale applied to the imported scan before it's used as the cutting tool, so the block seats with a slip fit." },
+        { key: "margin", label: "Plate margin", unit: "mm", min: 1, max: 10, step: 0.5,
+          description: "Solid plate border kept around the socket on every side." },
+        // The socket is the scan's own (fixed, ~8mm-tall) imported geometry scaled
+        // by `fit` and overcut 1mm past the plate's bottom face — see `mount.build`
+        // below. It only stays a genuine through-hole (not a blind pocket) while
+        // plateH < scanH*fit - 1; at the worst-case corner (fit at its slider
+        // minimum, 1) that's plateH < 7. max is capped at 6.5, half a millimetre
+        // inside that bound, so every reachable (plateH, fit) combination — not
+        // just the defaults — keeps `mount: { holes: 1 }` true.
+        { key: "plateH", label: "Plate thickness", unit: "mm", min: 2, max: 6.5, step: 0.5,
+          description: "Mount plate thickness. The socket cuts all the way through it." },
+        { key: "gap", label: "Gap from rebuild", unit: "mm", min: 5, max: 30, step: 1,
+          description: "Presentation-only spacing between `body` and `mount` in the assembly view, so the two never overlap." },
+      ],
+    },
+  ],
+  defaults: { scanW: 20, scanD: 14, scanH: 8, fit: 1.05, margin: 3, plateH: 4, gap: 10 },
+  // mountOffsetX: how far along X the mount plate sits from the rebuild, so
+  // the two solids never interpenetrate regardless of the current dimensions.
+  derive: (p) => ({ mountOffsetX: p.scanW + p.gap }),
+  parts: {
+    // Ghost overlay of the raw import — ref* deviation is computed against
+    // this by name (`reference: "scan"` on `body`, below) regardless of which
+    // view is active, so `ref` only needs to appear in the "reference" view,
+    // where it's shown translucent over `body` for visual alignment checking.
+    // It is deliberately absent from "assembly": measure()'s `ok` requires
+    // zero sub-part overlaps in the measured view, and a ghost coincident
+    // with its rebuild always overlaps by design.
+    ref: {
+      label: "Reference (ghost)",
+      views: ["reference"],
+      exportable: false,
+      display: { opacity: 0.3 },
+      build: (k) => k.import("scan"),
+    },
+    // Parametric rebuild of the scanned block. `reference: "scan"` tells
+    // measure() to compute deviation facts (xorVolume / volumeDeltaPct /
+    // bboxDelta) against the import; verify.expect.body below gates on them.
+    // Shown in both views: alone (fitted with `mount`) in "assembly", and
+    // against the ghost in "reference".
+    body: {
+      label: "Rebuild",
+      views: ["assembly", "reference"],
+      export: { name: "body" },
+      reference: "scan",
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }),
+    },
+    // The import used as a real component: a plate with a through-socket cut
+    // to the (clearance-scaled) scan shape. Offset along X so it never
+    // overlaps `body` in the assembly view.
+    mount: {
+      label: "Mount plate",
+      views: ["assembly"],
+      export: { name: "mount" },
+      build: (k, p, d) => {
+        const plate = k.box({
+          min: [d.mountOffsetX - p.margin, -p.margin, -p.plateH],
+          max: [d.mountOffsetX + p.scanW * p.fit + p.margin, p.scanD * p.fit + p.margin, 0],
+        });
+        const socket = k.import("scan")
+          .scale(p.fit)
+          .translate([d.mountOffsetX, 0, -p.plateH - 1]); // overcut past both plate faces
+        return plate.cut(socket);
+      },
+    },
+  },
+  // "assembly" is first so `measure`/`verify`/`render` (which default to the
+  // first view key) see only the two real, non-overlapping parts — `mount`'s
+  // socket never touches `body` (see `mountOffsetX`). "reference" is the
+  // ghost-overlay view, browsed by hand or with an explicit view argument.
+  views: { assembly: { label: "Assembly" }, reference: { label: "Reference overlay" } },
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      body: {
+        holes: 0,
+        watertight: true,
+        bbox: "<=[30,20,15]",
+        // Deviation gate: at the defaults, body reproduces the scan's exact
+        // box dimensions, so all three read near-zero — thresholds below
+        // leave real margin rather than sitting on the exact values.
+        refXorVolume: "<=5mm3",
+        refVolumeDeltaPct: "<=1",
+        refBboxDelta: "<=[0.2,0.2,0.2]",
+      },
+      mount: { holes: 1, watertight: true, bbox: "<=[40,25,10]" },
+      // Checked against the default ("assembly") view only — `body` and
+      // `mount` are real, non-overlapping parts by construction (see
+      // `mountOffsetX`). The "reference" view's ghost is deliberately
+      // coincident with `body` (that's the point of the overlay) and would
+      // always read overlaps > 0, which is why it isn't the default view.
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/assets.js

@@ -0,0 +1,19 @@
+// Node-side source mapping for part asset declarations (fonts + imports):
+// framework resolvers use global fetch, which cannot read file: URLs in Node,
+// so map those to bytes here before handing the decl down. Everything else
+// (http(s) strings, bytes, thunks) passes through untouched.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function nodeAssetSources(decl) {
+  if (!decl) return decl;
+  const out = {};
+  for (const [name, src] of Object.entries(decl)) {
+    const u = src instanceof URL ? src : typeof src === "string" && src.startsWith("file:") ? new URL(src) : null;
+    if (u?.protocol === "file:") {
+      const b = readFileSync(fileURLToPath(u));
+      out[name] = b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+    } else out[name] = src;
+  }
+  return out;
+}

package/src/testing/manifold.js

@@ -4,12 +4,24 @@
 import Module from "manifold-3d";
 import { createManifoldKernel } from "../framework/geometry/manifold-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
+import { ensureImports } from "../framework/imports.js";
+import { nodeAssetSources } from "./assets.js";
+import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
   if (fonts) { const opentype = (await import("opentype.js")).default;
-    for (const [name, buf] of await resolveFonts(fonts)) kernel._fonts.set(name, opentype.parse(buf)); }
+    for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, opentype.parse(buf)); }
+  if (imports) {
+    const decl = nodeAssetSources(imports);
+    const { resolveImports } = await import("../framework/imports.js");
+    const resolved = await resolveImports(decl);
+    const stepEntries = [...resolved].filter(([, a]) => a.format === "step")
+      .map(([name, a]) => ({ name, bytes: a.bytes, digest: a.digest }));
+    const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
+    await ensureImports(kernel, decl, meshes);
+  }
   return kernel;
 }

package/src/testing/occt.js

@@ -6,8 +6,10 @@ import path from "path";
 import fs from "fs";
 import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
+import { ensureImports } from "../framework/imports.js";
+import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -17,6 +19,7 @@ export async function bootOcctKernel({ fonts } = {}) {
   replicad.setOC(OC);
   const kernel = createOcctKernel(replicad);
   if (fonts) { const opentype = (await import("opentype.js")).default;
-    for (const [name, buf] of await resolveFonts(fonts)) kernel._fonts.set(name, opentype.parse(buf)); }
+    for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, opentype.parse(buf)); }
+  if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
   return kernel;
 }

package/src/testing/step-mesh-thread.js

@@ -0,0 +1,15 @@
+// src/testing/step-mesh-thread.js — runs INSIDE the worker_thread only.
+import { parentPort, workerData } from "node:worker_threads";
+import { bootOcctKernel } from "./occt.js";
+
+const kernel = await bootOcctKernel();
+const out = [];
+const transfer = [];
+for (const { name, bytes, digest } of workerData) {
+  await kernel._registerImport({ name, digest, step: bytes });
+  const { positions, indices } = kernel.import(name).toIndexedMesh({ quality: "print" });
+  out.push({ name, digest, positions, indices });
+  transfer.push(positions.buffer, indices.buffer);
+}
+parentPort.postMessage(out, transfer);
+process.exit(0);

package/src/testing/step-mesh.js

@@ -0,0 +1,17 @@
+// STEP → triangle mesh for the Node crossover (Manifold part importing STEP).
+// OCCT boots in a worker_thread — a separate isolate is a separate WASM world,
+// so the "never both kernels in one process" invariant holds by construction.
+import { Worker } from "node:worker_threads";
+
+export function tessellateStepAssets(entries) {
+  return new Promise((resolve, reject) => {
+    const w = new Worker(new URL("./step-mesh-thread.js", import.meta.url),
+      { workerData: entries.map(({ name, bytes, digest }) => ({ name, bytes, digest })) });
+    w.once("message", (out) => {
+      resolve(new Map(out.map((m) => [m.name, { digest: m.digest, positions: m.positions, indices: m.indices }])));
+      w.terminate();
+    });
+    w.once("error", reject);
+    w.once("exit", (code) => { if (code !== 0) reject(new Error(`step tessellation thread exited ${code}`)); });
+  });
+}

package/types/kernel.d.ts

@@ -477,6 +477,12 @@ export interface GeometryKernel {
   hullChain(inputs: HullInput[]): Shape2D;
   /** STEP bytes — OCCT only (Manifold throws `KernelCapabilityError`). */
   toSTEP(named: Array<{ name: string; solid: Solid }>): Promise<ArrayBuffer>;
+  /**
+   * Imported geometry declared in the part's `imports` field, registered
+   * pre-build by the framework via the underscore-prefixed `_registerImport`
+   * side-channel (not a part author's calling surface).
+   */
+  import(name: string): Solid;
 
   // Backend-optional: the sub-part cache brackets and WASM lifetime hooks. Every
   // framework caller reaches these through `?.`, so a third-party backend may

package/types/part.d.ts

@@ -300,6 +300,14 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
   enabled?: (p: P) => unknown;
   /** `false` = reference/preview-only: shown in the viewer, never exported. */
   exportable?: boolean;
+  /**
+   * Name of a declared `imports` entry this sub-part is held to. When set,
+   * `measure()` computes a `deviation` fact (symmetric-difference volume,
+   * volume delta %, bbox-corner drift) against that import's posed solid, and
+   * `verify.expect.<subpart>` may use the `refXorVolume` / `refVolumeDeltaPct`
+   * / `refBboxDelta` gate metrics.
+   */
+  reference?: string;
   /** Viewer-only override — `color` is `0xRRGGBB`, `opacity` is 0..1. */
   display?: { color?: number; opacity?: number };
   /** Filename / object name on export; defaults to the key. */
@@ -362,6 +370,12 @@ export interface SubPartExpectations {
   boundsMin?: Expectation;
   boundsMax?: Expectation;
   minWall?: Expectation;
+  /** Symmetric-difference volume vs. the sub-part's declared `reference` import. */
+  refXorVolume?: Expectation;
+  /** Percent volume delta vs. the sub-part's declared `reference` import. */
+  refVolumeDeltaPct?: Expectation;
+  /** Bounding-box corner drift `[dx, dy, dz]` vs. the sub-part's declared `reference` import. */
+  refBboxDelta?: Expectation;
 }
 
 /**