partforge 0.158.0 → 0.159.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.158.0",
+  "version": "0.159.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/mount-preview.js

@@ -23,6 +23,13 @@
 // it, so a parked preview is a paused one. `handle.animation` is null once
 // disposed.
 //
+// A playing animation also gets a play/pause/replay button in #viewbar,
+// directly before the view style button (preview-play-button.js): Pause while
+// it plays (or tweens to its intro view), Play while paused, Replay once a
+// one-time animation has finished. No button under reduced motion, for a still
+// file, with `animate: false`, or for a host with no #viewbar; the host can
+// still drive `handle.animation` (state / pause / resume / replay) itself.
+//
 // The decoder loads on demand (it carries the
 // GLTFLoader and meshopt), so a bundle that never mounts a preview never ships it.
 // Hence `ready`. Every handle method is safe before it resolves.
@@ -36,6 +43,7 @@ import { createTooltipPresenter } from "./tooltip.js";
 import { isFaceAlignedState } from "./projection.js";
 import { ENVIRONMENTS } from "./materials/environments.js";
 import { createPreviewPlayer } from "./preview-player.js";
+import { attachPreviewPlayButton } from "./preview-play-button.js";
 
 function previewPart({ meshes, view, meta }) {
   return {
@@ -112,6 +120,10 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
       const own = player;
       cleanups.push(() => own.dispose());
       player.start();
+      if (!reducedMotion && toolbar) {
+        const playButton = attachPreviewPlayButton(own, { toolbar, before: viewStyle.element }, { tooltip });
+        cleanups.push(() => playButton.detach());
+      }
     }
   });
   ready.catch(() => {}); // the host awaits it; never an unhandled rejection
@@ -151,7 +163,7 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     getView: () => live?.view ?? null,
     // null before ready, for a still file, with animate: false, and once disposed.
     get animation() {
-      return player ? { state: player.state, pause: player.pause, resume: player.resume } : null;
+      return player ? { state: player.state, pause: player.pause, resume: player.resume, replay: player.replay } : null;
     },
     getViewerState,
     setViewerState(next) {

package/src/framework/param-deps.js

@@ -5,7 +5,9 @@ import { resolveDerivedAttributed } from "./derive.js";
 import { createProbeKernel } from "./geometry/probe.js";
 import { inView, placeOf } from "./sub-part-views.js";
 import { byteAwareReplacer } from "./geometry/solid-hash.js";
-import { viewSubParts } from "./part-model.js";
+import { viewSubParts, resolveParamsAttributed, recordedParams } from "./part-model.js";
+import { newReadSink, expandReads } from "./read-recorder.js";
+import { probeSubPartPose } from "./pose-probe-core.js";
 
 export const RELEVANT_ALL = Symbol("relevant-all");
 
@@ -77,10 +79,12 @@ export function subPartParamKeys(part, view, params, readsOf, name) {
   const rec = readsOf?.(name);
   if (rec) {
     // The worker records the BUILD's reads; the sub-part's own show/hide gate
-    // is added here, as the prediction rung does (subPartReadKeys runs enabled()).
+    // and its place() reads in this view are added here, as the prediction rung
+    // does (subPartReadKeys runs enabled() and place()).
     const out = new Set(rec);
     const sp = part.parts[name];
     if (sp?.enabled) sp.enabled(recorder(params, out));
+    for (const k of placeReadKeys(part, view, params, name)) out.add(k);
     return [...out].sort();
   }
   const reads = subPartReadKeys(part, view, params);
@@ -88,16 +92,53 @@ export function subPartParamKeys(part, view, params, readsOf, name) {
   return keys.sort();
 }
 
-// Panel relevance from RECORDED reads: the union over on-screen sub-parts (a
-// not-yet-built one contributes its prediction — display only, so a wrong guess
-// costs one build's dimming), plus the gate params of every in-view sub-part.
+// The params one sub-part's place() reads in THIS view, derive attribution
+// included. A canonical delivery (jobs.js displayWithReads) is stamped with its
+// BUILD reads alone — the pose is applied as a matrix, and the pose fast path
+// needs a build-only stamp — so a param read only in place() (an explode slider
+// feeding views.cutaway) never reaches the recorded rung. The display side adds
+// it back here, per view: a view whose place() never reads the param leaves it
+// irrelevant. Runs place() on the geometry-free canonical token (no build); the
+// reads count whether or not the probe trusts the pose — they were read either
+// way. Never throws; an unreadable place() contributes nothing (a posed delivery
+// already recorded its place reads in the stamp). `resolved` lets a caller
+// walking many sub-parts run derive() once (a resolveParamsAttributed result).
+export function placeReadKeys(part, view, params, name, resolved) {
+  const sp = part.parts[name];
+  if (!sp || !placeOf(sp)) return [];
+  try {
+    resolved ??= resolveParamsAttributed(part, params);
+    const sink = newReadSink();
+    sink.attribution = resolved.attribution;
+    const rec = recordedParams(resolved, sink);
+    probeSubPartPose(sp, { view, purpose: "display", p: rec.p, d: rec.d }, { scope: "place" });
+    return expandReads(sink);
+  } catch {
+    return [];
+  }
+}
+
+// Panel relevance from RECORDED reads: the union over on-screen sub-parts, each
+// with its place() reads in this view (a not-yet-built one contributes its
+// prediction — display only, so a wrong guess costs one build's dimming), plus
+// the gate params of every in-view sub-part.
 export function recordedRelevantKeys(part, view, params, readsOf) {
   try {
     const relevant = new Set();
     let predicted = null;
+    let resolved = null;
     for (const name of viewSubParts(part, view, params)) {
       const rec = readsOf(name);
-      if (rec) { for (const k of rec) relevant.add(k); continue; }
+      if (rec) {
+        for (const k of rec) relevant.add(k);
+        // derive() once per call, and only if some sub-part has a pose to read.
+        // A throwing derive() costs only the place reads, never the recorded ones.
+        if (resolved === null && placeOf(part.parts[name])) {
+          try { resolved = resolveParamsAttributed(part, params); } catch { resolved = false; }
+        }
+        if (resolved) for (const k of placeReadKeys(part, view, params, name, resolved)) relevant.add(k);
+        continue;
+      }
       predicted ??= subPartReadKeys(part, view, params);
       if (predicted === RELEVANT_ALL) return RELEVANT_ALL;
       for (const k of predicted.get(name) ?? []) relevant.add(k);

package/src/framework/preview-play-button.js

@@ -0,0 +1,76 @@
+// The preview's play/pause/replay button (mount-preview.js): lets a visitor stop
+// a cached preview's baked autoplay animation while they read the page. A plain
+// `#viewbar button`, inserted directly before the view style button (#view-style,
+// after its divider), so it inherits the toolbar's sizing and hover styles.
+//
+// Three states, read off the player's onChange notifications (never polled):
+//   - Pause  while playing or during the intro camera tween;
+//   - Play   while paused — resumes from the pose it froze at;
+//   - Replay once a one-time animation has finished at its end pose — plays it
+//            again from the start, camera cues included. A looping animation
+//            never gets here.
+// The label (aria-label, and the tooltip, which reads it each time it shows)
+// names what a click does and so carries the state; there is deliberately no
+// aria-pressed (WAI-ARIA: a toggle whose label changes must not also report a
+// pressed state). A label change hides a tooltip that is showing, so it never
+// reads the old action; it comes back with the new text on the next hover.
+//
+// Made only for a player that plays: mount-preview never creates it under
+// reduced motion (the player never starts), for a still file, with
+// animate: false, or for a host with no #viewbar. Nothing is remembered: a
+// remount starts fresh.
+import { attachButtonTooltips } from "./tooltip.js";
+
+const svg = (body) => `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+// lucide "pause", "play" and "rotate-ccw".
+const STATES = {
+  pause: { label: "Pause animation", icon: svg(`<rect x="14" y="4" width="4" height="16" rx="1"/><rect x="6" y="4" width="4" height="16" rx="1"/>`) },
+  play: { label: "Play animation", icon: svg(`<polygon points="6 3 20 12 6 21 6 3"/>`) },
+  replay: { label: "Replay animation", icon: svg(`<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>`) },
+};
+
+// What a click does for a given player status.
+const actionFor = (status) => (status === "paused" ? "play" : status === "done" ? "replay" : "pause");
+
+export function attachPreviewPlayButton(player, { toolbar, before = null }, { tooltip = null } = {}) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.id = "pf-preview-play";
+  button.className = "pf-preview-play-button";
+  let action = null;
+  let tooltipBinding = null;
+
+  function render(status) {
+    const next = actionFor(status);
+    if (next === action) return;
+    action = next;
+    const { label, icon } = STATES[next];
+    button.innerHTML = icon;
+    button.setAttribute("aria-label", label);
+    if (!tooltip) button.title = label;
+    tooltipBinding?.hide(); // a showing tooltip still names the old action
+  }
+  render(player.state().status);
+
+  const anchor = before && before.parentElement === toolbar ? before : [...toolbar.children].find((c) => c.id === "theme") ?? null;
+  toolbar.insertBefore(button, anchor);
+  tooltipBinding = tooltip ? attachButtonTooltips(tooltip, [{ element: button }]) : null;
+
+  const onClick = () => {
+    if (action === "pause") player.pause();
+    else if (action === "play") player.resume();
+    else player.replay();
+  };
+  button.addEventListener("click", onClick);
+  const off = player.onChange((s) => render(s.status));
+
+  return {
+    element: button,
+    detach() {
+      off();
+      button.removeEventListener("click", onClick);
+      tooltipBinding?.detach();
+      button.remove();
+    },
+  };
+}

package/src/framework/preview-player.js

@@ -18,6 +18,14 @@
 //    opacity, no ground hold, no cue — so the visitor sees exactly what the
 //    file draws without a player (the opening pose, every sub-part opaque; an
 //    opacity fade-in must not leave a sub-part hidden for good).
+//
+// A host can pause, resume and — once a one-time animation has finished —
+// replay it (the preview's play/pause button, preview-play-button.js). Pause
+// stops any camera move where it is (viewer.cancelCameraTween, as the live
+// driver does): a cancelled tween never fires its onComplete, and createPlayback
+// re-honors an abandoned intro or sweep on the next play(). An orbit while
+// paused stays paused. onChange(cb) reports every status change, so a control
+// never polls.
 import { createPlayback } from "./animation.js";
 import { invertRigid, mulMat4 } from "./geometry/pose.js";
 
@@ -99,6 +107,21 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
   const restInverse = Object.fromEntries(Object.keys(tracks).map((name) => [name, invertRigid(rest[name])]));
 
   let offFrame = null, offOrbit = null, started = false, disposed = false;
+  const listeners = new Set();
+  let lastStatus = playback.state().status;
+
+  function snapshotState() {
+    const { status, t } = playback.state();
+    return { status, t };
+  }
+  function notify() {
+    const now = snapshotState();
+    if (now.status === lastStatus) return;
+    lastStatus = now.status;
+    for (const cb of [...listeners]) {
+      try { cb(now); } catch (error) { console.warn("partforge: preview animation listener failed", error); }
+    }
+  }
 
   function apply(t) {
     const seconds = t * duration;
@@ -111,7 +134,7 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
     if (snap.status !== "intro" || !snap.cue) return;
     viewer.tweenCameraTo(snap.cue.view, {
       duration: INTRO_TWEEN_SECONDS,
-      onComplete: () => { if (!disposed) playback.introDone(); },
+      onComplete: () => { if (!disposed) { playback.introDone(); notify(); } },
     });
   }
 
@@ -120,11 +143,12 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
     if (!snap) return; // not playing: intro, paused, or done — the last poses stand
     apply(snap.t);
     if (snap.cue) viewer.tweenCameraTo(snap.cue.view, { duration: snap.cue.sweep ?? INTRO_TWEEN_SECONDS });
+    notify();
   }
 
   function onOrbit() {
     playback.disarmCues();
-    if (playback.state().status === "intro") playback.introDone();
+    if (playback.state().status === "intro") { playback.introDone(); notify(); }
   }
 
   return {
@@ -137,25 +161,44 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
       offFrame = viewer.onFrame(onFrame);
       offOrbit = viewer.onCameraStart(onOrbit);
       honorIntro(playback.play());
+      notify();
     },
     pause() {
-      if (!disposed) playback.pause();
+      if (disposed || !offFrame) return;
+      const { status } = playback.state();
+      if (status !== "playing" && status !== "intro") return;
+      viewer.cancelCameraTween(); // an intro tween or a cue's sweep stops where it is
+      playback.pause();
+      notify();
     },
     resume() {
       if (disposed || playback.state().status !== "paused") return;
       honorIntro(playback.play());
+      notify();
+    },
+    // From `done` only (a one-time animation resting at its end pose): play it
+    // again exactly as on arrival — t = 0 pose and opacity first, then the
+    // re-armed intro cue (createPlayback's play() from done resets t and cues).
+    replay() {
+      if (disposed || playback.state().status !== "done") return;
+      apply(0);
+      honorIntro(playback.play());
+      notify();
+    },
+    onChange(cb) {
+      if (disposed) return () => {};
+      listeners.add(cb);
+      return () => listeners.delete(cb);
     },
     dispose() {
       if (disposed) return;
       disposed = true;
+      listeners.clear();
       if (!offFrame) return; // never played (not started, or reduced motion): nothing to undo
       offFrame(); offOrbit();
       offFrame = offOrbit = null;
       viewer.holdGround(false);
     },
-    state() {
-      const { status, t } = playback.state();
-      return { status, t };
-    },
+    state: snapshotState,
   };
 }

package/types/index.d.ts

@@ -809,6 +809,8 @@ export interface PreviewRuntime {
     state(): { status: "idle" | "intro" | "playing" | "paused" | "done"; t: number };
     pause(): void;
     resume(): void;
+    /** Play a finished one-time animation again from the start (its camera cues included); a no-op unless `state().status` is `"done"`. */
+    replay(): void;
   } | null;
   renderMode: {
     get(): RenderMode;