partforge 0.143.1 → 0.144.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.143.1",
+  "version": "0.144.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

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

@@ -764,6 +764,44 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         build,
       );
     },
+    // The change tracker's boolean diff (oracle/changes.js): two plain meshes in,
+    // added (new − old) and removed (old − new) material out, split into connected
+    // pieces. Never cached — it runs outside any beginSubPart bracket — and every
+    // WASM object is T()-tracked, so the caller's cleanup() frees all of it.
+    _meshDiff: (oldMesh, newMesh, { maxTriangles = 300000, minVolume = 0 } = {}) => {
+      const tris = (mesh) => (mesh.indices?.length ?? 0) / 3;
+      if (tris(oldMesh) + tris(newMesh) > maxTriangles) return { ok: false, reason: "too-large" };
+      let a, b;
+      try {
+        a = T(manifoldFromMesh(wasm, oldMesh.positions, oldMesh.indices));
+        b = T(manifoldFromMesh(wasm, newMesh.positions, newMesh.indices));
+      } catch {
+        return { ok: false, reason: "not-watertight" };
+      }
+      const regions = (mm) => {
+        const pieces = mm.decompose().map((p) => T(p));
+        return pieces
+          .map((p) => {
+            const { min, max } = p.boundingBox();
+            return {
+              mm3: p.volume(),
+              at: [0, 1, 2].map((i) => (min[i] + max[i]) / 2),
+              size: [0, 1, 2].map((i) => max[i] - min[i]),
+            };
+          })
+          .filter((r) => r.mm3 >= minVolume)
+          .sort((x, y) => y.mm3 - x.mm3);
+      };
+      const added = T(b.subtract(a));
+      const removed = T(a.subtract(b));
+      return {
+        ok: true,
+        addedMm3: added.volume(),
+        removedMm3: removed.volume(),
+        added: regions(added),
+        removed: regions(removed),
+      };
+    },
     // Polygon-with-holes extrude in one op: even/odd fill turns the extra contours into
     // holes regardless of their winding (outer + holes, no per-hole boolean cut).
     // A Shape2D `profile` (curve-native, possibly multi-region) materializes through

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

@@ -287,6 +287,7 @@ export function createOcctKernel(replicad) {
       _s: shape,
       _labels: labels,
       _hash: hash,
+      _baseHash: baseHash,
       _pose: pose,
       _mat: () => mat(),
       label: (name) => {

package/src/framework/geometry/solid-hash.js

@@ -2,8 +2,43 @@
 // folds via FNV-1a → base36. Solid operands are passed as their own (already
 // computed) short `_hash` string, so composing two solids stays O(1) and the
 // resulting key length stays bounded no matter how deep the build graph is.
+
+// Optional hash-graph recording for the oracle's change tracker
+// (oracle/changes.js). Off by default — `h` pays one null check. While on, every
+// call records its result with the op name and the operand hashes it consumed, so
+// the tracker can tell WHICH op first produced a different hash between two builds.
+// Single-threaded by construction (one worker, one synchronous build).
+let recording = null; // { map, limit, overflow }
+
+export function startHashRecording({ limit = 20000 } = {}) {
+  recording = { map: new Map(), limit, overflow: false };
+}
+
+export function stopHashRecording() {
+  const r = recording;
+  recording = null;
+  if (!r || r.overflow) return null;
+  return r.map;
+}
+
+const stringLeaves = (x, out) => {
+  if (typeof x === "string") out.push(x);
+  else if (Array.isArray(x)) for (const y of x) stringLeaves(y, out);
+  return out;
+};
+
 export function h(...parts) {
-  return fnv(parts.map(canon).join("|"));
+  const out = fnv(parts.map(canon).join("|"));
+  if (recording && !recording.overflow) {
+    const { map } = recording;
+    if (map.size >= recording.limit) recording.overflow = true;
+    else if (!map.has(out)) {
+      const op = typeof parts[0] === "string" ? parts[0] : null;
+      const inputs = stringLeaves(parts.slice(1), []).filter((s) => map.has(s));
+      map.set(out, { op, inputs, label: op === "label" && typeof parts[2] === "string" ? parts[2] : null });
+    }
+  }
+  return out;
 }
 
 function canon(x) {
@@ -14,6 +49,11 @@ function canon(x) {
 
 // FNV-1a folded to 32-bit space (collision risk acceptable: retained only for one
 // sub-part's build graph ~3–15 nodes, rebuilt each round, no accumulation).
+// These hashes are now also compared ACROSS inspect rounds: the oracle's change
+// tracker (oracle/changes.js) reads an equal final hash as "unchanged", and its
+// measure memo reuses that sub-part's facts. A collision there would report a
+// changed sub-part as unchanged and serve its stale measurements — the same
+// trust the solid cache already extends to these keys, and no wider.
 function fnv(s) {
   let hsh = 0x811c9dc5;
   for (let i = 0; i < s.length; i++) { hsh ^= s.charCodeAt(i); hsh = Math.imul(hsh, 0x01000193); }

package/src/framework/jobs.js

@@ -33,8 +33,15 @@ const loadInspect = () => Promise.all([
   import("./oracle/build.js"),
   import("./oracle/measure.js"),
   import("./oracle/verify.js"),
+  import("./oracle/changes.js"),
 ]);
 
+// The change tracker's baseline lives for the worker's lifetime (a tab, a headless
+// pool member) — one per worker, not per job, so an `inspect` can diff against the
+// PREVIOUS one under the same `changesKey`. Created lazily on first use so a
+// session that never passes `changesKey` never allocates it.
+let changeTracker = null;
+
 // The cut & print kit loads the same way, on the first export-bundle job: its writers,
 // layout and README (export/*) and the process exporters behind them are dead weight to
 // a session that never downloads a kit. test/worker-layering.test.js keeps every one of
@@ -597,12 +604,27 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // unrecognized value must never quietly buy less checking than the caller
       // asked for.
       const quick = msg.checks === "quick";
-      const [{ buildView }, { measure }, { verify }] = await loadInspect();
+      const [{ buildView }, { measure }, { verify }, { createChangeTracker }] = await loadInspect();
       const view = msg.view ?? Object.keys(part.views)[0];
+      // Only the defaults-params inspect is tracked: `msg.params` non-empty means a
+      // parameterized inspect, which is a different geometry and must never become
+      // (or be diffed against) the tracked baseline.
+      const tracking = typeof msg.changesKey === "string" && msg.changesKey.length > 0
+        && Object.keys(msg.params ?? {}).length === 0;
       const reads = newReadSink();
-      const built = buildView(kernel, part, view, msg.params ?? {}, { reads });
+      // Nothing may sit between begin() and the try below: a throw there would
+      // leave the hash recording running with no abort().
+      if (tracking) { changeTracker ??= createChangeTracker(); changeTracker.begin(msg.changesKey, view); }
+      let built;
+      try {
+        built = buildView(kernel, part, view, msg.params ?? {}, { reads });
+      } catch (e) {
+        if (tracking) changeTracker.abort();
+        throw e;
+      }
+      if (tracking) changeTracker.endBuild(built);
       const measured = measure(kernel, part, view, msg.params ?? {},
-        { minWall: !quick, gaps: !quick, built, reads });
+        { minWall: !quick, gaps: !quick, built, reads, ...(tracking ? { memo: changeTracker.memo } : {}) });
       const report = {
         measure: measured,
         verify: verify(kernel, part, {
@@ -622,7 +644,10 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // an inspect with no `matchTargets` answers on exactly the shape it always has.
       const match = await scoreMatchTargets(built, msg.matchTargets, onProgress);
       if (match) report.match = match;
-      post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
+      // Past measure()'s own kernel.cleanup(): finish() reads only `_hash` strings,
+      // shape hashes, placement matrices, and JS-owned mesh/volume data, never a live solid.
+      const changeFields = tracking ? changeTracker.finish(kernel, view, built, measured) : {};
+      post({ type: "report", ...report, ...changeFields }, match?.map((m) => m.delta.data.buffer) ?? []);
     } else if (opts.jobs && Object.hasOwn(opts.jobs, msg.type)) {
       await opts.jobs[msg.type](kernel, part, msg, post, { isStale: opts.isStale });
     }

package/src/framework/oracle/changes.js

@@ -0,0 +1,208 @@
+// What changed since the previous inspect of this view — the agent's
+// "did my edit do what I meant" signal (spec: partforge-cloud
+// docs/superpowers/specs/2026-09-30-geometry-diff-design.md). One tracker per
+// kernel lifetime (a worker, a headless pool); best-effort by design: a retired
+// worker, a new key or a new view simply has no baseline. Also hosts the measure
+// memo for sub-parts whose final hash did not change.
+//
+// Call order inside one inspect: begin → buildView → endBuild(built) → measure →
+// finish. endBuild is where every LIVE-solid read happens (hashes and the indexed
+// mesh the boolean diff needs): measure ends with kernel.cleanup(), which frees
+// the posed solids, so finish works only from what endBuild captured plus
+// measure's volumes.
+import { startHashRecording, stopHashRecording } from "../geometry/solid-hash.js";
+import { changedRoots } from "./op-graph.js";
+import { bounds } from "./mesh.js";
+import { composePose } from "../geometry/pose.js";
+
+// The share of the consumer's whole-report timeout this tracker may spend,
+// measured from begin() — buildView, endBuild's re-meshing and measure all run
+// before finish, so a budget counted from finish alone could push the report
+// past partforge-cloud's REPORT_TIMEOUT_MS (8 s), which discards match, measure
+// and verify together. 6 s leaves verify and match scoring the rest.
+export const REPORT_SHARE_MS = 6000;
+
+const centre = (positions) => {
+  const b = bounds(positions);
+  return [0, 1, 2].map((i) => (b.min[i] + b.max[i]) / 2);
+};
+const shapeHashOf = (s) => s?._canon?.hash ?? s?._baseHash ?? null;
+// The rotation block of a solid's placement — the trailing rigid transforms on
+// top of its shape hash: Manifold's canon chain ({op, ...}) or OCCT's pending
+// pose ({t, ...}). Composed rather than compared entry by entry, so two chains
+// that land on the same orientation agree. null when the backend exposes none.
+const rotationOf = (s) => {
+  const steps = s?._canon?.chain?.map(({ op, ...r }) => ({ t: op, ...r })) ?? s?._pose;
+  if (!Array.isArray(steps)) return null;
+  const m = composePose(steps);
+  return [m[0], m[1], m[2], m[4], m[5], m[6], m[8], m[9], m[10]];
+};
+const rotationChanged = (a, b) => !!a && !!b && a.some((v, i) => Math.abs(v - b[i]) > 1e-6);
+const triangleCount = (mesh) => (mesh?.indices ? mesh.indices.length / 3 : (mesh?.positions?.length ?? 0) / 9);
+// The boolean diff needs an INDEXED mesh. buildView's mesh is Manifold's
+// non-indexed soup, so a Manifold solid is re-meshed; an OCCT display mesh is
+// already indexed (and OCCT has no boolean diff), so it is copied rather than
+// re-tessellated at export quality.
+const indexedMeshOf = (solid, mesh) => {
+  const m = mesh?.indices ? mesh : solid.toIndexedMesh();
+  return { positions: Float32Array.from(m.positions), indices: Uint32Array.from(m.indices) };
+};
+
+export function createChangeTracker({ now = Date.now, budgetMs = 2000, maxTriangles = 300000 } = {}) {
+  let key = null;
+  let view = null;         // the view this round is building (from begin)
+  let baseline = null;     // { view, hashes:Set|null (null: the record overflowed), subparts: Map(name -> entry) }
+  let record = null;
+  // Map(name -> {hash, shape, rotation, centre, mesh, volume}) from endBuild;
+  // `mesh` is null for a sub-part too big to diff (over maxTriangles/2).
+  let captured = null;
+  let startedAt = null;    // begin()'s clock reading: the report deadline counts from here
+  let memoPrev = new Map(), memoNext = new Map();
+  let pairPrev = new Map(), pairNext = new Map();
+  const mk = (hash, k2) => `${hash}\u0000${k2}`;      // facts depend on geometry, not the name
+  const pk = (a, ha, b, hb) => `${a}\u0000${ha}\u0000${b}\u0000${hb}`;
+
+  // Stored under a structuredClone: the caller's `facts`/`gap` object is also
+  // handed out as part of the oracle's REPORT, which a consumer is free to
+  // mutate. Without the clone, that mutation reaches through the same object
+  // reference into the memo and poisons a later hit; cloning on write is what
+  // keeps the memo's copy independent of whatever happens to the report.
+  // Cloned on read too, for the same reason in the other direction: a hit is
+  // handed out in the report. Every clone is guarded — a value structuredClone
+  // refuses is simply not memoized (or reads as a miss), so measure measures
+  // instead of throwing.
+  const clone = (v) => { try { return structuredClone(v); } catch { return undefined; } };
+  const memo = {
+    get: (name, hash, k2) => {
+      const v = memoPrev.get(mk(hash, k2));
+      const c = v === undefined ? undefined : clone(v);
+      return c ? { ...c, name } : undefined;
+    },
+    set: (name, hash, k2, facts) => { const c = clone(facts); if (c !== undefined) memoNext.set(mk(hash, k2), c); },
+    getPair: (a, ha, b, hb) => { const v = pairPrev.get(pk(a, ha, b, hb)); return v === undefined ? undefined : clone(v); },
+    setPair: (a, ha, b, hb, gap) => { const c = clone(gap); if (c !== undefined) pairNext.set(pk(a, ha, b, hb), c); },
+  };
+
+  const reset = () => { baseline = null; memoPrev = new Map(); pairPrev = new Map(); };
+  const clearRound = () => { record = null; captured = null; startedAt = null; memoNext = new Map(); pairNext = new Map(); };
+  const prevFor = (v) => (baseline?.view === v ? baseline : null);
+
+  return {
+    memo,
+    begin(k, v) {
+      if (k !== key) { key = k; reset(); }
+      view = v;
+      clearRound();
+      startedAt = now();
+      startHashRecording();
+    },
+    endBuild(built) {
+      record = stopHashRecording();
+      captured = null;
+      if (!Array.isArray(built)) return;
+      try {
+        const prev = prevFor(view);
+        captured = new Map();
+        for (const { name, solid, mesh } of built) {
+          const hash = solid?._hash ?? null;
+          const old = prev?.subparts.get(name);
+          // An unchanged sub-part keeps the stored entry: no re-mesh for it.
+          if (old && hash && old.hash === hash) { captured.set(name, { ...old }); continue; }
+          // Re-meshing is uncounted by finish's budget, so a sub-part too big for
+          // the boolean diff anyway (the pair is refused past maxTriangles) is not
+          // captured at all: next round it falls back to the volume-delta verdict.
+          const big = triangleCount(mesh) > maxTriangles / 2;
+          captured.set(name, {
+            hash, shape: shapeHashOf(solid), rotation: rotationOf(solid),
+            centre: centre(mesh.positions), mesh: big ? null : indexedMeshOf(solid, mesh),
+          });
+        }
+      } catch {
+        captured = null;
+      }
+    },
+    abort() { stopHashRecording(); clearRound(); },
+    finish(kernel, v, built, measured) {
+      try {
+        // No capture means no baseline can be stored for this build: forget the
+        // old one too, so the next round reports {} rather than diffing two builds back.
+        if (!Array.isArray(built) || !captured || v !== view) { reset(); return {}; }
+        const start = now();
+        // Whichever ends first: the diff budget, or the report's share counted from begin().
+        const deadline = Math.min(start + budgetMs, (startedAt ?? start) + REPORT_SHARE_MS);
+        const vol = new Map((measured?.subparts ?? []).map((s) => [s.name, s.volume]));
+        const prev = prevFor(v);
+        const out = [];
+        let unchanged = 0, skipped = null, verdicts = 0, timedOut = false;
+        for (const [name, entry] of captured) {
+          entry.volume = vol.get(name) ?? null;
+          if (!prev) continue;
+          const old = prev.subparts.get(name);
+          if (!old) { out.push({ name, verdict: "new" }); verdicts++; continue; }
+          const { hash, shape, mesh, rotation } = entry;
+          if (hash && hash === old.hash) { unchanged++; verdicts++; continue; }
+          // Both graphs are needed: against a missing baseline graph every op reads as new.
+          const ops = record?.size && prev.hashes && hash ? changedRoots(record, hash, prev.hashes) : [];
+          const withOps = (o) => (ops.length ? { ...o, changedOps: ops } : o);
+          if (shape && shape === old.shape) {
+            // `moved` is the bounding-box centre's offset, so a rotation about the
+            // centre reads as ≈0 — `rotated` is what says the orientation changed.
+            const a = old.centre, b = entry.centre;
+            const rotated = rotationChanged(old.rotation, rotation);
+            out.push(withOps({ name, verdict: "moved", moved: [0, 1, 2].map((i) => b[i] - a[i]), ...(rotated ? { rotated: true } : {}) }));
+            verdicts++;
+            continue;
+          }
+          // Budget spent: this build is still stored whole as the next baseline
+          // (captured holds every entry), but nothing more is diffed.
+          if (timedOut || now() > deadline) { timedOut = true; continue; }
+          const delta = { volumeDeltaMm3: (entry.volume ?? 0) - (old.volume ?? 0) };
+          // Either side too big to have been captured: the diff would refuse it anyway.
+          if (!mesh || !old.mesh) {
+            if (typeof kernel?._meshDiff === "function") skipped ??= "too-large";
+            out.push(withOps({ name, verdict: "reshaped", ...delta })); verdicts++; continue;
+          }
+          if (typeof kernel?._meshDiff !== "function") {
+            out.push(withOps({ name, verdict: "reshaped", ...delta })); verdicts++; continue;
+          }
+          const floor = Math.max(0.5, 1e-4 * Math.abs(entry.volume ?? 0));
+          // A throw (a WASM fault, OOM) is not one of the reported skip reasons: it
+          // falls back to the volume delta and the loop goes on, so the baseline
+          // still rotates to this build.
+          let d;
+          try { d = kernel._meshDiff(old.mesh, mesh, { maxTriangles, minVolume: floor }); } catch { d = null; }
+          if (!d?.ok) {
+            if (d) skipped ??= d.reason;
+            out.push(withOps({ name, verdict: "reshaped", ...delta })); verdicts++; continue;
+          }
+          const add = d.addedMm3 > floor, rem = d.removedMm3 > floor;
+          const regions = [
+            ...d.added.map((r) => ({ change: "added", ...r })),
+            ...d.removed.map((r) => ({ change: "removed", ...r })),
+          ].sort((x, y) => y.mm3 - x.mm3).slice(0, 3);
+          out.push(withOps({
+            name, verdict: add && !rem ? "added" : rem && !add ? "removed" : "reshaped",
+            addedMm3: d.addedMm3, removedMm3: d.removedMm3, ...(regions.length ? { regions } : {}),
+          }));
+          verdicts++;
+        }
+        if (prev) for (const name of prev.subparts.keys()) if (!captured.has(name)) { out.push({ name, verdict: "deleted" }); verdicts++; }
+        baseline = { view: v, hashes: record ? new Set(record.keys()) : null, subparts: captured };
+        memoPrev = memoNext; pairPrev = pairNext;
+        if (!prev) return {};
+        if (timedOut && verdicts === 0) return { changesSkipped: "timeout" };
+        if (timedOut) skipped ??= "timeout";
+        // "unchanged" is a claim about EVERY sub-part, so a timed-out one rules it out.
+        const changes = out.length === 0 && !timedOut
+          ? { unchanged: true, subparts: [], unchangedSubparts: unchanged }
+          : { subparts: out, unchangedSubparts: unchanged };
+        return skipped ? { changes, changesSkipped: skipped } : { changes };
+      } catch {
+        reset();
+        return {};
+      } finally {
+        clearRound();
+      }
+    },
+  };
+}

package/src/framework/oracle/gaps.js

@@ -20,17 +20,30 @@ export const pairKey = (a, b) => [a, b].sort().join("×");
 // `bvhCache` is an optional caller-owned Map — see cachedBVH for the doctrine;
 // measure() draws min-wall's index out of the same one, so each sub-part mesh is
 // indexed once, not twice.
+// `prior(a, b) → {distance, at}|undefined` lets a caller skip a pair's distance
+// query entirely (the measure memo: both sub-parts' hashes matched a stored
+// pair). `onPair(a, b, gap)` is called for every pair, computed or reused, so
+// the caller can re-store what it just confirmed or learned. BVHs are built
+// lazily, one per sub-part, only for a sub-part that has at least one pair not
+// covered by `prior` — an all-unchanged view builds no BVH at all.
 //   → [{ a, b, distance, at: [x,y,z] }]
-export function meshGaps(built, { bvhCache } = {}) {
+export function meshGaps(built, { bvhCache, prior, onPair } = {}) {
   const hasTris = (m) => (m.indices ? m.indices.length > 0 : m.positions.length > 0);
-  const bvhs = built
-    .filter(({ mesh }) => hasTris(mesh))
-    .map(({ name, mesh }) => ({ name, bvh: cachedBVH(mesh, bvhCache) }));
+  const items = built.filter(({ mesh }) => hasTris(mesh));
+  const bvhOf = new Map();
+  const bvh = (it) => {
+    if (!bvhOf.has(it.name)) bvhOf.set(it.name, cachedBVH(it.mesh, bvhCache));
+    return bvhOf.get(it.name);
+  };
   const out = [];
-  for (let i = 0; i < bvhs.length; i++) {
-    for (let j = i + 1; j < bvhs.length; j++) {
-      const { distance, at } = bvhs[i].bvh.distanceTo(bvhs[j].bvh);
-      out.push({ a: bvhs[i].name, b: bvhs[j].name, distance, at });
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      const a = items[i].name, b = items[j].name;
+      const reused = prior?.(a, b);
+      const { distance, at } = reused ?? bvh(items[i]).distanceTo(bvh(items[j]));
+      const g = { a, b, distance, at };
+      onPair?.(a, b, { distance, at });
+      out.push(g);
     }
   }
   return out;

package/src/framework/oracle/measure.js

@@ -135,8 +135,9 @@ const transformPoint = (m, [x, y, z]) => [
 // is carried into the export pose by a rigid matrix — no second build — and the bed is
 // that pose's own lowest Z; `at` comes back in display coordinates, where every other
 // finding of this view sits. An unreadable or identical pose measures as shown.
-function printPoseOverhang(mesh, sp, { view, p, d, maxAngle, displayBedZ }) {
-  const m = p ? displayToPrintMatrix(sp, { view, p, d }) : null;
+// `m` is displayToPrintMatrix's answer, resolved by the caller: the measure memo
+// keys on it, since the pose comes from place() and is not part of the solid's hash.
+function printPoseOverhang(mesh, m, { maxAngle, displayBedZ }) {
   if (!m) return overhang(mesh, { maxAngle, bedZ: displayBedZ });
   const positions = Float32Array.from(mesh.positions);
   transformPositions(positions, m);
@@ -297,6 +298,42 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   const sheetBudget = { left: opts.sheetBudgetMs ?? SHEET_CHECK_BUDGET_MS, now: opts.now ?? Date.now };
   const subparts = built.map(({ name, solid, mesh }) => {
     const sheet = isSheetPart(part.parts[name]);
+    // A sub-part that is never printed (`exportable: false` — a reference ghost, a
+    // probe slab, a placeholder) is not judged for overhang, and neither is a sheet
+    // part (laser-cut, never printed). For one that is, the display→print matrix
+    // (printPoseOverhang) is read off place() with the resolved params — geometry-free,
+    // so it is resolved here, ahead of the memo, which must key on it.
+    const printed = part.parts[name]?.exportable !== false && !sheet;
+    const printMatrix = overhangAngle != null && printed && poseParams?.p
+      ? displayToPrintMatrix(part.parts[name], { view, p: poseParams.p, d: poseParams.d })
+      : null;
+    // Memo key = the inputs this sub-part's facts actually depend on, besides its
+    // own geometry hash: whether min-wall ran, at what sample budget and against
+    // which declared band, the overhang angle, and whether the sub-part is
+    // exportable (it gates overhangArea/overhangAngle/overhangAt via `printed`,
+    // below — without it, toggling `exportable` on unchanged geometry would
+    // return a stale overhang reading, or a non-exportable ghost would share a
+    // real sub-part's entry), and the display→print matrix the overhang reading
+    // poses the mesh by (it comes from place() and the params, not the geometry, so
+    // a param that moves only the print pose leaves the hash unchanged). Withheld for sheet parts, a declared `reference`
+    // sub-part (deviation reads another import), any sub-part when the view
+    // holds a sheet part (the budgeted 2-D pass and print-pose sizes are
+    // call-scoped, not per-sub-part cacheable), and a solid with no `_hash`
+    // (nothing to key reuse on).
+    const memoKey = opts.memo && !sheetView && !sheet && !part.parts[name]?.reference && solid?._hash
+      ? JSON.stringify({
+        mw: !!opts.minWall, s: minWallSamples ?? null, band: wallBands[name] ?? null,
+        oh: overhangAngle ?? null, ex: printed,
+        pm: printMatrix ? Array.from(printMatrix) : null,
+      })
+      : null;
+    if (memoKey) {
+      const hit = opts.memo.get(name, solid._hash, memoKey);
+      // Re-store on a hit: the memo rotates prev→next per round (changes.js), so
+      // a hit read only from `prev` and never re-written would be reused every
+      // OTHER round, not every round an unchanged sub-part is measured.
+      if (hit) { subBounds.push(hit.bounds); opts.memo.set(name, solid._hash, memoKey, hit); return hit; }
+    }
     const b = bounds(mesh.positions);
     subBounds.push(b);
     // Resolved lazily and only when asked for: without min-wall, a single-sub-part
@@ -306,13 +343,10 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       ? minWall(mesh, { bvh: cachedBVH(mesh, bvhCache), maxSamples: minWallSamples, band: wallBands[name] ?? null })
       : null;
     // One pass over the triangles, no index — cheap enough for every lap. The bed
-    // is this sub-part's own lowest Z in its PRINT pose (printPoseOverhang). A
-    // sub-part that is never printed (`exportable: false` — a reference ghost, a
-    // probe slab, a placeholder) is not judged. A sheet part is laser-cut, never
-    // printed: no overhang reading for it either.
-    const printed = part.parts[name]?.exportable !== false && !sheet;
+    // is this sub-part's own lowest Z in its PRINT pose (printPoseOverhang); `printed`
+    // (above) says whether it is judged at all.
     const oh = overhangAngle != null && printed
-      ? printPoseOverhang(mesh, part.parts[name], { view, ...poseParams, maxAngle: overhangAngle, displayBedZ: b.min[2] })
+      ? printPoseOverhang(mesh, printMatrix, { maxAngle: overhangAngle, displayBedZ: b.min[2] })
       : null;
     const vol = solid.volume();
     // Deviation-from-reference: only for a sub-part that declares `reference:
@@ -335,7 +369,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
         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 {
+    const facts = {
       name,
       bbox: size(b),
       bounds: { min: b.min, max: b.max },
@@ -373,6 +407,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       ...(printBboxes?.[name]?.size ? { printBbox: printBboxes[name].size } : {}),
       ...(printBboxes?.[name]?.error ? { printBboxError: printBboxes[name].error } : {}),
     };
+    if (memoKey) opts.memo.set(name, solid._hash, memoKey, facts);
+    return facts;
   });
 
   // Declared probes, evaluated regardless of view (they are part-level facts —
@@ -394,7 +430,16 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // pairGapChecks reads an empty table as "measured, and this pair has no distance"
   // and fails a declared gate on it, while an absent table reads as no reading.
   const measuredGaps = opts.gaps !== false;
-  const gaps = measuredGaps ? (built.length > 1 ? meshGaps(built, { bvhCache }) : []) : undefined;
+  const hashOf = new Map(built.map(({ name, solid }) => [name, solid?._hash ?? null]));
+  const gaps = measuredGaps
+    ? (built.length > 1
+      ? meshGaps(built, {
+        bvhCache,
+        prior: opts.memo ? (a, b) => (hashOf.get(a) && hashOf.get(b) ? opts.memo.getPair(a, hashOf.get(a), b, hashOf.get(b)) : undefined) : undefined,
+        onPair: opts.memo ? (a, b, g) => { if (hashOf.get(a) && hashOf.get(b)) opts.memo.setPair(a, hashOf.get(a), b, hashOf.get(b), g); } : undefined,
+      })
+      : [])
+    : undefined;
 
   // Rebuilds with the same kernel and cleans up at its end — every solid fact
   // above is already read, so this is safe.

package/src/framework/oracle/op-graph.js

@@ -0,0 +1,49 @@
+// Which operation FIRST produced a different result between two builds. The hash
+// graph comes from solid-hash.js's recorder; a hash absent from the previous build
+// is a changed op, and a changed op whose inputs are all unchanged is a ROOT —
+// everything downstream changed only because a root did. Pure; no kernel.
+
+export function ancestry(record, finalHash) {
+  const seen = new Set();
+  const stack = [finalHash];
+  while (stack.length) {
+    const k = stack.pop();
+    if (seen.has(k)) continue;
+    seen.add(k);
+    for (const i of record.get(k)?.inputs ?? []) stack.push(i);
+  }
+  return seen;
+}
+
+export function changedRoots(record, finalHash, baselineHashes, { max = 5 } = {}) {
+  const anc = ancestry(record, finalHash);
+  const isNew = (k) => record.has(k) && !baselineHashes.has(k);
+  // Forward edges inside this sub-part's ancestry, for the label search.
+  const consumers = new Map();
+  for (const k of anc) for (const i of record.get(k)?.inputs ?? []) {
+    if (!consumers.has(i)) consumers.set(i, []);
+    consumers.get(i).push(k);
+  }
+  const labelFor = (k) => {
+    const queue = [k];
+    const seen = new Set();
+    while (queue.length) {
+      const c = queue.shift();
+      if (seen.has(c)) continue;
+      seen.add(c);
+      const e = record.get(c);
+      if (e?.op === "label" && e.label) return e.label;
+      for (const n of consumers.get(c) ?? []) queue.push(n);
+    }
+    return null;
+  };
+  const out = [];
+  for (const [k, e] of record) {
+    if (out.length >= max) break;
+    if (!anc.has(k) || !isNew(k)) continue;
+    if (e.inputs.some(isNew)) continue;
+    const label = labelFor(k);
+    out.push(label ? { op: e.op ?? "op", label } : { op: e.op ?? "op" });
+  }
+  return out;
+}

package/src/framework/stale-touch-guard.js

@@ -1,63 +1,63 @@
 // src/framework/stale-touch-guard.js
-// Keeps the camera controls from holding onto a finger that has already left
-// the screen.
+// Keeps the viewer from holding onto a finger that has already left the
+// screen.
 //
 // OrbitControls tracks every pointer that goes down on the canvas and forgets
-// one only on its pointerup or pointercancel. When the page is embedded in a
-// host that runs its own gestures (a chat app's WKWebView, which scrolls the
-// conversation on a vertical drag), the host can take a drag over and the page
-// never hears that finger lift. The controls then keep it as down forever: the
-// next one-finger drag reads as a two-finger pinch (it zooms), and with two
-// stuck, no drag moves the camera at all.
+// one only on its pointerup or pointercancel, and the view cube, the cutaway
+// handles and measure mode track pointers the same way on their own elements.
+// When the page is embedded in a host that runs its own gestures (a chat app's
+// WKWebView, which scrolls the conversation on a vertical drag), the host can
+// take a drag over and the page never hears that finger lift. Whatever it went
+// down on then keeps it as down forever: for the controls the next one-finger
+// drag reads as a two-finger pinch (it zooms), and with two stuck, no drag
+// moves the camera at all; the view cube keeps its press, so a hover over it
+// spins the camera.
 //
-// Two measures, both on the canvas's document and both passive:
+// Two measures, both on the root's document and both passive:
 //
 // 1. Do-nothing touchstart/touchend/touchcancel listeners. WebKit on iOS hands
 //    a touch to the page only where the page listens for TOUCH events, and the
-//    controls listen for pointer events alone, so without these the host's
+//    viewer listens for pointer events alone, so without these the host's
 //    gesture recognizers could claim a drag the page itself was handling.
 //
-// 2. Stale fingers are cancelled on arrival. A touch pointerdown marked
-//    isPrimary is the first finger of a brand-new gesture, so no other touch
-//    can really be down; every touch id still recorded as down on the canvas is
-//    sent the pointercancel it missed, from a capture listener on the document
-//    (which runs before the controls' own listener on the canvas). A second
+// 2. Stale fingers are cancelled on arrival. Every touch that goes down inside
+//    the viewer's root is recorded with the element it went down on (a touch
+//    outside the root is the host's business and is never recorded). A touch
+//    pointerdown marked isPrimary is the first finger of a brand-new gesture,
+//    so no other touch can really be down; every touch id still recorded is
+//    sent the pointercancel it missed, on the element it went down on and
+//    carrying the isPrimary it went down with (the view cube ignores a
+//    non-primary pointer, cancel included), from a capture listener on the
+//    document (which runs before any listener inside the root). A second
 //    finger of the same gesture is never primary, so pinch and two-finger pan
 //    are untouched.
 //
-// The controls release pointer capture for the id they remove, and that call
-// throws for an id the browser has already forgotten, aborting their cleanup
-// half way (the move listeners and the gesture state would stay live). So the
-// canvas's releasePointerCapture is wrapped to ignore that one failure.
+// Whatever receives the cancel releases pointer capture for that id, and that
+// call throws for an id the browser has already forgotten, aborting the
+// cleanup half way (OrbitControls would keep its move listeners and gesture
+// state live; the view cube would keep its press). So while a cancel is being
+// dispatched, its element's releasePointerCapture ignores that one failure,
+// and is put back the moment the dispatch returns.
 const TOUCH_TYPES = ["touchstart", "touchend", "touchcancel"];
 
-export function guardStaleTouches(element) {
-  const doc = element.ownerDocument;
+export function guardStaleTouches(root) {
+  const doc = root.ownerDocument;
   if (!doc) return () => {};
   const noop = () => {};
-  const touchesDown = new Set();
-
-  const release = element.releasePointerCapture;
-  if (typeof release === "function") {
-    element.releasePointerCapture = function releaseIfHeld(pointerId) {
-      try {
-        release.call(this, pointerId);
-      } catch {
-        // Already released: the finger is gone, which is all the caller wanted.
-      }
-    };
-  }
+  const touchesDown = new Map(); // pointerId -> { target, isPrimary } it went down with
 
   const onDown = (event) => {
     if (event.pointerType !== "touch") return;
     if (event.isPrimary && touchesDown.size) {
-      for (const pointerId of [...touchesDown]) {
+      for (const [pointerId, down] of [...touchesDown]) {
         if (pointerId === event.pointerId) continue;
         touchesDown.delete(pointerId);
-        element.dispatchEvent(new PointerEvent("pointercancel", { pointerId, pointerType: "touch", bubbles: true }));
+        cancelStale(down, pointerId);
       }
     }
-    if (event.target === element) touchesDown.add(event.pointerId);
+    if (root.contains(event.target)) {
+      touchesDown.set(event.pointerId, { target: event.target, isPrimary: event.isPrimary });
+    }
   };
   const onEnd = (event) => { touchesDown.delete(event.pointerId); };
 
@@ -71,7 +71,28 @@ export function guardStaleTouches(element) {
     doc.removeEventListener("pointerdown", onDown, { capture: true });
     doc.removeEventListener("pointerup", onEnd, { capture: true });
     doc.removeEventListener("pointercancel", onEnd, { capture: true });
-    if (typeof release === "function") element.releasePointerCapture = release;
     touchesDown.clear();
   };
 }
+
+function cancelStale({ target, isPrimary }, pointerId) {
+  const release = target.releasePointerCapture;
+  const ownRelease = Object.hasOwn(target, "releasePointerCapture");
+  if (typeof release === "function") {
+    target.releasePointerCapture = function releaseIfHeld(id) {
+      try {
+        release.call(this, id);
+      } catch {
+        // Already released: the finger is gone, which is all the caller wanted.
+      }
+    };
+  }
+  try {
+    target.dispatchEvent(new PointerEvent("pointercancel", { pointerId, pointerType: "touch", isPrimary, bubbles: true }));
+  } finally {
+    if (typeof release === "function") {
+      if (ownRelease) target.releasePointerCapture = release;
+      else delete target.releasePointerCapture;
+    }
+  }
+}

package/src/framework/viewer.js

@@ -205,9 +205,11 @@ export function createViewer(container, part) {
 
   const controls = new OrbitControls(activeCamera, renderer.domElement);
   controls.enableDamping = true;
-  // A finger a host gesture swallowed would otherwise stay "down" in the
-  // controls forever (every later drag zooms) — see stale-touch-guard.js.
-  const disposeTouchGuard = guardStaleTouches(renderer.domElement);
+  // A finger a host gesture swallowed would otherwise stay "down" forever in
+  // whatever it went down on — the controls (every later drag zooms), the view
+  // cube, the cutaway handles, measure mode — so the guard watches the whole
+  // container they all live in. See stale-touch-guard.js.
+  const disposeTouchGuard = guardStaleTouches(container);
 
   // --- render on demand -------------------------------------------------------
   // The loop ticks every animation frame (controls, tweens, frame listeners —

package/src/oracle.js

@@ -19,6 +19,10 @@ export { meshVolume, bboxSize, bounds, meshArea } from "./framework/oracle/mesh.
 export { buildView } from "./framework/oracle/build.js";
 export { measure } from "./framework/oracle/measure.js";
 export { verify } from "./framework/oracle/verify.js";
+// Change tracking — the `inspect` job's opt-in "what changed since my last
+// inspect of this view" signal, re-exported so a downstream harness can run the
+// same tracker outside the job loop (e.g. across a scripted sequence of builds).
+export { createChangeTracker } from "./framework/oracle/changes.js";
 export { buildBVH, meshTriangles } from "./framework/oracle/bvh.js";
 export { minWall } from "./framework/oracle/min-wall.js";
 export { overhang } from "./framework/oracle/overhang.js";

package/types/oracle.d.ts

@@ -11,6 +11,9 @@ export {
   measure, verify, buildView,
   type MeasureReport, type SubPartFacts, type SheetFacts, type AggregateFacts, type BuiltSubPart,
   type VerifyReport, type VerifyCaseResult, type VerifyCheck, type CheckStatus,
+  // change tracking
+  createChangeTracker,
+  type ChangeTracker, type ChangesReport, type SubPartChange, type ChangeRegion, type ChangeOpRef,
   // mesh facts, gaps, BVH, min wall
   meshVolume, bboxSize, bounds, meshArea, assemblyGaps, meshGaps, buildBVH, meshTriangles, minWall, overhang,
   type Gap, type BVH,

package/types/testing.d.ts

@@ -73,6 +73,16 @@ export interface WorkerJob {
    * relative order of the targets sharing that kind, never by index.
    */
   matchTargets?: MatchTarget[];
+  /**
+   * `inspect`: opt into change tracking. Opaque — the worker keeps one baseline
+   * per key, per worker lifetime, best-effort (a retired worker, a new key, or a
+   * new `view` simply has no baseline yet). A new key forgets whatever baseline
+   * the previous one held. Only an inspect with no (or empty) `params` is tracked
+   * — a parameterized inspect is a different geometry and never becomes, or is
+   * diffed against, the baseline. When present, `report.changes`/
+   * `report.changesSkipped` are added; absent, the report is unchanged.
+   */
+  changesKey?: string;
 }
 
 /**
@@ -485,6 +495,13 @@ export function measure(
      * build of the same view you are asking about.
      */
     built?: BuiltSubPart[];
+    /**
+     * A `ChangeTracker`'s `memo` — reuses a previous round's facts (and sub-part
+     * pair gap distances) for any sub-part whose final hash did not change,
+     * instead of re-deriving them. Opaque; hand in `changeTracker.memo` and
+     * nothing else.
+     */
+    memo?: unknown;
   },
 ): MeasureReport;
 
@@ -574,6 +591,92 @@ export function verify(
   },
 ): VerifyReport;
 
+// --- change tracking ---------------------------------------------------------
+
+/** One root operation behind a sub-part's changed final hash, named by the op graph. */
+export interface ChangeOpRef {
+  op: string;
+  label?: string;
+}
+
+/** One connected region of material a mesh boolean diff found added or removed. */
+export interface ChangeRegion {
+  change: "added" | "removed";
+  mm3: number;
+  at: [number, number, number];
+  size: [number, number, number];
+}
+
+export interface SubPartChange {
+  name: string;
+  verdict: "new" | "deleted" | "moved" | "added" | "removed" | "reshaped";
+  /**
+   * `verdict: "moved"` only: the sub-part's new bounding-box centre minus its old
+   * one, in mm. A rotation about that centre reads as ≈[0, 0, 0] — see `rotated`.
+   */
+  moved?: [number, number, number];
+  /** `verdict: "moved"` only, present (true) when the placement's orientation changed too. */
+  rotated?: boolean;
+  /** `verdict: "reshaped" | "added" | "removed"`: new volume minus old, in mm³. */
+  volumeDeltaMm3?: number;
+  /** `verdict: "added" | "removed" | "reshaped"`, when a mesh boolean diff ran. */
+  addedMm3?: number;
+  removedMm3?: number;
+  /** Up to 3 largest added/removed regions from the mesh boolean diff, largest first. */
+  regions?: ChangeRegion[];
+  /** The named root operations behind the changed hash, when the op graph covers it. */
+  changedOps?: ChangeOpRef[];
+}
+
+export interface ChangesReport {
+  /** True only when every sub-part's final hash matched the previous build's. */
+  unchanged?: true;
+  subparts: SubPartChange[];
+  unchangedSubparts: number;
+}
+
+/**
+ * Per-worker, best-effort "what changed since the last inspect of this view"
+ * tracker behind `inspect`'s `changesKey`. One tracker holds exactly one
+ * baseline at a time (per `begin`'s `key`); a new key or a new `view` simply has
+ * no baseline yet, which is reported as `{}` from `finish`, not an error.
+ *
+ * Call order for one round: `begin` → `buildView` → `endBuild(built)` →
+ * (optionally `measure` with `{ memo: tracker.memo }`) → `finish`. A failure
+ * before `endBuild`/`finish` calls `abort()` instead, which forgets the round
+ * without touching the stored baseline.
+ */
+export interface ChangeTracker {
+  /** Hand to `measure`'s `memo` option to reuse facts for unchanged sub-parts. */
+  readonly memo: unknown;
+  /** Start a round. `key` identifies the baseline; a different key forgets it. */
+  begin(key: string, view: string): void;
+  /** Capture the just-built view. Call right after `buildView`, before `kernel.cleanup()`. */
+  endBuild(built: BuiltSubPart[]): void;
+  /** The round failed before `finish`: discard it without touching the baseline. */
+  abort(): void;
+  /**
+   * Diff this build against the stored baseline and roll it forward as the next
+   * baseline. Call after `measure()` — `measure` calls `kernel.cleanup()`
+   * internally, which is fine: `finish` reads only hash strings, JS-owned mesh
+   * arrays, and `measured.subparts[].volume`, never a live solid.
+   */
+  finish(
+    kernel: GeometryKernel,
+    view: string,
+    built: BuiltSubPart[],
+    measured: MeasureReport,
+  ): { changes?: ChangesReport; changesSkipped?: string };
+}
+
+export function createChangeTracker(opts?: {
+  now?: () => number;
+  /** Milliseconds the mesh boolean diff may spend across one `finish()` call (default 2000). */
+  budgetMs?: number;
+  /** Sub-parts whose combined old+new triangle count exceeds this skip the mesh diff (default 300000). */
+  maxTriangles?: number;
+}): ChangeTracker;
+
 // --- silhouette match scoring -----------------------------------------------
 
 /**