partforge 0.1.0 → 0.4.0

package/src/framework/controls.js

@@ -6,9 +6,40 @@
 // enables it and reveals those controls right below it.
 // All controls mutate the shared `params` object and call onDirty() on change.
 
+import { renderMarkdown } from "./markdown.js";
+
 // Short numeric string without float noise (4 dp max) for the value box.
 const numStr = (v) => String(Math.round(v * 1e4) / 1e4);
 
+// --- relevance (dim controls / hide sections that don't affect on-screen parts) ---
+// `relevant` is a Set of param keys, or any non-Set value (e.g. RELEVANT_ALL) → show all.
+function applyRelevance(relevant, controls, sections) {
+  const showAll = !(relevant instanceof Set);
+  for (const { key, el: node } of controls) {
+    const irrelevant = !showAll && !relevant.has(key);
+    node.classList.toggle("irrelevant", irrelevant);
+    if (irrelevant) node.title = "Doesn't affect the parts in the current view";
+    else node.removeAttribute("title");
+  }
+  for (const { el: node, keys } of sections) {
+    const anyRelevant = showAll || [...keys].some((k) => relevant.has(k));
+    node.classList.toggle("section-hidden", !anyRelevant);
+  }
+}
+
+// --- visibility (hidden controls/sections) --------------------------------
+export const visibleAdvanced = (sec) => (sec.advanced ?? []).filter((d) => !d.hidden);
+export const visibleFeatures = (sec) => (sec.features ?? []).filter((f) => !f.hidden);
+// Standalone toggle checkboxes a preset section can show (outside the Advanced fold),
+// e.g. preview switches. Each: { key, label, on?, description?, hidden? }.
+export const visibleToggles = (sec) => (sec.toggles ?? []).filter((t) => !t.hidden);
+export function sectionRenders(sec) {
+  if (sec.hidden) return false;
+  if (sec.features) return visibleFeatures(sec).length > 0;
+  const hasPresets = sec.presets && Object.keys(sec.presets).length > 0;
+  return !!hasPresets || visibleAdvanced(sec).length > 0 || visibleToggles(sec).length > 0;
+}
+
 // Parse a typed value → clamped to [min, max], or null if not a finite number.
 export function clampToRange(raw, min, max) {
   const v = parseFloat(raw);
@@ -16,6 +47,58 @@ export function clampToRange(raw, min, max) {
   return Math.min(max, Math.max(min, v));
 }
 
+// --- info glyph + shared popover ------------------------------------------
+// One popover element, reused across glyphs (only one open at a time). Global
+// dismiss listeners are registered once at module load.
+let popover = null;
+function ensurePopover() {
+  if (!popover || !popover.isConnected) {
+    popover = document.createElement("div");
+    popover.className = "popover";
+    popover.hidden = true;
+    document.body.append(popover);
+  }
+  return popover;
+}
+function closePopover() {
+  if (popover && !popover.hidden) {
+    popover.hidden = true;
+    if (popover._owner) { popover._owner.setAttribute("aria-expanded", "false"); popover._owner = null; }
+  }
+}
+if (typeof document !== "undefined") {
+  document.addEventListener("click", (e) => {
+    if (popover && !popover.hidden && !popover.contains(e.target) && !e.target.closest?.(".info")) closePopover();
+  });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape") closePopover(); });
+}
+
+// Append a focusable ⓘ glyph to `container` that toggles the shared popover with
+// `description` (Markdown). No-op when description is empty.
+function attachInfo(container, description) {
+  if (typeof description !== "string" || !description.trim()) return;
+  const glyph = document.createElement("button");
+  glyph.type = "button";
+  glyph.className = "info";
+  glyph.textContent = "ⓘ";
+  glyph.setAttribute("aria-label", "More info");
+  glyph.setAttribute("aria-expanded", "false");
+  glyph.addEventListener("click", (e) => {
+    e.stopPropagation();
+    const pop = ensurePopover();
+    if (pop._owner === glyph) { closePopover(); return; } // toggle off
+    closePopover();
+    pop.innerHTML = renderMarkdown(description);
+    pop.hidden = false;
+    pop._owner = glyph;
+    glyph.setAttribute("aria-expanded", "true");
+    const r = glyph.getBoundingClientRect();
+    pop.style.top = `${r.bottom + 6}px`;
+    pop.style.left = `${Math.max(8, r.left - 8)}px`;
+  });
+  container.append(glyph);
+}
+
 function el(tag, className, text) {
   const node = document.createElement(tag);
   if (className) node.className = className;
@@ -32,7 +115,9 @@ function makeSlider(def, params, onChange) {
   const numeric = def.control === "number";
   const wrap = el("div", "slider");
   const row = el("div", "row");
-  row.append(el("label", "", def.label));
+  const label = el("label", "", def.label);
+  attachInfo(label, def.description);
+  row.append(label);
 
   // editable value box (+ optional unit suffix)
   const val = el("div", "val");
@@ -96,70 +181,102 @@ function advancedBlock() {
 }
 
 export function buildControls(root, parameters, params, onDirty) {
+  const controls = []; // { key, el } per control element
+  const sections = []; // { el, keys:Set } per rendered section
   for (const sec of parameters) {
+    if (!sectionRenders(sec)) continue;
     const section = el("div", "section");
-    section.append(el("div", "sec-title", sec.title));
-    if (sec.features) buildFeatureSection(section, sec, params, onDirty);
-    else buildPresetSection(section, sec, params, onDirty);
+    const title = el("div", "sec-title", sec.title);
+    attachInfo(title, sec.description);
+    section.append(title);
+    const keys = new Set();
+    const register = (key, node) => { controls.push({ key, el: node }); keys.add(key); };
+    if (sec.features) buildFeatureSection(section, sec, params, onDirty, register);
+    else buildPresetSection(section, sec, params, onDirty, register);
     root.append(section);
+    sections.push({ el: section, keys });
   }
+  return { applyRelevance: (relevant) => applyRelevance(relevant, controls, sections) };
 }
 
-function buildPresetSection(section, sec, params, onDirty) {
-  // preset picker, below the title, full width
-  const preset = document.createElement("select");
-  preset.className = "preset";
-  const presetNames = Object.keys(sec.presets);
-  for (const name of [...presetNames, "Custom"]) {
-    const o = document.createElement("option");
-    o.value = name;
-    o.textContent = name;
-    preset.append(o);
+function buildPresetSection(section, sec, params, onDirty, register) {
+  // preset picker, below the title, full width (omitted when the section has no presets)
+  let preset = null;
+  const presetNames = sec.presets ? Object.keys(sec.presets) : [];
+  if (presetNames.length) {
+    preset = document.createElement("select");
+    preset.className = "preset";
+    for (const name of [...presetNames, "Custom"]) {
+      const o = document.createElement("option");
+      o.value = name; o.textContent = name; preset.append(o);
+    }
+    preset.value = presetNames[0];
+    section.append(preset);
   }
-  preset.value = presetNames[0];
-  section.append(preset);
 
-  const { adv, toggle } = advancedBlock();
+  // standalone toggle checkboxes (e.g. preview switches), shown below the preset and
+  // outside the Advanced fold so they stay visible. Independent of the preset selector.
+  for (const t of visibleToggles(sec)) {
+    const row = el("label", "feat");
+    const box = document.createElement("input");
+    box.type = "checkbox";
+    box.checked = params[t.key] > 0;
+    const lbl = el("span", "", t.label);
+    attachInfo(lbl, t.description);
+    row.append(box, lbl);
+    box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
+    register(t.key, row);
+    section.append(row);
+  }
+
+  const advanced = visibleAdvanced(sec);
   const syncs = {};
-  for (const def of sec.advanced) {
-    const s = makeSlider(def, params, () => {
-      preset.value = "Custom";
-      onDirty?.();
-    });
-    adv.append(s.wrap);
-    syncs[def.key] = s.sync;
+  if (advanced.length) {
+    const { adv, toggle } = advancedBlock();
+    for (const def of advanced) {
+      const s = makeSlider(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); });
+      adv.append(s.wrap);
+      syncs[def.key] = s.sync;
+      register(def.key, s.wrap);
+    }
+    section.append(toggle, adv);
   }
-  section.append(toggle, adv);
 
   // applying a preset overwrites its keys and refreshes this section's sliders
-  preset.addEventListener("change", () => {
-    const bundle = sec.presets[preset.value];
-    if (!bundle) return; // "Custom"
-    Object.assign(params, bundle);
-    for (const key in syncs) if (key in params) syncs[key]();
-    onDirty?.();
-  });
+  if (preset) {
+    preset.addEventListener("change", () => {
+      const bundle = sec.presets[preset.value];
+      if (!bundle) return; // "Custom"
+      Object.assign(params, bundle);
+      for (const key in syncs) if (key in params) syncs[key]();
+      onDirty?.();
+    });
+  }
 }
 
-function buildFeatureSection(section, sec, params, onDirty) {
+function buildFeatureSection(section, sec, params, onDirty, register) {
   // Everything lives under Advanced: each feature is a checkbox followed by its
   // own controls, which appear directly below it when the box is checked.
   const { adv, toggle } = advancedBlock();
   section.append(toggle, adv);
 
-  for (const feat of sec.features) {
+  for (const feat of visibleFeatures(sec)) {
     const checkRow = el("label", "feat");
     const box = document.createElement("input");
     box.type = "checkbox";
     box.checked = params[feat.key] > 0;
-    checkRow.append(box, el("span", "", feat.label));
+    const featLabel = el("span", "", feat.label);
+    attachInfo(featLabel, feat.description);
+    checkRow.append(box, featLabel);
+    register(feat.key, checkRow);
 
     const group = el("div", "feat-group");
     const syncs = [];
-    for (const def of feat.sliders) {
+    for (const def of feat.sliders.filter((d) => !d.hidden)) {
       const s = makeSlider(def, params, onDirty);
       group.append(s.wrap);
       syncs.push(s.sync);
+      register(def.key, s.wrap);
     }
     group.classList.toggle("hidden", !box.checked);
 

package/src/framework/debug-overlay.js

@@ -0,0 +1,40 @@
+// src/framework/debug-overlay.js
+// A dev-only overlay (shown under ?debug) with a caching on/off toggle and a
+// readout of the last build's time + what the cache did. Self-contained: it
+// creates its own DOM and knows nothing about geometry — mount.js wires it in.
+export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
+  const box = document.createElement("div");
+  box.id = "pf-debug";
+  Object.assign(box.style, {
+    position: "fixed", bottom: "12px", right: "12px", zIndex: "9999",
+    font: "12px ui-monospace, monospace", background: "rgba(0,0,0,0.7)",
+    color: "#e6e6e6", padding: "8px 10px", borderRadius: "6px",
+    lineHeight: "1.5", whiteSpace: "pre",
+  });
+
+  const label = document.createElement("label");
+  label.style.cssText = "display:block;cursor:pointer;margin-bottom:4px";
+  const cb = document.createElement("input");
+  cb.type = "checkbox";
+  cb.checked = initialCachingOn;
+  cb.style.marginRight = "6px";
+  label.append(cb, document.createTextNode("Caching"));
+
+  const readout = document.createElement("div");
+  readout.textContent = "build: —";
+
+  box.append(label, readout);
+  document.body.appendChild(box);
+
+  cb.addEventListener("change", () => onToggle?.(cb.checked));
+
+  return {
+    update({ ms, hits = 0, misses = 0, skipped = 0, rebuilt = 0 } = {}) {
+      const l2 = cb.checked ? `${hits} hit / ${misses} miss` : "off";
+      readout.textContent =
+        `build: ${ms != null ? Math.round(ms) + " ms" : "—"}\n` +
+        `L2 ops: ${l2}\n` +
+        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt`;
+    },
+  };
+}

package/src/framework/geometry/edge-selector.js

@@ -0,0 +1,17 @@
+// Map partforge's declarative edge selector onto a replicad EdgeFinder filter.
+//   undefined          → undefined (all edges)
+//   (e) => e...         → passed through (raw replicad finder escape hatch)
+//   { dir, inPlane, at, near } → a filter applying the given criteria (AND)
+const AXIS = { X: [1, 0, 0], Y: [0, 1, 0], Z: [0, 0, 1] };
+
+export function toEdgeFinder(selector) {
+  if (selector == null) return undefined;
+  if (typeof selector === "function") return selector;
+  return (e) => {
+    let f = e;
+    if (selector.dir != null) f = f.inDirection(Array.isArray(selector.dir) ? selector.dir : AXIS[selector.dir]);
+    if (selector.inPlane != null) f = f.inPlane(selector.inPlane, selector.at);
+    if (selector.near != null) f = f.containsPoint(selector.near);
+    return f;
+  };
+}

package/src/framework/geometry/errors.js

@@ -0,0 +1,10 @@
+// Thrown by a backend that can't perform a requested op (e.g. Manifold has no
+// fillet/chamfer). The framework catches `.code === "NEEDS_OCCT"` and reroutes
+// the part to the OCCT backend.
+export class KernelCapabilityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KernelCapabilityError";
+    this.code = "NEEDS_OCCT";
+  }
+}

package/src/framework/geometry/face-selector.js

@@ -0,0 +1,19 @@
+// Map partforge's declarative face selector onto a replicad FaceFinder filter.
+//   undefined / null   → undefined (all faces)
+//   (f) => f...         → passed through (raw replicad finder escape hatch)
+//   { dir, inPlane, at, near } → a filter applying the given criteria (AND)
+// dir picks faces whose normal runs along that axis (i.e. parallel to the
+// perpendicular plane): X→YZ, Y→XZ, Z→XY.
+const PERP_PLANE = { X: "YZ", Y: "XZ", Z: "XY" };
+
+export function toFaceFinder(selector) {
+  if (selector == null) return undefined;
+  if (typeof selector === "function") return selector;
+  return (f) => {
+    let r = f;
+    if (selector.dir != null) r = r.parallelTo(PERP_PLANE[selector.dir]);
+    if (selector.inPlane != null) r = r.inPlane(selector.inPlane, selector.at);
+    if (selector.near != null) r = r.containsPoint(selector.near);
+    return r;
+  };
+}

package/src/framework/geometry/kernel.js

@@ -3,12 +3,17 @@
 
 /**
  * @typedef {Object} Solid  An opaque handle to a backend solid.
+ * @property {string} _hash   content hash (Manifold backend only; drives the worker solid cache)
  * @property {(tool: Solid) => Solid} cut
  * @property {(tools: Solid[]) => Solid} cutAll      batch subtract (backend-optimized)
  * @property {(other: Solid) => Solid} intersect     boolean intersection (Manifold)
+ * @property {() => Solid} clone   independent copy (replicad consumes solids on transform)
+ * @property {() => {min:number[],max:number[],center:number[],size:number[]}} boundingBox   axis-aligned bounds (query)
+ * @property {(thickness:number, openFaces:object) => Solid} shell   hollow inward (OCCT only); openFaces selector required
  * @property {(v: number[]) => Solid} translate
  * @property {(deg: number, center: number[], axis: number[]) => Solid} rotate
  * @property {(plane: "XY"|"XZ"|"YZ") => Solid} mirror
+ * @property {(factor:number, center?:number[]) => Solid} scale   uniform scale about center (default origin)
  * @property {() => number} volume                   solid volume in mm³ (Manifold; used by collision tests)
  * @property {(opts?: {quality?: "preview"|"print"}) => {positions:Float32Array, normals:Float32Array, indices:Uint32Array, triangles:number}} toMesh
  * @property {(opts?: {quality?: "preview"|"print"}) => Promise<ArrayBuffer>} toSTL
@@ -16,8 +21,11 @@
  *
  * @typedef {Object} GeometryKernel
  * @property {(rBottom:number, rTop:number, h:number, opts?:{center?:boolean}) => Solid} cylinder
+ * @property {(o:{od:number,h:number,bore:number}) => Solid} boredCylinder   compound: bored-through cylinder (one cache node)
+ * @property {(r:number) => Solid} sphere   sphere centred at the origin
  * @property {(min:number[], max:number[]) => Solid} box
- * @property {(points2D:number[][], h:number) => Solid} prism   extrude polygon from z=0
+ * @property {(points2D:number[][], h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0 (optional twist° + uniform top taper)
+ * @property {(points2D:number[][], opts?:{degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union
  * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only

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

@@ -1,4 +1,7 @@
 import { helixTube } from "./helix-tube.js";
+import { KernelCapabilityError } from "./errors.js";
+import { h } from "./solid-hash.js";
+import { createSolidCache } from "./solid-cache.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
@@ -21,6 +24,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const T = (obj) => { tracked.push(obj); return obj; };
   const unionRaw = (ms) => ms.reduce((a, b) => T(a.add(b))); // track each reduce step
 
+  const cache = createSolidCache();
+  // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
+  // tracks the result, and returns the triple the cache needs to pin/dispose it.
+  const cached = (hash, computeM) => cache.lookup(hash, () => {
+    const m = computeM();                 // already T()-tracked by the op
+    return { value: wrap(m, hash), pin: m, dispose: () => m.delete?.() };
+  });
+
   // Copy the mesh out into JS-owned arrays (so it survives cleanup) and free the
   // transient mesh handle.
   function meshOut(m, asStl) {
@@ -47,41 +58,88 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     return { positions, indices };
   }
 
-  const wrap = (m) => ({
+  const wrap = (m, hash) => ({
     _m: m,
-    cut: (t) => wrap(T(m.subtract(t._m))),
-    cutAll: (tools) => wrap(T(m.subtract(unionRaw(tools.map((t) => t._m))))),
-    intersect: (t) => wrap(T(m.intersect(t._m))),
+    _hash: hash,
+    cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
+    cutAll: (tools) => cached(h("cutAll", hash, tools.map((t) => t._hash)),
+      () => T(m.subtract(unionRaw(tools.map((t) => t._m))))),
+    intersect: (t) => cached(h("intersect", hash, t._hash), () => T(m.intersect(t._m))),
+    clone: () => wrap(m, hash),
+    boundingBox: () => {
+      const b = m.boundingBox();           // { min: Vec3, max: Vec3 }
+      const min = [...b.min], max = [...b.max];
+      return {
+        min, max,
+        center: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+        size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
+      };
+    },
     volume: () => m.volume(),
-    translate: (v) => wrap(T(m.translate(v))),
+    genus: () => m.genus(),
+    isEmpty: () => m.isEmpty(),
+    translate: (v) => wrap(T(m.translate(v)), h("translate", hash, v)),
     rotate: (deg, center, axis) => {
       const euler = [axis[0] * deg, axis[1] * deg, axis[2] * deg];
       const a = T(m.translate([-center[0], -center[1], -center[2]]));
       const b = T(a.rotate(euler));
-      return wrap(T(b.translate(center)));
+      return wrap(T(b.translate(center)), h("rotate", hash, deg, center, axis));
+    },
+    mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane])), h("mirror", hash, plane)),
+    scale: (factor, center = [0, 0, 0]) => {
+      if (!(factor > 0)) throw new Error("scale: factor must be > 0");
+      const a = T(m.translate([-center[0], -center[1], -center[2]]));
+      const b = T(a.scale([factor, factor, factor]));
+      return wrap(T(b.translate(center)), h("scale", hash, factor, center));
     },
-    mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane]))),
     toMesh: () => meshOut(m, false),
     toSTL: () => Promise.resolve(meshOut(m, true)),
     toIndexedMesh: () => indexedMeshOut(m),
+    fillet: () => { throw new KernelCapabilityError("fillet requires the OCCT backend"); },
+    chamfer: () => { throw new KernelCapabilityError("chamfer requires the OCCT backend"); },
+    shell: () => { throw new KernelCapabilityError("shell requires the OCCT backend"); },
   });
 
   return {
-    cylinder: (rb, rt, h, { center = false } = {}) => wrap(T(Manifold.cylinder(h, rb, rt, segs, center))),
+    cylinder: (rb, rt, h2, { center = false } = {}) =>
+      wrap(T(Manifold.cylinder(h2, rb, rt, segs, center)), h("cylinder", rb, rt, h2, center, segs)),
+    // Compound op: hashed ATOMICALLY from its own args, so it is a single cache
+    // node — its internal cylinders/cut are never retained. The template for
+    // future compounds: build internals with T(), return the final tracked solid.
+    boredCylinder: ({ od, h: height, bore }) => cached(h("boredCylinder", od, height, bore, segs), () => {
+      const body = T(Manifold.cylinder(height, od / 2, od / 2, segs, false));
+      const tool0 = T(Manifold.cylinder(height + 4, bore / 2, bore / 2, segs, false));
+      const tool = T(tool0.translate([0, 0, -2])); // raw ops: track each result
+      return T(body.subtract(tool));
+    }),
+    sphere: (r) => wrap(T(Manifold.sphere(r, segs)), h("sphere", r, segs)),
     box: (min, max) => {
       const cube = T(Manifold.cube([max[0] - min[0], max[1] - min[1], max[2] - min[2]]));
-      return wrap(T(cube.translate(min)));
-    },
-    prism: (pts, h) => {
-      const cs = T(CrossSection.ofPolygons([pts]));
-      return wrap(T(cs.extrude(h)));
+      return wrap(T(cube.translate(min)), h("box", min, max));
     },
-    helixSweptTube: (o) => wrap(T(helixTube(wasm, { ...o, ...tube }))),
-    union: (solids) => wrap(unionRaw(solids.map((s) => s._m))), // unionRaw already tracks its result
+    prism: (pts, height, { twist = 0, scaleTop = 1 } = {}) =>
+      cached(h("prism", pts, height, twist, scaleTop, segs), () => {
+        if (scaleTop < 0) throw new Error("prism: scaleTop must be ≥ 0");
+        const cs = T(CrossSection.ofPolygons([pts]));
+        if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
+        const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
+        return T(cs.extrude(height, nDiv, twist, scaleTop));
+      }),
+    helixSweptTube: (o) => cached(h("helixSweptTube", o, tube), () => T(helixTube(wasm, { ...o, ...tube }))),
+    revolve: (pts, { degrees = 360 } = {}) =>
+      cached(h("revolve", pts, degrees, segs), () => {
+        for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
+        return T(Manifold.revolve([pts], segs, degrees));
+      }),
+    union: (solids) => cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
     toSTEP: () => { throw new Error("STEP export not supported by the Manifold backend"); },
-    // Free every WASM object created since the last cleanup. Call after each job
-    // once its meshes/buffers have been copied out (meshOut already did).
-    cleanup: () => { for (const o of tracked) o.delete?.(); tracked.length = 0; },
+    beginSubPart: (name) => cache.begin(name),
+    endSubPart: () => cache.end(),
+    cacheStats: () => cache.stats(),
+    resetCacheStats: () => cache.resetStats(),
+    // Free every WASM object created since the last cleanup EXCEPT solids the cache
+    // still pins (they must survive for the next build to resume from them).
+    cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },
   };
 }