partforge 0.69.0 → 0.71.0

package/docs/KERNEL-CONTRACT.md

@@ -98,6 +98,37 @@ them loses sub-part caching and mesh-topology gates (`holes`, emptiness), nothin
 a part (never inside a `beginSubPart`/`endSubPart` bracket), it drops cache partitions that
 have gone unbuilt for three consecutive rebinds.
 
+`beginSubPart`/`endSubPart` brackets MAY nest: only the outermost pair opens and
+commits a round, and an inner pair is a balanced no-op. Nesting is real rather than
+theoretical — `buildView` opens a round of its own, so any caller that brackets around
+a view build contains one. A backend that keeps a single open round (rather than a
+stack) must collapse inner pairs this way; committing on the inner `end()` would close
+the outer round early and leave the rest of that build uncached.
+
+Sub-part brackets bound cache RETENTION, not reuse: a solid one sub-part builds is reused
+by any other that asks for the same content hash, so a sheet of identical cells split
+across row sub-parts evaluates each distinct cell once rather than once per row. An adopted
+entry is retained by both partitions and disposed only when the last one drops it.
+
+The oracle (`buildView`, `assemblyOverlaps`) brackets under partition names of its
+own rather than the display sub-part names, and a host adding another oracle-side build
+should do the same. Both reuse the display build's solids through the cross-partition
+index, so measuring a view costs almost nothing right after drawing it; keeping them in
+separate partitions is what stops a measurement's own geometry — verify walks cases with
+params of their own — from displacing the geometry the viewer is showing.
+
+**Transform hoisting.** Booleans commute with rigid transforms, so a conforming backend MAY
+lift a transform every operand shares out of the boolean and apply it to the result
+instead — which is what lets N identically-built copies share one evaluation. Two
+consequences a host must expect. Hoisting evaluates the boolean in a different frame, so
+the result is geometrically equivalent but **not** guaranteed mesh-identical: vertex order,
+triangulation, and triangle count may differ (measured on the in-repo `scott-label`
+lettering: same genus and bounding box, volume agreeing to ~1e-9 relative, ~1% more
+triangles). Output stays deterministic for a given build. And an op is eligible only if it
+provably commutes with the transform — `fillet`/`chamfer` do NOT, because their edge
+selectors can be world-space, so hoisting past one would select different edges and emit
+wrong geometry.
+
 **`import`.** `kernel.import(name) → Solid` returns previously-registered imported geometry
 (STL/STEP/3MF geometry declared in a part's `imports` field); `_registerImport`/
 `_importDigest`/`_acceptsStep`/`_acceptsMesh` are the underscore-prefixed side-channel the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.69.0",
+  "version": "0.71.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/assembly.js

@@ -9,10 +9,17 @@ import { viewSubParts, resolveParams, buildPosed } from "./part-model.js";
 //   → [{ a, b, volume, location }] for each offending pair (empty = no collisions)
 export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1 } = {}) {
   const { p, d } = resolveParams(part, params);
-  const posed = viewSubParts(part, view, p).map((name) => ({
-    name,
-    solid: buildPosed(kernel, part, name, { purpose: "display", view, p, d }),
-  }));
+  // Same posed solids buildView builds, so this round is almost entirely hits off
+  // that one; only the pairwise intersects below are new. Its own oracle partition,
+  // for the reason buildView's comment gives.
+  kernel.beginSubPart?.(`oracle:overlaps:${view}`);
+  let posed;
+  try {
+    posed = viewSubParts(part, view, p).map((name) => ({
+      name,
+      solid: buildPosed(kernel, part, name, { purpose: "display", view, p, d }),
+    }));
+  } catch (e) { kernel.endSubPart?.(); throw e; } // never strand the round on a failed build
 
   const overlaps = [];
   for (let i = 0; i < posed.length; i++) {
@@ -27,6 +34,7 @@ export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance =
       }
     }
   }
-  kernel.cleanup?.(); // free the per-check WASM objects
+  kernel.endSubPart?.();
+  kernel.cleanup?.(); // free the per-check WASM objects (cached solids are pinned)
   return overlaps;
 }

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

@@ -7,6 +7,7 @@ import { h } from "./solid-hash.js";
 import { ensureOutward, openEdgeCount } from "./mesh-repair.js";
 import { manifoldFromMesh } from "./mesh-build.js";
 import { createSolidCache } from "./solid-cache.js";
+import { hoistCommonSuffix } from "./transform-hoist.js";
 import { addSugar } from "./solid-sugar.js";
 import { makeShape2dFactory } from "./shape2d.js";
 import { offsetRegions } from "./contour-offset.js";
@@ -94,6 +95,20 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     return { value: wrap(m, hash), pin: m, dispose: () => m.delete?.() };
   });
 
+  // Booleans commute with any invertible affine map, so a transform EVERY operand
+  // ends with can be lifted out of the boolean and applied to its result instead.
+  // That is what collapses N identically-built copies into one evaluation: with the
+  // shared transform gone, the operand hashes are identical for every copy, so the
+  // boolean itself hits the cache. Returns null when nothing is shared, leaving the
+  // caller on its ordinary path.
+  const hoistBoolean = (opName, solids, evaluate) => {
+    const { hoisted, residuals } = hoistCommonSuffix(solids.map((s2) => s2._canon.chain));
+    if (!hoisted.length) return null;
+    const ops = solids.map((s2, i) => replay(wrap(s2._canon.m, s2._canon.hash), residuals[i]));
+    const canonical = cached(h(opName, ops.map((s2) => s2._hash)), () => evaluate(ops));
+    return replay(canonical, hoisted);
+  };
+
   // Contour-IR region list -> flat point rings at `nSeg` (outer + holes, even/odd
   // fill sorts them out). The one place the IR meets CrossSection.ofPolygons.
   const regionPolys = (regions, nSeg) => regions.flatMap((rg) =>
@@ -306,14 +321,27 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     }
   };
 
+  // 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(
+    (s2, r) => (r.op === "translate" ? s2.translate(r.v) : s2.rotate(r.deg, r.center, r.axis)), solid);
+
+  // `canon` is this solid expressed as a base solid plus the trailing transform chain
+  // applied to it (oldest first). Only ops that provably COMMUTE with a rigid
+  // transform extend the chain — translate, rotate, and label; everything else starts
+  // a fresh canonical base. fillet/chamfer are deliberately excluded even though they
+  // look eligible: their edge selectors can be world-space, so filleting the
+  // untranslated base would pick different edges — wrong geometry, not a missed hit.
+  //
   // `self` names the wrapper being built so the degrading public fillet/chamfer
   // can delegate to their throwing `_`-prefixed twins above without re-deriving
   // the cache key or the capability checks. Declared as a binding the closures
   // capture: every reference runs after addSugar has returned.
-  const wrap = (m, hash) => {
+  const wrap = (m, hash, canon = { m, hash, chain: [] }) => {
     const self = addSugar({
     _m: m,
     _hash: hash,
+    _canon: canon,
     cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
     // THROWING forms. These are the composition primitives — internal callers
     // that have their own recovery (prismRoundAllFast, which answers a failed
@@ -388,6 +416,11 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // registry entry lives exactly as long as the cache pins the solid — eviction
     // disposes both, so the registry can't grow unboundedly across regenerates.
     label: (name) => {
+      // Labeling only re-stamps surface ids, so it commutes with the trailing
+      // transform. This is load-bearing rather than an optimization: the common
+      // authoring idiom labels each piece AFTER positioning it, which would give every
+      // copy its own canonical base and stop the hoist below from ever firing.
+      if (canon.chain.length) return replay(wrap(canon.m, canon.hash).label(name), canon.chain);
       const lh = h("label", hash, name);
       return cache.lookup(lh, () => {
         // Blend-aware re-stamp. If this mesh carries blend surfaces (the boundaryLines
@@ -492,14 +525,16 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     volume: () => m.volume(),
     genus: () => m.genus(),
     isEmpty: () => m.isEmpty(),
-    translate: (v) => wrap(T(m.translate(v)), h("translate", hash, v)),
+    translate: (v) => wrap(T(m.translate(v)), h("translate", hash, v),
+      { m: canon.m, hash: canon.hash, chain: [...canon.chain, { op: "translate", v }] }),
     rotate: (deg, center, axis) => {
       const nz = (axis[0] !== 0) + (axis[1] !== 0) + (axis[2] !== 0);
       const a = T(m.translate([-center[0], -center[1], -center[2]]));
       const b = nz <= 1
         ? T(a.rotate([axis[0] * deg, axis[1] * deg, axis[2] * deg]))   // basis axis — euler is exact; unchanged
         : T(a.transform(axisAngleMat4(axis, deg)));                    // general axis-angle
-      return wrap(T(b.translate(center)), h("rotate", hash, deg, center, axis));
+      return wrap(T(b.translate(center)), h("rotate", hash, deg, center, axis),
+        { m: canon.m, hash: canon.hash, chain: [...canon.chain, { op: "rotate", deg, center, axis }] });
     },
     mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane])), h("mirror", hash, plane)),
     scale: (factor, center) => { // factor validated (and center defaulted) by addSugar
@@ -603,7 +638,8 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // would pin one WASM object under two entries and eviction would dispose it twice.
     union: (solids) => solids.length === 1
       ? solids[0]
-      : cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
+      : hoistBoolean("union", solids, (ops) => unionRaw(ops.map((s) => s._m)))
+        ?? cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
     // Imported geometry, registered pre-build by the framework via `_registerImport`
     // (ensureImports, Task 8). The master Manifold is kernel-lifetime (untracked —
     // see `imports` above); wrap() is free, so every call is cheap.

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

@@ -1,23 +1,52 @@
 // Worker-side cache of boundary-op solids, partitioned per sub-part. Retention is
 // bounded to the CURRENT build's graph: each begin()/end() bracket rebuilds a
 // sub-part's retained set from scratch, disposing any entry not re-used this round.
+// Partitions bound RETENTION, never reuse: a `index` keyed by hash spans them all, so
+// geometry one sub-part builds is adopted by the next rather than rebuilt (a sheet of
+// identical cells split across row sub-parts paid that rebuild per row). An adopted
+// entry is retained by BOTH partitions, so disposal is refcounted — see release().
 // WASM-agnostic — it stores opaque {value, pin, dispose} triples supplied by the
 // caller (the Manifold backend), so it is unit-testable with plain objects.
 export function createSolidCache() {
-  const caches = new Map(); // name -> Map(hash -> { value, pin, dispose })
+  const caches = new Map(); // name -> Map(hash -> { value, pin, dispose, refs })
   const pinned = new Set();  // every live `pin` across all sub-parts
+  const index = new Map();   // hash -> entry, ACROSS partitions: identical geometry built
+                             // for one sub-part is reused by every other (see lookup).
   const lastBuilt = new Map(); // name -> rebind generation of the partition's last begin()
   let generation = 0;          // bumped only by sweep() (i.e. per part rebind)
   let name = null, active = null, prev = null;
+  let depth = 0;               // bracket nesting; only the OUTERMOST one is real (see begin)
   let hits = 0, misses = 0;
 
+  // One partition stops retaining `entry`. Disposal waits for the LAST holder:
+  // a solid shared across sub-parts is one WASM object, so disposing it when the
+  // first partition drops it would leave every other partition — and the shared
+  // index — pointing at freed memory. Dropping the index entry in the same breath
+  // is what keeps the cache from handing out a disposed solid later.
+  const release = (hash, entry) => {
+    if (--entry.refs > 0) return;
+    if (index.get(hash) === entry) index.delete(hash);
+    pinned.delete(entry.pin);
+    entry.dispose();
+  };
+
   return {
-    begin(n) { name = n; lastBuilt.set(n, generation); prev = caches.get(n) ?? new Map(); active = new Map(); },
+    // Nested brackets collapse into the outermost one. There is a single open
+    // round (name/active/prev), not a stack, so an inner begin() would otherwise
+    // rebind it and the inner end() would commit-and-close the OUTER round early —
+    // evicting its entries and leaving the rest of that build uncached. Callers
+    // nest legitimately now that buildView brackets: an outer bracket is free to
+    // contain one, and the inner pair becomes a no-op.
+    begin(n) {
+      if (depth++ > 0) return;
+      name = n; lastBuilt.set(n, generation); prev = caches.get(n) ?? new Map(); active = new Map();
+    },
 
     end() {
+      if (depth > 0 && --depth > 0) return; // inner bracket — the outer one still owns the round
       if (name == null) return;
       for (const [hash, entry] of prev) {
-        if (!active.has(hash)) { pinned.delete(entry.pin); entry.dispose(); } // evict
+        if (!active.has(hash)) release(hash, entry); // this partition drops it
       }
       caches.set(name, active);
       name = null; active = prev = null;
@@ -31,7 +60,7 @@ export function createSolidCache() {
       generation++;
       for (const [n, entries] of caches) {
         if (generation - (lastBuilt.get(n) ?? 0) < 3) continue;
-        for (const entry of entries.values()) { pinned.delete(entry.pin); entry.dispose(); }
+        for (const [hash, entry] of entries) release(hash, entry); // refcounted: a shared solid survives
         caches.delete(n);
         lastBuilt.delete(n);
       }
@@ -41,9 +70,14 @@ export function createSolidCache() {
       if (name == null) return make().value; // not bracketed → no caching
       if (active.has(hash)) { hits++; return active.get(hash).value; }
       if (prev.has(hash)) { hits++; const e = prev.get(hash); active.set(hash, e); return e.value; }
+      // Another sub-part already built this exact solid — adopt it. `refs` rises
+      // because a second partition now retains it; see release().
+      if (index.has(hash)) { hits++; const e = index.get(hash); e.refs++; active.set(hash, e); return e.value; }
       misses++;
       const entry = make();
+      entry.refs = 1;
       active.set(hash, entry);
+      index.set(hash, entry);
       pinned.add(entry.pin);
       return entry.value;
     },

package/src/framework/geometry/transform-hoist.js

@@ -0,0 +1,47 @@
+// Pure suffix-matching for boolean transform hoisting. A solid carries the trailing
+// transform chain applied to its canonical base (`canon.chain`, oldest first, so the
+// LAST record is the outermost transform). Booleans commute with any invertible
+// affine map, so a transform every operand ends with can be lifted out of the boolean
+// and applied to its result instead — which is what lets 30 identically-built cells
+// share ONE evaluated union instead of 30.
+//
+// Matching is SYMBOLIC (compare the recorded arguments), never numeric: deriving a
+// residual as X⁻¹·xᵢ would make rotations disagree in the last bits from copy to copy
+// and the hoist would silently stop firing. Comparing arguments is exact.
+
+const same = (a, b) => {
+  if (a.op !== b.op) return false;
+  if (a.op === "translate") return vecEq(a.v, b.v);
+  return a.deg === b.deg && vecEq(a.center, b.center) && vecEq(a.axis, b.axis);
+};
+const vecEq = (a, b) => a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+
+export function hoistCommonSuffix(chains) {
+  const rest = chains.map((c) => c.slice());
+  const hoisted = [];
+  for (;;) {
+    if (rest.some((c) => c.length === 0)) break;
+    const last = rest.map((c) => c[c.length - 1]);
+    if (last.every((r) => same(r, last[0]))) {
+      hoisted.unshift(last[0]);
+      for (const c of rest) c.pop();
+      continue;
+    }
+    // Trailing translations that DISAGREE still share a common part, and splitting it
+    // out is what the grid case needs: a cell's hub ends .at([cx,cy,0]) while its
+    // support ends .at([cx,cy,z]), so exact matching alone would hoist nothing.
+    // Translations commute, so translate(vᵢ) = translate(v₀) ∘ translate(vᵢ−v₀), and
+    // subtracting shared coordinates is exact. Splitting leaves a translate behind on
+    // every other operand, so nothing deeper can match — this always ends the loop.
+    if (!last.every((r) => r.op === "translate")) break;
+    const v0 = last[0].v;
+    for (const [i, c] of rest.entries()) {
+      const d = [last[i].v[0] - v0[0], last[i].v[1] - v0[1], last[i].v[2] - v0[2]];
+      c.pop();
+      if (d[0] !== 0 || d[1] !== 0 || d[2] !== 0) c.push({ op: "translate", v: d });
+    }
+    hoisted.unshift({ op: "translate", v: v0 });
+    break;
+  }
+  return { hoisted, residuals: rest };
+}

package/src/framework/oracle/build.js

@@ -7,8 +7,19 @@ import { viewSubParts, resolveParams, buildPosed } from "../part-model.js";
 // before they free the kernel. Meshes are JS-owned arrays and survive cleanup.
 export function buildView(kernel, part, view, params = {}) {
   const { p, d } = resolveParams(part, params);
-  return viewSubParts(part, view, p).map((name) => {
-    const solid = buildPosed(kernel, part, name, { purpose: "display", view, p, d });
-    return { name, solid, mesh: solid.toMesh() };
-  });
+  // Cache round for the whole view. The name is the ORACLE's, deliberately not the
+  // display sub-part names the generate path brackets under: a distinct partition
+  // still reuses those solids (the cache indexes entries by content hash across
+  // partitions), while keeping this round's own eviction away from the geometry the
+  // viewer is showing — bracketing under the display names would make running the
+  // oracle throw away the display cache. One name per view also bounds retention:
+  // verify walks its cases through here, so each case evicts the previous rather
+  // than accumulating every case's geometry at once.
+  kernel.beginSubPart?.(`oracle:view:${view}`);
+  try {
+    return viewSubParts(part, view, p).map((name) => {
+      const solid = buildPosed(kernel, part, name, { purpose: "display", view, p, d });
+      return { name, solid, mesh: solid.toMesh() };
+    });
+  } finally { kernel.endSubPart?.(); }
 }