partforge 0.46.3 → 0.47.0

package/docs/AUTHORING-PARTS.md

@@ -132,9 +132,17 @@ export default {
 ## Animations
 
 A part may declare named animations — pure keyframe data that drives **existing
-params** over time. The viewer shows a transport bar (play/scrub/step); hosts
-drive the same engine via `runtime.animation`; `partforge render` can render
-stills at any position. The reference part is `src/parts/hinged-box.js`.
+params** over time. The viewer shows a transport bar (play/scrub, with ‹ ›
+pagers between animations); hosts drive the same engine via
+`runtime.animation`; `partforge render` can render stills at any position. The
+reference part is `src/parts/hinged-box.js`.
+
+Step labels surface on the scrubber rather than in a readout: hovering or
+dragging along the timeline names the chapter under the pointer, and with the
+scrubber focused **PageUp / PageDown jump whole chapters** (PageUp forward,
+matching the key's native slider direction). Screen readers get the same
+information from the scrubber's `aria-valuetext`, which reads
+`"<step label> — <percent>"`.
 
 ```js
 animations: {
@@ -149,7 +157,7 @@ animations: {
   },
   assemble: {
     label: "Assemble",
-    steps: [                  // steps play in order; prev/next navigate them
+    steps: [                  // steps play in order; named on the scrubber as you hover/drag
       { label: "Lower the lid", camera: "left", duration: 1.0,
         tracks: { lidLift: [[0, 40], [1, 0]] } },
       { label: "Open", camera: "iso", duration: 1.0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.46.3",
+  "version": "0.47.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/animation-controls.js

@@ -5,7 +5,7 @@
 // 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 { normalizeAnimations, createPlayback, stepIndexAt } from "./animation.js";
 import { createInfoPopover, attachInfo } from "./controls.js";
 
 function el(tag, className, text) {
@@ -14,14 +14,66 @@ function el(tag, className, text) {
   if (text != null) node.textContent = text;
   return node;
 }
+function setBtnLabel(b, label) {
+  b.setAttribute("aria-label", label);
+  b.title = label;
+}
 function btn(className, text, label) {
   const b = el("button", className, text);
   b.type = "button";
-  b.setAttribute("aria-label", label);
-  b.title = label;
+  setBtnLabel(b, label);
   return b;
 }
 
+// Where the transport bar may sit, given the stage width, the bar's natural
+// width, and the viewbar's left edge (all px, viewbarLeft stage-relative).
+// null → the CSS default (centered) already clears the viewbar. Otherwise
+// inline overrides: `left` slides the bar toward the stage's `margin`, and
+// when even that isn't enough, `maxWidth` caps the bar so the `gap` holds.
+export function planAnimBarPlacement({ stageWidth, barWidth, viewbarLeft }, { gap = 10, margin = 12 } = {}) {
+  const centeredLeft = (stageWidth - barWidth) / 2;
+  const limit = viewbarLeft - gap - barWidth;
+  if (centeredLeft <= limit) return null;
+  const left = Math.max(margin, limit);
+  const available = Math.max(0, viewbarLeft - gap - margin);
+  return barWidth > available ? { left, maxWidth: available } : { left };
+}
+
+// The scrubber's resolution: `t` is reported to the user as one of this many
+// steps, and read back the same way.
+export const SCRUB_STEPS = 1000;
+
+// Snap a seek target UP onto the scrubber's grid.
+//
+// syncUi rounds `t` onto that grid to position the thumb, but a chapter
+// boundary rarely lands on it: with three equal chapters, 1/3 rounds DOWN to
+// 0.333 — which is in the chapter BEFORE the one the playhead is really in. The
+// bar then reports a chapter it is not at, and the next arrow-key nudge reads
+// the rounded value back and "moves" the user a chapter without the position
+// changing. Rounding up keeps the grid value on the same side of the boundary
+// as `t`, so the playhead and what the scrubber shows always agree.
+//
+// A chapter shorter than one step can't be represented at all; nothing here can
+// fix that, and lint's minimum step duration keeps it out of reach.
+export function snapUpToScrubGrid(t) {
+  const stepped = Math.ceil(t * SCRUB_STEPS - 1e-9) / SCRUB_STEPS;
+  return Math.min(1, Math.max(0, stepped));
+}
+
+// "Close enough to a chapter's start to count as being ON it." One scrubber
+// step, for the same reason: finer than the grid is finer than anything the
+// user can see or land on.
+const AT_BOUNDARY = 1 / SCRUB_STEPS;
+
+// Center-x for the chapter bubble, in px within the scrub wrap: the bubble
+// tracks `fraction` along the timeline but never hangs past either end. A
+// wrap narrower than the bubble has no legal band — park it in the middle.
+export function clampBubbleX(fraction, wrapWidth, bubbleWidth) {
+  if (wrapWidth <= bubbleWidth) return wrapWidth / 2;
+  const half = bubbleWidth / 2;
+  return Math.min(Math.max(fraction * wrapWidth, half), wrapWidth - half);
+}
+
 // A setter for an element's text that MUTATES its existing text node instead of
 // replacing it. `el.textContent = x` always replaces the node, and WebKit will
 // not dispatch a `click` on an element whose text node was replaced between
@@ -76,30 +128,133 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     pick.append(o);
   }
   const title = el("span", "pf-anim-title", "");
-  bar.append(animations.length > 1 ? pick : title);
+  // Multi-animation parts page with ‹ › at the card's outer edges — whole
+  // animations only, never chapters (chapters are the bubble + PageUp/Down).
+  const paged = animations.length > 1;
+  const prevAnimBtn = paged ? btn("pf-anim-page", "‹", "Previous animation") : null;
+  const nextAnimBtn = paged ? btn("pf-anim-page", "›", "Next animation") : null;
+  if (prevAnimBtn) bar.append(prevAnimBtn);
+  bar.append(paged ? 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.min = "0"; scrub.max = String(SCRUB_STEPS); 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);
+  bar.append(infoSlot, playBtn, scrubWrap, resetBtn);
+  if (nextAnimBtn) bar.append(nextAnimBtn);
   container.append(bar);
+  // Chapter bubble: floats above the scrubber naming the chapter under the
+  // pointer (hover) or playhead (scrub).
+  //
+  // It is a child of the STAGE, not of the bar, for the same reason the ⓘ
+  // popover is a child of document.body: when the bar runs out of room it caps
+  // its width and sets overflow:hidden (see applyPlacement), and anything
+  // inside it is clipped — the bubble sits above the bar's content box, so it
+  // was clipped away entirely in exactly the narrow layouts where a shrunken
+  // timeline needs its labels most. Living on the stage puts it out of that
+  // clip, and out of the placement ResizeObserver's subtree as well.
+  //
+  // Non-interactive and aria-hidden: the accessible chapter channel is the
+  // scrubber's aria-valuetext, not this flag.
+  const chapterBubble = el("span", "pf-anim-chapter");
+  chapterBubble.setAttribute("aria-hidden", "true");
+  container.append(chapterBubble);
 
-  // Per-animation chrome: title, ⓘ description, step buttons, scrubber ticks.
+  // A reveal is either HOVER-owned or TRANSIENT. A hover reveal lives until the
+  // pointer leaves; a transient one (keyboard jump, scrub, touch) fades itself.
+  //
+  // `hoverInside` marks the pointer as the current owner, and while it is set a
+  // transient reveal deliberately arms no fade — a drag fires pointermove then
+  // an `input` on every step, so the transient timer would otherwise be the last
+  // one set and would blank the label under a finger that never left.
+  //
+  // Every path that hides the bubble clears the latch too, so it can never
+  // outlive the reveal it guards: an animation switch hides the bubble while the
+  // pointer sits still, and a gesture the browser steals for scrolling delivers
+  // pointercancel instead of pointerleave.
+  const BUBBLE_FADE_MS = 1000;
+  let bubbleFadeTimer = 0;
+  let hoverInside = false;
+  // The label's rendered width is re-measured only when the label itself
+  // changes: showChapterBubble runs on every pointermove, and offsetWidth
+  // forces a synchronous layout. Writing through textSetter keeps the text node
+  // stable per the WebKit rule above, rather than replacing it per move.
+  const setBubbleText = textSetter(chapterBubble);
+  let bubbleLabel = null;
+  let bubbleWidth = 0;
+  function showChapterBubble(fraction, { transient = false } = {}) {
+    if (current.steps.length <= 1) return;
+    const f = Math.min(1, Math.max(0, fraction));
+    const label = current.steps[stepIndexAt(current, f)].label;
+    if (label !== bubbleLabel) {
+      bubbleLabel = label;
+      setBubbleText(label);
+      bubbleWidth = chapterBubble.offsetWidth;
+    }
+    // Stage-relative, because the bubble lives on the stage rather than in the
+    // wrap: track the point along the timeline, then lift clear of the bar.
+    const wrapRect = scrubWrap.getBoundingClientRect();
+    const stageRect = container.getBoundingClientRect();
+    chapterBubble.style.left =
+      `${wrapRect.left - stageRect.left + clampBubbleX(f, wrapRect.width, bubbleWidth)}px`;
+    chapterBubble.style.bottom = `${stageRect.bottom - wrapRect.top + 8}px`;
+    chapterBubble.classList.add("pf-show");
+    clearTimeout(bubbleFadeTimer);
+    bubbleFadeTimer = 0;
+    if (transient && !hoverInside) bubbleFadeTimer = setTimeout(hideChapterBubble, BUBBLE_FADE_MS);
+  }
+  function fadeChapterBubble() {
+    if (!chapterBubble.classList.contains("pf-show")) return;
+    clearTimeout(bubbleFadeTimer);
+    bubbleFadeTimer = setTimeout(hideChapterBubble, BUBBLE_FADE_MS);
+  }
+  function hideChapterBubble() {
+    clearTimeout(bubbleFadeTimer);
+    bubbleFadeTimer = 0;
+    hoverInside = false;
+    chapterBubble.classList.remove("pf-show");
+  }
+  const onWrapPointerMove = (e) => {
+    if (current.steps.length <= 1) return; // no chapters: no bubble, and no layout read
+    const rect = scrubWrap.getBoundingClientRect();
+    if (!rect.width) return;
+    hoverInside = true;
+    showChapterBubble((e.clientX - rect.left) / rect.width);
+  };
+  // A touch pointer's leave arrives with the finger lift, so hiding outright
+  // would blank the label the tap just asked for — and touch has no hover to
+  // read it with afterwards. Let it fade like a keyboard reveal instead. A
+  // mouse leaving still hides at once: the pointer moving away IS the dismissal.
+  const onWrapPointerLeave = (e) => {
+    hoverInside = false;
+    if (e?.pointerType === "touch") fadeChapterBubble();
+    else hideChapterBubble();
+  };
+  scrubWrap.addEventListener("pointermove", onWrapPointerMove);
+  scrubWrap.addEventListener("pointerleave", onWrapPointerLeave);
+  scrubWrap.addEventListener("pointercancel", onWrapPointerLeave);
+
+  // Per-animation chrome: title, ⓘ description, pager labels, scrubber ticks.
   function syncStructure() {
     title.textContent = current.label;
+    hideChapterBubble();
+    if (paged) {
+      // Name the destination. Activating a pager keeps focus on it and leaves
+      // its glyph unchanged, so without this a screen reader re-announces the
+      // same generic "Next animation" and never says what is now selected.
+      const i = animations.indexOf(current);
+      const at = (d) => animations[(i + d + animations.length) % animations.length].label;
+      setBtnLabel(prevAnimBtn, `Previous animation: ${at(-1)}`);
+      setBtnLabel(nextAnimBtn, `Next animation: ${at(1)}`);
+    }
     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)) {
@@ -116,12 +271,13 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // 1. Text goes through textSetter (see above), so the button's text node is
   //    mutated and never replaced. This is the one that matters, because it
   //    holds even when the glyph legitimately changes under a held finger —
-  //    playback ending, or a step boundary crossing, mid-press.
+  //    playback ending mid-press.
   // 2. Each element has its own renderer that leaves early when its own value
-  //    is unchanged, so a playing transport does no DOM work per frame at all.
-  //    Per ELEMENT, not per write: driving several elements off one shared
-  //    state key means a step change also redraws the button, which was still
-  //    enough to lose the click before rule 1 was in place.
+  //    is unchanged, so a playing transport touches only what actually moved:
+  //    the scrubber's value, and aria-valuetext when it crosses a reporting
+  //    step. Per ELEMENT, not per write: driving several elements off one
+  //    shared state key means a step change also redraws the button, which was
+  //    still enough to lose the click before rule 1 was in place.
   //
   // Without rule 1 this cost the pause click outright: press, release, no click
   // event at all, and only ever while playing — the one moment the button is
@@ -129,9 +285,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // ~100ms; a synthetic 0ms one survives, which is why automated clicking never
   // saw it). Reset was never affected: nothing rewrites that button per frame.
   const setPlayGlyph = textSetter(playBtn);
-  const setStepText = textSetter(stepLabel);
   let shownActive = null;
-  let shownStep = null;
 
   function renderPlayButton(active) {
     if (active === shownActive) return;
@@ -142,26 +296,42 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     playBtn.title = label;
   }
 
-  function renderStepLabel(stepIndex) {
-    if (current.steps.length <= 1 || stepIndex === shownStep) return;
-    shownStep = stepIndex;
-    const step = current.steps[stepIndex];
-    setStepText(`${stepIndex + 1}/${current.steps.length} · ${step.label}`);
+  // aria-valuetext is the accessible chapter channel — the bubble is aria-hidden,
+  // so this is the only place the chapter name reaches assistive tech. An
+  // attribute write never eats clicks (see the WebKit note above), but a screen
+  // reader announces every CHANGE, and during playback the position moves on its
+  // own: an exact percentage would chatter ~100 times a run with the scrubber
+  // focused. So while playing the percentage is reported in 10% steps. A
+  // user-driven seek reports the exact position, which is when precision is the
+  // feedback the user asked for.
+  let shownValuetext = null;
+  function renderValuetext(t, stepIndex, playing) {
+    const pct = Math.round(t * 100);
+    const shown = playing ? Math.round(pct / 10) * 10 : pct;
+    const text = current.steps.length > 1
+      ? `${current.steps[stepIndex].label} — ${shown}%`
+      : `${shown}%`;
+    if (text === shownValuetext) return;
+    shownValuetext = text;
+    scrub.setAttribute("aria-valuetext", text);
   }
 
   function syncUi() {
     const { status, t, stepIndex } = playback.state();
-    // The scrubber is the one thing that genuinely moves every frame. Assigning
-    // `.value` updates a property rather than replacing a child node, so it
-    // costs no clicks — and it is not what anyone reaches for mid-playback.
-    scrub.value = String(Math.round(t * 1000));
-    renderPlayButton(status === "playing" || status === "intro");
-    renderStepLabel(stepIndex);
+    const playing = status === "playing" || status === "intro";
+    scrub.value = String(Math.round(t * SCRUB_STEPS));
+    renderPlayButton(playing);
+    renderValuetext(t, stepIndex, playing);
   }
 
-  // selectAnimation swaps in a fresh playback whose state can coincide with the
-  // outgoing one; the chrome still has to re-render for the new animation.
-  function invalidateUi() { shownActive = null; shownStep = null; }
+  // Belt-and-braces for the animation swap. Both caches above key on the exact
+  // value written to the DOM, so today a stale one can only ever agree with what
+  // is already on screen — this reset is currently redundant, and no test can
+  // pin it. It is kept because the cache it replaced (the old step readout) keyed
+  // on a step INDEX, which genuinely collided across animations at index 0: any
+  // future renderer keyed on a proxy rather than on its rendered value needs
+  // this hook to already exist.
+  function invalidateUi() { shownActive = null; shownValuetext = null; }
 
   // --- driver -----------------------------------------------------------------
   // A frame that throws — a malformed cue or track that slipped past lint, a
@@ -220,8 +390,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     playback = createPlayback(current);
     if (animations.length > 1) pick.value = name;
     syncStructure();
-    invalidateUi(); // a fresh playback starts idle at step 0 — the same key the
-                    // outgoing one may have been showing, but for another animation
+    invalidateUi();
     syncUi();
   }
 
@@ -245,21 +414,136 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
       guarded(() => playback.play());
     }
   };
-  const onScrub = () => { disarmAutoplay(); guarded(() => playback.seek(Number(scrub.value) / 1000)); };
-  const onPrev = () => { disarmAutoplay(); guarded(() => playback.stepPrev()); };
-  const onNext = () => { disarmAutoplay(); guarded(() => playback.stepNext()); };
+  const onScrub = () => {
+    disarmAutoplay();
+    const f = Number(scrub.value) / SCRUB_STEPS;
+    showChapterBubble(f, { transient: true });
+    guarded(() => playback.seek(f));
+  };
+  // PageUp/PageDown jump whole chapters — the keyboard replacement for the
+  // removed step buttons. PageUp goes FORWARD, matching the key's native
+  // slider direction (it increases the value). Single-step animations keep
+  // the browser's native coarse seek instead.
+  //
+  // Targets are derived from the chapter the playhead is IN rather than by
+  // scanning stepStarts for the nearest boundary — same answers (verified
+  // equivalent across the whole 0..1 range), but it reads as the rule it
+  // implements and allocates nothing per keypress.
+  //
+  // AT_BOUNDARY decides "am I at this chapter's start or inside it", which is
+  // what makes PageDown step back rather than restart. It is one scrubber step
+  // because that is the finest position the user can see or reach: a tolerance
+  // finer than the grid would call a playhead that just landed on a boundary
+  // "inside" the chapter, and PageDown would restart it forever instead of
+  // walking back.
+  const onScrubKeydown = (e) => {
+    if (current.steps.length <= 1) return;
+    if (e.key !== "PageUp" && e.key !== "PageDown") return;
+    e.preventDefault();
+    disarmAutoplay();
+    const { t } = playback.state();
+    const starts = current.stepStarts;
+    const i = stepIndexAt(current, t);
+    const target = snapUpToScrubGrid(e.key === "PageUp"
+      ? (starts[i + 1] ?? 1)
+      // Inside a chapter, back up to its own start (restart it); already at the
+      // start, step to the chapter before — the video-player convention.
+      : (t > starts[i] + AT_BOUNDARY ? starts[i] : (starts[i - 1] ?? 0)));
+    // seek() abandons a pending cue but cannot touch the viewer's camera, so an
+    // in-flight tween would keep travelling to the position we just left.
+    viewer.cancelCameraTween();
+    showChapterBubble(target, { transient: true });
+    guarded(() => playback.seek(target));
+  };
+  const cycleAnimation = (dir) => {
+    disarmAutoplay();
+    const i = animations.indexOf(current);
+    selectAnimation(animations[(i + dir + animations.length) % animations.length].name);
+  };
+  const onPrevAnim = () => cycleAnimation(-1);
+  const onNextAnim = () => cycleAnimation(1);
   const onPick = () => { disarmAutoplay(); selectAnimation(pick.value); };
   const onResetClick = () => { disarmAutoplay(); doReset(); };
+  prevAnimBtn?.addEventListener("click", onPrevAnim);
+  nextAnimBtn?.addEventListener("click", onNextAnim);
   playBtn.addEventListener("click", onPlayClick);
   scrub.addEventListener("input", onScrub);
-  prevBtn.addEventListener("click", onPrev);
-  nextBtn.addEventListener("click", onNext);
+  scrub.addEventListener("keydown", onScrubKeydown);
   pick.addEventListener("change", onPick);
   resetBtn.addEventListener("click", onResetClick);
 
   syncStructure();
   syncUi();
 
+  // --- placement: keep clear of the viewbar ---------------------------------
+  // chrome.css centers the bar (left: 50% / translateX(-50%)), and nothing in
+  // CSS can stop that centered position sliding under #viewbar when the stage
+  // narrows — the viewbar's width is dynamic (cutaway's Flip/Reset appear and
+  // disappear), so a static reservation would either overlap or waste centre
+  // space. Measure instead: when the two bars' vertical bands intersect, clamp
+  // the bar's left so a 10px gap to the viewbar holds, capping its width if
+  // even the stage's 12px margin isn't enough. Overrides are inline and
+  // cleared at the top of every pass, so chrome.css (or a host that
+  // re-anchors either bar out of the shared band) stays authoritative the
+  // moment the constraint stops binding. The clear-measure-apply sequence is
+  // loop-safe: it settles within one frame, so ResizeObserver — which reports
+  // rendered sizes at frame boundaries — never sees the intermediate state.
+  const viewbarEl = container.querySelector("#viewbar");
+  let placementRaf = 0;
+  function applyPlacement() {
+    placementRaf = 0;
+    bar.style.left = "";
+    bar.style.transform = "";
+    bar.style.maxWidth = "";
+    bar.style.overflow = "";
+    bar.classList.remove("pf-squeezed");
+    const vb = viewbarEl?.getBoundingClientRect();
+    const barRect = bar.getBoundingClientRect();
+    if (!vb || barRect.top >= vb.bottom || barRect.bottom <= vb.top) return;
+    const stageRect = container.getBoundingClientRect();
+    const plan = planAnimBarPlacement({
+      stageWidth: stageRect.width,
+      barWidth: barRect.width,
+      viewbarLeft: vb.left - stageRect.left,
+    });
+    if (!plan) return;
+    bar.style.left = `${plan.left}px`;
+    bar.style.transform = "none";
+    // maxWidth is the last resort, only reached when even the margin can't
+    // hold the gap — and the bar's flex children have hard minimums that don't
+    // shrink to fit a tighter cap. overflow:hidden is applied here, inline,
+    // rather than as a static rule so it is scoped to the capped state and the
+    // (far more common) uncapped bar never clips anything.
+    //
+    // Nothing that floats above the bar may live inside it, or this clips it:
+    // the ⓘ popover is on document.body and the chapter bubble is on the stage,
+    // both for that reason.
+    if (plan.maxWidth != null) {
+      bar.style.maxWidth = `${plan.maxWidth}px`;
+      bar.style.overflow = "hidden";
+      // Under the cap the bar sheds the pagers (~40px with their gaps). They are
+      // pure convenience — the picker beside them reaches every animation — and
+      // spending that width on the timeline is what keeps the scrubber
+      // targetable instead of letting it collapse toward nothing.
+      bar.classList.add("pf-squeezed");
+    }
+  }
+  function schedulePlacement() {
+    if (typeof requestAnimationFrame !== "function") return applyPlacement();
+    if (!placementRaf) placementRaf = requestAnimationFrame(applyPlacement);
+  }
+  // Observing the bar itself catches content-driven width changes — the ⓘ glyph
+  // appearing or disappearing when only some animations declare a description;
+  // the viewbar, cutaway's actions; the stage, rail drags and window resizes.
+  const placementObserver = typeof ResizeObserver === "function"
+    ? new ResizeObserver(schedulePlacement) : null;
+  if (placementObserver) {
+    placementObserver.observe(container);
+    placementObserver.observe(bar);
+    if (viewbarEl) placementObserver.observe(viewbarEl);
+  }
+  schedulePlacement();
+
   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
@@ -299,13 +583,21 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     detach() {
       offFrame();
       offOrbit();
+      prevAnimBtn?.removeEventListener("click", onPrevAnim);
+      nextAnimBtn?.removeEventListener("click", onNextAnim);
       playBtn.removeEventListener("click", onPlayClick);
       scrub.removeEventListener("input", onScrub);
-      prevBtn.removeEventListener("click", onPrev);
-      nextBtn.removeEventListener("click", onNext);
+      scrub.removeEventListener("keydown", onScrubKeydown);
       pick.removeEventListener("change", onPick);
       resetBtn.removeEventListener("click", onResetClick);
       info.dispose();
+      placementObserver?.disconnect();
+      if (placementRaf && typeof cancelAnimationFrame === "function") cancelAnimationFrame(placementRaf);
+      scrubWrap.removeEventListener("pointermove", onWrapPointerMove);
+      scrubWrap.removeEventListener("pointerleave", onWrapPointerLeave);
+      scrubWrap.removeEventListener("pointercancel", onWrapPointerLeave);
+      hideChapterBubble(); // also clears hoverInside
+      chapterBubble.remove(); // a stage child, so the bar taking itself out misses it
       bar.remove();
     },
     __viewer: viewer, // test hook only

package/src/framework/app.css

@@ -222,6 +222,9 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 .pf-anim-bar {
   display: flex; align-items: center; gap: 8px;
   padding: 6px 10px;
+  /* Never shorter than #viewbar's card sharing the same bottom edge:
+     34px button + 2×4px padding + 2×1px border (border-box). */
+  min-height: 44px;
   background: var(--pf-surface); border: 1px solid var(--pf-border);
   border-radius: var(--pf-radius-control); box-shadow: var(--pf-shadow-float);
 }
@@ -236,19 +239,55 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 .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; }
+  /* The widest thing in the bar after the timeline, and the cheapest to give
+     up: a select's default `min-width: auto` floors it at its longest option,
+     so under pressure it would hold full width while the scrubber collapsed.
+     Let it yield first, and faster than everything else — but not to a bare
+     chevron: below this the control stops naming the animation it selects. */
+  min-width: 44px; flex-shrink: 4;
+}
+/* A child of the stage, not of the bar (the capped bar clips its contents, and
+   this sits above them) — animation-controls.js sets left/bottom per reveal,
+   stage-relative. z-index clears .pf-anim-bar's 15. */
+.pf-anim-chapter {
+  position: absolute; transform: translateX(-50%); z-index: 16;
+  font-family: var(--pf-mono); font-size: 10px; color: var(--pf-text-2);
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control); box-shadow: var(--pf-shadow-float);
+  padding: 3px 8px; white-space: nowrap;
+  pointer-events: none;
+  /* Out of flow, so nothing else constrains it: a long chapter label would
+     otherwise run past both ends of the scrubber and off a narrow stage.
+     Capped at the wrap's nominal width and ellipsised instead. */
+  max-width: 220px; overflow: hidden; text-overflow: ellipsis;
+  opacity: 0; transition: opacity .12s ease;
+}
+.pf-anim-chapter.pf-show { opacity: 1; }
+/* 220px when there is room. The floor is what matters under pressure: a
+   timeline is a pointing target, and below ~96px it stops being one — the
+   chapter ticks collapse onto each other and a drag can't resolve a chapter.
+   Everything else in the bar yields before this does. */
+.pf-anim-scrub-wrap {
+  position: relative; display: inline-flex; align-items: center;
+  width: 220px; min-width: 80px;
+}
+/* Capped bar: the pagers go, and their width goes to the timeline. */
+.pf-anim-bar.pf-squeezed .pf-anim-page { display: none; }
 .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;
 }
 
+@media (prefers-reduced-motion: reduce) {
+  .pf-anim-chapter { transition: none; }
+}
+
+@media (max-width: 360px) {
+  /* #viewbar's card is 40px here (30px buttons) — keep the floor in step. */
+  .pf-anim-bar { min-height: 40px; }
+}
+
 /* 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/chrome.css

@@ -163,7 +163,10 @@
 
 /* --- 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. */
+   #viewbar's, so a host that re-anchors this bar still inherits its chrome.
+   animation-controls.js may inline-override left/transform/max-width (and
+   overflow while width-capped) to hold a 10px gap to #viewbar, and clears
+   the overrides whenever centered placement fits. */
 .pf-anim-bar {
   position: absolute; left: 50%; bottom: 14px; transform: translateX(-50%);
   z-index: 15; max-width: calc(100% - 24px);