partforge 0.165.1 → 0.166.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.165.1",
+  "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/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,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 }
@@ -462,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 {
@@ -472,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
@@ -705,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/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

@@ -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. */