partforge 0.165.0 → 0.165.1

package/docs/KERNEL-CONTRACT.md

@@ -106,13 +106,17 @@ relying on consumption should gate it with a `verify` volume assertion.
 **B-rep class.** Core plus native `fillet`/`chamfer`/`shell` and `toSTEP`. The in-repo
 OCCT/replicad backend is the reference.
 
-**Optional ops.** `KERNEL_OPTIONAL_OPS` (`beginSubPart`/`endSubPart`/`sweepCache`/
+**Optional ops.** `KERNEL_OPTIONAL_OPS` (`beginSubPart`/`endSubPart`/`sweepCache`/`dropCache`/
 `cacheStats`/`resetCacheStats`/`cleanup`) and `SOLID_OPTIONAL_OPS` (`genus`/`isEmpty`) may
 be omitted entirely; callers in the framework guard with `?.`/`typeof`. A host that omits
 them loses sub-part caching and mesh-topology gates (`holes`, emptiness), nothing else.
 `sweepCache()` is the cache's rebind hygiene hook: called once when a worker is rebound to
 a part (never inside a `beginSubPart`/`endSubPart` bracket), it drops cache partitions that
-have gone unbuilt for three consecutive rebinds.
+have gone unbuilt for three consecutive rebinds. `dropCache()` drops every partition at
+once, under the same never-mid-bracket rule: the worker calls it on each booted kernel
+before an export job, because a display build's retained solids and the export's own
+build share one WASM heap, and on a very large part the cache alone can leave too little
+heap for the export. The next display build after an export is cold.
 
 `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

package/package.json

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

package/src/framework/export/bed-layout.js

@@ -47,16 +47,26 @@ export function bedWidthFor(part) {
   }
 }
 
-// `pieces`: [{ name, solid, ...rest }] in export order. Map-form pieces are laid out
-// together; legacy ones keep their export pose, and so do sheet pieces — a sheet's pose IS
-// its placement, so sheet exports come out assembled. Returns a new array, same order.
+// Map-form pieces are laid out together; legacy ones keep their export pose, and so do
+// sheet pieces — a sheet's pose IS its placement, so sheet exports come out assembled.
+export function laidOutOnBed(part, name) {
+  const sp = part.parts[name];
+  return formOf(sp) === "map" && !isSheetPart(sp);
+}
+
+// `boxes`: [{ name, box }] for the laid-out pieces, in export order → Map(name → offset).
+// Bounds alone are enough, which is what lets the 3MF export free each piece as soon as
+// it is meshed and shift the mesh afterwards (feedback #212).
+export function exportLayoutOffsets(part, boxes) {
+  if (boxes.length === 0) return new Map();
+  return bedLayout(boxes.map(({ name, box }) => ({ key: name, ...box })), { width: bedWidthFor(part) });
+}
+
+// `pieces`: [{ name, solid, ...rest }] in export order. Returns a new array, same order,
+// laid-out pieces translated (see laidOutOnBed).
 export function layoutExportPieces(part, pieces) {
-  const laidOut = (sp) => formOf(sp) === "map" && !isSheetPart(sp);
-  const mapPieces = pieces.filter(({ name }) => laidOut(part.parts[name]));
+  const mapPieces = pieces.filter(({ name }) => laidOutOnBed(part, name));
   if (mapPieces.length === 0) return pieces;
-  const offsets = bedLayout(
-    mapPieces.map(({ name, solid }) => ({ key: name, ...solid.boundingBox() })),
-    { width: bedWidthFor(part) },
-  );
+  const offsets = exportLayoutOffsets(part, mapPieces.map(({ name, solid }) => ({ name, box: solid.boundingBox() })));
   return pieces.map((pc) => (offsets.has(pc.name) ? { ...pc, solid: pc.solid.translate(offsets.get(pc.name)) } : pc));
 }

package/src/framework/export/bundle.js

@@ -392,6 +392,7 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
       pp.triangles = indices.length / 3;
     }
     builtPrints.push(pp);
+    kernel.cleanup?.(); // pp keeps only JS-owned data; free this piece's solids before the next (feedback #212)
   }
   const prints = dedupe(builtPrints, (x) => x.hash, (a, b) => a.triangles === b.triangles && a.color === b.color
       && near(a.volume, b.volume) && a.size.every((x, i) => near(x, b.size[i])))

package/src/framework/geometry/kernel.js

@@ -36,7 +36,7 @@ export const KERNEL_OPS = [
 // OCCT's replicad shapes need no dispose bookkeeping). jobs.js calls all of these via
 // `?.`, so a third-party backend may simply omit them.
 export const KERNEL_OPTIONAL_OPS = [
-  "beginSubPart", "endSubPart", "sweepCache", "cacheStats", "resetCacheStats", "cleanup",
+  "beginSubPart", "endSubPart", "sweepCache", "dropCache", "cacheStats", "resetCacheStats", "cleanup",
   // Drains the feature-skip warnings recorded since the last drain — a fillet or
   // chamfer the geometry defeated and the backend skipped rather than failed the
   // build over. Both backends implement it; a host that never calls it sees the
@@ -170,6 +170,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(name:string) => void} [beginSubPart]   open a per-sub-part solid-cache round (both backends)
  * @property {() => void} [endSubPart]                close the cache round (always pair with beginSubPart)
  * @property {() => void} [sweepCache]   drop cache partitions idle for 3 rebinds; call once per setPart, never mid-bracket
+ * @property {() => void} [dropCache]    drop EVERY cache partition (the worker calls it before an export); never mid-bracket
  * @property {() => {hits:number,misses:number}} [cacheStats]
  * @property {() => void} [resetCacheStats]
  * @property {() => void} [cleanup]   free per-job WASM objects (Manifold backend); call after each job

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

@@ -1063,6 +1063,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
     sweepCache: () => cache.sweep(),
+    dropCache: () => cache.clear(),
     cacheStats: () => cache.stats(),
     resetCacheStats: () => cache.resetStats(),
     // Drain the feature-skip warnings recorded since the last drain (see

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

@@ -859,6 +859,7 @@ export function createOcctKernel(replicad) {
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
     sweepCache: () => cache.sweep(),
+    dropCache: () => cache.clear(),
     cacheStats: () => cache.stats(),
     resetCacheStats: () => cache.resetStats(),
     // Drain the feature-skip warnings recorded since the last drain — the

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

@@ -66,6 +66,20 @@ export function createSolidCache() {
       }
     },
 
+    // Drop EVERY partition, whatever its age — the next build of each sub-part is
+    // cold. The worker calls this before an export (feedback #212): the display
+    // build's retained solids and the export's own print-quality build share one
+    // WASM heap, and on a 105-plate forge the display cache alone held ~1.75 GB,
+    // so the export ran out of heap after a few plates on a phone. Like sweep(),
+    // never mid-bracket — the worker's job queue is serial.
+    clear() {
+      for (const entries of caches.values()) {
+        for (const [hash, entry] of entries) release(hash, entry); // refcounted: each partition lets go once
+      }
+      caches.clear();
+      lastBuilt.clear();
+    },
+
     lookup(hash, make) {
       if (name == null) return make().value; // not bracketed → no caching
       if (active.has(hash)) { hits++; return active.get(hash).value; }

package/src/framework/jobs.js

@@ -163,6 +163,22 @@ async function scoreMatchTargets(built, targets, onProgress) {
   }
 }
 
+// The WASM traps that mean the kernel ran out of heap (or was corrupted by doing so).
+const HEAP_TRAP_RE = /out of bounds memory access|memory access out of bounds|Cannot enlarge memory|out of memory/i;
+
+// A piece of a many-piece export failed: say WHICH piece, how far the export got, and
+// — when it is the heap that ran out — the one remedy the user can apply. The raw
+// message stays LAST, after a colon, so a host's own trap classifier still matches it.
+function exportPieceError(thrown, { kernel, piece, index, count }) {
+  const err = describeKernelThrow(thrown, { evidence: kernel._throwEvidence?.(thrown) });
+  if (count < 2 || err?.code) return err; // one piece: the error already names it; coded errors are routed, not shown
+  const raw = String(err?.message || err);
+  const advice = HEAP_TRAP_RE.test(raw)
+    ? " ran out of memory — export fewer parts at a time (each export needs room for the parts it builds)"
+    : " failed";
+  return new Error(`exporting "${piece}" (part ${index + 1} of ${count})${advice}: ${raw}`, { cause: thrown });
+}
+
 export async function handle(kernel, part, msg, post, opts = {}) {
   const isStale = opts.isStale ?? (() => false);
   const onProgress = (phase) => post({ type: "progress", phase, jobId: msg.jobId });
@@ -500,9 +516,18 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");
       const out = [];
-      for (const name of names) {
+      for (const [i, name] of names.entries()) {
         onProgress(`building ${label(name)}`);
-        out.push({ name: exportName(name), data: await posed(name, "export", onProgress).toSTL({ quality: msg.quality ?? "print" }) });
+        try {
+          out.push({ name: exportName(name), data: await posed(name, "export", onProgress).toSTL({ quality: msg.quality ?? "print" }) });
+        } catch (thrown) {
+          throw exportPieceError(thrown, { kernel, piece: label(name), index: i, count: names.length });
+        }
+        // Each file is JS-owned once toSTL returns, so this piece's solids can go now.
+        // Without it a many-piece export held every piece's print-quality build until
+        // the job ended — the 105-plate forge of feedback #212 ran out of heap at
+        // about the 100th plate.
+        kernel.cleanup?.();
       }
       post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out, jobId: msg.jobId },
            out.map((pp) => bufferOf(pp.data)));
@@ -523,12 +548,27 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     } else if (msg.type === "export-3mf") {
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");
-      const { layoutExportPieces } = await loadBedLayout();
-      const meshes = layoutExportPieces(part, names.map((name) => {
+      // One piece in the kernel at a time, as export-stl: build, read the bounds the bed
+      // layout needs, mesh into JS-owned arrays, free — then lay out from the bounds and
+      // shift the meshes (translation only, so this is the layout layoutExportPieces makes).
+      const { laidOutOnBed, exportLayoutOffsets } = await loadBedLayout();
+      const built = [];
+      for (const [i, name] of names.entries()) {
         onProgress(`building ${label(name)}`);
-        return { name, solid: posed(name, "export", onProgress) };
-      })).map(({ name, solid }) => {
-        const { positions, indices } = solid.toIndexedMesh({ quality: msg.quality ?? "print" });
+        try {
+          const solid = posed(name, "export", onProgress);
+          const box = laidOutOnBed(part, name) ? solid.boundingBox() : null;
+          const { positions, indices } = solid.toIndexedMesh({ quality: msg.quality ?? "print" });
+          built.push({ name, box, positions, indices });
+        } catch (thrown) {
+          throw exportPieceError(thrown, { kernel, piece: label(name), index: i, count: names.length });
+        }
+        kernel.cleanup?.();
+      }
+      const offsets = exportLayoutOffsets(part, built.filter((b) => b.box));
+      const meshes = built.map(({ name, positions, indices }) => {
+        const o = offsets.get(name);
+        if (o) for (let j = 0; j < positions.length; j += 3) { positions[j] += o[0]; positions[j + 1] += o[1]; positions[j + 2] += o[2]; }
         return { name: exportName(name), positions, indices, color: printColor(part.parts[name]?.display) };
       });
       onProgress("writing 3MF file");

package/src/framework/worker.js

@@ -30,6 +30,15 @@ async function manifoldKernels() {
   };
 }
 
+// Jobs that build every selected sub-part again at export quality. Before one runs,
+// the worker drops its kernels' display caches (dropCache): the cache's retained
+// solids and the export's build share one WASM heap, and on a very large part the
+// display build alone held ~1.75 GB — on a phone, enough that exporting three of a
+// 105-plate forge's plates ran out of heap (feedback #212). The cost is one cold
+// display build after an export; exports are rare and deliberate, a failed one
+// costs the user the whole job.
+const EXPORT_JOBS = new Set(["export-stl", "export-step", "export-3mf", "export-bundle"]);
+
 async function occtKernel() {
   const [{ default: opencascade }, wasmUrlMod, replicad, { createOcctKernel }] = await Promise.all([
     import("replicad-opencascadejs/src/replicad_single.js"),
@@ -115,6 +124,11 @@ export function runWorker(part, opts = {}) {
           // A generate superseded while it sat in the queue never builds at all.
           if (job.epoch !== null && job.epoch !== epoch) continue;
           kernel = await kernelFor(job.data);
+          if (EXPORT_JOBS.has(job.data?.type)) {
+            manifold?.preview.dropCache?.();
+            manifold?.print.dropCache?.();
+            occt?.dropCache?.();
+          }
           // handle() declares each message's transferables (the big binary buffers).
           const post = (m, transfer = []) => postMessage(m, transfer);
           if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, jobs: opts.jobs }); continue; }

package/types/kernel.d.ts

@@ -642,6 +642,8 @@ export interface GeometryKernel {
   endSubPart?(): void;
   /** Drop cache partitions idle for 3 rebinds. Never call mid-bracket. */
   sweepCache?(): void;
+  /** Drop every cache partition — the worker calls this before an export job. Never call mid-bracket. */
+  dropCache?(): void;
   cacheStats?(): { hits: number; misses: number };
   resetCacheStats?(): void;
   /** Free per-job WASM objects (Manifold backend); call after each job. */