partforge 0.143.1 → 0.144.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.143.1",
+  "version": "0.144.1",
   "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/blend-surfaces.js

@@ -22,6 +22,12 @@
 //   { kind: "spine", pts, closed, r }
 //                                   general chain (mesh-fillet generalTool): the
 //                                   ball-centre polyline itself; r is the radius
+//   { kind: "planes", planes: [{ n, d }], tol }
+//                                   roundAll's flat faces (mesh-roundall.js
+//                                   flatFacePlanes): a point within tol of one plane
+//                                   (n·x = d) takes its normal; anywhere else — the
+//                                   rounded band off its seams — there is none, and
+//                                   creased-normals keeps the facet average
 //
 // A path's polyline usually STANDS FOR a smooth curve (a circle's rim, an outline's
 // rounded corner): its per-segment cylinders would shade faceted around the curve,
@@ -105,10 +111,32 @@ export function mapSurface(desc, M) {
         M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
       return { kind: "spine", closed: desc.closed, pts: desc.pts.map((p) => applyPt(M, p)), r: desc.r * s };
     }
+    case "planes": {
+      const s = Math.cbrt(Math.abs(
+        M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
+      return { kind: "planes", tol: desc.tol * s, planes: desc.planes.map(({ n, d }) => {
+        const n2 = norm(applyDir(M, n)) ?? n;
+        const p = applyPt(M, [n[0] * d, n[1] * d, n[2] * d]);
+        return { n: n2, d: n2[0] * p[0] + n2[1] * p[1] + n2[2] * p[2] };
+      }) };
+    }
     default: throw new Error(`blend surface: unknown kind ${desc.kind}`);
   }
 }
 
+// The plane x lies on, or null — off every plane, or on two at once (where two
+// flat faces would meet, which a rounded result never shows, so no answer is right).
+function planeNormal(desc, x) {
+  let hit = null;
+  for (const pl of desc.planes) {
+    const n = pl.n;
+    if (Math.abs(n[0] * x[0] + n[1] * x[1] + n[2] * x[2] - pl.d) > desc.tol) continue;
+    if (hit) return null;
+    hit = n;
+  }
+  return hit;
+}
+
 // Nearest spine point to x, in the descriptor's own frame.
 function spinePoint(desc, x) {
   switch (desc.kind) {
@@ -240,6 +268,7 @@ function nearestSegment(desc, x) {
 // Unit spine→point direction at x in the descriptor's frame, or null where undefined.
 export function surfaceNormal(desc, x) {
   if (desc.kind === "path") return pathNormal(desc, x);
+  if (desc.kind === "planes") return planeNormal(desc, x);
   if (desc.kind === "spine") {
     const { bi, bt } = nearestSegment(desc, x);
     if (bi < 0) return null;

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

@@ -18,8 +18,8 @@ import { meshToStl } from "./mesh-stl.js";
 import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
-import { affineAt, invertAffine, mapSurface } from "./blend-surfaces.js";
-import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
+import { affineAt, IDENTITY, invertAffine, mapSurface } from "./blend-surfaces.js";
+import { flatFacePlanes, meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
 import { SEGS, circleSegs, doubleCurvatureSegs } from "./circle-segs.js";
 import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
@@ -294,12 +294,20 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // round-trip, so the descriptor's original frame stays valid). Folding the band
   // into a single blend id, as this used to, lost every descriptor with it: a labeled
   // fillet shaded with facet normals again.
+  //
+  // "Blend" here is any surface that must keep an id of its own: a fillet band (the
+  // boundaryLines policy) or a surface carrying an analytic descriptor at all —
+  // roundAll's flat-face planes ride on a SMOOTH surface, and folding that into the
+  // base id would drop them and bring the flat-face shading gradient back on every
+  // labeled roundAll. Each keeps the policy it had (none, for the roundAll surface).
+  const keepsOwnId = (oid) => !!oidPolicies.get(oid)?.boundaryLines || blendSurfaces.has(oid);
   const reserveBlendRestamp = (oids) => {
-    const blends = [...oids].filter((oid) => !!oidPolicies.get(oid)?.boundaryLines);
+    const blends = [...oids].filter(keepsOwnId);
     const baseId = Manifold.reserveIDs(1 + blends.length);
     const blendIdFor = new Map(blends.map((oid, i) => [oid, baseId + 1 + i]));
     for (const [oid, id2] of blendIdFor) {
-      oidPolicies.set(id2, BLEND);
+      const pol = oidPolicies.get(oid);
+      if (pol !== undefined) oidPolicies.set(id2, pol);
       const surf = blendSurfaces.get(oid);
       if (surf) blendSurfaces.set(id2, surf);
     }
@@ -405,7 +413,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
           const isBlend = (oid) => !!oidPolicies.get(oid)?.boundaryLines;
           if (![...new Set(g0.runOriginalID)].some(isBlend)) return T(filleted._m.asOriginal());
           const { baseId, blendIdFor } = reserveBlendRestamp(new Set(g0.runOriginalID));
-          g0.runOriginalID = Uint32Array.from(g0.runOriginalID, (o) => (isBlend(o) ? blendIdFor.get(o) : baseId));
+          g0.runOriginalID = Uint32Array.from(g0.runOriginalID, (o) => blendIdFor.get(o) ?? baseId);
           // The constructor re-welds, and that can pinch a latent sliver off a
           // component as fresh femto-debris (the same rebirth dropDebris's own
           // compose() loop guards against) — sweep the reconstruction too.
@@ -423,6 +431,39 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     }
   };
 
+  // The reference roundAll's flat faces (mesh-roundall.js flatFacePlanes): the
+  // input's flat faces, which the chain returns exactly to their planes, become a
+  // "planes" descriptor on the result's surface so creased-normals shades them —
+  // and the band's seams beside them — with the plane's own normal. The tolerance
+  // sits well under the first ring of band vertices off each face (the same ring
+  // meshRoundAll's simplify tolerance protects), so only the face and its seam
+  // vertices are on a plane. Keyed on geometry like every descriptor (see
+  // blendSurfaces above), so it is never removed with the cache entry.
+  const markFlatFaces = (input, out, r) => {
+    const gi = input.getMesh();
+    let planes;
+    try {
+      planes = flatFacePlanes(gi, { policyFor: (oid) => oidPolicies.get(oid) });
+    } finally {
+      gi.delete?.();
+    }
+    if (!planes.length) return out;
+    const segs = roundAllSegs(2 * r, quality);
+    const tol = Math.min(1e-3, 0.25 * r * (1 - Math.cos((2 * Math.PI) / segs)));
+    const go = out.getMesh();
+    try {
+      const roid = go.runOriginalID, rt = go.runTransform;
+      for (let i = 0; i < roid.length; i++) {
+        // a fresh original carries no runTransform at all — identity, as creased-normals reads it
+        const inv = rt && rt.length >= (i + 1) * 12 ? invertAffine(affineAt(rt, i)) : IDENTITY;
+        if (inv) blendSurfaces.set(roid[i], mapSurface({ kind: "planes", planes, tol }, inv));
+      }
+    } finally {
+      go.delete?.();
+    }
+    return out;
+  };
+
   // Replay a recorded transform chain onto a solid. Each record maps back to the op
   // that produced it, so the replayed solid rebuilds the same chain on its own canon.
   const replay = (solid, chain) => chain.reduce(
@@ -503,7 +544,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       // key omits it for the same reason); it just spells out that the ball
       // tessellation, and so the result, is tier-dependent.
       return cached(h("roundAll", hash, r, quality), () =>
-        prismRoundAllFast(m, hash, r) ?? T(meshRoundAll(wasm, m, r, quality)));
+        prismRoundAllFast(m, hash, r) ?? markFlatFaces(m, T(meshRoundAll(wasm, m, r, quality)), r));
     },
     // batch difference: first minus the union of the rest, evaluated as one boolean
     // tree — no materialized intermediate union (the unionRaw memory note applies)
@@ -538,7 +579,6 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         // fresh so cached-solid reuse under another label cannot collide — the same
         // guarantee asOriginal() gives the plain path below.
         const g0 = m.getMesh();
-        const isBlend = (oid) => !!oidPolicies.get(oid)?.boundaryLines;
         const oids0 = new Set(g0.runOriginalID);
         // Sector-aware re-stamp: a provenance-sectored loft (the `sector` policy
         // marker) must keep every run's identity — folding them (either the plain
@@ -561,14 +601,16 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
             featureLabels.set(newId, name);
             const pol = oidPolicies.get(oldId);
             if (pol !== undefined) oidPolicies.set(newId, pol);
+            const surf = blendSurfaces.get(oldId); // analytic normals ride the 1:1 stamp too
+            if (surf) blendSurfaces.set(newId, surf);
             setIds.push(newId);
           }
           return { value: wrap(o, lh), pin: o, dispose: () => {
-            for (const id2 of setIds) { featureLabels.delete(id2); oidPolicies.delete(id2); }
+            for (const id2 of setIds) { featureLabels.delete(id2); oidPolicies.delete(id2); blendSurfaces.delete(id2); }
             o.delete?.();
           } };
         }
-        if ([...oids0].some(isBlend)) {
+        if ([...oids0].some(keepsOwnId)) {
           const { baseId, blendIdFor, blendIds } = reserveBlendRestamp(oids0);
           // base-group policy: the same triangle-weighted majority vote as the plain
           // path, but over the NON-blend runs only — blend runs would elect BLEND for
@@ -578,7 +620,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
           const weightByKey = new Map();
           let bestWeight = -1, basePol;
           for (let r = 0; r < roid.length; r++) {
-            if (isBlend(roid[r])) continue;
+            if (blendIdFor.has(roid[r])) continue;
             const pol = oidPolicies.get(roid[r]) ?? SMOOTH;
             const key = `${pol.creaseAngle}/${pol.sameSurfaceLines}/${!!pol.boundaryLines}`;
             const weight = (weightByKey.get(key) || 0) + (ri[r + 1] / 3 - ri[r] / 3);
@@ -586,7 +628,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
             const better = weight > bestWeight || (weight === bestWeight && !pol.sameSurfaceLines && basePol?.sameSurfaceLines);
             if (better) { bestWeight = weight; basePol = pol; }
           }
-          g0.runOriginalID = Uint32Array.from(roid, (o2) => (isBlend(o2) ? blendIdFor.get(o2) : baseId));
+          g0.runOriginalID = Uint32Array.from(roid, (o2) => blendIdFor.get(o2) ?? baseId);
           const o = T(new Manifold(g0));
           g0.delete?.();
           featureLabels.set(baseId, name);
@@ -764,6 +806,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/mesh-roundall.js

@@ -29,6 +29,7 @@
 // the two facetings still meets the tier's sagitta tolerance.
 
 import { segsForSagitta } from "./circle-segs.js";
+import { SMOOTH, cosDeg } from "./shading-policy.js";
 
 // Sphere tessellation from the facet sagitta r·(1 − cos(π/segs)): pick the
 // fewest segments that keep it under the quality tier's tolerance — its own
@@ -83,6 +84,121 @@ export function meshRoundAll(wasm, m, r, quality) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Flat-face shading. The reference path's result is one fresh surface, shaded
+// SMOOTH (35° crease), and the rounding ball's facets bend far less than that, so
+// a flat face used to share its corner normals with the band facets around it.
+// The vertex sum is unweighted, so a large face split into two triangles — a
+// sloped palm plate's top — took a several-degree tilt at each corner and showed
+// it as a shading gradient across the whole face (cloud feedback #167).
+//
+// The cure rests on the invariant above: the chain returns every planar face of
+// the input to its own plane. So the input's flat faces, found here, say exactly
+// where the result is flat; the backend registers them as an analytic "planes"
+// descriptor (blend-surfaces.js), and creased-normals then shades every vertex on
+// one of those planes — the band's seam vertices too, since the band is tangent
+// there — with the plane's normal, the same way a fillet band's seam agrees with
+// its face.
+//
+// "Flat" means flat the way the INPUT shades it: a coplanar group counts only if
+// every edge bounding it is one creased-normals would shade hard (a bend past the
+// surface's crease angle, or a cut seam). A rod's wall facets, or a slot's sides
+// running tangentially into its round ends, meet their neighbours softly — the
+// input already shades them as part of a curved surface, and pinning them to
+// their own planes would facet the rounded result.
+//
+// `g` is a MeshGL (or the same fields on plain arrays); `policyFor(oid)` returns
+// that surface's shading policy. Returns [{ n, d }] with n·x = d on the plane.
+const PLANE_COS = cosDeg(0.05); // coplanar neighbours: a boolean split, not a bend
+export function flatFacePlanes(g, { policyFor = () => SMOOTH } = {}) {
+  const np = g.numProp, vp = g.vertProperties, tris = g.triVerts;
+  const nTri = (tris.length / 3) | 0, nVert = (vp.length / np) | 0;
+  const remap = new Uint32Array(nVert);
+  for (let i = 0; i < nVert; i++) remap[i] = i;
+  const mf = g.mergeFromVert, mt = g.mergeToVert;
+  if (mf && mt) for (let i = 0; i < mf.length; i++) remap[mf[i]] = mt[i];
+  const triOID = new Uint32Array(nTri);
+  const ri = g.runIndex, roid = g.runOriginalID;
+  if (ri && roid) for (let r = 0; r < roid.length; r++)
+    for (let t = ri[r] / 3; t < ri[r + 1] / 3; t++) triOID[t] = roid[r];
+
+  // facet normals, areas and centroids; a degenerate triangle has no normal and
+  // takes no part — it neither joins a face nor disqualifies one
+  const fn = new Float64Array(nTri * 3), area = new Float64Array(nTri), cen = new Float64Array(nTri * 3);
+  let span = 0;
+  for (let t = 0; t < nTri; t++) {
+    const a = tris[t * 3] * np, b = tris[t * 3 + 1] * np, c = tris[t * 3 + 2] * np;
+    const ux = vp[b] - vp[a], uy = vp[b + 1] - vp[a + 1], uz = vp[b + 2] - vp[a + 2];
+    const vx = vp[c] - vp[a], vy = vp[c + 1] - vp[a + 1], vz = vp[c + 2] - vp[a + 2];
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+    const L = Math.hypot(nx, ny, nz);
+    area[t] = L / 2;
+    if (L > 0) { fn[t * 3] = nx / L; fn[t * 3 + 1] = ny / L; fn[t * 3 + 2] = nz / L; }
+    for (let k = 0; k < 3; k++) cen[t * 3 + k] = (vp[a + k] + vp[b + k] + vp[c + k]) / 3;
+    span = Math.max(span, Math.abs(vp[a]), Math.abs(vp[a + 1]), Math.abs(vp[a + 2]));
+  }
+  const live = (t) => area[t] > 1e-9;
+  const dot = (t, u) => fn[t * 3] * fn[u * 3] + fn[t * 3 + 1] * fn[u * 3 + 1] + fn[t * 3 + 2] * fn[u * 3 + 2];
+
+  // edge → incident triangles, on welded vertex ids
+  const edges = new Map();
+  for (let t = 0; t < nTri; t++) for (let k = 0; k < 3; k++) {
+    const p = remap[tris[t * 3 + k]], q = remap[tris[t * 3 + ((k + 1) % 3)]];
+    const key = p < q ? p * nVert + q : q * nVert + p;
+    const list = edges.get(key);
+    if (list) list.push(t); else edges.set(key, [t]);
+  }
+
+  // coplanar groups (union-find over shared edges)
+  const parent = new Int32Array(nTri);
+  for (let t = 0; t < nTri; t++) parent[t] = t;
+  const find = (t) => { while (parent[t] !== t) { parent[t] = parent[parent[t]]; t = parent[t]; } return t; };
+  for (const list of edges.values()) {
+    if (list.length !== 2) continue;
+    const [t, u] = list;
+    if (live(t) && live(u) && dot(t, u) > PLANE_COS) parent[find(t)] = find(u);
+  }
+
+  // a group is a flat face only if every edge leaving it would shade hard
+  const soft = new Uint8Array(nTri); // indexed by group root
+  const hard = (t, u) => {
+    const pt = policyFor(triOID[t]) ?? SMOOTH, pu = policyFor(triOID[u]) ?? SMOOTH;
+    if (triOID[t] !== triOID[u] && !(pt.boundaryLines || pu.boundaryLines)) return true;
+    return dot(t, u) < cosDeg(pt.creaseAngle);
+  };
+  for (const list of edges.values()) {
+    if (list.length !== 2) continue; // non-manifold: no smooth neighbour to share with
+    const [t, u] = list;
+    if (!live(t) || !live(u) || find(t) === find(u)) continue;
+    if (!hard(t, u)) soft[find(t)] = 1;
+    if (!hard(u, t)) soft[find(u)] = 1;
+  }
+
+  // one area-weighted plane per surviving group, merged where two groups share a
+  // plane (a degenerate triangle can split one face into two)
+  const acc = new Map();
+  for (let t = 0; t < nTri; t++) {
+    if (!live(t)) continue;
+    const root = find(t);
+    if (soft[root]) continue;
+    let e = acc.get(root);
+    if (!e) acc.set(root, (e = { n: [0, 0, 0], c: [0, 0, 0], a: 0 }));
+    for (let k = 0; k < 3; k++) { e.n[k] += fn[t * 3 + k] * area[t]; e.c[k] += cen[t * 3 + k] * area[t]; }
+    e.a += area[t];
+  }
+  const dTol = Math.max(1e-6, span * 1e-7);
+  const planes = [];
+  for (const e of acc.values()) {
+    const L = Math.hypot(...e.n);
+    if (!(L > 0)) continue;
+    const n = e.n.map((x) => x / L);
+    const d = (n[0] * e.c[0] + n[1] * e.c[1] + n[2] * e.c[2]) / e.a;
+    const dup = planes.find((p) => p.n[0] * n[0] + p.n[1] * n[1] + p.n[2] * n[2] > PLANE_COS && Math.abs(p.d - d) < dTol);
+    if (!dup) planes.push({ n, d });
+  }
+  return planes;
+}
+
 // ---------------------------------------------------------------------------
 // Prism detection for the fast path (manifold-backend.js). The Minkowski chain
 // above is seconds-per-thousand-triangles, but roundAll's expensive real-world

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 -----------------------------------------------
 
 /**