partforge 0.41.0 → 0.45.0

package/src/framework/pose-probe.js

@@ -1,116 +1,9 @@
-// Geometry-free pose probe: run a subpart's build()+place() against a stub kernel
-// whose token solids carry (a) a content-hash chain built with the shared h() and
-// (b) pending rigid pose steps, mirroring the backends' pose-lazy bookkeeping.
-// The fast path compares probe results ACROSS PARAM CHANGES ONLY — probe hashes
-// are never compared to backend hashes, so they only need to be stable and to
-// fold every geometry-affecting argument.
-//
-// Trust model: any query op (boundingBox/volume/…) during a build marks that
-// subpart untrusted — a query result could feed geometry OR pose, and the probe
-// returns dummies, so neither hash stability nor pose values can be believed.
-// A FUNCTION passed as (or nested inside) an op argument is untrusted for the
-// same reason the OCCT backend refuses to hash function selectors (see `selKey`
-// in occt-backend.js): a closure like `(e) => e.inDirection([0,0,p.z])` has the
-// same source text at every value of `p.z`, so hashing it would hold baseHash
-// stable while the real geometry changed — precisely the false-positive the fast
-// path must never make. Untrusted subparts simply take the normal regen path.
-import { h } from "./geometry/solid-hash.js";
-import { addSugar } from "./geometry/solid-sugar.js";
-import { SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS, OCCT_ONLY_OPS } from "./geometry/kernel.js";
-import { MAX_PROBE_OPS, ProbeRunawayError } from "./geometry/probe.js";
-import { viewSubParts, resolveParams } from "./jobs.js";
-
-const NAN3 = () => [NaN, NaN, NaN];
-
-function makeProbeSession() {
-  const state = { count: 0, queried: false, unhashable: false };
-  const tick = () => { if (++state.count > MAX_PROBE_OPS) throw new ProbeRunawayError(`pose probe exceeded ${MAX_PROBE_OPS} ops`); };
-
-  // Queries return dummies AND poison trust (see module comment).
-  const QUERY_DUMMIES = {
-    boundingBox: () => ({ min: NAN3(), max: NAN3() }), // addSugar derives center/size
-    volume: () => NaN,
-    genus: () => NaN,
-    isEmpty: () => false,
-    area: () => NaN,
-    toRegions: () => [],
-    simple: () => ({ outer: [[NaN, NaN]], holes: [] }),
-    toMesh: () => ({ positions: new Float32Array(9), normals: new Float32Array(0), triangles: 1, edges: new Float32Array(0) }),
-    toSTL: () => new ArrayBuffer(0),
-    toIndexedMesh: () => ({ positions: new Float32Array(9), indices: new Uint32Array(3) }),
-  };
-
-  // Operand tokens fold into a hash key by their own (pose-folded) hash; plain
-  // data canonicalizes via h(). Functions can't be hashed at all (see the module
-  // comment), so they poison trust AND get a per-call unique key — belt and
-  // braces, so the hash can't collide even before the trust check is consulted.
-  //
-  // The walk mirrors h()'s `canon` exactly (array → elements, other object → own
-  // enumerable values), because a function nested inside an options object —
-  // `fillet({ r, edges: (e) => … })`, the normal calling convention — is reached
-  // by canon, not by the top-level argument check.
-  let unhashable = 0;
-  const argKey = (a) => {
-    if (a && a.__poseToken) return a.__folded();
-    if (typeof a === "function") { state.unhashable = true; return `fn#${unhashable++}`; }
-    if (Array.isArray(a)) return a.map(argKey);
-    if (a && typeof a === "object") return Object.fromEntries(Object.keys(a).map((k) => [k, argKey(a[k])]));
-    return a;
-  };
-
-  function token(hash, pose) {
-    const folded = () => (pose.length ? h("posed", hash, pose) : hash);
-    const foldOp = (op) => (...args) => { tick(); return token(h(op, folded(), ...args.map(argKey)), []); };
-    const t = {
-      __poseToken: true,
-      __folded: folded,
-      _hash: hash,
-      _pose: pose,
-      // The rigid vocabulary stays out of the hash: recorded as pending steps,
-      // exactly like the OCCT backend's pose-lazy wrap. All transform sugar
-      // (rotateAbout/along/at/rotateX…) composes onto these via addSugar.
-      translate: (v) => { tick(); return token(hash, [...pose, { t: "translate", v }]); },
-      rotate: (deg, center, axis) => { tick(); return token(hash, [...pose, { t: "rotate", deg, center, axis }]); },
-      clone: () => t, // tokens are immutable — sharing is safe
-      // regions() is a data-returning query in disguise: on a real backend the
-      // scission ARRAY LENGTH is param-dependent data, so a build branching on
-      // `regions().length` could hold baseHash stable while geometry changed.
-      // It therefore poisons trust like any other query; the single token is
-      // still returned so op chains on regions()[0] don't crash mid-probe.
-      regions: () => { tick(); state.queried = true; return [token(h("regions", folded()), [])]; },
-    };
-    for (const [op, dummy] of Object.entries(QUERY_DUMMIES))
-      t[op] = (...a) => { tick(); state.queried = true; return dummy(...a); };
-    // Every other contract op folds pose + args into a fresh hash. Generated from
-    // the kernel-contract lists so new ops can never silently drift out of the probe.
-    for (const op of [...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_OPS, ...OCCT_ONLY_OPS])
-      t[op] ??= foldOp(op);
-    return addSugar(t);
-  }
-
-  // Kernel: catch-all factory — any op makes a fresh token hashed from its args.
-  const kernelQueries = {
-    toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
-    cleanup: () => {}, beginSubPart: () => {}, endSubPart: () => {},
-    cacheStats: () => ({ hits: 0, misses: 0 }), resetCacheStats: () => {},
-  };
-  const ignore = (key) => typeof key !== "string" || key === "then" || key === "toJSON" || key[0] === "_";
-  const kernel = new Proxy({}, {
-    get(_t, key) {
-      if (ignore(key)) return undefined;
-      if (key in kernelQueries) return kernelQueries[key];
-      return (...args) => { tick(); return token(h(key, ...args.map(argKey)), []); };
-    },
-  });
-
-  return { kernel, state };
-}
-
-const finiteVec = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
-const stepsFinite = (steps) => steps.every((st) =>
-  st.t === "translate"
-    ? finiteVec(st.v)
-    : Number.isFinite(st.deg) && finiteVec(st.center) && finiteVec(st.axis));
+// Geometry-free pose probe over a view — see pose-probe-core.js for the probe
+// session itself and the trust model. This wrapper resolves params/derive and
+// walks the view's sub-parts; it stays separate so lint can import the core
+// without dragging in the part-model/jobs layer (purity).
+import { probeSubPartPose } from "./pose-probe-core.js";
+import { viewSubParts, resolveParams } from "./part-model.js";
 
 // Probe every subpart the view shows. Never throws; a failing/queried/weird
 // subpart yields { trusted: false } and the others still probe.
@@ -124,16 +17,7 @@ export function probePoses(part, view, params) {
   }
   const { p, d } = resolved;
   for (const name of viewSubParts(part, view, params)) {
-    try {
-      const { kernel, state } = makeProbeSession(); // fresh op budget + trust per subpart
-      const sp = part.parts[name];
-      let s = sp.build(kernel, p, d);
-      if (sp.place) s = sp.place(s, { view, purpose: "display", p, d });
-      const ok = s && s.__poseToken && !state.queried && !state.unhashable && stepsFinite(s._pose);
-      out.set(name, ok ? { baseHash: s._hash, pose: s._pose, trusted: true } : { trusted: false });
-    } catch {
-      out.set(name, { trusted: false });
-    }
+    out.set(name, probeSubPartPose(part.parts[name], { view, purpose: "display", p, d }));
   }
   return out;
 }

package/src/framework/regen-loop.js

@@ -9,7 +9,9 @@
 // - markDirty() bumps the params version and debounces a kick, so dragging a
 //   slider queues one build per pause, not one per pixel;
 // - a build that a mid-flight edit outdated is reported stale by buildDone()
-//   (return false → the caller discards the meshes and kicks a rebuild).
+//   (return false → the caller discards the meshes and kicks a rebuild);
+// - markDirty({debounce:false}) bumps without arming the timer (the animation
+//   fast-apply path kicks explicitly).
 export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
   let kernelReady = false;
   let generating = false;
@@ -30,10 +32,15 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
   return {
     kick,
     ready() { if (disposed) return; kernelReady = true; kick(); },
-    markDirty() {
+    // `debounce: false` is the animation driver's mode: the version still bumps
+    // (stale in-flight builds are still detected), but no timer is armed — the
+    // driver kicks explicitly after the pose fast path has repaired, so a
+    // pose-only frame sends no job and a geometry frame dispatches immediately
+    // whenever the worker is idle (best-effort at worker cadence, clock-free).
+    markDirty({ debounce = true } = {}) {
       paramsVersion++;
       clearTimeout(timer);
-      timer = setTimeout(kick, debounceMs);
+      if (debounce) timer = setTimeout(kick, debounceMs);
     },
     // The build finished (meshes / needs-occt / error). Returns whether its result
     // is still current; the caller applies the meshes only on true, then kicks.

package/src/framework/safe-name.js

@@ -0,0 +1,26 @@
+// One hardened slug for every part-derived string that ends up as a filename, a
+// path segment, or a zip entry name.
+//
+// A PartDefinition is DATA, not trusted developer source: downstream hosts
+// (partforge-cloud) run LLM-generated and user-supplied parts, so `meta.title`,
+// `views[k].label` and `parts[x].export.name` are untrusted input. A title of
+// "../../.ssh/authorized" must not steer a render write out of its output
+// directory, and a zip entry must not carry a separator that a naive extractor
+// would honour (zip-slip).
+//
+// Deliberately DOM-free and free of `node:` builtins: the geometry worker, the
+// browser shell and the headless testing tree all import this.
+
+// Lowercase, reduce to [a-z0-9._-], collapse runs, and refuse to start with a
+// dot or dash — that is what kills ".." and dotfiles at the same time. Anything
+// that sanitizes away to nothing (a title that is entirely CJK or emoji, or the
+// empty string) yields `fallback`, so callers never build a name-less path.
+export function safeName(s, fallback = "part") {
+  const out = String(s ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[.-]+/, "")
+    .replace(/[.-]+$/, "");
+  return out || fallback;
+}

package/src/framework/verify-metrics.js

@@ -6,11 +6,11 @@
 // attached whatever the status — a passing-but-sampled reading is exactly the
 // case a reader needs told about). `manifoldOnly` facts are null on OCCT parts.
 //
-// This lives in framework/ rather than testing/ deliberately: the set of legal
+// This lives one level above framework/oracle/ deliberately: the set of legal
 // `verify.expect` metrics is part of the PartDefinition CONTRACT, which both the
-// verify runner (testing) and the linter (partforge/lint) must agree on. Keeping
-// it here lets the linter import the vocabulary without reaching measure.js or
-// jobs.js, which pull in the geometry kernels. This module must stay import-free.
+// verify runner (oracle/verify.js) and the linter (partforge/lint) must agree on.
+// Keeping it here lets the linter import the vocabulary without reaching
+// measure.js, which pulls in the geometry kernels. Must stay import-free.
 export const SUBPART_METRICS = {
   holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes,
     hint: "genus is wrong — an unintended tunnel exists or an intended bore is blocked; make cut tools pierce fully (overcut past the faces)" },

package/src/framework/view-state.js

@@ -1,36 +1,35 @@
 // Persist a little viewer UI state across browser reloads (notably Vite dev
-// auto-refresh) in localStorage. All keys are global. Reads/writes are guarded:
-// if localStorage is unavailable (private mode, disabled) or a value is corrupt,
-// reads return the documented default and writes are no-ops — persistence never
-// throws.
+// auto-refresh). `camera` and `theme` live in localStorage under global
+// keys — they're viewer preferences, not part state. The active view is different:
+// it's scoped to one part and stored in sessionStorage, so a hot reload keeps your
+// tab but the name can't bleed into another part that happens to share a view name,
+// and a fresh session opens on the part's own default (see default-view.js).
+// Reads/writes are guarded: if storage is unavailable (private mode, disabled) or a
+// value is corrupt, reads return the documented default and writes are no-ops —
+// persistence never throws.
 
 const KEY = {
-  rotating: "partforge:rotating",
   camera: "partforge:camera",
-  view: "partforge:view",
   theme: "partforge:theme",
 };
 
+const viewKey = (partKey) => `partforge:view:${partKey}`;
+
 function read(key) {
   try { return localStorage.getItem(key); } catch { return null; }
 }
 function write(key, value) {
   try { localStorage.setItem(key, value); } catch { /* storage unavailable — no-op */ }
 }
-
-const isVec3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n) => Number.isFinite(n));
-
-export function loadRotating() {
-  const raw = read(KEY.rotating);
-  if (raw === "false") return false;
-  if (raw === "true") return true;
-  return true; // default: auto-rotate on (matches the viewer's default)
+function readSession(key) {
+  try { return sessionStorage.getItem(key); } catch { return null; }
 }
-
-export function saveRotating(on) {
-  write(KEY.rotating, on ? "true" : "false");
+function writeSession(key, value) {
+  try { sessionStorage.setItem(key, value); } catch { /* storage unavailable — no-op */ }
 }
 
+const isVec3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n) => Number.isFinite(n));
+
 export function loadCamera() {
   const raw = read(KEY.camera);
   if (!raw) return null;
@@ -56,10 +55,15 @@ export function saveTheme(mode) {
   if (mode === "light" || mode === "dark") write(KEY.theme, mode);
 }
 
-export function loadView() {
-  return read(KEY.view); // raw string or null; caller validates against available tabs
+// `partKey` identifies the part — createViewTabs passes `meta.title`. Without one
+// there is nothing safe to key on, so both calls no-op rather than falling back to a
+// shared key (the cross-part bleed this scoping exists to remove).
+export function loadView(partKey) {
+  if (typeof partKey !== "string" || !partKey) return null;
+  return readSession(viewKey(partKey)); // raw string or null; caller validates against available tabs
 }
 
-export function saveView(name) {
-  if (typeof name === "string" && name) write(KEY.view, name);
+export function saveView(partKey, name) {
+  if (typeof partKey !== "string" || !partKey) return;
+  if (typeof name === "string" && name) writeSession(viewKey(partKey), name);
 }

package/src/framework/view-tabs.js

@@ -1,22 +1,37 @@
+import { resolveDefaultView } from "./default-view.js";
 import { loadView, saveView } from "./view-state.js";
 
 // The view-tab segmented control. When the part declares `views`, the buttons are
 // generated from it (part.views is the single source of truth — host pages leave
 // the #part div empty); a part without `views` keeps whatever buttons the page
-// hand-wrote. The active view persists across reloads via view-state.
+// hand-wrote. Which tab opens is resolveDefaultView's call, not key order. The
+// active tab then persists per part for the rest of the browser session, so a
+// Vite dev reload doesn't throw you back mid-edit.
 export function createViewTabs(el, part, { onChange }) {
   const generated = !!(el && part.views);
+  const partKey = part?.meta?.title ?? "";
+  const resolved = resolveDefaultView(part);
   if (generated) {
-    el.innerHTML = Object.entries(part.views)
-      .map(([key, v], i) => `<button data-part="${key}"${i === 0 ? ' class="on"' : ""}>${v?.label ?? key}</button>`)
-      .join("");
+    // Built node-by-node with textContent/dataset rather than an innerHTML
+    // template — view keys and labels come from the part, which is untrusted
+    // data (hosts run LLM-generated and user-supplied parts), so a label of
+    // `<img src=x onerror=...>` must land as text, not as markup.
+    el.replaceChildren(...Object.entries(part.views).map(([key, v]) => {
+      const btn = document.createElement("button");
+      btn.dataset.part = key;
+      btn.textContent = v?.label ?? key;
+      if (key === resolved) btn.classList.add("on");
+      return btn;
+    }));
   }
 
   const setActive = (btn) => { for (const b of el.children) b.classList.toggle("on", b === btn); };
 
-  // Initial view: the saved one if it still matches a tab, else the active (first) tab.
+  // Initial view: the session-saved one if it still matches a tab, else the active
+  // button — the resolved default for a generated bar, or whatever the page's own
+  // markup marked `on` for a hand-written one.
   const defaultView = el.querySelector("button.on")?.dataset.part ?? el.querySelector("button")?.dataset.part;
-  const saved = loadView();
+  const saved = loadView(partKey);
   const savedBtn = saved ? [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === saved) : null;
   let view = savedBtn ? saved : defaultView;
   if (savedBtn) setActive(savedBtn);
@@ -25,7 +40,7 @@ export function createViewTabs(el, part, { onChange }) {
     const btn = e.target.closest("button[data-part]");
     if (!btn) return;
     view = btn.dataset.part;
-    saveView(view);
+    saveView(partKey, view);
     setActive(btn);
     onChange(view);
   };
@@ -33,6 +48,19 @@ export function createViewTabs(el, part, { onChange }) {
 
   return {
     current: () => view,
+    // Programmatic switch — the click path without the click. Used by an
+    // embedder (mount's handle.setView) to change tabs from outside the DOM.
+    // Returns false for a name that isn't a tab so callers can validate.
+    select: (name) => {
+      if (name === view) return true; // already active — nothing to do
+      const btn = [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === name);
+      if (!btn) return false;
+      view = name;
+      saveView(partKey, view);
+      setActive(btn);
+      onChange(view);
+      return true;
+    },
     detach: () => {
       el.removeEventListener("click", onClick);
       if (generated) el.innerHTML = ""; // we generated these buttons; hand-written markup stays

package/src/framework/viewer-controls.js

@@ -1,17 +1,17 @@
-import { loadRotating, saveRotating, saveCamera, loadTheme, saveTheme } from "./view-state.js";
+import { saveCamera, loadTheme, saveTheme } from "./view-state.js";
 import { attachButtonTooltips } from "./tooltip.js";
 
-// Wire the optional viewer-chrome buttons (pause / reframe / theme) to the viewer,
+// Wire the optional viewer-chrome buttons (reframe / theme) to the viewer,
 // plus persist the camera pose. Element refs in (mount resolves defaults); each
 // button is optional — pass nothing and its behavior is simply absent. Returns
 // { detach } removing every listener this attached.
 export function attachViewerControls(
   viewer,
-  { pause: pauseBtn, reframe: reframeBtn, theme: themeBtn } = {},
+  { reframe: reframeBtn, theme: themeBtn } = {},
   { tooltip } = {},
 ) {
   const tooltipBinding = tooltip
-    ? attachButtonTooltips(tooltip, [pauseBtn, reframeBtn, themeBtn].map((element) => ({ element })))
+    ? attachButtonTooltips(tooltip, [reframeBtn, themeBtn].map((element) => ({ element })))
     : null;
 
   // Theme: toggle the page chrome (CSS vars keyed off <html data-theme>) and the
@@ -34,26 +34,6 @@ export function attachViewerControls(
   const onThemeClick = () => applyTheme(theme === "light" ? "dark" : "light");
   themeBtn?.addEventListener("click", onThemeClick);
 
-  // Pause/resume the idle auto-rotation.
-  let rotating = loadRotating();
-  viewer.setAutoRotate(rotating);
-  const syncPause = () => {
-    if (!pauseBtn) return;
-    pauseBtn.textContent = rotating ? "⏸" : "▶";
-    const label = rotating ? "Pause rotation" : "Resume rotation";
-    pauseBtn.setAttribute("aria-label", label);
-    if (!tooltip) pauseBtn.title = label;
-    tooltipBinding?.sync();
-  };
-  syncPause();
-  const onPauseClick = () => {
-    rotating = !rotating;
-    viewer.setAutoRotate(rotating);
-    syncPause();
-    saveRotating(rotating);
-  };
-  pauseBtn?.addEventListener("click", onPauseClick);
-
   // Re-fit the camera to the current view.
   if (reframeBtn) {
     reframeBtn.setAttribute("aria-label", "Re-frame model");
@@ -63,7 +43,7 @@ export function attachViewerControls(
   reframeBtn?.addEventListener("click", onReframeClick);
 
   // Persist the camera when the user finishes an orbit/zoom, and right before a
-  // reload (captures the latest pose, including auto-rotation drift).
+  // reload (captures the latest pose).
   viewer.onCameraEnd(() => saveCamera(viewer.getCameraState()));
   const onPageHide = () => saveCamera(viewer.getCameraState());
   window.addEventListener("pagehide", onPageHide);
@@ -71,7 +51,6 @@ export function attachViewerControls(
   return {
     detach: () => {
       themeBtn?.removeEventListener("click", onThemeClick);
-      pauseBtn?.removeEventListener("click", onPauseClick);
       reframeBtn?.removeEventListener("click", onReframeClick);
       window.removeEventListener("pagehide", onPageHide);
       tooltipBinding?.detach();

package/src/framework/viewer-lighting.js

@@ -3,8 +3,15 @@ import * as THREE from "three";
 const KEY_COLOR = 0xffffff, KEY_INTENSITY = 1.45;
 const FILL_COLOR = 0xe5efff, FILL_INTENSITY = 0.65;
 
+// The persistent sky/ground ambient. Shared with the offscreen thumbnail path
+// (viewer.js renderMeshPayloads), which builds its own throwaway scene and so needs
+// the same hemisphere fill to avoid rendering faces outside the key/fill cones near-black.
+export function createHemisphereLight() {
+  return new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+}
+
 export function addViewerLights(scene) {
-  const hemisphere = new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+  const hemisphere = createHemisphereLight();
   const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
   key.position.set(8, 14, 10);
   const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);