partforge 0.41.0 → 0.44.0

package/src/framework/animation-controls.js

@@ -0,0 +1,243 @@
+// Transport bar + playback driver for part-declared animations. The bar is
+// framework-generated DOM appended to the stage (no host markup needed, like
+// the debug overlay); the driver ticks the pure playback state machine
+// (animation.js) from the viewer's frame loop and routes every param write
+// through the mount-supplied applyValues hook — the same path as a slider
+// edit, minus the regen debounce. Returns null when the part declares no
+// (valid) animations, so mount can wire it unconditionally.
+import { normalizeAnimations, createPlayback } from "./animation.js";
+import { createInfoPopover, attachInfo } from "./controls.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+function btn(className, text, label) {
+  const b = el("button", className, text);
+  b.type = "button";
+  b.setAttribute("aria-label", label);
+  b.title = label;
+  return b;
+}
+
+export function attachAnimationControls(viewer, part, { container, applyValues, getParamValues }) {
+  // A malformed animations block must degrade to "no transport bar", never a
+  // crashed mount — lint reports the specifics; the viewer just goes without.
+  let animations;
+  try { animations = normalizeAnimations(part); } catch { animations = []; }
+  if (!animations.length) return null;
+
+  const reducedMotion = typeof matchMedia === "function"
+    && matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const tweenDuration = reducedMotion ? 0 : 0.6; // reduced motion: jump cut, no sweep
+
+  let current = animations[0];
+  let playback = createPlayback(current);
+  let snapshot = null; // tracked-param values before this animation first drove them
+
+  // Autoplay: at most one animation declares it (lint-enforced). Armed until
+  // the user manually touches the transport — and never armed at all under
+  // prefers-reduced-motion: self-starting motion is exactly what that setting
+  // opts out of. The transport still plays everything on request.
+  const autoplayAnim = animations.find((a) => a.autoplay) ?? null;
+  let autoplayArmed = !!autoplayAnim && !reducedMotion;
+  const disarmAutoplay = () => { autoplayArmed = false; };
+
+  // --- DOM --------------------------------------------------------------------
+  const bar = el("div", "pf-anim-bar");
+  const info = createInfoPopover();
+
+  const pick = document.createElement("select");
+  pick.className = "pf-anim-pick";
+  pick.setAttribute("aria-label", "Choose animation");
+  for (const a of animations) {
+    const o = document.createElement("option");
+    o.value = a.name; o.textContent = a.label;
+    pick.append(o);
+  }
+  const title = el("span", "pf-anim-title", "");
+  bar.append(animations.length > 1 ? pick : title);
+  const infoSlot = el("span", "pf-anim-info");
+  const playBtn = btn("pf-anim-play", "▶", "Play animation");
+  const prevBtn = btn("pf-anim-step-btn", "‹", "Previous step");
+  const stepLabel = el("span", "pf-anim-step", "");
+  const nextBtn = btn("pf-anim-step-btn", "›", "Next step");
+  const scrubWrap = el("span", "pf-anim-scrub-wrap");
+  const scrub = document.createElement("input");
+  scrub.type = "range";
+  scrub.min = "0"; scrub.max = "1000"; scrub.step = "1"; scrub.value = "0";
+  scrub.className = "pf-anim-scrub";
+  scrub.setAttribute("aria-label", "Animation position");
+  scrubWrap.append(scrub);
+  const resetBtn = btn("pf-anim-reset", "↺", "Reset animation");
+  bar.append(infoSlot, playBtn, prevBtn, stepLabel, nextBtn, scrubWrap, resetBtn);
+  container.append(bar);
+
+  // Per-animation chrome: title, ⓘ description, step buttons, scrubber ticks.
+  function syncStructure() {
+    title.textContent = current.label;
+    infoSlot.replaceChildren();
+    attachInfo(infoSlot, current.description ?? "", info);
+    const stepped = current.steps.length > 1;
+    prevBtn.hidden = nextBtn.hidden = stepLabel.hidden = !stepped;
+    for (const n of scrubWrap.querySelectorAll(".pf-anim-tick")) n.remove();
+    if (stepped) {
+      for (const t of current.stepStarts.slice(1)) {
+        const tick = el("span", "pf-anim-tick");
+        tick.style.left = `${t * 100}%`;
+        scrubWrap.append(tick);
+      }
+    }
+  }
+
+  function syncUi() {
+    const { status, t, stepIndex } = playback.state();
+    const active = status === "playing" || status === "intro";
+    playBtn.textContent = active ? "⏸" : "▶";
+    playBtn.setAttribute("aria-label", active ? "Pause animation" : "Play animation");
+    playBtn.title = playBtn.getAttribute("aria-label");
+    scrub.value = String(Math.round(t * 1000));
+    if (current.steps.length > 1) {
+      const step = current.steps[stepIndex];
+      stepLabel.textContent = `${stepIndex + 1}/${current.steps.length} · ${step.label}`;
+    }
+  }
+
+  // --- driver -----------------------------------------------------------------
+  // A frame that throws — a malformed cue or track that slipped past lint, a
+  // viewer that rejects a view name — must cost that frame, not the render
+  // loop: this callback runs from the viewer's frame listeners, and letting it
+  // propagate would take the other listeners down with it. Warn once, then
+  // stay quiet so a bad frame can't flood the console 60x a second.
+  let frameFailureWarned = false;
+  function apply(r) {
+    if (!r) return;
+    try {
+      // First write for this run: remember what the user's params were, so Reset
+      // can put them back.
+      if (snapshot == null && Object.keys(r.values).length) snapshot = getParamValues(current.trackedKeys);
+      applyValues(r.values);
+      if (r.cue) {
+        viewer.tweenCameraTo(r.cue.view, {
+          duration: tweenDuration,
+          // An intro cue gates playback until the tween settles; mid-timeline
+          // cues overlap playback and need no completion signal.
+          onComplete: r.status === "intro" ? () => apply(playback.introDone()) : undefined,
+        });
+      }
+      syncUi();
+    } catch (err) {
+      if (!frameFailureWarned) {
+        frameFailureWarned = true;
+        console.warn("partforge: animation frame failed", err);
+      }
+    }
+  }
+
+  function doReset() {
+    playback.reset();
+    viewer.cancelCameraTween();
+    if (snapshot) { applyValues(snapshot); snapshot = null; }
+    syncUi();
+  }
+
+  function selectAnimation(name) {
+    const next = animations.find((a) => a.name === name);
+    if (!next || next === current) return;
+    doReset();
+    current = next;
+    playback = createPlayback(current);
+    if (animations.length > 1) pick.value = name;
+    syncStructure();
+    syncUi();
+  }
+
+  const offFrame = viewer.onFrame((dt) => apply(playback.tick(dt)));
+  // User orbit: the viewer has already cancelled any cue tween (its own
+  // "start" handler); disarm the remaining cues, and if an intro tween was
+  // gating playback, settle the gate — cancel() never fires onComplete, so
+  // without this the machine would sit in "intro" forever.
+  const offOrbit = viewer.onCameraStart(() => {
+    playback.disarmCues();
+    if (playback.state().status === "intro") apply(playback.introDone());
+  });
+
+  const onPlayClick = () => {
+    disarmAutoplay();
+    const active = playback.state().status;
+    if (active === "playing" || active === "intro") {
+      viewer.cancelCameraTween();
+      apply(playback.pause());
+    } else {
+      apply(playback.play());
+    }
+  };
+  const onScrub = () => { disarmAutoplay(); apply(playback.seek(Number(scrub.value) / 1000)); };
+  const onPrev = () => { disarmAutoplay(); apply(playback.stepPrev()); };
+  const onNext = () => { disarmAutoplay(); apply(playback.stepNext()); };
+  const onPick = () => { disarmAutoplay(); selectAnimation(pick.value); };
+  const onResetClick = () => { disarmAutoplay(); doReset(); };
+  playBtn.addEventListener("click", onPlayClick);
+  scrub.addEventListener("input", onScrub);
+  prevBtn.addEventListener("click", onPrev);
+  nextBtn.addEventListener("click", onNext);
+  pick.addEventListener("change", onPick);
+  resetBtn.addEventListener("click", onResetClick);
+
+  syncStructure();
+  syncUi();
+
+  const runtime = {
+    // An unknown name is a host bug, not a request to play whatever happens to
+    // be selected — say so and do nothing rather than silently animating
+    // something else.
+    play(name) {
+      disarmAutoplay();
+      if (name != null && !animations.some((a) => a.name === name)) {
+        console.warn(`partforge: unknown animation "${name}"`);
+        return;
+      }
+      if (name) selectAnimation(name);
+      apply(playback.play());
+    },
+    pause() { disarmAutoplay(); viewer.cancelCameraTween(); apply(playback.pause()); },
+    seek(t) { disarmAutoplay(); apply(playback.seek(t)); },
+    stop() { disarmAutoplay(); doReset(); },
+    state: () => ({ animation: current.name, ...playback.state() }),
+  };
+
+  const handle = {
+    runtime,
+    // A user edit to any control (or a host setParams) takes over the params:
+    // pause playback rather than fight over them.
+    notifyUserEdit() {
+      disarmAutoplay();
+      viewer.cancelCameraTween();
+      playback.userEdited();
+      syncUi();
+    },
+    // Mount calls this on first ready and on every view/tab switch.
+    autoplayKick() {
+      if (!autoplayArmed || !autoplayAnim) return;
+      if (current !== autoplayAnim) selectAnimation(autoplayAnim.name);
+      const { status } = playback.state();
+      if (status !== "playing" && status !== "intro") apply(playback.play());
+    },
+    detach() {
+      offFrame();
+      offOrbit();
+      playBtn.removeEventListener("click", onPlayClick);
+      scrub.removeEventListener("input", onScrub);
+      prevBtn.removeEventListener("click", onPrev);
+      nextBtn.removeEventListener("click", onNext);
+      pick.removeEventListener("change", onPick);
+      resetBtn.removeEventListener("click", onResetClick);
+      info.dispose();
+      bar.remove();
+    },
+    __viewer: viewer, // test hook only
+  };
+  return handle;
+}

package/src/framework/animation.js

@@ -0,0 +1,217 @@
+// Timeline model + playback state machine for part-declared animations
+// (spec: docs/superpowers/specs/2026-08-02-model-animation-design.md).
+// Pure and import-free on purpose: no DOM, no clock, no three — the driver
+// (animation-controls.js) owns time and the viewer owns rendering, and both
+// partforge/lint and the Node CLI import this module, so it must satisfy the
+// lint purity guarantee (test/lint-purity.test.js).
+
+export const EASINGS = {
+  linear: (t) => t,
+  "ease-in": (t) => t * t,
+  "ease-out": (t) => 1 - (1 - t) * (1 - t),
+  "ease-in-out": (t) => t * t * (3 - 2 * t),
+};
+export const DEFAULT_EASING = "ease-in-out";
+
+// Normalize one animations-map entry to the canonical shape every consumer
+// (playback, transport UI, lint, CLI) works against: a step list (a bare
+// `tracks` form becomes one anonymous step), normalized step starts, and the
+// camera declaration desugared to a sorted cue list. Assumes lint-valid input;
+// runtime callers guard with try/catch (see attachAnimationControls).
+export function normalizeAnimation(name, spec) {
+  const steps = spec.steps
+    ? spec.steps.map((s, i) => ({
+        label: s.label ?? `Step ${i + 1}`,
+        duration: s.duration,
+        easing: s.easing ?? spec.easing ?? DEFAULT_EASING,
+        tracks: s.tracks ?? {},
+        camera: s.camera ?? null,
+      }))
+    : [{
+        label: null, duration: spec.duration,
+        easing: spec.easing ?? DEFAULT_EASING,
+        tracks: spec.tracks ?? {}, camera: null,
+      }];
+  const totalDuration = steps.reduce((sum, s) => sum + s.duration, 0) || 1;
+  let acc = 0;
+  const stepStarts = steps.map((s) => { const t = acc / totalDuration; acc += s.duration; return t; });
+  let cues;
+  if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera }];
+  else if (Array.isArray(spec.camera)) cues = spec.camera.map(([t, view]) => ({ t, view }));
+  else cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera }] : []));
+  const trackedKeys = [...new Set(steps.flatMap((s) => Object.keys(s.tracks)))];
+  return {
+    name, label: spec.label ?? name, description: spec.description ?? null,
+    loop: !!spec.loop, autoplay: !!spec.autoplay, steps, stepStarts, totalDuration, cues, trackedKeys,
+  };
+}
+
+export function normalizeAnimations(part) {
+  return Object.entries(part?.animations ?? {}).map(([name, spec]) => normalizeAnimation(name, spec));
+}
+
+// Step containing t. Boundaries belong to the LATER step, and t clamps to [0,1].
+export function stepIndexAt(anim, t) {
+  const tc = Math.min(1, Math.max(0, t));
+  let idx = 0;
+  for (let i = 0; i < anim.stepStarts.length; i++) if (tc >= anim.stepStarts[i]) idx = i;
+  return idx;
+}
+
+// Most recent cue at or before t, or null. This is both the CLI's default
+// camera for a still and the cue play() honors when starting mid-timeline.
+export function cueAt(anim, t) {
+  let g = null;
+  for (const c of anim.cues) if (c.t <= t) g = c;
+  return g;
+}
+
+// The timeline segments (global [start,end] spans) in which `key` is tracked.
+function segmentsFor(anim, key) {
+  const out = [];
+  anim.steps.forEach((step, i) => {
+    const kf = step.tracks[key];
+    if (!kf) return;
+    const start = anim.stepStarts[i];
+    const end = i + 1 < anim.steps.length ? anim.stepStarts[i + 1] : 1;
+    out.push({ start, end, keyframes: kf, easing: step.easing });
+  });
+  return out;
+}
+
+// Piecewise-linear keyframe interpolation at (already-eased) local time u.
+function interpKeyframes(kf, u) {
+  if (u <= kf[0][0]) return kf[0][1];
+  for (let i = 1; i < kf.length; i++) {
+    const [t1, v1] = kf[i];
+    if (u <= t1) {
+      const [t0, v0] = kf[i - 1];
+      return t1 === t0 ? v1 : v0 + (v1 - v0) * ((u - t0) / (t1 - t0));
+    }
+  }
+  return kf[kf.length - 1][1];
+}
+
+function evaluateTrack(anim, key, t) {
+  const segs = segmentsFor(anim, key);
+  let prev = null;
+  for (const seg of segs) {
+    if (t < seg.start) break;
+    if (t <= seg.end) {
+      const span = seg.end - seg.start || 1;
+      const local = (EASINGS[seg.easing] ?? EASINGS[DEFAULT_EASING])((t - seg.start) / span);
+      return interpKeyframes(seg.keyframes, local);
+    }
+    prev = seg;
+  }
+  // Outside every segment: hold the nearest boundary value, so a param tracked
+  // only in step 2 doesn't jump while step 1 plays.
+  return prev ? prev.keyframes[prev.keyframes.length - 1][1] : segs[0].keyframes[0][1];
+}
+
+// Evaluate the whole animation at normalized position t ∈ [0,1] (over the
+// TOTAL duration — the same t the scrubber, seek(t), and the CLI's --at use).
+export function evaluate(anim, t) {
+  const tc = Math.min(1, Math.max(0, t));
+  const values = {};
+  for (const key of anim.trackedKeys) values[key] = evaluateTrack(anim, key, tc);
+  return { stepIndex: stepIndexAt(anim, tc), values };
+}
+
+// --- playback state machine --------------------------------------------------
+// Owns WHAT the animation is doing (position, status, cue arming); the driver
+// owns WHEN (it feeds dt from the viewer's frame loop) and WHERE the results
+// go (params + camera tweens). Statuses: idle → intro (a governing camera cue
+// is tweening; params hold) → playing → paused/done. "intro" is entered on any
+// play() with an armed, unfired cue at-or-before the current position — that
+// covers both the t=0 intro and play-from-the-middle honoring the governing
+// cue. Cues crossed DURING playback fire without gating (overlapping tween).
+export function createPlayback(anim) {
+  let status = "idle";
+  let t = 0;
+  let armed = true;       // user orbit disarms cues until reset/replay
+  let firedCueT = -1;     // cues with t <= firedCueT already fired this run
+  let stopAt = null;      // stepNext/playStep pause playback on reaching this t
+
+  const snapshot = (cue = null) => ({ t, status, ...evaluate(anim, t), cue });
+
+  const governingCue = () => {
+    if (!armed) return null;
+    let g = null;
+    for (const c of anim.cues) if (c.t <= t && c.t > firedCueT) g = c;
+    return g;
+  };
+
+  function begin() {
+    const cue = governingCue();
+    if (cue) { firedCueT = Math.max(firedCueT, cue.t); status = "intro"; }
+    else status = "playing";
+    return snapshot(cue);
+  }
+
+  function play() {
+    if (status === "playing" || status === "intro") return snapshot();
+    if (t >= 1 && !anim.loop) { t = 0; firedCueT = -1; armed = true; } // replay from start re-arms
+    stopAt = null;
+    return begin();
+  }
+  function pause() {
+    if (status === "playing" || status === "intro") status = "paused";
+    return snapshot();
+  }
+  function introDone() {
+    if (status === "intro") status = "playing";
+    return snapshot();
+  }
+  function seek(v) {
+    t = Math.min(1, Math.max(0, v));
+    status = "paused";
+    stopAt = null;
+    firedCueT = -1; // a later play() re-honors the cue governing the new position
+    return snapshot();
+  }
+  function playStep(i) {
+    const idx = Math.min(anim.steps.length - 1, Math.max(0, i));
+    t = anim.stepStarts[idx];
+    stopAt = idx + 1 < anim.steps.length ? anim.stepStarts[idx + 1] : 1;
+    firedCueT = -1;
+    return begin();
+  }
+  function stepNext() {
+    const cur = stepIndexAt(anim, t);
+    return cur + 1 < anim.steps.length ? playStep(cur + 1) : snapshot();
+  }
+  function stepPrev() {
+    return playStep(Math.max(0, stepIndexAt(anim, t) - 1));
+  }
+  function reset() {
+    t = 0; status = "idle"; stopAt = null; firedCueT = -1; armed = true;
+    return snapshot();
+  }
+  function disarmCues() { armed = false; }
+  function userEdited() { if (status === "playing" || status === "intro") status = "paused"; }
+
+  function tick(dt) {
+    if (status !== "playing" || !(dt > 0)) return null;
+    t += dt / anim.totalDuration;
+    if (anim.loop) {
+      if (t >= 1) t -= Math.floor(t);
+    } else if (stopAt != null && t >= stopAt) {
+      t = stopAt; stopAt = null; status = "paused";
+    } else if (t >= 1) {
+      t = 1; status = "done";
+    }
+    let cue = null;
+    if (armed) {
+      for (const c of anim.cues) if (c.t <= t && c.t > firedCueT) cue = c;
+      if (cue) firedCueT = cue.t;
+    }
+    return snapshot(cue);
+  }
+
+  return {
+    play, pause, toggle: () => (status === "playing" || status === "intro" ? pause() : play()),
+    introDone, seek, stepNext, stepPrev, playStep, reset, disarmCues, userEdited, tick,
+    state: () => ({ status, t, stepIndex: stepIndexAt(anim, t) }),
+  };
+}

package/src/framework/app.css

@@ -217,6 +217,38 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   #viewbar .pf-cutaway-actions button { min-width: 44px; padding: 0 6px; }
 }
 
+/* animation transport bar (placement: chrome.css's .pf-anim-bar). APPEARANCE
+   is ungated for the same reason as #viewbar above. */
+.pf-anim-bar {
+  display: flex; align-items: center; gap: 8px;
+  padding: 6px 10px;
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control); box-shadow: var(--pf-shadow-float);
+}
+.pf-anim-bar button {
+  border: 0; background: transparent; color: var(--pf-muted);
+  cursor: pointer; font-size: 13px; padding: 2px 4px;
+}
+.pf-anim-bar button:hover { color: var(--pf-text-2); }
+.pf-anim-title, .pf-anim-pick {
+  font-family: var(--pf-mono); font-size: 11px; color: var(--pf-text-2);
+}
+.pf-anim-pick {
+  background: var(--pf-input-bg); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control); padding: 3px 6px;
+}
+.pf-anim-step {
+  font-family: var(--pf-mono); font-size: 10px; color: var(--pf-muted-2);
+  min-width: 90px; text-align: center; white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.pf-anim-scrub-wrap { position: relative; display: inline-flex; align-items: center; width: 140px; }
+.pf-anim-scrub { width: 100%; accent-color: var(--pf-accent); }
+.pf-anim-tick {
+  position: absolute; top: 50%; width: 2px; height: 8px; margin-top: -4px;
+  background: var(--pf-muted); pointer-events: none;
+}
+
 /* Legacy id-only markup only: classed markup's viewbar lives inside .pf-stage
    (bottom-right, see chrome.css's .pf-float-viewbar) so it never meets the
    top-left floating #panel card. Legacy markup still floats #viewbar top-right

package/src/framework/assembly.js

@@ -1,4 +1,4 @@
-import { viewSubParts, resolveParams, buildPosed } from "./jobs.js";
+import { viewSubParts, resolveParams, buildPosed } from "./part-model.js";
 
 // Collision check for an assembled view: build each sub-part in its display
 // (assembly) pose and return the pairs whose solid-intersection volume exceeds

package/src/framework/backend-select.js

@@ -0,0 +1,25 @@
+// Chooses which geometry backend (manifold vs occt) a part should build against.
+// This is framework-level policy, not geometry-kernel plumbing: it knows the full
+// PartDefinition shape (meta.backend, defaults, parts[name].build), unlike
+// everything in geometry/, which is part-agnostic.
+import { OCCT_ONLY_OPS } from "./geometry/kernel.js";
+import { createProbeKernel } from "./geometry/probe.js";
+import { resolveDerived } from "./derive.js";
+
+const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
+
+export function detectBackend(part, params = {}) {
+  if (part.meta?.backend) return part.meta.backend;
+  const p = { ...part.defaults, ...params };
+  let d = {};
+  // A throwing derive must not escape here — this runs on the main thread mid
+  // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
+  // build hits the same throw and posts a proper error for the UI.
+  try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
+  const { kernel, used } = createProbeKernel();
+  for (const name of Object.keys(part.parts)) {
+    try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
+  }
+  for (const op of used) if (OCCT_ONLY.has(op)) return "occt";
+  return "manifold";
+}

package/src/framework/camera-tween.js

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+import { EASINGS } from "./animation.js";
+
+// Retargetable orbit-camera tween for animation camera cues: eased spherical
+// interpolation of {position, target} pairs about the (linearly moving) orbit
+// target, shortest-path in azimuth, clamped off the poles so OrbitControls
+// never gimbal-locks on a "top"/"bottom" cue. Pure math, no clock — the viewer
+// feeds dt seconds into update() each frame and applies the returned pose.
+const POLE_EPS = 0.01;
+
+function toSpherical(position, target) {
+  const off = new THREE.Vector3().fromArray(position).sub(new THREE.Vector3().fromArray(target));
+  const sph = new THREE.Spherical().setFromVector3(off);
+  sph.phi = Math.min(Math.PI - POLE_EPS, Math.max(POLE_EPS, sph.phi));
+  return sph;
+}
+
+export function createCameraTween() {
+  let tw = null; // { fromSph, toSph, fromTarget, toTarget, duration, elapsed, onComplete }
+
+  // `from` is always the CALLER's current pose, which is what makes a restart
+  // mid-flight retarget smoothly: the new tween begins wherever the camera is.
+  function start(from, to, { duration = 0.6, onComplete } = {}) {
+    const fromSph = toSpherical(from.position, from.target);
+    const toSph = toSpherical(to.position, to.target);
+    const d = toSph.theta - fromSph.theta;
+    if (d > Math.PI) toSph.theta -= 2 * Math.PI;
+    if (d < -Math.PI) toSph.theta += 2 * Math.PI;
+    tw = {
+      fromSph, toSph,
+      fromTarget: new THREE.Vector3().fromArray(from.target),
+      toTarget: new THREE.Vector3().fromArray(to.target),
+      duration, elapsed: 0, onComplete,
+    };
+  }
+
+  function update(dt) {
+    if (!tw) return null;
+    tw.elapsed += dt;
+    const done = tw.elapsed >= tw.duration;
+    const u = done ? 1 : EASINGS["ease-in-out"](tw.elapsed / tw.duration);
+    const lerp = (a, b) => a + (b - a) * u;
+    const sph = new THREE.Spherical(
+      lerp(tw.fromSph.radius, tw.toSph.radius),
+      lerp(tw.fromSph.phi, tw.toSph.phi),
+      lerp(tw.fromSph.theta, tw.toSph.theta),
+    );
+    const target = tw.fromTarget.clone().lerp(tw.toTarget, u);
+    const position = new THREE.Vector3().setFromSpherical(sph).add(target);
+    const onComplete = tw.onComplete;
+    if (done) tw = null;
+    const out = { position: position.toArray(), target: target.toArray(), done };
+    if (done) onComplete?.();
+    return out;
+  }
+
+  return { start, update, cancel: () => { tw = null; }, isActive: () => !!tw };
+}

package/src/framework/chrome.css

@@ -161,6 +161,14 @@
 .pf-float-tabs { top: 12px; left: 50%; transform: translateX(-50%); }
 .pf-float-viewbar { bottom: 12px; right: 12px; }
 
+/* --- animation transport bar (generated by animation-controls.js) ----------
+   PLACEMENT ONLY, per the rule above; appearance lives in app.css next to
+   #viewbar's, so a host that re-anchors this bar still inherits its chrome. */
+.pf-anim-bar {
+  position: absolute; left: 50%; bottom: 14px; transform: translateX(-50%);
+  z-index: 15; max-width: calc(100% - 24px);
+}
+
 /* ---- the narrow-layout tab bar ------------------------------------------
    Created by mobile-tabs.js (no host markup declares it). Hidden by default:
    below the breakpoint the rail sits beside the viewer and needs no tab, so
@@ -229,6 +237,14 @@
   }
   .pf-rail-seam { display: none; }
   .pf-tabbar { display: flex; }
+  /* Lift the transport bar clear of the viewbar. On a phone the bar is nearly
+     the full stage width (max-width: 100% - 24px) while #viewbar sits at the
+     bottom-right of the same stage, at the same z-index — so at bottom: 14px
+     the transport bar paints straight over cutaway/reframe/theme and
+     makes them unclickable. The viewbar occupies 12px…56px from the bottom
+     (12px offset + 4px padding + 34px button + 4px padding + 2px border);
+     64px clears it with an 8px gap. */
+  .pf-anim-bar { bottom: 64px; }
 }
 
 

package/src/framework/controls.js

@@ -48,10 +48,20 @@ export function clampToRange(raw, min, max) {
 }
 
 // --- info glyph + per-panel popover -----------------------------------------
+// Popover top edge: below the glyph when it fits, flipped above when the
+// viewport bottom would clip it (e.g. the animation transport bar's ⓘ, which
+// sits at the bottom of the stage). Pure, for direct unit testing — happy-dom
+// reports zero layout metrics, so the flip can't be exercised via the DOM.
+export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight }) {
+  const below = glyphBottom + 6;
+  if (below + popHeight <= viewportHeight - 8) return below;
+  return Math.max(8, glyphTop - 6 - popHeight);
+}
+
 // One popover element per panel, shared by all its glyphs (only one open at a
 // time). Document-level dismiss listeners are registered per panel and removed
 // by panel.dispose().
-function createInfoPopover() {
+export function createInfoPopover() {
   const pop = el("div", "popover");
   pop.hidden = true;
   document.body.append(pop);
@@ -78,7 +88,7 @@ function createInfoPopover() {
       owner = glyph;
       glyph.setAttribute("aria-expanded", "true");
       const r = glyph.getBoundingClientRect();
-      pop.style.top = `${r.bottom + 6}px`;
+      pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
       pop.style.left = `${Math.max(8, r.left - 8)}px`;
     },
     dispose() {
@@ -91,7 +101,7 @@ function createInfoPopover() {
 
 // Append a focusable ⓘ glyph to `container` that toggles the panel's shared
 // popover with `description` (Markdown). No-op when description is empty.
-function attachInfo(container, description, info) {
+export function attachInfo(container, description, info) {
   if (typeof description !== "string" || !description.trim()) return;
   const glyph = document.createElement("button");
   glyph.type = "button";