partforge 0.41.0 → 0.44.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);
   };

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.js

@@ -5,6 +5,7 @@ import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
+import { createCameraTween } from "./camera-tween.js";
 import { addViewerLights, captureLightPoses, createCaptureLights } from "./viewer-lighting.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
@@ -113,8 +114,6 @@ export function createViewer(container, part) {
 
   const controls = new OrbitControls(camera, renderer.domElement);
   controls.enableDamping = true;
-  controls.autoRotate = true;
-  controls.autoRotateSpeed = 1.6;
 
   // --- lights + grid --------------------------------------------------------
   const liveLights = addViewerLights(scene);
@@ -214,6 +213,39 @@ export function createViewer(container, part) {
     cutaway.setSubpart(name, subMesh[name], subLines[name]);
   }
 
+  // --- animation hooks --------------------------------------------------------
+  // Frame listeners get dt (seconds, clamped so a background-tab return doesn't
+  // fast-forward playback) inside the render loop — so a parked viewer
+  // (setActive(false)) automatically halts playback too: no loop, no ticks.
+  const frameListeners = new Set();
+  function onFrame(cb) { frameListeners.add(cb); return () => frameListeners.delete(cb); }
+
+  const camTween = createCameraTween();
+  // Tween the orbit camera to a canonical angle, framed on what's visible now.
+  // Presentational only; a caller passing duration 0 gets a jump cut.
+  function tweenCameraTo(viewName, { duration = 0.6, onComplete } = {}) {
+    const box = getVisibleWorldBounds();
+    if (!box || box.isEmpty()) { onComplete?.(); return; }
+    const center = box.getCenter(new THREE.Vector3()).toArray();
+    const size = box.getSize(new THREE.Vector3());
+    // radius = full max extent (not half), matching frameTo's framing distance so a
+    // live camera cue doesn't land twice as close as the reframe button and crop the part.
+    const pose = cameraPoseForView(viewName, { center, radius: Math.max(size.x, size.y, size.z) || 12 });
+    camTween.start(
+      { position: camera.position.toArray(), target: controls.target.toArray() },
+      { position: pose.position, target: pose.target },
+      { duration, onComplete },
+    );
+  }
+  const cancelCameraTween = () => camTween.cancel();
+
+  // User grabbing the orbit cancels any cue tween (the user owns the camera) and
+  // tells subscribers (the animation driver disarms remaining cues).
+  const cameraStartListeners = new Set();
+  const onControlsStart = () => { camTween.cancel(); for (const cb of [...cameraStartListeners]) cb(); };
+  controls.addEventListener("start", onControlsStart);
+  function onCameraStart(cb) { cameraStartListeners.add(cb); return () => cameraStartListeners.delete(cb); }
+
   // Smooth shading within CREASE_ANGLE of a shared edge, hard edge past it — so the
   // round body and helical groove read smooth while bore rims, drum faces, and
   // groove walls stay crisp. Lower = more hard edges; raise toward Math.PI/3 for
@@ -330,18 +362,8 @@ export function createViewer(container, part) {
     frameTo(names.filter((n) => subMesh[n].visible && subCache[n]));
   }
 
-  let autoRotateRequested = true;
-  function syncAutoRotate() {
-    controls.autoRotate = autoRotateRequested && !cutaway.isEnabled;
-  }
-  function setAutoRotate(on) {
-    autoRotateRequested = !!on;
-    syncAutoRotate();
-  }
   function setCutawayEnabled(on) {
-    const changed = cutaway.setEnabled(on);
-    syncAutoRotate();
-    return changed;
+    return cutaway.setEnabled(on);
   }
 
   // Swap the scene background, grid, and edge-line colors for the given theme.
@@ -489,8 +511,19 @@ export function createViewer(container, part) {
   }
 
   // --- render loop ----------------------------------------------------------
-  function renderFrame() {
+  // The tween is applied after controls.update() so the cue wins the frame, and
+  // the frame listeners run before render so a playback frame draws its own pose.
+  let lastFrameTime = null;
+  function renderFrame(time) {
+    const dt = lastFrameTime == null ? 0 : Math.min(0.1, (time - lastFrameTime) / 1000);
+    lastFrameTime = time;
     controls.update();
+    const tw = camTween.update(dt);
+    if (tw) {
+      camera.position.fromArray(tw.position);
+      controls.target.fromArray(tw.target);
+    }
+    for (const cb of [...frameListeners]) cb(dt);
     if (cutaway.isEnabled) cutaway.updateForCamera();
     renderer.render(scene, camera);
     cutaway.renderOverlay(renderer, camera);
@@ -504,8 +537,8 @@ export function createViewer(container, part) {
   // that cannot do that — partforge-cloud's phone tab bar uses
   // `visibility: hidden`, because the canvas has to keep its size for build
   // screenshots — gets no such signal: the full-resolution MSAA drawing buffer
-  // stays resident and this loop keeps rendering an auto-rotating scene at
-  // 60fps behind an invisible pane. On an iPhone that is tens of megabytes and
+  // stays resident and this loop keeps rendering the scene at 60fps behind an
+  // invisible pane. On an iPhone that is tens of megabytes and
   // continuous GPU work nobody can see, so the host has to say so explicitly.
   //
   // Parking stops the loop and releases the drawing buffer. `setSize(1, 1,
@@ -530,6 +563,7 @@ export function createViewer(container, part) {
       return;
     }
     resize(); // rebuild the buffer at whatever size the container is now
+    lastFrameTime = null; // parked time is not elapsed time — no dt jump on unpark
     renderer.setAnimationLoop(renderFrame);
   }
 
@@ -595,6 +629,10 @@ export function createViewer(container, part) {
     // closure (and whatever it captured) alive.
     renderer.domElement.removeEventListener("webglcontextlost", onContextLostEvent);
     contextLostListeners.clear();
+    controls.removeEventListener("start", onControlsStart);
+    cameraStartListeners.clear();
+    frameListeners.clear();
+    camTween.cancel();
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
@@ -624,7 +662,10 @@ export function createViewer(container, part) {
     frame,
     captureCanonicalViews,
     captureCurrent,
-    setAutoRotate,
+    onFrame,
+    tweenCameraTo,
+    cancelCameraTween,
+    onCameraStart,
     setActive,
     onContextLost,
     setTheme,

package/src/hinged-box-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/hinged-box.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/index.js

@@ -3,4 +3,4 @@
 // must NOT be imported from a part's build functions — those run in a Web Worker.
 // Part build functions import geometry helpers from "partforge/geometry" instead.
 export { mount } from "./framework/index.js";
-export { viewSubParts } from "./framework/jobs.js";
+export { viewSubParts } from "./framework/part-model.js";

package/src/parts/hinged-box.js

@@ -0,0 +1,94 @@
+// Animation reference part — a box with a hinged lid. Worked example for
+// docs/AUTHORING-PARTS.md "Animations": pose-only animated params (lidAngle,
+// lidLift) driven through place(), an intro camera + markdown description on
+// `open`, a looping `cycle`, and a stepped `assemble` with per-step cameras.
+export default {
+  meta: { title: "Hinged Box", units: "mm" },
+  parameters: [
+    {
+      id: "box",
+      title: "Box",
+      description: "Outer dimensions of the base. The lid is a flat plate of the same wall thickness.",
+      advanced: [
+        { key: "width", label: "Width", unit: "mm", min: 20, max: 120, step: 1,
+          description: "Outer width (X)." },
+        { key: "depth", label: "Depth", unit: "mm", min: 20, max: 120, step: 1,
+          description: "Outer depth (Y). The hinge runs along the rear edge." },
+        { key: "height", label: "Height", unit: "mm", min: 10, max: 80, step: 1,
+          description: "Outer height of the base (Z)." },
+        { key: "wall", label: "Wall", unit: "mm", min: 1.2, max: 5, step: 0.2,
+          description: "Wall and lid thickness." },
+      ],
+    },
+    {
+      id: "pose",
+      title: "Pose",
+      description: "Presentation pose. The **Open lid** and **Assemble** animations drive these — both are pose-only, so animating them never rebuilds geometry.",
+      advanced: [
+        { key: "lidAngle", label: "Lid angle", unit: "°", min: 0, max: 110, step: 1,
+          description: "Hinge opening angle about the rear top edge." },
+        { key: "lidLift", label: "Lid lift", unit: "mm", min: 0, max: 60, step: 1,
+          description: "Assembly explode offset: raises the lid straight up off the hinge." },
+      ],
+    },
+  ],
+  defaults: { width: 60, depth: 40, height: 24, wall: 2, lidAngle: 0, lidLift: 0 },
+  parts: {
+    base: {
+      label: "Base",
+      views: ["box"],
+      export: { name: "base" },
+      build: (k, p) =>
+        k.box({ min: [0, 0, 0], max: [p.width, p.depth, p.height] })
+          .cut(k.box({ min: [p.wall, p.wall, p.wall], max: [p.width - p.wall, p.depth - p.wall, p.height + 1] })),
+    },
+    lid: {
+      label: "Lid",
+      views: ["box"],
+      export: { name: "lid" },
+      build: (k, p) => k.box({ min: [0, 0, p.height], max: [p.width, p.depth, p.height + p.wall] }),
+      // Display: swing about the hinge line (rear top edge, axis +X through
+      // [0, depth, height]; negative angle opens upward), then the assembly
+      // lift. Export: the lid prints flat beside the base. Both poses are
+      // rigid motions of the same solid, and neither reads `view` — the two
+      // invariants lint's place rules hold every part to.
+      place: (s, { purpose, p }) =>
+        purpose === "export"
+          ? s.translate([p.width + 10, 0, -p.height])
+          : s.rotate(-p.lidAngle, [0, p.depth, p.height], [1, 0, 0]).translate([0, 0, p.lidLift]),
+    },
+  },
+  views: { box: { label: "Box" } },
+  animations: {
+    open: {
+      label: "Open lid",
+      description: "Swings the lid to **110°** about the rear hinge line.\n\nPose-only: playback runs at frame rate with no geometry rebuild.",
+      camera: "front",
+      duration: 1.2,
+      tracks: { lidAngle: [[0, 0], [1, 110]] },
+    },
+    cycle: {
+      label: "Open / close",
+      duration: 2.4,
+      loop: true,
+      easing: "linear",
+      autoplay: true,
+      tracks: { lidAngle: [[0, 0], [0.5, 110], [1, 0]] },
+    },
+    assemble: {
+      label: "Assemble",
+      description: "How the parts come together: the lid drops onto the base, then swings open to check hinge clearance.",
+      steps: [
+        { label: "Lower the lid", camera: "left", duration: 1.0, tracks: { lidLift: [[0, 40], [1, 0]] } },
+        { label: "Open to check clearance", camera: "iso", duration: 1.0, tracks: { lidAngle: [[0, 0], [1, 110]] } },
+      ],
+    },
+  },
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      base: { bbox: "<=[200,200,200]" },
+      _view: { overlaps: 0 },
+    },
+  },
+};