partforge 0.28.0 → 0.31.0

package/docs/AUTHORING-PARTS.md

@@ -337,6 +337,13 @@ their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`
 profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so
 changing any of them is a fresh cache node while an identical rebuild is a hit.
 
+This holds on **both backends** — and on OCCT, `translate`/`rotate` are additionally
+*pose-lazy*: the backend re-poses the cached solid's cached tessellation instead of
+re-running any B-rep work. A parameter that only feeds a final placement rotation (a
+lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
+slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
+rather than baking them into the geometry earlier.
+
 ---
 
 ## Parameters: the control-panel schema

package/docs/ERROR-PATTERNS.md

@@ -47,7 +47,7 @@ test parses every one; keep prose like this as plain paragraphs):
 - **Cause:** replicad transforms and booleans (`translate`/`rotate`/`mirror`/`cut`/…) consume their operand — the input solid is deleted and a new one returned.
 - **Fix:** Never reuse a solid after transforming it; take a `.clone()` first when you need the original again. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (the `s.clone()` row).
 
-The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code.
+The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code. (Since the OCCT solid cache landed, the in-repo backend clones internally before every consuming replicad call, so wrapped `Solid`s effectively have value semantics and this crash should no longer reproduce through the kernel API — but the portable rule stands: per KERNEL-CONTRACT.md a backend MAY consume, so a part must still not rely on reuse.)
 
 ## probe-routed-to-occt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.28.0",
+  "version": "0.31.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/download.js

@@ -2,9 +2,16 @@ import { zipSync } from "fflate";
 
 // Browser file-download helpers. Pure DOM/Blob utilities with no app state — the
 // worker produces the bytes; these just hand them to the browser as a download.
+//
+// `sink` is an optional escape hatch for embedders that cannot download from
+// their own document — e.g. partforge running inside a null-origin sandboxed
+// iframe, where a blob: URL is blob:null and browsers such as WebKit refuse to
+// load it. When `sink` is supplied it receives the FINAL bytes and no DOM work
+// happens here; the embedder saves them from a context that can.
 
-// Trigger a download of one binary blob under `filename`.
-export function triggerDownload(data, filename, mime) {
+// Trigger a download of one binary blob under `filename` (or hand it to `sink`).
+export function triggerDownload(data, filename, mime, sink) {
+  if (typeof sink === "function") { sink({ data, filename, mime }); return; }
   const url = URL.createObjectURL(new Blob([data], { type: mime }));
   const a = document.createElement("a");
   a.href = url;
@@ -14,10 +21,11 @@ export function triggerDownload(data, filename, mime) {
 }
 
 // Download a set of built parts: a single part downloads directly; multiple parts
-// are bundled into one flat, store-only (level 0) zip named `zipName`.
-export function downloadParts({ parts, ext, mime }, zipName) {
-  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime);
+// are bundled into one flat, store-only (level 0) zip named `zipName`. `sink`, if
+// given, is forwarded to triggerDownload so it receives the final bytes.
+export function downloadParts({ parts, ext, mime }, zipName, sink) {
+  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime, sink);
   const entries = {};
   for (const p of parts) entries[`${p.name}.${ext}`] = new Uint8Array(p.data);
-  triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip");
+  triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip", sink);
 }

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

@@ -8,6 +8,7 @@ import { addSugar } from "./solid-sugar.js";
 import { addShape2dSugar } from "./shape2d-sugar.js";
 import { assembleRegions } from "./shape2d-regions.js";
 import { finishKernel } from "./kernel-front.js";
+import { meshToStl } from "./mesh-stl.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
@@ -363,21 +364,14 @@ function creasedNormals(g, sharpCos, featureLabels) {
 }
 
 function stlFromMesh(g) {
-  const tris = g.triVerts, vp = g.vertProperties, np = g.numProp, n = tris.length / 3;
-  const ab = new ArrayBuffer(84 + n * 50); const dv = new DataView(ab); dv.setUint32(80, n, true);
-  let o = 84; const P = (i) => [vp[i*np], vp[i*np+1], vp[i*np+2]];
-  for (let i = 0; i < n; i++) {
-    const a = P(tris[i*3]), b = P(tris[i*3+1]), c = P(tris[i*3+2]);
-    // Per-facet flat normal from the winding (Manifold is CCW → outward). Slicers
-    // recompute this, but viewers that light from the stored normal (macOS
-    // Preview/Quick Look) render the mesh unlit if it's left as zero.
-    const ux = b[0]-a[0], uy = b[1]-a[1], uz = b[2]-a[2];
-    const vx = c[0]-a[0], vy = c[1]-a[1], vz = c[2]-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) || 1;
-    dv.setFloat32(o, nx/L, true); dv.setFloat32(o+4, ny/L, true); dv.setFloat32(o+8, nz/L, true); o += 12;
-    for (const p of [a, b, c]) for (const x of p) { dv.setFloat32(o, x, true); o += 4; }
-    dv.setUint16(o, 0, true); o += 2;
+  const vp = g.vertProperties, np = g.numProp;
+  const nVert = (vp.length / np) | 0;
+  let positions;
+  if (np === 3) {
+    positions = vp; // already x,y,z per vertex
+  } else {
+    positions = new Float32Array(nVert * 3);
+    for (let i = 0; i < nVert; i++) { positions[i*3] = vp[i*np]; positions[i*3+1] = vp[i*np+1]; positions[i*3+2] = vp[i*np+2]; }
   }
-  return ab;
+  return meshToStl(positions, g.triVerts);
 }

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

@@ -0,0 +1,27 @@
+// Pure-JS binary STL writer, shared by both geometry backends. Takes a flat
+// vertex-position array (x,y,z per vertex) and triangle indices, and returns a
+// binary STL ArrayBuffer. STL is a triangle-mesh format, so this is the one and
+// only STL path — OCCT and Manifold both feed it a mesh. It deliberately does
+// NOT touch Blobs: the sandbox worker on Safari cannot read a Blob, so every
+// export must hand back a raw ArrayBuffer.
+export function meshToStl(positions, indices) {
+  const n = (indices.length / 3) | 0;
+  const ab = new ArrayBuffer(84 + n * 50);
+  const dv = new DataView(ab);
+  dv.setUint32(80, n, true); // triangle count (80-byte header left zero)
+  let o = 84;
+  const P = (i) => [positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]];
+  for (let i = 0; i < n; i++) {
+    const a = P(indices[i * 3]), b = P(indices[i * 3 + 1]), c = P(indices[i * 3 + 2]);
+    // Per-facet flat normal from the winding. Slicers recompute this, but some
+    // viewers (macOS Preview/Quick Look) render unlit if it's left zero.
+    const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
+    const vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - 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) || 1;
+    dv.setFloat32(o, nx / L, true); dv.setFloat32(o + 4, ny / L, true); dv.setFloat32(o + 8, nz / L, true); o += 12;
+    for (const p of [a, b, c]) for (const x of p) { dv.setFloat32(o, x, true); o += 4; }
+    dv.setUint16(o, 0, true); o += 2;
+  }
+  return ab;
+}

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

@@ -1,6 +1,20 @@
 // OCCT backend via replicad. Same GeometryKernel shape as the Manifold backend,
 // and the only backend with toSTEP(). This is where today's drum.js kernel calls
 // (makeCylinder, makeHelix+genericSweep, draw/extrude, cut/fuse) now live.
+//
+// Caching: the SAME createSolidCache as the Manifold backend, bracketed per
+// sub-part by jobs.js. Two backend-specific twists:
+//   - replicad ops CONSUME their operands (transform/boolean inputs are deleted),
+//     so every op that feeds a possibly-cached shape into replicad clones it
+//     first. Disposal is free: replicad wrappers release their WASM through a
+//     FinalizationRegistry when the JS object is collected, so evicted cache
+//     entries need no dispose bookkeeping (unlike Manifold's tracked/cleanup).
+//   - translate/rotate are POSE-LAZY: they accumulate rigid steps on the wrap
+//     (pose.js) instead of running OCCT transforms, and toMesh caches the BASE
+//     solid's tessellation and re-poses the cached vertices in JS. A pose-only
+//     param change (a lid's open angle) therefore re-runs no OCCT op at all.
+//     Ops that need the real B-rep (booleans, fillet/chamfer/shell, exports,
+//     volume, boundingBox) materialize the pending pose through replicad first.
 import { toEdgeFinder } from "./edge-selector.js";
 import { toFaceFinder } from "./face-selector.js";
 import { addSugar } from "./solid-sugar.js";
@@ -12,47 +26,66 @@ import { classifyFaceGroups } from "./feature-attribution.js";
 import { resolveRings } from "./loft.js";
 import { resolveSweepStations } from "./sweep.js";
 import { normalizeProfile } from "./profile.js";
+import { h } from "./solid-hash.js";
+import { createSolidCache } from "./solid-cache.js";
+import { composePose, transformPositions } from "./pose.js";
+import { meshToStl } from "./mesh-stl.js";
 const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.5 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
 
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
-          makeCompound, loft, draw, exportSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
+          makeCompound, loft, draw, exportSTEP, measureVolume, makeSphere, makeLine, Plane, getOC } = replicad;
 
   // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
   // see occt-repair.js for the policies and why they differ per op.
   const { validChamfer, safeOp } = createOcctRepair(measureVolume);
 
+  const cache = createSolidCache();
+  // Boundary ops route through cache.lookup. pin is unused here (no cleanup() —
+  // GC frees WASM via replicad's FinalizationRegistry) and dispose is a no-op:
+  // dropping the evicted reference is all the freeing OCCT needs.
+  const cached = (hash, make) => cache.lookup(hash, () => {
+    const value = make();
+    return { value, pin: value, dispose: () => {} };
+  });
+  // Function-form selectors (the raw replicad finder escape hatch) can capture
+  // params in a closure the source text doesn't show, so they can't be trusted to
+  // a content hash: give each call a fresh key, making the op and everything
+  // downstream of it a cache miss. Declarative selectors hash normally.
+  let unhashable = 0;
+  const selKey = (sel) => (typeof sel === "function" ? `fn#${unhashable++}` : sel);
+
   // Feature labels: each entry snapshots the labeled solid's geometry at the moment
-  // the label applies; transforms move the snapshots along, booleans merge the two
-  // sides' lists. At toMesh() time result faces are classified against the snapshots.
+  // the label applies; materialization moves the snapshots along with the shape,
+  // booleans merge the two sides' lists. At toMesh() time result faces are
+  // classified against the snapshots — in BASE space for a posed solid, which is
+  // sound because classification is pose-invariant (both meshes share the frame).
   const cloneLabels = (ls) => ls.map((l) => ({ label: l.label, snapshot: l.snapshot.clone() }));
   const mapLabels = (ls, f) => ls.map((l) => ({ label: l.label, snapshot: f(l.snapshot.clone()) }));
 
-  const wrap = (shape, labels = []) => addSugar({
-    _s: shape,
-    _labels: labels,
-    label: (name) => wrap(shape, [...labels, { label: name, snapshot: shape.clone() }]),
-    cut: (t) => wrap(shape.cut(t._s), [...cloneLabels(labels), ...cloneLabels(t._labels ?? [])]),
-    cutAll: (tools) => wrap(
-      shape.cut(makeCompound(tools.map((t) => t._s))),
-      [...cloneLabels(labels), ...tools.flatMap((t) => cloneLabels(t._labels ?? []))]
-    ),
-    intersect: (t) => wrap(shape.intersect(t._s), [...cloneLabels(labels), ...cloneLabels(t._labels ?? [])]),
-    union: (t) => wrap(shape.fuse(t._s), [...cloneLabels(labels), ...cloneLabels(t._labels ?? [])]),
-    clone: () => wrap(shape.clone(), cloneLabels(labels)),
-    boundingBox: () => {
-      const [min, max] = shape.boundingBox.bounds; // addSugar derives center/size
-      return { min: [...min], max: [...max] };
-    },
-    translate: (v) => wrap(shape.translate(v), mapLabels(labels, (s) => s.translate(v))),
-    rotate: (deg, center, axis) => wrap(shape.rotate(deg, center, axis), mapLabels(labels, (s) => s.rotate(deg, center, axis))),
-    mirror: (plane) => wrap(shape.mirror(plane), mapLabels(labels, (s) => s.mirror(plane))),
-    scale: (factor, center) => wrap(shape.scale(factor, center), mapLabels(labels, (s) => s.scale(factor, center))), // validated/defaulted by addSugar
-    toMesh: ({ quality = "preview" } = {}) => {
+  // Apply pending pose steps to a (freshly cloned) replicad shape.
+  const applySteps = (sh, steps) => steps.reduce(
+    (cur, st) => (st.t === "translate" ? cur.translate(st.v) : cur.rotate(st.deg, st.center, st.axis)), sh);
+
+  // `hash` is the content hash of the POSED solid; `baseHash` keys the pose-free
+  // base (they're equal when `pose` is empty). Every op below that consumes a
+  // shape clones it first — cached values must survive reuse across builds.
+  const wrap = (shape, labels = [], hash, pose = [], baseHash = hash) => {
+    // Materialize the pending pose through replicad, yielding a pose-free wrap.
+    // Cached under the posed hash so repeated ops on the same posed solid reuse it.
+    const mat = () => (pose.length === 0 ? self : cached(hash, () => wrap(
+      applySteps(shape.clone(), pose),
+      labels.map((l) => ({ label: l.label, snapshot: applySteps(l.snapshot.clone(), pose) })),
+      hash,
+    )));
+
+    // The base solid's tessellation (+ label classification), cached per quality.
+    // Pose-independent by construction: meshed from the base shape and base-space
+    // snapshots, so every pose of the same base reuses one entry.
+    const baseMesh = (quality) => cached(h("mesh", baseHash, quality), () => {
       const m = shape.mesh(MESH[quality]);
       const out = {
         positions: Float32Array.from(m.vertices),
-        normals: new Float32Array(0), // let the main thread crease (matches prior look)
         indices: Uint32Array.from(m.triangles),
         triangles: m.triangles.length / 3,
       };
@@ -64,29 +97,137 @@ export function createOcctKernel(replicad) {
         Object.assign(out, classifyFaceGroups(m, soups));
       }
       return out;
-    },
-    toSTL: ({ quality = "print" } = {}) => shape.blobSTL(MESH[quality]).arrayBuffer(),
-    fillet: (radius, selector) => wrap(safeOp(shape, (sh) => sh.fillet(radius, toEdgeFinder(selector)), `fillet(${radius})`), cloneLabels(labels)),
-    chamfer: (distance, selector) => wrap(validChamfer(shape, toEdgeFinder(selector), distance), cloneLabels(labels)),
-    shell: (thickness, openFaces) => {
-      if (openFaces == null) throw new Error("shell: openFaces is required (a fully closed hollow is not supported)");
-      // replicad shells inward with a positive thickness in this version, keeping outer dimensions.
-      return wrap(safeOp(shape, (sh) => sh.shell(thickness, toFaceFinder(openFaces)), `shell(${thickness})`), cloneLabels(labels));
-    },
-    volume: () => measureVolume(shape),
-    toIndexedMesh: () => {
-      const m = shape.mesh(MESH.preview);
-      return { positions: Float32Array.from(m.vertices), indices: Uint32Array.from(m.triangles) };
-    },
-  });
+    });
+    // Fresh posed copies of the cached arrays — jobs.js transfers the buffers to
+    // the main thread (detaching them), so the cache must never hand out its own.
+    const posedPositions = (base) => {
+      const positions = Float32Array.from(base.positions);
+      if (pose.length) transformPositions(positions, composePose(pose));
+      return positions;
+    };
+
+    const self = addSugar({
+      _s: shape,
+      _labels: labels,
+      _hash: hash,
+      _pose: pose,
+      _mat: () => mat(),
+      label: (name) => {
+        const a = mat();
+        return wrap(a._s, [...cloneLabels(a._labels), { label: name, snapshot: a._s.clone() }], h("label", hash, name));
+      },
+      cut: (t) => {
+        const key = h("cut", hash, t._hash);
+        return cached(key, () => {
+          const a = mat(), b = t._mat();
+          return wrap(a._s.clone().cut(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
+        });
+      },
+      cutAll: (tools) => {
+        const key = h("cutAll", hash, tools.map((t) => t._hash));
+        return cached(key, () => {
+          const a = mat(), bs = tools.map((t) => t._mat());
+          return wrap(
+            a._s.clone().cut(makeCompound(bs.map((b) => b._s.clone()))),
+            [...cloneLabels(a._labels), ...bs.flatMap((b) => cloneLabels(b._labels))],
+            key,
+          );
+        });
+      },
+      intersect: (t) => {
+        const key = h("intersect", hash, t._hash);
+        return cached(key, () => {
+          const a = mat(), b = t._mat();
+          return wrap(a._s.clone().intersect(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
+        });
+      },
+      union: (t) => {
+        const key = h("union", [hash, t._hash]);
+        return cached(key, () => {
+          const a = mat(), b = t._mat();
+          return wrap(a._s.clone().fuse(b._s.clone()), [...cloneLabels(a._labels), ...cloneLabels(b._labels)], key);
+        });
+      },
+      clone: () => wrap(shape.clone(), cloneLabels(labels), hash, pose, baseHash),
+      boundingBox: () => {
+        const [min, max] = mat()._s.boundingBox.bounds; // addSugar derives center/size
+        return { min: [...min], max: [...max] };
+      },
+      // Pose-lazy: no OCCT work, just a recorded step + the composed hash.
+      translate: (v) => wrap(shape, labels, h("translate", hash, v), [...pose, { t: "translate", v }], baseHash),
+      rotate: (deg, center, axis) => wrap(shape, labels, h("rotate", hash, deg, center, axis), [...pose, { t: "rotate", deg, center, axis }], baseHash),
+      mirror: (plane) => {
+        const key = h("mirror", hash, plane);
+        return cached(key, () => {
+          const a = mat();
+          return wrap(a._s.clone().mirror(plane), mapLabels(a._labels, (s) => s.mirror(plane)), key);
+        });
+      },
+      scale: (factor, center) => { // factor validated (and center defaulted) by addSugar
+        const key = h("scale", hash, factor, center);
+        return cached(key, () => {
+          const a = mat();
+          return wrap(a._s.clone().scale(factor, center), mapLabels(a._labels, (s) => s.scale(factor, center)), key);
+        });
+      },
+      toMesh: ({ quality = "preview" } = {}) => {
+        const base = baseMesh(quality);
+        const out = {
+          positions: posedPositions(base),
+          normals: new Float32Array(0), // let the main thread crease (matches prior look)
+          indices: Uint32Array.from(base.indices),
+          triangles: base.triangles,
+        };
+        if (base.featureIds) { out.featureIds = Uint16Array.from(base.featureIds); out.features = base.features; }
+        return out;
+      },
+      toSTL: ({ quality = "print" } = {}) => {
+        const base = baseMesh(quality);
+        return Promise.resolve(meshToStl(posedPositions(base), Uint32Array.from(base.indices)));
+      },
+      fillet: (radius, selector) => {
+        const key = h("fillet", hash, radius, selKey(selector));
+        return cached(key, () => {
+          const a = mat();
+          return wrap(safeOp(a._s.clone(), (sh) => sh.fillet(radius, toEdgeFinder(selector)), `fillet(${radius})`), cloneLabels(a._labels), key);
+        });
+      },
+      chamfer: (distance, selector) => {
+        const key = h("chamfer", hash, distance, selKey(selector));
+        // validChamfer probes on internal clones and never consumes its input.
+        return cached(key, () => {
+          const a = mat();
+          return wrap(validChamfer(a._s, toEdgeFinder(selector), distance), cloneLabels(a._labels), key);
+        });
+      },
+      shell: (thickness, openFaces) => {
+        if (openFaces == null) throw new Error("shell: openFaces is required (a fully closed hollow is not supported)");
+        const key = h("shell", hash, thickness, selKey(openFaces));
+        // replicad shells inward with a positive thickness in this version, keeping outer dimensions.
+        return cached(key, () => {
+          const a = mat();
+          return wrap(safeOp(a._s.clone(), (sh) => sh.shell(thickness, toFaceFinder(openFaces)), `shell(${thickness})`), cloneLabels(a._labels), key);
+        });
+      },
+      volume: () => measureVolume(mat()._s),
+      toIndexedMesh: () => {
+        const base = baseMesh("preview");
+        return { positions: posedPositions(base), indices: Uint32Array.from(base.indices) };
+      },
+    });
+    return self;
+  };
 
   // cylinder OR frustum (loft of two circles) when rb !== rt
-  const cylinder = (rb, rt, h, { center = false } = {}) => {
-    const z0 = center ? -h / 2 : 0;
-    if (Math.abs(rb - rt) < 1e-9) return wrap(makeCylinder(rb, h, [0, 0, z0]));
-    const w1 = assembleWire([makeCircle(rb, [0, 0, z0])]);
-    const w2 = assembleWire([makeCircle(rt, [0, 0, z0 + h])]);
-    return wrap(loft([w1, w2]));
+  const cylinder = (rb, rt, hgt, { center = false } = {}) => {
+    const key = h("cylinder", rb, rt, hgt, center);
+    return cached(key, () => {
+      const z0 = center ? -hgt / 2 : 0;
+      if (Math.abs(rb - rt) < 1e-9) return wrap(makeCylinder(rb, hgt, [0, 0, z0]), [], key);
+      const w1 = assembleWire([makeCircle(rb, [0, 0, z0])]);
+      const w2 = assembleWire([makeCircle(rt, [0, 0, z0 + hgt])]);
+      return wrap(loft([w1, w2]), [], key);
+    });
   };
 
   // Draw a closed Drawing from a Contour: a legacy 2-D point list (all straight edges,
@@ -157,15 +298,22 @@ export function createOcctKernel(replicad) {
       return (ringArea(r) >= 0) === wantOuter ? r : r.slice().reverse();
     });
   };
-  const wrapShape2d = (drawing) => {
+  // Shape2D carries a content hash (so a Solid op over a profile can key on it)
+  // but stays UNCACHED — Drawings already clone before every consuming replicad
+  // call, and 2-D booleans are cheap next to the B-rep work they feed.
+  const wrapShape2d = (drawing, hash) => {
     const toRegions = () => assembleRegions(drawingRegionRings(drawing));
     return addShape2dSugar({
       _drawing: drawing,
       _shape2d: true,
-      union:     (o) => wrapShape2d(drawing.clone().fuse(liftDrawing(o)._drawing.clone())),
-      cut:       (o) => wrapShape2d(drawing.clone().cut(liftDrawing(o)._drawing.clone())),
-      cutAll:    (os) => wrapShape2d(os.map(liftDrawing).reduce((acc, t) => acc.cut(t._drawing.clone()), drawing.clone())),
-      intersect: (o) => wrapShape2d(drawing.clone().intersect(liftDrawing(o)._drawing.clone())),
+      _hash: hash,
+      union:     (o) => { const t = liftDrawing(o); return wrapShape2d(drawing.clone().fuse(t._drawing.clone()), h("union2d", hash, t._hash)); },
+      cut:       (o) => { const t = liftDrawing(o); return wrapShape2d(drawing.clone().cut(t._drawing.clone()), h("cut2d", hash, t._hash)); },
+      cutAll:    (os) => {
+        const ts = os.map(liftDrawing);
+        return wrapShape2d(ts.reduce((acc, t) => acc.cut(t._drawing.clone()), drawing.clone()), h("cutAll2d", hash, ts.map((t) => t._hash)));
+      },
+      intersect: (o) => { const t = liftDrawing(o); return wrapShape2d(drawing.clone().intersect(t._drawing.clone()), h("intersect2d", hash, t._hash)); },
       // corners map onto replicad's Offset2DConfig.lineJoinType; "chamfer" → "bevel", a
       // true 45° corner cut (a straight chord). Manifold now matches this via a
       // single-chord Round join (see manifold-backend offset) — the two agree to float
@@ -183,52 +331,64 @@ export function createOcctKernel(replicad) {
         // guards this — a replicad upgrade that renames it must keep that test green.
         if (!result || !result.innerShape)
           throw new Error("Shape2D.offset: offset collapses the shape (reduce |delta|)");
-        return wrapShape2d(result);
+        return wrapShape2d(result, h("offset2d", hash, delta, corners));
       },
       area: () => regionsArea(toRegions()),                 // no native Drawing area → derive from materialized regions
       boundingBox: () => { const b = drawing.boundingBox; return { min: [b.bounds[0][0], b.bounds[0][1]], max: [b.bounds[1][0], b.bounds[1][1]] }; },
       toRegions,
-      clone: () => wrapShape2d(drawing.clone()),
+      clone: () => wrapShape2d(drawing.clone(), hash),
     }, { shape2d, extrude: kernel.extrude, revolve: kernel.revolve });
   };
-  const shape2d = (profile) => (profile && profile._shape2d ? profile : wrapShape2d(drawingFromProfile(profile)));
+  const shape2d = (profile) => (profile && profile._shape2d ? profile : wrapShape2d(drawingFromProfile(profile), h("shape2d", profile)));
 
   // extrude a 2-D polygon from z=0 (arguments validated by the kernel front)
-  const prism = (pts, h, { twist = 0, scaleTop = 1 } = {}) => {
-    const sketch = contourDrawing(pts).sketchOnPlane("XY");
-    if (twist === 0 && scaleTop === 1) return wrap(sketch.extrude(h));
-    const cfg = {};
-    if (twist !== 0) cfg.twistAngle = twist;
-    if (scaleTop !== 1) cfg.extrusionProfile = { profile: "linear", endFactor: scaleTop };
-    return wrap(sketch.extrude(h, cfg));
+  const prism = (pts, hgt, { twist = 0, scaleTop = 1 } = {}) => {
+    const key = h("prism", pts, hgt, twist, scaleTop);
+    return cached(key, () => {
+      const sketch = contourDrawing(pts).sketchOnPlane("XY");
+      if (twist === 0 && scaleTop === 1) return wrap(sketch.extrude(hgt), [], key);
+      const cfg = {};
+      if (twist !== 0) cfg.twistAngle = twist;
+      if (scaleTop !== 1) cfg.extrusionProfile = { profile: "linear", endFactor: scaleTop };
+      return wrap(sketch.extrude(hgt, cfg), [], key);
+    });
   };
 
   // revolve a lathe profile [[r,z],…] around the Z axis (degrees defaults to 360)
   const revolve = (pts, { degrees = 360 } = {}) => {
-    const region = pts && pts._shape2d ? pts._drawing.clone() : contourDrawing(pts);
-    return wrap(region.sketchOnPlane("XZ").revolve([0, 0, 1], { angle: degrees }));
+    const key = h("revolve", pts && pts._shape2d ? pts._hash : pts, degrees);
+    return cached(key, () => {
+      const region = pts && pts._shape2d ? pts._drawing.clone() : contourDrawing(pts);
+      return wrap(region.sketchOnPlane("XZ").revolve([0, 0, 1], { angle: degrees }), [], key);
+    });
   };
 
   // extrude a polygon-with-holes region from z=0: cut each hole Drawing out of the outer
   // Drawing (winding-agnostic 2-D boolean), sketch it, then extrude (twist/taper via cfg).
   // A Shape2D `profile` (already a Drawing, possibly multi-region) extrudes directly off
   // its own `_drawing` (cloned — replicad booleans/extrude consume their operand).
-  const extrude = (profile, h, { twist = 0, scaleTop = 1 } = {}) => {
-    const region = profile && profile._shape2d ? profile._drawing.clone() : drawingFromProfile(profile);
-    const sketch = region.sketchOnPlane("XY");
-    if (twist === 0 && scaleTop === 1) return wrap(sketch.extrude(h));
-    const cfg = {};
-    if (twist !== 0) cfg.twistAngle = twist;
-    if (scaleTop !== 1) cfg.extrusionProfile = { profile: "linear", endFactor: scaleTop };
-    return wrap(sketch.extrude(h, cfg));
+  const extrude = (profile, hgt, { twist = 0, scaleTop = 1 } = {}) => {
+    const key = h("extrude", profile && profile._shape2d ? profile._hash : profile, hgt, twist, scaleTop);
+    return cached(key, () => {
+      const region = profile && profile._shape2d ? profile._drawing.clone() : drawingFromProfile(profile);
+      const sketch = region.sketchOnPlane("XY");
+      if (twist === 0 && scaleTop === 1) return wrap(sketch.extrude(hgt), [], key);
+      const cfg = {};
+      if (twist !== 0) cfg.twistAngle = twist;
+      if (scaleTop !== 1) cfg.extrusionProfile = { profile: "linear", endFactor: scaleTop };
+      return wrap(sketch.extrude(hgt, cfg), [], key);
+    });
   };
 
   // ring loft: each ring becomes a closed polygon wire placed at its z (native loft closes
   // the ends for closed wires). closed:true loops are Manifold-only (replicad loft is open).
   const loftOp = (rings, { ruled = true, closed = false } = {}) => {
     if (closed) throw new Error("loft: closed:true loops are only supported on the Manifold backend");
-    const wires = resolveRings(rings).map(({ pts2d, z }) => contourDrawing(pts2d).sketchOnPlane("XY", z).wire);
-    return wrap(loft(wires, { ruled }));
+    const key = h("loft", rings, ruled);
+    return cached(key, () => {
+      const wires = resolveRings(rings).map(({ pts2d, z }) => contourDrawing(pts2d).sketchOnPlane("XY", z).wire);
+      return wrap(loft(wires, { ruled }), [], key);
+    });
   };
 
   // Sweep a 2-D profile along a 3-D polyline path. DEFAULT (§3A recipe): loft the SAME
@@ -237,7 +397,7 @@ export function createOcctKernel(replicad) {
   // mechanism, not a tolerance). smooth:true switches to the OCCT-native genericSweep along
   // a spline spine for an exact swept B-rep (STEP-exact / preview-faceted, parity waived —
   // the same contract loft ships for ruled:false). closed:true loops are Manifold-only.
-  const sweepSmooth = (profile2D, path3D, cornerRadius) => {
+  const sweepSmooth = (profile2D, path3D, cornerRadius, key) => {
     const edges = [];
     for (let i = 0; i < path3D.length - 1; i++) edges.push(makeLine(path3D[i], path3D[i + 1]));
     const spine = assembleWire(edges);
@@ -246,35 +406,75 @@ export function createOcctKernel(replicad) {
     return wrap(genericSweep(profileWire, spine, {
       transitionMode: cornerRadius > 0 ? "round" : "right", // sharp miter analogue vs rounded joint
       forceProfileSpineOthogonality: true,
-    }));
+    }), [], key);
   };
   const sweep = (profile2D, path3D, { closed = false, cornerRadius = 0, ruled = true, smooth = false } = {}) => {
     if (closed) throw new Error("sweep: closed:true loops are only supported on the Manifold backend");
-    if (smooth) return sweepSmooth(profile2D, path3D, cornerRadius);
-    const { stations } = resolveSweepStations(profile2D, path3D, { closed, cornerRadius });
-    const wires = stations.map((ring) => assembleWire(ring.map((p, i) => makeLine(p, ring[(i + 1) % ring.length]))));
-    return wrap(loft(wires, { ruled }));
+    const key = h("sweep", profile2D, path3D, closed, cornerRadius, ruled, smooth);
+    return cached(key, () => {
+      if (smooth) return sweepSmooth(profile2D, path3D, cornerRadius, key);
+      const { stations } = resolveSweepStations(profile2D, path3D, { closed, cornerRadius });
+      const wires = stations.map((ring) => assembleWire(ring.map((p, i) => makeLine(p, ring[(i + 1) % ring.length]))));
+      return wrap(loft(wires, { ruled }), [], key);
+    });
   };
 
   // circle profile swept along a helix (frenet)
-  const helixSweptTube = ({ pathR, profileR, pitch, turns, z0, lefthand }) => {
-    const spine = makeHelix(pitch, pitch * turns, pathR, [0, 0, z0], [0, 0, 1], lefthand);
-    const dir = lefthand ? -1 : 1;
-    const tangent = [0, dir * pathR, pitch / (2 * Math.PI)];
-    const profile = assembleWire([makeCircle(profileR, [pathR, 0, z0], tangent)]);
-    return wrap(genericSweep(profile, spine, { frenet: true }));
+  const helixSweptTube = (o) => {
+    const key = h("helixSweptTube", o);
+    return cached(key, () => {
+      const { pathR, profileR, pitch, turns, z0, lefthand } = o;
+      const spine = makeHelix(pitch, pitch * turns, pathR, [0, 0, z0], [0, 0, 1], lefthand);
+      const dir = lefthand ? -1 : 1;
+      const tangent = [0, dir * pathR, pitch / (2 * Math.PI)];
+      const profile = assembleWire([makeCircle(profileR, [pathR, 0, z0], tangent)]);
+      return wrap(genericSweep(profile, spine, { frenet: true }), [], key);
+    });
   };
 
   const kernel = finishKernel({
     cylinder, // boredCylinder: the kernel front's default composition is exactly right here
-    box: (min, max) => wrap(makeBox(min, max)), prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube,
-    sphere: (r) => wrap(makeSphere(r)),
-    union: (solids) => wrap(
-      solids.map((s) => s._s).reduce((a, b) => a.fuse(b)),
-      solids.flatMap((s) => cloneLabels(s._labels ?? []))
-    ),
+    box: (min, max) => cached(h("box", min, max), () => wrap(makeBox(min, max), [], h("box", min, max))),
+    prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube,
+    sphere: (r) => cached(h("sphere", r), () => wrap(makeSphere(r), [], h("sphere", r))),
+    union: (solids) => {
+      const key = h("union", solids.map((s) => s._hash));
+      return cached(key, () => {
+        const ms = solids.map((s) => s._mat());
+        return wrap(
+          ms.map((m) => m._s.clone()).reduce((a, b) => a.fuse(b)),
+          ms.flatMap((m) => cloneLabels(m._labels)),
+          key,
+        );
+      });
+    },
     shape2d,
-    toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._s }))).arrayBuffer(),
+    toSTEP: (named) => {
+      // Blob-free STEP: replicad's exportSTEP writes the STEP text to OCCT's
+      // virtual FS, reads it, and wraps it in a Blob. Safari's sandbox worker
+      // cannot read a Blob, so we intercept the FS read to capture the raw
+      // Uint8Array before it is wrapped, and return an ArrayBuffer instead. The
+      // interception is synchronous (exportSTEP is sync) and restored in finally.
+      const oc = getOC();
+      const realRead = oc.FS.readFile.bind(oc.FS);
+      let captured = null;
+      oc.FS.readFile = (path, ...rest) => {
+        const bytes = realRead(path, ...rest);
+        if (typeof path === "string" && path.toLowerCase().endsWith(".step")) captured = bytes;
+        return bytes;
+      };
+      try {
+        exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._mat()._s })));
+      } finally {
+        oc.FS.readFile = realRead;
+      }
+      if (!captured) throw new Error("STEP export produced no bytes");
+      return Promise.resolve(captured.buffer.slice(captured.byteOffset, captured.byteOffset + captured.byteLength));
+    },
+    beginSubPart: (name) => cache.begin(name),
+    endSubPart: () => cache.end(),
+    cacheStats: () => cache.stats(),
+    resetCacheStats: () => cache.resetStats(),
   });
   return kernel;
 }

package/src/framework/geometry/pose.js

@@ -0,0 +1,47 @@
+// Rigid-pose math for the OCCT backend's lazy transforms. A pose is a list of
+// {t:"translate", v} / {t:"rotate", deg, center, axis} steps not yet applied to
+// the underlying B-rep shape; composePose folds them (in application order) into
+// one column-major mat4, and transformPositions re-poses a cached tessellation's
+// vertices with it. Pure JS — unit-testable without booting a kernel.
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+
+// column-major 4x4 product: (A·B)[c][r] = Σk A[k][r]·B[c][k]
+function mul(A, B) {
+  const o = new Array(16);
+  for (let c = 0; c < 4; c++)
+    for (let r = 0; r < 4; r++)
+      o[c * 4 + r] = A[r] * B[c * 4] + A[4 + r] * B[c * 4 + 1] + A[8 + r] * B[c * 4 + 2] + A[12 + r] * B[c * 4 + 3];
+  return o;
+}
+
+const translation = (v) => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, v[0], v[1], v[2], 1];
+
+// axis-angle rotation about an axis THROUGH `center`: T(center) · R(axis, deg) · T(−center)
+function rotationAbout(deg, center, axis) {
+  const len = Math.hypot(axis[0], axis[1], axis[2]) || 1;
+  const x = axis[0] / len, y = axis[1] / len, z = axis[2] / len;
+  const t = (deg * Math.PI) / 180, c = Math.cos(t), s = Math.sin(t), C = 1 - c;
+  const R = [
+    c + x * x * C, y * x * C + z * s, z * x * C - y * s, 0,
+    x * y * C - z * s, c + y * y * C, z * y * C + x * s, 0,
+    x * z * C + y * s, y * z * C - x * s, c + z * z * C, 0,
+    0, 0, 0, 1,
+  ];
+  return mul(translation(center), mul(R, translation([-center[0], -center[1], -center[2]])));
+}
+
+const stepMatrix = (s) => (s.t === "translate" ? translation(s.v) : rotationAbout(s.deg, s.center, s.axis));
+
+// Fold steps so the EARLIEST step applies first: p' = Mn · … · M1 · p.
+export const composePose = (steps) => steps.reduce((m, s) => mul(stepMatrix(s), m), IDENTITY);
+
+// Apply a mat4 to an interleaved xyz Float32Array in place.
+export function transformPositions(positions, m) {
+  for (let i = 0; i < positions.length; i += 3) {
+    const x = positions[i], y = positions[i + 1], z = positions[i + 2];
+    positions[i] = m[0] * x + m[4] * y + m[8] * z + m[12];
+    positions[i + 1] = m[1] * x + m[5] * y + m[9] * z + m[13];
+    positions[i + 2] = m[2] * x + m[6] * y + m[10] * z + m[14];
+  }
+}

package/src/framework/mount.js

@@ -62,7 +62,7 @@ function createCleanupStack() {
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -287,12 +287,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
         }
         case "download-parts":
           ui.hideBusy();
-          downloadParts(data, zipName);
+          downloadParts(data, zipName, onDownload);
           ui.setStatus(`${data.parts.length} part(s) downloaded`);
           break;
         case "download":
           ui.hideBusy();
-          triggerDownload(data.data, data.filename, data.mime);
+          triggerDownload(data.data, data.filename, data.mime, onDownload);
           ui.setStatus(`${data.filename} downloaded`);
           break;
         case "needs-occt":