partforge 0.27.0 → 0.31.0

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

@@ -3,6 +3,7 @@ import { triggerDownload, downloadParts } from "./download.js";
 import { createViewer } from "./viewer.js";
 import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
+import { attachRail } from "./rail.js";
 import { createTooltipPresenter } from "./tooltip.js";
 import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
@@ -61,13 +62,21 @@ 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);
   const els = {
     viewer: elements.viewer ?? legacyContainer ?? byId("app"),
     controls: elements.controls ?? legacyControls ?? byId("controls"),
+    rail: elements.rail ?? byId("panel"),
+    // No id fallback: attachRail defaults shell to rail.parentElement, which is
+    // right for the standard markup (rail is a direct child of .pf-shell). A
+    // host that wraps its rail in an extra element (e.g. a React layout div)
+    // must pass this explicitly, or the seam ends up positioned against the
+    // wrong ancestor. Left undefined (not null) when unsupplied so rail.js's
+    // own default still applies.
+    shell: elements.shell,
     status: {
       status: elements.status?.status ?? byId("status"),
       busy: elements.status?.busy ?? byId("busy"),
@@ -84,6 +93,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
       reframe: elements.chrome?.reframe ?? byId("reframe"),
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
+      railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
     },
   };
 
@@ -97,6 +107,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
       cutaway: els.chrome.cutaway,
     }, { tooltip });
     cleanup.defer(() => cutawayChrome.detach());
+    // Resizable/collapsible controls rail. No-ops when the host lays out the
+    // framework itself (no #panel / no elements.rail).
+    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell });
+    cleanup.defer(() => railChrome.detach());
     const hover = attachHoverLabels(viewer, { part, tooltip }); // always-on hover inspection (no-op on touch-only devices)
     cleanup.defer(() => hover.detach());
     const ui = createStatusUi({ ...els.status, exports: [els.exports.stl, els.exports.step, els.exports.threeMf] });
@@ -273,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":