partforge 0.165.1 → 0.167.0

package/docs/KERNEL-CONTRACT.md

@@ -107,7 +107,7 @@ relying on consumption should gate it with a `verify` volume assertion.
 OCCT/replicad backend is the reference.
 
 **Optional ops.** `KERNEL_OPTIONAL_OPS` (`beginSubPart`/`endSubPart`/`sweepCache`/`dropCache`/
-`cacheStats`/`resetCacheStats`/`cleanup`) and `SOLID_OPTIONAL_OPS` (`genus`/`isEmpty`) may
+`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
@@ -117,6 +117,13 @@ once, under the same never-mid-bracket rule: the worker calls it on each booted
 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
@@ -888,6 +895,17 @@ built. So **a `meshes` post is current as of the moment it is posted**: it is ne
 previous part's geometry surfacing after a rebind, and a host may take it as the build
 outcome for the part it currently has mounted.
 
+**Progressive generates.** A generate carrying `progressive: true` (mount's
+`progressiveBuild` option) also posts `{type:"meshes-partial", meshes}` while it runs:
+the sub-parts built so far, batched at most every 300 ms, each posted right after a
+sub-part boundary's staleness check. A batch that is stale by the time it is posted is
+dropped by the worker, never downgraded to `superseded` — the job's own final post still
+settles it. The final `{type:"meshes"}` then carries only the sub-parts no batch did, so
+every sub-part arrives exactly once, its buffers transferred with it. A batch settles
+nothing: `ready`, `onBuild` and a host's own "build finished" wait for `meshes`. A host
+that reads worker replies itself and turns `progressive` on must add the batches up; one
+that never sends it sees the protocol exactly as before.
+
 **Host-side rule for `superseded`.** partforge's own `mount()` does not handle a
 `superseded` message, and does not need to: in its single-mount flow the regen loop
 serializes generates, so no generate is ever in flight when the next one is sent and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.165.1",
+  "version": "0.167.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/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", "dropCache", "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
@@ -171,6 +171,9 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @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
@@ -1064,6 +1077,9 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     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/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,11 +85,9 @@ 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);
       }
     },
 
@@ -78,6 +103,34 @@ export function createSolidCache() {
       }
       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) {
@@ -90,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);
@@ -98,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,9 @@ 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?, progressive? } → { type:"meshes", meshes, ms }
+//       progressive: true also posts { type:"meshes-partial", meshes } batches while it
+//       builds; the final `meshes` then carries only the sub-parts no batch did
 //   { 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 +165,11 @@ async function scoreMatchTargets(built, targets, onProgress) {
   }
 }
 
+// A progressive generate hands over its built sub-parts at most this often (ms).
+const PROGRESSIVE_BATCH_MS = 300;
+const transferOf = (meshes) => meshes.flatMap((m) =>
+  [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
+
 // 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;
 
@@ -462,6 +469,10 @@ 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);
+      let lastBatchAt = t0; // progressive delivery's clock (below)
       for (const [i, name] of msg.subparts.entries()) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
         try {
@@ -472,6 +483,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
@@ -481,12 +493,22 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         if (i < msg.subparts.length - 1) {
           await new Promise((r) => setTimeout(r, 0));
           if (isStale()) return void post({ type: "superseded" });
+          // Progressive delivery (msg.progressive): hand over what is built so far,
+          // so a host shows a many-sub-part view filling in instead of waiting for
+          // the last sub-part (feedback #212: a 105-plate park showed nothing for
+          // ~45 s). Batched by time, never per sub-part, so a view of many cheap
+          // pieces is not a flood of messages. Posted only after the stale check
+          // above, so a batch is current as of the moment it is posted; the final
+          // `meshes` carries whatever is left, and the job's warnings and timing.
+          if (msg.progressive && meshes.length > 0 && Date.now() - lastBatchAt >= PROGRESSIVE_BATCH_MS) {
+            const batch = meshes.splice(0);
+            post({ type: "meshes-partial", meshes: batch }, transferOf(batch));
+            lastBatchAt = Date.now();
+          }
         }
       }
-      const transfer = meshes.flatMap((m) =>
-        [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
       post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.(),
-             ...(warnings.length ? { warnings } : {}) }, transfer);
+             ...(warnings.length ? { warnings } : {}) }, transferOf(meshes));
     } else if (msg.type === "capture-generate") {
       // A private, job-correlated one-shot channel for captureView — builds a
       // (possibly non-active) view's meshes off the regen loop, so it can never
@@ -705,5 +727,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,11 @@ 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.167.0: `progressiveBuild: true` shows a many-sub-part view
+// filling in as its sub-parts finish — the worker then also posts `meshes-partial`
+// batches, and the final `meshes` carries only what no batch did, so a host reading
+// worker replies itself must add them up; 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 +519,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
                               files, panelState,
                               annotateSend = "viewbar",
                               selectionPopover,
+                              cacheBudgetMB,
+                              progressiveBuild = false,
                               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 +647,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
@@ -1010,6 +1020,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     let framedView = null; // the view the camera was last framed to (null until first show)
     let cameraRestored = false; // saved camera applied once, on the first frame after load
+    let partialView = null;        // the view whose first build is shown in batches (showPartial)
+    let partialCameraKept = false; // that build must not reframe on completion
     let cutawayRestored = false; // a carried cutaway, applied once — after any preview, never on one
     let selectionRestored = false; // a carried selection, tried once, after the camera
     function restoreCarriedSelection() {
@@ -1069,7 +1081,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, ...(progressiveBuild ? { progressive: true } : {}) }, backend);
           jobs++;
         }
         return jobs;
@@ -1131,7 +1143,13 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     }
 
     function showView(needed) {
-      const frame = view() !== framedView;
+      let frame = view() !== framedView;
+      // A first build shown in batches (showPartial) completes: frame the whole view now,
+      // unless the user moved the camera meanwhile or a restored camera stands.
+      if (partialView === view()) {
+        partialView = null;
+        if (frame && partialCameraKept) { frame = false; framedView = view(); cameraRestored = true; }
+      }
       viewer.showAssembly(needed, { frame });
       if (frame) {
         framedView = view();
@@ -1283,6 +1301,63 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       }
     }
 
+    // Apply a delivery built at the LIVE params — a final `meshes` whose build is still
+    // fresh, or a progressive batch (meshes-partial) of a build that still is.
+    function applyFreshMeshes(meshes) {
+      liveDelivered = true; // only a delivery that is applied beats a preview still decoding
+      for (const m of meshes) {
+        viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
+        // The view its job was SENT for, and the frame the worker delivered
+        // in: "canonical" (place() not applied — mount poses it below) or
+        // "posed". An older worker sends no frame; its meshes are posed.
+        cache.record(m.name, m.reads, dispatched.get(m.name)?.view ?? view(), m.frame ?? "posed");
+        // A sub-part that built into NOTHING. Manifold booleans return an
+        // empty solid rather than throwing (a bore wider than its body),
+        // and typed values may sit outside the authored range, so a
+        // "successful" build can deliver zero triangles — recorded here,
+        // reported below once the view is whole. Undefined counts (a
+        // host's synthetic reply) are not empty.
+        if (m.triangles === 0) emptySubParts.add(m.name); else emptySubParts.delete(m.name);
+        // Stamp the fast path's pose baseline. Only here, inside the
+        // non-stale branch: the stamp must describe the geometry actually
+        // delivered, which buildDone() true guarantees is at the live params.
+        fastPath.recordDelivered(m.name);
+      }
+      // setSubGeometry reset every delivered mesh's matrix, so each one gets
+      // its display pose now, after its geometry landed: a canonical mesh
+      // place() at the live params, a posed one a cleared matrix. `fresh`:
+      // an untrusted live place() here clears the pose but keeps the stamp
+      // (host and worker probes agree by construction at these params;
+      // forgetting on a disagreement would rebuild at the same params forever).
+      fastPath.apply(meshes.map((m) => m.name), undefined, { fresh: true });
+      recordFrames(meshes);
+    }
+
+    // Progressive delivery (feedback #212). A view with many sub-parts posts what it has
+    // built in batches while the job runs, and the view fills in as they land. Framing is
+    // the one hazard: showView frames once per view, and framing to the first batch
+    // would leave a park's camera zoomed in on five plates. So a first build with nothing
+    // on screen frames to the first batch, and showView frames the whole view when the
+    // build completes — unless the user has moved the camera since, or a carried or
+    // persisted camera was restored, which win as they always have.
+    cleanup.defer(viewer.onCameraStart(() => { if (partialView === view()) partialCameraKept = true; }));
+    function showPartial() {
+      const needed = viewSubParts(part, view(), params);
+      // Everything already on screen (an edit), or a cached preview filling the
+      // gaps: the ordinary path shows it.
+      if (previewGate.isActive() || needed.every((n) => viewer.hasSubMesh(n))) return refreshView();
+      const present = needed.filter((n) => viewer.hasSubMesh(n));
+      let frame = false;
+      if (view() !== framedView && partialView !== view()) {
+        partialView = view();
+        partialCameraKept = false;
+        const cam = !cameraRestored ? viewerState?.camera ?? loadCamera() : null;
+        if (cam) { viewer.setCameraState(cam); cameraRestored = true; partialCameraKept = true; }
+        else frame = true;
+      }
+      viewer.showAssembly(present, { frame });
+    }
+
     ui.showBusy("booting kernel"); // visible from first paint until the kernel is ready
 
     // Bundle filename for a multi-part export (single parts download under their own name).
@@ -1305,36 +1380,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
           ui.showBusy(data.phase);
           ui.setStatus(`${data.phase}…`);
           break;
+        case "meshes-partial":
+          // A batch of a progressive build: shown only while that build is still
+          // current. It settles nothing — the job's final `meshes` does.
+          if (!loop.isFresh()) break;
+          applyFreshMeshes(data.meshes);
+          showPartial();
+          updateRelevance();
+          break;
         case "meshes": {
           const fresh = loop.buildDone();
           if (fresh) { // stale results (params changed mid-build) are discarded
-            liveDelivered = true; // only a delivery that is applied beats a preview still decoding
-            for (const m of data.meshes) {
-              viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
-              // The view its job was SENT for, and the frame the worker delivered
-              // in: "canonical" (place() not applied — mount poses it below) or
-              // "posed". An older worker sends no frame; its meshes are posed.
-              cache.record(m.name, m.reads, dispatched.get(m.name)?.view ?? view(), m.frame ?? "posed");
-              // A sub-part that built into NOTHING. Manifold booleans return an
-              // empty solid rather than throwing (a bore wider than its body),
-              // and typed values may sit outside the authored range, so a
-              // "successful" build can deliver zero triangles — recorded here,
-              // reported below once the view is whole. Undefined counts (a
-              // host's synthetic reply) are not empty.
-              if (m.triangles === 0) emptySubParts.add(m.name); else emptySubParts.delete(m.name);
-              // Stamp the fast path's pose baseline. Only here, inside the
-              // non-stale branch: the stamp must describe the geometry actually
-              // delivered, which buildDone() true guarantees is at the live params.
-              fastPath.recordDelivered(m.name);
-            }
-            // setSubGeometry reset every delivered mesh's matrix, so each one gets
-            // its display pose now, after its geometry landed: a canonical mesh
-            // place() at the live params, a posed one a cleared matrix. `fresh`:
-            // an untrusted live place() here clears the pose but keeps the stamp
-            // (host and worker probes agree by construction at these params;
-            // forgetting on a disagreement would rebuild at the same params forever).
-            fastPath.apply(data.meshes.map((m) => m.name), undefined, { fresh: true });
-            recordFrames(data.meshes);
+            applyFreshMeshes(data.meshes);
             // The whole view is live: every sub-part the preview drew has just been
             // replaced in place, so the tools it held back come back. Before
             // refreshView, so showView restores a carried cutaway on this build.

package/src/framework/regen-loop.js

@@ -53,6 +53,9 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
       return genVersion === paramsVersion;
     },
     version: () => paramsVersion,
+    // A build is in flight and nothing has edited the params since it was sent —
+    // the test a progressive batch (meshes-partial) must pass to be shown.
+    isFresh: () => pending > 0 && genVersion === paramsVersion,
     // Terminal: cancel the pending debounce and refuse all future sends.
     dispose() { disposed = true; clearTimeout(timer); },
   };

package/src/framework/worker.js

@@ -138,8 +138,13 @@ export function runWorker(part, opts = {}) {
           // generate that goes stale once dequeued. Both would otherwise post the OLD
           // part's meshes after a rebind. Downgrading them to `superseded` keeps the
           // contract simple: a `meshes` post is current as of the moment it is posted.
-          const gated = (m, transfer = []) =>
-            (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
+          // A progressive batch that went stale is simply dropped: the job's own
+          // final reply (or its superseded) still settles the cycle.
+          const gated = (m, transfer = []) => {
+            if (m.type === "meshes-partial" && isStale()) return;
+            if (m.type === "meshes" && isStale()) return post({ type: "superseded" });
+            post(m, transfer);
+          };
           await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, jobs: opts.jobs });
         } catch (thrown) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.

package/types/index.d.ts

@@ -218,6 +218,23 @@ 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;
+  /**
+   * Show a view filling in as its sub-parts finish, instead of all at once when the
+   * last one does — the difference on a forge of dozens of heavy pieces is the whole
+   * build time. Off by default. When on, the geometry worker also posts
+   * `{ type: "meshes-partial", meshes }` batches during a build and the final
+   * `{ type: "meshes" }` carries only the sub-parts no batch did: a host that reads
+   * worker replies itself must add the batches up.
+   */
+  progressiveBuild?: boolean;
   /** 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

@@ -644,6 +644,12 @@ export interface GeometryKernel {
   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. */