partforge 0.63.0 → 0.64.0

package/src/framework/geometry/mesh-repair.js

@@ -0,0 +1,87 @@
+// Repair + diagnostics for imported meshes (STL/3MF soup, or already-indexed). Files in the
+// wild are inconsistently wound and sometimes non-manifold, so the import path runs these
+// before handing a mesh to Manifold.ofMesh: orient it outward, then measure how far it is
+// from watertight so the caller can decide whether to warn or refuse the import.
+
+import { reverseWinding } from "./mesh-build.js";
+
+// Read triangle `t`'s three vertex indices, working for both an indexed mesh (`indices` is
+// the triangle-index array) and an unindexed soup (`indices` is null/undefined, so the
+// triangle's own position offsets double as its "indices": 3t, 3t+1, 3t+2).
+function triIndices(indices, t) {
+  if (indices) return [indices[t * 3], indices[t * 3 + 1], indices[t * 3 + 2]];
+  return [t * 3, t * 3 + 1, t * 3 + 2];
+}
+
+function triCount(positions, indices) {
+  return indices ? indices.length / 3 : positions.length / 9;
+}
+
+function vertex(positions, i) {
+  return [positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]];
+}
+
+// Signed volume (mm^3) of a closed mesh: Sigma det(a,b,c)/6 over triangles, the standard
+// divergence-theorem formula. Positive when triangles wind CCW-outward, negative when the
+// whole mesh is inside-out. Works on soup (indices omitted) and indexed meshes alike, and
+// doesn't require the mesh to actually be closed - an open mesh just gives a meaningless
+// number, which is exactly the signal ensureOutward needs (sign, not validity).
+export function signedVolume(positions, indices) {
+  const n = triCount(positions, indices);
+  let vol = 0;
+  for (let t = 0; t < n; t++) {
+    const [i0, i1, i2] = triIndices(indices, t);
+    const [ax, ay, az] = vertex(positions, i0);
+    const [bx, by, bz] = vertex(positions, i1);
+    const [cx, cy, cz] = vertex(positions, i2);
+    vol += ax * (by * cz - bz * cy) - ay * (bx * cz - bz * cx) + az * (bx * cy - by * cx);
+  }
+  return vol / 6;
+}
+
+// Flip the whole mesh outward-facing if it's currently inside-out (negative signed volume),
+// by reversing every triangle's winding in place. A no-op when already outward (or when the
+// sign is ambiguous because the mesh isn't closed - nothing sensible to do there anyway).
+export function ensureOutward(positions, indices) {
+  if (signedVolume(positions, indices) < 0) reverseWinding(indices);
+}
+
+// Count boundary ("open") half-edges after welding vertices by exact position. A watertight
+// mesh has every directed edge matched by an opposite-direction edge on the neighboring
+// triangle; an edge whose reverse is missing borders a hole (or a non-manifold seam) and is
+// the diagnostic for "this import isn't a solid". The weld key is built from the raw
+// (Float32-precision) coordinate values - exact match is correct here because soup vertices
+// straight out of one STL/3MF file that are meant to coincide already have identical float32
+// bit patterns; no epsilon merge needed.
+export function openEdgeCount(positions, indices) {
+  const n = triCount(positions, indices);
+
+  // Weld: coordinate key -> canonical vertex id.
+  const weld = new Map();
+  function weldedId(i) {
+    const [x, y, z] = vertex(positions, i);
+    const key = `${x},${y},${z}`;
+    let id = weld.get(key);
+    if (id === undefined) { id = weld.size; weld.set(key, id); }
+    return id;
+  }
+
+  // Tally every directed edge (a -> b) across all triangles.
+  const edges = new Map();
+  for (let t = 0; t < n; t++) {
+    const [i0, i1, i2] = triIndices(indices, t);
+    const a = weldedId(i0), b = weldedId(i1), c = weldedId(i2);
+    for (const [u, v] of [[a, b], [b, c], [c, a]]) {
+      const key = `${u},${v}`;
+      edges.set(key, (edges.get(key) || 0) + 1);
+    }
+  }
+
+  // An edge is open when its reverse direction never appears.
+  let open = 0;
+  for (const key of edges.keys()) {
+    const [u, v] = key.split(",");
+    if (!edges.has(`${v},${u}`)) open++;
+  }
+  return open;
+}

package/src/framework/geometry/occt-backend.js

@@ -37,12 +37,17 @@ const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.25 }, print: { tol
 
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
-          loft, draw, exportSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
+          loft, draw, exportSTEP, importSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
 
   // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
   // see occt-repair.js for the policies and why they differ per op.
   const { validChamfer, safeOp } = createOcctRepair(measureVolume);
 
+  // name -> { shape, digest } | { error, digest } — imported geometry the framework
+  // registers pre-build via `_registerImport` (kernel-lifetime, untracked by the
+  // solid cache: imports are the framework's own memo, keyed by name+digest).
+  const imports = new Map();
+
   const cache = createSolidCache();
   // Boundary ops route through cache.lookup. pin is unused here (no cleanup() —
   // GC frees WASM via replicad's FinalizationRegistry) and dispose is a no-op:
@@ -487,6 +492,33 @@ export function createOcctKernel(replicad) {
     // surface.
     _offsetRegions: offsetRegions,
     toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._mat()._s }))).arrayBuffer(),
+    // Imported geometry, registered pre-build by the framework via `_registerImport`
+    // (ensureImports, Task 8). Every call clones the master shape — replicad ops
+    // consume their operands, and the master must never be handed out directly, or
+    // a second `import(name)` call would see the first caller's transform.
+    import: (name) => {
+      const e = imports.get(name);
+      if (!e) throw new Error(`import: unknown import "${name}" — declare it in the part's \`imports\` field`);
+      if (e.error) throw e.error; // lazy: unusable-format entries fail at use, not at registration
+      return wrap(e.shape.clone(), [], h("import", name, e.digest));
+    },
+    // Side-channel (underscore = off-contract, probe-invisible). Registration is
+    // TOTAL — it never throws for an unusable format (e.g. an STL/3MF import on
+    // this backend); an `{error}` entry is stored verbatim and thrown by
+    // `import(name)` above at call time (spec: "Registration is total; errors are
+    // lazy"). Re-registering the same name+digest is a no-op EXCEPT an error entry
+    // is always upgradable (the post-crossover retry depends on this — see
+    // `_importDigest`).
+    _registerImport: async ({ name, digest, step, error }) => {
+      const prev = imports.get(name);
+      if (!prev?.error && prev?.digest === digest) return; // error entries are always upgradable
+      if (error) { imports.set(name, { error, digest }); return; }
+      imports.set(name, { shape: await importSTEP(new Blob([step])), digest });
+    },
+    // Registration memo: undefined for an error entry, so a later registration with
+    // the same digest can upgrade it rather than being treated as a no-op repeat.
+    _importDigest: (name) => { const e = imports.get(name); return e?.error ? undefined : e?.digest; },
+    _acceptsStep: true,
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
     sweepCache: () => cache.sweep(),

package/src/framework/geometry/stl-parse.js

@@ -0,0 +1,45 @@
+// Pure-JS STL reader (ascii + binary), the read twin of mesh-stl.js's writer.
+// Returns triangle soup: positions x,y,z per vertex, indices 0..3n-1. Vertex
+// welding is deliberately NOT done here — Manifold's Mesh.merge() welds at
+// import (mesh-build.js), and the soup keeps this parser trivial and exact.
+const u8of = (b) => (b instanceof ArrayBuffer ? new Uint8Array(b) : b);
+
+function isAscii(u8) {
+  // "solid" prefix is not enough (binary files sometimes start with it);
+  // require an ascii "facet" token in the first 1 KB too.
+  const head = String.fromCharCode(...u8.slice(0, 1024));
+  return head.trimStart().startsWith("solid") && head.includes("facet");
+}
+
+export function parseStl(bytes) {
+  const u8 = u8of(bytes);
+  return isAscii(u8) ? parseAscii(u8) : parseBinary(u8);
+}
+
+function parseAscii(u8) {
+  const text = new TextDecoder().decode(u8);
+  const V = [];
+  const re = /vertex\s+([-+0-9.eE]+)\s+([-+0-9.eE]+)\s+([-+0-9.eE]+)/g;
+  for (let m; (m = re.exec(text)); ) V.push(Number(m[1]), Number(m[2]), Number(m[3]));
+  if (V.length === 0 || V.length % 9 !== 0)
+    throw new Error(`ascii STL parse failed: ${V.length / 3} vertices (not a multiple of 3)`);
+  return soup(Float32Array.from(V));
+}
+
+function parseBinary(u8) {
+  if (u8.length < 84) throw new Error("binary STL truncated: shorter than the 84-byte header");
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  const n = dv.getUint32(80, true);
+  if (u8.length < 84 + n * 50) throw new Error(`binary STL truncated: header says ${n} triangles, file has ${Math.floor((u8.length - 84) / 50)}`);
+  const positions = new Float32Array(n * 9);
+  for (let i = 0; i < n; i++) {
+    const o = 84 + i * 50 + 12; // skip the facet normal
+    for (let j = 0; j < 9; j++) positions[i * 9 + j] = dv.getFloat32(o + j * 4, true);
+  }
+  return soup(positions);
+}
+
+const soup = (positions) => ({
+  positions,
+  indices: Uint32Array.from({ length: positions.length / 3 }, (_, i) => i),
+});

package/src/framework/geometry/threemf-parse.js

@@ -0,0 +1,87 @@
+// Minimal 3MF reader, the read twin of threemf.js's writer. 3MF is an OPC
+// package (a zip) holding an XML model; unzip (fflate), find the model part,
+// extract vertices/triangles/per-item transforms and the model unit, and
+// merge every build item into one soup-free indexed mesh in millimetres.
+//
+// Regex-based extraction, NOT a DOM parse — workers have no DOMParser and the
+// worker graph must stay DOM-free (test/worker-layering.test.js enforces
+// this transitively). Scope: geometry only — materials, colors and beam
+// lattices are ignored, and only top-level <object><mesh> content is read
+// (no <components> nesting).
+import { unzipSync } from "fflate";
+
+const UNIT_MM = { micron: 0.001, millimeter: 1, centimeter: 10, inch: 25.4, foot: 304.8, meter: 1000 };
+
+export function parse3MF(bytes) {
+  const u8 = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+  let files;
+  try {
+    files = unzipSync(u8);
+  } catch (e) {
+    throw new Error(`3mf import: not a readable zip archive (${e?.message || e})`);
+  }
+  const modelPath = Object.keys(files).find((f) => f.toLowerCase().endsWith(".model"));
+  if (!modelPath) throw new Error("3mf import: archive has no 3D model part (*.model)");
+  const xml = new TextDecoder().decode(files[modelPath]);
+
+  const unit = xml.match(/<model\b[^>]*\bunit="([^"]+)"/)?.[1] ?? "millimeter";
+  const scale = UNIT_MM[unit];
+  if (!scale) throw new Error(`3mf import: unknown unit "${unit}"`);
+
+  // objects: id -> { P: number[] (already scaled to mm), I: number[] }
+  const objects = new Map();
+  const objRe = /<object\b[^>]*\bid="(\d+)"[^>]*>([\s\S]*?)<\/object>/g;
+  for (let m; (m = objRe.exec(xml)); ) {
+    const [, id, body] = m;
+    const P = [], I = [];
+    const vRe = /<vertex\b[^>]*\bx="([^"]+)"[^>]*\by="([^"]+)"[^>]*\bz="([^"]+)"/g;
+    for (let v; (v = vRe.exec(body)); ) P.push(+v[1] * scale, +v[2] * scale, +v[3] * scale);
+    const tRe = /<triangle\b[^>]*\bv1="(\d+)"[^>]*\bv2="(\d+)"[^>]*\bv3="(\d+)"/g;
+    for (let t; (t = tRe.exec(body)); ) I.push(+t[1], +t[2], +t[3]);
+    if (I.length) objects.set(id, { P, I });
+  }
+  if (objects.size === 0) throw new Error("3mf import: model contains no mesh geometry");
+
+  // Build items: <item objectid="N" transform="m00 m01 m02 m10 m11 m12 m20 m21
+  // m22 m30 m31 m32"/> — row-major 4x3, translation in the last row, per the
+  // 3MF core spec (the transform is applied to a row vector: v' = v*M, i.e.
+  // x' = x*m00 + y*m10 + z*m20 + m30, and so on). No <build>, or an object
+  // with no matching item, falls back to identity placement.
+  //
+  // Attributes are pulled independently from each <item> tag (rather than in
+  // one fixed-order regex) because `objectid` and `transform` can appear in
+  // either order and a single ordered pattern with an optional middle group
+  // can match the tag while silently leaving `transform` uncaptured.
+  const items = [];
+  const itemTagRe = /<item\b[^>]*\/>/g;
+  for (let m; (m = itemTagRe.exec(xml)); ) {
+    const tag = m[0];
+    const id = tag.match(/\bobjectid="(\d+)"/)?.[1];
+    if (!id) continue;
+    const t = tag.match(/\btransform="([^"]+)"/)?.[1];
+    items.push({ id, t: t ? t.trim().split(/\s+/).map(Number) : null });
+  }
+  const chosen = items.length ? items : [...objects.keys()].map((id) => ({ id, t: null }));
+
+  const V = [], Tr = [];
+  for (const { id, t } of chosen) {
+    const o = objects.get(id);
+    if (!o) continue;
+    const base = V.length / 3;
+    for (let i = 0; i < o.P.length; i += 3) {
+      let x = o.P[i], y = o.P[i + 1], z = o.P[i + 2];
+      if (t) {
+        // Translation components (m30 m31 m32) are expressed in model units
+        // per the 3MF spec, same as vertex coordinates — scale them to mm too
+        // so they combine correctly with the already-scaled x/y/z above.
+        const x2 = t[0] * x + t[3] * y + t[6] * z + t[9] * scale;
+        const y2 = t[1] * x + t[4] * y + t[7] * z + t[10] * scale;
+        const z2 = t[2] * x + t[5] * y + t[8] * z + t[11] * scale;
+        x = x2; y = y2; z = z2;
+      }
+      V.push(x, y, z);
+    }
+    for (const idx of o.I) Tr.push(base + idx);
+  }
+  return { positions: Float32Array.from(V), indices: Uint32Array.from(Tr) };
+}

package/src/framework/geometry-service.js

@@ -31,8 +31,10 @@ export function createGeometryService({ createWorker, onMessage }) {
   // Post a job to the chosen backend's worker. The message's own `type` says what to
   // do (generate / export-stl / export-3mf / export-step); `backend` picks the worker
   // — manifold for preview/STL/3MF, occt for STEP (the caller passes "occt" for that).
+  // `transfer` carries transferable buffers (e.g. priming a mesh's positions/indices
+  // into `prime-imports` without a structured-clone copy).
   return {
-    send: (msg, backend = "manifold") => workers[backend].postMessage(msg),
+    send: (msg, backend = "manifold", transfer = []) => workers[backend].postMessage(msg, transfer),
     terminate: () => terminateWorkers([workers.manifold, workers.occt]),
   };
 }

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}`));
+    },
+  },
+];