partforge 0.46.4 → 0.47.1

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,
@@ -543,6 +551,12 @@ advanced: [
 ],
 ```
 
+**Collapsing.** Each section is a disclosure. A panel with **three or fewer
+sections opens every section and every Advanced fold on load**; beyond that they
+all start closed, because the rail is a fixed-height column and a long part
+otherwise scrolls forever. Set `collapsed: true` or `collapsed: false` on a
+section to override the rule in either direction.
+
 ---
 
 ## Designing the control panel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.46.4",
+  "version": "0.47.1",
   "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,11 +14,14 @@ 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;
 }
 
@@ -36,6 +39,41 @@ export function planAnimBarPlacement({ stageWidth, barWidth, viewbarLeft }, { ga
   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
@@ -90,30 +128,137 @@ 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);
+
+  // 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 —
+    // the BAR's top, not the wrap's. The touch layout wraps the bar into rows
+    // with the timeline on the lower one, so "above the wrap" would sit the
+    // bubble on the chooser row. checkTransportTargets pins this.
+    const wrapRect = scrubWrap.getBoundingClientRect();
+    const barRect = bar.getBoundingClientRect();
+    const stageRect = container.getBoundingClientRect();
+    chapterBubble.style.left =
+      `${wrapRect.left - stageRect.left + clampBubbleX(f, wrapRect.width, bubbleWidth)}px`;
+    chapterBubble.style.bottom = `${stageRect.bottom - barRect.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, step buttons, scrubber ticks.
+  // 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)) {
@@ -130,12 +275,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
@@ -143,9 +289,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;
@@ -156,26 +300,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
@@ -234,8 +394,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();
   }
 
@@ -259,15 +418,61 @@ 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);
 
@@ -295,6 +500,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     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;
@@ -308,22 +514,31 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     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 (~320px)
-    // that don't shrink to fit a tighter cap. overflow:hidden only applies
-    // here, inline, because a static rule in app.css would also clip the ⓘ
-    // info popover in the (far more common) uncapped state.
+    // 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 (step label
-  // text, animation switch); the viewbar, cutaway's actions; the stage, rail
-  // drags and window resizes.
+  // 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) {
@@ -372,15 +587,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

@@ -64,10 +64,19 @@ canvas { display: block; }
 .section:not(.section-hidden) ~ .section:not(.section-hidden) {
   border-top: 1px solid var(--pf-border);
 }
+.sec-header { display: flex; align-items: center; gap: 4px; }
 .sec-title {
+  flex: 1; display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  width: 100%; margin: 0 0 9px; padding: 0; border: 0; background: transparent; cursor: pointer;
+  text-align: left;
   font-family: var(--pf-mono); font-size: 10px; font-weight: 600;
-  letter-spacing: 0.14em; text-transform: uppercase; color: var(--pf-muted-2); margin-bottom: 9px;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--pf-muted-2);
 }
+.sec-title:hover { color: var(--pf-text-2); }
+.sec-title .chev { display: inline-block; transition: transform 0.15s ease; }
+.sec-title .chev::before { content: "▾"; }
+.sec-title[aria-expanded="false"] .chev { transform: rotate(-90deg); }
+.sec-body.hidden { display: none; }
 select.preset {
   width: 100%; background: var(--pf-input-bg); color: var(--pf-text-2);
   border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 7px 9px;
@@ -159,11 +168,20 @@ button.action:disabled { opacity: .5; cursor: default; }
 
 /* keyboard focus ring shared across the panel's interactive controls */
 .seg button:focus-visible, select.preset:focus-visible, .dl-row button:focus-visible,
-button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-visible {
+button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible, #viewbar button:focus-visible {
   outline: none;
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
 
+/* `when` disabling. Distinct from .irrelevant (relevance dimming) on purpose:
+   two mechanisms that look identical make the panel impossible to reason about. */
+.disabled { opacity: 0.5; pointer-events: none; }
+
+/* The wrapper a titled inner group renders into. Conditions hide the wrapper;
+   the disclosure hides `.adv` inside it. Unused until `when` becomes authorable
+   in phase 5, but the class exists from Task 7 and must have a rule. */
+.adv-wrap.hidden { display: none; }
+
 /* part tabs (placement: .pf-float-tabs; legacy markup keeps the old float) */
 #topbar:not(.pf-float-tabs) { position: fixed; top: 12px; left: 50%; transform: translateX(-50%); z-index: 15; }
 #topbar .seg {
@@ -239,24 +257,108 @@ 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; }
 }
 
+/* ---- transport bar, touch layout ----------------------------------------
+   The rules above size the BAR; these size the things you press inside it. At
+   a 13px glyph in 2px/4px of padding, play, reset and the ‹ › pagers measure
+   ~20x20, with 8px between neighbours — mouse targets. Measured on a 390px
+   stage: a tap 12px off the pause button's centre, ordinary finger error,
+   landed on the bar's background and did nothing; a little further landed on
+   a pager, which SWITCHES ANIMATION. The scrubber fared worse, flex-shrinking
+   toward nothing.
+
+   So give every control the 44px minimum, and accept the rows that costs: at
+   44px per target they do not fit a 320-390px stage on one line.
+
+   Both query conditions matter. The width half is the framework's own narrow
+   layout (chrome.css's 720px breakpoint, measured on the STAGE — partforge in
+   an iframe sized to a phone-width card gets it too); the pointer half catches
+   a phone in landscape, wider than 720px and still all thumbs.
+
+   The bar stays a single flat flex line that WRAPS, in source order — no
+   `order` overrides, deliberately: a reordered flex row splits visual order
+   from DOM order, and with it from focus order, so a keyboard on a narrow
+   window would tab in spatial zigzags. Wrapping in source order keeps
+   reading, tab and touch order one sequence, and keeps the pagers bracketing
+   the bar's ends like the wide layout:
+
+       ‹ [ animation v ] (i) ▶        <- wraps where the width runs out
+         [===·===·==o===]  ↺ ›
+
+   The timeline takes whatever width its row has left and drops to a wider
+   row of its own below ~360px. scripts/check-app.mjs's checkTransportTargets
+   pins the result. */
+@media (max-width: 719px), (pointer: coarse) {
+  .pf-anim-bar {
+    flex-wrap: wrap; justify-content: center;
+    column-gap: 4px; row-gap: 2px; padding: 4px 8px;
+  }
+  .pf-anim-bar button {
+    min-width: 44px; min-height: 44px; padding: 0;
+    display: inline-flex; align-items: center; justify-content: center;
+  }
+  .pf-anim-title, .pf-anim-pick { min-width: 0; }
+  /* The picker is a target too, not a caption — it opens the animation list. */
+  .pf-anim-pick { max-width: 100%; min-height: 44px; padding: 3px 10px; }
+  /* The 200px basis makes the timeline BID for real room: at a phone width it
+     loses the bid, wraps, and inherits most of a row; 120px is the floor it
+     can be squeezed to when sharing one. */
+  .pf-anim-scrub-wrap { flex: 1 1 200px; min-width: 120px; width: auto; min-height: 44px; }
+  /* The INPUT is the thing a finger has to land on — height on the wrap alone
+     leaves an ~18px native strip as the real target, with dead slack around
+     it. The track paints centered, so this is invisible; only the hit area
+     grows. */
+  .pf-anim-scrub { min-height: 44px; }
+}
+
 /* 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