partforge 0.165.0 → 0.166.0

package/docs/KERNEL-CONTRACT.md

@@ -106,13 +106,24 @@ 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`/
-`cacheStats`/`resetCacheStats`/`cleanup`) and `SOLID_OPTIONAL_OPS` (`genus`/`isEmpty`) may
+**Optional ops.** `KERNEL_OPTIONAL_OPS` (`beginSubPart`/`endSubPart`/`sweepCache`/`dropCache`/
+`setCacheBudget`/`trimCache`/`cacheBytes`/`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.
+`setCacheBudget(bytes)` bounds the bytes the cache's retained solids may hold (the
+Manifold backend estimates each from its triangle and vertex counts); `trimCache()`
+then drops whole partitions, least recently built first, until they fit. A trim frees
+solids, so it runs only where no caller holds one — never inside a bracket and never
+right after one whose solids are still in use; jobs.js trims after each display
+sub-part is meshed and when a job returns. The budget arrives on `generate` messages
+as `cacheBudget` (bytes, `null` = unbounded), from mount's `cacheBudgetMB` option.
 
 `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.166.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/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", "setCacheBudget", "trimCache", "cacheBytes", "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,10 @@ 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 {(bytes:number) => void} [setCacheBudget]   bound the solid cache's retained bytes (Infinity = unbounded)
+ * @property {() => number} [trimCache]   drop least recently built partitions until the cache fits its budget; only where no cached solid is held
+ * @property {() => number} [cacheBytes]  the cache's estimated retained bytes
  * @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

@@ -61,6 +61,8 @@ function axisAngleMat4(axis, deg) {
   return [R00, R10, R20, 0,  R01, R11, R21, 0,  R02, R12, R22, 0,  0, 0, 0, 1];
 }
 
+const BYTES_PER_TRI = 160, BYTES_PER_VERT = 24;
+
 export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const { Manifold, CrossSection } = wasm;
   const segs = SEGS[quality], tube = TUBE[quality];
@@ -128,7 +130,18 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   };
   const judgedUnion = (ms) => judged("union", ms, unionRaw(ms));
 
-  const cache = createSolidCache();
+  // A retained solid's heap, estimated from its counts (solid-cache.js MEMORY BUDGET):
+  // Manifold keeps per triangle three half-edges, a face normal, a triangle reference and
+  // its share of the collider, and per vertex a position and a normal.
+  // CrossSections (memoized 2-D profiles) are small: a few dozen bytes per vertex.
+  // Measured against the heap a 105-plate forge's cache held (feedback #212).
+  const cache = createSolidCache({
+    sizeOf: (pin) => {
+      if (typeof pin?.numTri === "function") return pin.numTri() * BYTES_PER_TRI + pin.numVert() * BYTES_PER_VERT;
+      if (typeof pin?.numVert === "function") return pin.numVert() * 32;
+      return 0;
+    },
+  });
   // Feature-skip warnings (the OCCT backend's safeOp policy, adopted here): a
   // fillet/chamfer whose mesh machinery is defeated by the geometry returns its
   // INPUT solid unchanged and records one message here instead of failing the
@@ -1063,6 +1076,10 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
     sweepCache: () => cache.sweep(),
+    dropCache: () => cache.clear(),
+    setCacheBudget: (bytes) => cache.setBudget(bytes),
+    trimCache: () => cache.trim(),
+    cacheBytes: () => cache.retainedBytes(),
     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

@@ -7,7 +7,21 @@
 // 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() {
+//
+// MEMORY BUDGET (feedback #212). Retaining a whole view's build graph is what makes an
+// edit rebuild in seconds, and it is also most of the heap a big view holds: opening a
+// 105-plate forge peaked at 3.3 GB with the cache and 0.95 GB without, which a phone's
+// browser tab cannot hold. `setBudget(bytes)` bounds it; `trim()` then disposes whole
+// partitions, least recently built first, until the retained solids fit. A sub-part
+// trimmed away simply rebuilds cold next time. `sizeOf(pin)` is the caller's estimate
+// of one retained object's bytes (the Manifold backend reads its triangle and vertex
+// counts); it is asked once per entry, at the first trim() after the entry was made.
+//
+// trim() is NOT done inside end(): a caller may still be using a round's solids after
+// closing it (buildView hands its built view to measure), and a trim there would free
+// them under it. jobs.js trims where nothing is held — after each display sub-part has
+// been meshed and cleaned up, and when a job ends.
+export function createSolidCache({ sizeOf = () => 0 } = {}) {
   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
@@ -17,6 +31,11 @@ export function createSolidCache() {
   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;
+  let budget = Infinity;       // bytes the retained solids may hold (setBudget)
+  let bytes = 0;               // the retained solids' estimated size, each entry once
+  let tick = 0;                // begin() order, for least-recently-built eviction
+  const lastUsed = new Map();  // name -> tick of the partition's last begin()
+  const unsized = new Set();   // entries made since the last trim(), size not yet read
 
   // 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
@@ -27,8 +46,16 @@ export function createSolidCache() {
     if (--entry.refs > 0) return;
     if (index.get(hash) === entry) index.delete(hash);
     pinned.delete(entry.pin);
+    unsized.delete(entry);
+    bytes -= entry.size ?? 0;
     entry.dispose();
   };
+  const dropPartition = (n) => {
+    for (const [hash, entry] of caches.get(n) ?? []) release(hash, entry); // refcounted: a shared solid survives
+    caches.delete(n);
+    lastBuilt.delete(n);
+    lastUsed.delete(n);
+  };
 
   return {
     // Nested brackets collapse into the outermost one. There is a single open
@@ -39,7 +66,7 @@ export function createSolidCache() {
     // 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();
+      name = n; lastBuilt.set(n, generation); lastUsed.set(n, ++tick); prev = caches.get(n) ?? new Map(); active = new Map();
     },
 
     end() {
@@ -58,12 +85,52 @@ export function createSolidCache() {
     // the eviction line, so recently-viewed views stay warm across edits.
     sweep() {
       generation++;
-      for (const [n, entries] of caches) {
+      for (const n of [...caches.keys()]) {
         if (generation - (lastBuilt.get(n) ?? 0) < 3) continue;
-        for (const [hash, entry] of entries) release(hash, entry); // refcounted: a shared solid survives
-        caches.delete(n);
-        lastBuilt.delete(n);
+        dropPartition(n);
+      }
+    },
+
+    // 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();
+      lastUsed.clear();
+    },
+
+    // Bytes the retained solids may hold; Infinity (the default) never trims.
+    setBudget(b) {
+      budget = typeof b === "number" && b >= 0 ? b : Infinity;
+    },
+
+    // Dispose whole partitions, least recently built first, until the retained solids
+    // fit the budget. Never mid-bracket, and only where no caller holds a cached solid
+    // (see the header). Returns how many partitions it dropped.
+    trim() {
+      if (name != null) return 0;
+      for (const entry of unsized) {
+        let s = 0;
+        try { s = Math.max(0, Number(sizeOf(entry.pin)) || 0); } catch { s = 0; }
+        entry.size = s;
+        bytes += s;
+      }
+      unsized.clear();
+      let dropped = 0;
+      while (bytes > budget && lastUsed.size > 0) {
+        let oldest = null, at = Infinity;
+        for (const [n, t] of lastUsed) if (t < at) { at = t; oldest = n; }
+        dropPartition(oldest);
+        dropped++;
       }
+      return dropped;
     },
 
     lookup(hash, make) {
@@ -76,6 +143,7 @@ export function createSolidCache() {
       misses++;
       const entry = make();
       entry.refs = 1;
+      unsized.add(entry);
       active.set(hash, entry);
       index.set(hash, entry);
       pinned.add(entry.pin);
@@ -84,6 +152,7 @@ export function createSolidCache() {
 
     isPinned: (pin) => pinned.has(pin),
     stats: () => ({ hits, misses }),
+    retainedBytes: () => bytes,
     resetStats: () => { hits = 0; misses = 0; },
   };
 }

package/src/framework/jobs.js

@@ -65,7 +65,7 @@ const loadBedLayout = () => import("./export/bed-layout.js");
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
-//   { type:"generate", subparts, view, params } → { type:"meshes", meshes, ms }
+//   { type:"generate", subparts, view, params, cacheBudget? } → { type:"meshes", meshes, ms }
 //   { type:"export-stl", view, params }         → { type:"download-parts", ext, mime, parts }
 //   { type:"export-step", view, params }        → { type:"download", data, filename, mime }
 //   { type:"export-bundle", view, params, parts, options }
@@ -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 });
@@ -446,6 +462,9 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       kernel.takeBuildWarnings?.();
       const warnings = [...jobWarnings];   // job-level notices ride along with the per-sub-part ones
       kernel.resetCacheStats?.(); // count hits/misses for just this job
+      // The host's bound on the solid cache (mount's cacheBudgetMB), in bytes; null
+      // means unbounded. Kept by the kernel, so the oracle's builds share it.
+      if (Object.hasOwn(msg, "cacheBudget")) kernel.setCacheBudget?.(msg.cacheBudget ?? Infinity);
       for (const [i, name] of msg.subparts.entries()) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
         try {
@@ -456,6 +475,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           for (const message of kernel.takeBuildWarnings?.() ?? []) warnings.push({ part: name, message });
           if (useCache) kernel.endSubPart?.(); // always close the bracket — a throw mid-build must not strand pinned solids
           kernel.cleanup?.();                  // free this round's transients (cached/pinned solids survive)
+          kernel.trimCache?.();                // over the host's budget: drop the least recently built sub-parts' solids
         }
         // Cooperative cancel: yield one macrotask so queued messages (a newer
         // generate, a part rebind) can be seen, then stop at this boundary if
@@ -500,9 +520,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 +552,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");
@@ -665,5 +709,6 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     else post({ type: "error", message: String(err?.message || err), jobId: msg.jobId });
   } finally {
     kernel.cleanup?.();
+    kernel.trimCache?.(); // a job holds no cached solid once it has returned (solid-cache.js MEMORY BUDGET)
   }
 }

package/src/framework/mount.js

@@ -286,7 +286,8 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.158.0: a preview GLB may carry its view's autoplay
+// Embedding contract (0.166.0: `cacheBudgetMB` bounds the worker's solid cache —
+// pass a small one on phones; 0.158.0: a preview GLB may carry its view's autoplay
 // animation — mount({ preview }) draws its opening pose and does not play it,
 // mountPreview plays it unless `animate: false`, and exportPreview bakes it only
 // when every track is place-only; 0.147.0: a cached `preview` GLB is drawn before
@@ -515,6 +516,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
                               files, panelState,
                               annotateSend = "viewbar",
                               selectionPopover,
+                              cacheBudgetMB,
                               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);
@@ -641,6 +643,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     const qs = new URLSearchParams(location.search);
     const debug = qs.has("debug");
     let cachingOn = !(debug && qs.has("nocache"));
+    // The host's bound on the worker's solid cache, sent with every generate (null =
+    // unbounded). A phone host passes a small one: the cache of a very large view is
+    // most of its heap (feedback #212). Anything but a positive finite number is ignored.
+    const cacheBudgetBytes = Number.isFinite(cacheBudgetMB) && cacheBudgetMB > 0 ? Math.round(cacheBudgetMB * 2 ** 20) : null;
     let lastGen = { skipped: 0, rebuilt: 0, posed: 0 }; // Layer-0/1 counts for the most recent generate
     // Sub-parts the pose fast path has repaired since the last build was dispatched.
     // A SET of names, not a running total: a slider drag re-repairs the same
@@ -1069,7 +1075,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         for (const backend of ["manifold", "occt"]) {
           const subparts = missing.filter((n) => (backends[n] ?? "manifold") === backend);
           if (subparts.length === 0) continue;
-          service.send({ type: "generate", subparts, view: view(), params, cache: cachingOn }, backend);
+          service.send({ type: "generate", subparts, view: view(), params, cache: cachingOn, cacheBudget: cacheBudgetBytes }, backend);
           jobs++;
         }
         return jobs;

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/index.d.ts

@@ -218,6 +218,14 @@ export interface MountOptions {
   onPick?: (event: PickEvent) => void;
   /** Opt in to the selection popover (requires `onPick`): a pick opens a popover at the spot with the sub-part's appearance controls, and with `slot: true` an empty region the host floats its own UI over (`runtime.selection`). */
   selectionPopover?: { slot: boolean };
+  /**
+   * Bound, in MB, on the geometry worker's solid cache — the built solids it keeps so
+   * an edit rebuilds only what changed. Unbounded by default. Past the bound the least
+   * recently built sub-parts' solids are freed and those sub-parts rebuild cold on the
+   * next edit. Pass a small bound on phones: a very large view's cache can hold
+   * gigabytes, more than a mobile browser tab is allowed.
+   */
+  cacheBudgetMB?: number;
   /** Receive exported bytes instead of partforge's own DOM download. */
   onDownload?: (file: DownloadPayload) => void;
   /** The active view (tab) name — emitted once on mount, then on every change. */

package/types/kernel.d.ts

@@ -642,6 +642,14 @@ 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;
+  /** Bound the solid cache's retained bytes (`Infinity` = unbounded, the default). */
+  setCacheBudget?(bytes: number): void;
+  /** Drop the least recently built partitions until the cache fits its budget. Only where no cached solid is held. */
+  trimCache?(): number;
+  /** The cache's estimated retained bytes. */
+  cacheBytes?(): number;
   cacheStats?(): { hits: number; misses: number };
   resetCacheStats?(): void;
   /** Free per-job WASM objects (Manifold backend); call after each job. */