partforge 0.48.0 → 0.50.0

package/README.md

@@ -165,18 +165,20 @@ viewer re-poses the meshes it already has — instantly, with no worker rebuild;
 `onBuild` does not fire for those pose-only edits. Anything that changes the
 geometry itself rebuilds as usual.
 
-For parts that declare `animations`, `runtime.animation` exposes the viewer's
-playback engine (`null` otherwise):
+When any view declares `animations`, `runtime.animation` exposes the viewer's
+playback engine (`null` otherwise). Animations are **view-owned**
+(`views.<name>.animations`), so the engine is scoped to the active view — call
+`setView` first to reach another view's set:
 
 ```js
-runtime.animation.play("open");   // switch + play (camera cue and all)
+runtime.animation.play("open");   // switch + play, within the ACTIVE view (camera cue and all)
 runtime.animation.seek(0.5);      // scrub, normalized 0..1 (pauses)
 runtime.animation.pause();
-runtime.animation.stop();         // reset + restore pre-animation params
-runtime.animation.state();        // { animation, status, t, stepIndex }
+runtime.animation.stop();         // reset + restore pre-animation params and clear opacity overrides
+runtime.animation.state();        // { view, animation, status, t, stepIndex }
 ```
 
-A part can mark at most one animation `autoplay: true` to start it
+A view can mark at most one of its animations `autoplay: true` to start it
 automatically on first show and again on every view switch — until the user
 touches the transport — or anything writes params (`runtime.setParams`
 included) or calls a `runtime.animation` method; any of those disarms

package/bin/cli.js

@@ -8,7 +8,7 @@ import { pathToFileURL } from "node:url";
 import { resolve, dirname } from "node:path";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { detectBackend } from "../src/framework/backend-select.js";
-import { normalizeAnimation, evaluate, cueAt } from "../src/framework/animation.js";
+import { viewAnimations, evaluate, cueAt } from "../src/framework/animation.js";
 import { bootOcctKernel } from "../src/testing/occt.js";
 import { bootManifoldKernel } from "../src/testing/manifold.js";
 import { measure } from "../src/framework/oracle/measure.js";
@@ -185,19 +185,46 @@ const commands = {
       if (view !== undefined && !Object.hasOwn(part.views ?? {}, view)) {
         die(`unknown view "${view}" (have: ${Object.keys(part.views ?? {}).join(", ") || "none"})\n${usage}`);
       }
+      // Resolve --animation across views, still BEFORE the kernel boots (the
+      // header's rule: a flag typo shouldn't pay a WASM boot, and this depends
+      // only on `part`). A unique name implies its owning view, overriding the
+      // default-view rule; an ambiguous one needs the positional view argument.
+      // NOT a --view flag: --views already means camera angles.
+      let anim = null, animView;
+      if (flags.animation !== undefined) {
+        const byView = viewAnimations(part);
+        // Deduped: two views declaring the same name would otherwise report
+        // "(declared: shared, shared)".
+        const declared = () =>
+          [...new Set([...byView.values()].flat().map((x) => x.name))].join(", ") || "none";
+        const owners = [...byView.entries()]
+          .filter(([, anims]) => anims.some((x) => x.name === flags.animation))
+          .map(([v]) => v);
+        if (view !== undefined) {
+          if (!owners.includes(view)) {
+            throw new Error(owners.length
+              ? `animation "${flags.animation}" is not in view "${view}" — it lives in view ${owners.map((v) => `"${v}"`).join(", ")}`
+              : `unknown animation "${flags.animation}" (declared: ${declared()})`);
+          }
+          animView = view;
+        } else if (owners.length === 1) {
+          animView = owners[0];
+        } else if (owners.length > 1) {
+          die(`--animation "${flags.animation}" is ambiguous (views ${owners.map((v) => `"${v}"`).join(", ")}) — pass the positional view argument\n${usage}`);
+        } else {
+          throw new Error(`unknown animation "${flags.animation}" (declared: ${declared()})`);
+        }
+        // Already normalized by viewAnimations — no normalizeAnimation call here.
+        anim = byView.get(animView).find((x) => x.name === flags.animation);
+      }
+
       const kernel = await bootKernel(part);
 
-      if (flags.animation === undefined) {
+      if (anim === null) {
         const files = await renderViews(kernel, part, view, { views, out: outDir, params: baseParams });
         for (const f of files) console.log(`wrote ${f}`);
         process.exit(0);
       }
-
-      const spec = part.animations?.[flags.animation];
-      if (!spec) {
-        throw new Error(`unknown animation "${flags.animation}" (have: ${Object.keys(part.animations ?? {}).join(", ") || "none"})`);
-      }
-      const anim = normalizeAnimation(flags.animation, spec);
       // Frames: --step renders one still at the END of that step (its fully
       // applied state); --at takes positions normalized over the animation's
       // TOTAL duration (same t as the viewer scrubber / runtime seek).
@@ -241,11 +268,11 @@ const commands = {
         frames = ts.map((t, i) => ({ t, tag: `${flags.animation}-t${tags[i]}` }));
       }
       for (const frame of frames) {
-        const { values } = evaluate(anim, frame.t);
+        const { values, opacity } = evaluate(anim, frame.t);
         const cue = cueAt(anim, frame.cueT ?? frame.t);
         const frameViews = views ?? (cue ? [cue.view] : undefined);
-        const files = await renderViews(kernel, part, view, {
-          views: frameViews, out: outDir, params: { ...baseParams, ...values }, tag: frame.tag,
+        const files = await renderViews(kernel, part, animView, {
+          views: frameViews, out: outDir, params: { ...baseParams, ...values }, tag: frame.tag, opacity,
         });
         for (const f of files) console.log(`wrote ${f}`);
       }

package/docs/AUTHORING-PARTS.md

@@ -85,7 +85,7 @@ export default {
       export?: { name },                   // filename/object name on export; defaults to the key
     },
   },
-  views: { <name>: { label, default? } },  // the view tabs (a view = a set of sub-parts)
+  views: { <name>: { label, default?, animations? } },  // view tabs; a view may own animations (below)
 };
 ```
 
@@ -131,11 +131,23 @@ 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, 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`.
+A **view** may declare named animations — pure keyframe data that drives
+**existing params** over time and fades the view's own sub-parts in and out.
+Animations belong to the view that declares them: they live under
+`views.<name>.animations`, never at the top level of the part (a top-level
+`animations` key is a lint error — `animation-not-in-view` — and is ignored at
+runtime: no bar, no crash).
+
+The viewer shows a transport bar (play/scrub, with ‹ › pagers between
+animations) **only while the active view declares animations**, listing exactly
+that view's set; views without animations render no bar at all. Switching views
+resets playback: the running animation stops, its param snapshot is restored,
+all opacity overrides are cleared, and the incoming view's transport starts
+fresh at its first animation, position 0 — no animation state survives a view
+switch. Hosts drive the same engine via `runtime.animation`, scoped to the
+active view (call `setView` first to reach another view's animations);
+`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
@@ -144,42 +156,87 @@ matching the key's native slider direction). Screen readers get the same
 information from the scrubber's `aria-valuetext`, which reads
 `"<step label> — <percent>"`.
 
+This is the shipped reference part's own block — `views.box` owns all three
+animations, and `assemble` opens with a fade rather than a motion:
+
 ```js
-animations: {
-  open: {
-    label: "Open lid",
-    description: "Optional **CommonMark**, shown behind the ⓘ glyph.",
-    camera: "front",          // optional: intro angle, cue list, or per-step (below)
-    duration: 1.2,            // seconds
-    loop: false,              // true = wraps continuously (single-step only)
-    easing: "ease-in-out",    // linear | ease-in | ease-out | ease-in-out
-    tracks: { lidAngle: [[0, 0], [1, 110]] },   // param -> [t, value] keyframes
-  },
-  assemble: {
-    label: "Assemble",
-    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,
-        tracks: { lidAngle: [[0, 0], [1, 110]] } },
-    ],
+views: {
+  box: {
+    label: "Box",
+    animations: {
+      open: {
+        label: "Open lid",
+        description: "Swings the lid to **110°** about the rear hinge line.\n\nPose-only: playback runs at frame rate with no geometry rebuild.",
+        camera: "front",        // optional: intro angle, cue list, or per-step (below)
+        duration: 1.2,          // seconds
+        tracks: { lidAngle: [[0, 0], [1, 110]] },   // param -> [t, value] keyframes
+      },
+      cycle: {
+        label: "Open / close",
+        duration: 2.4,
+        loop: true,             // wraps continuously (single-step only)
+        easing: "linear",       // linear | ease-in | ease-out | ease-in-out
+        autoplay: true,         // at most one per view
+        tracks: { lidAngle: [[0, 0], [0.5, 110], [1, 0]] },
+      },
+      assemble: {
+        label: "Assemble",
+        description: "How the parts come together: the lid fades in above the base, drops on, then swings open to check hinge clearance.",
+        steps: [                // steps play in order; named on the scrubber as you hover/drag
+          { label: "Lid appears", camera: "iso", duration: 0.8,
+            opacity: { lid: [[0, 0], [1, 1]] },        // sub-part -> [t, 0..1] keyframes
+            tracks: { lidLift: [[0, 40], [1, 40]] } }, // hold the lift while it fades in
+          { label: "Lower the lid", camera: "left", duration: 1.0,
+            tracks: { lidLift: [[0, 40], [1, 0]] } },
+          { label: "Open to check clearance", camera: "iso", duration: 1.0,
+            tracks: { lidAngle: [[0, 0], [1, 110]] } },
+        ],
+      },
+    },
   },
-}
+},
 ```
 
 Rules (all lint-enforced):
 
-- An animation has **either** `tracks` (a single anonymous step) **or** `steps`.
+- Animations are declared under `views.<name>.animations` — one map per view,
+  each name unique within its view. Two views may reuse a name; each owns its
+  own animation.
+- An animation has **either** `tracks`/`opacity` (a single anonymous step)
+  **or** `steps`. Never both forms, never neither.
 - Tracks reference numeric params from `defaults`. Keyframe `t` is normalized
   per step, strictly ascending from exactly 0 to exactly 1; values must sit
   inside the owning control's min/max (the engine applies them unclamped).
 - Params not tracked anywhere keep their current values; a param tracked in
   one step holds its nearest keyframe value while other steps play.
-- A step may declare a `camera` and **no** `tracks` — an establishing shot that
-  swings the view while the model holds still. At least one step still has to
-  carry tracks, or the animation animates nothing. Note the holding value is the
-  nearest keyframe, not whatever the user last set: a leading camera-only step
-  shows the animation's opening pose, the same one `t = 0` would show.
+- `opacity` sits beside `tracks` and fades sub-parts instead of moving them.
+  It is keyed by **sub-part name**, and the sub-part must belong to the owning
+  view (`animation-opacity-unknown-part` otherwise); values run 0 (hidden) to 1
+  (normal) and are lint-checked against that range
+  (`animation-opacity-range`). Keyframes follow exactly the same rules as param
+  tracks — per-step normalized `t`, strictly ascending from 0 to 1 — including
+  the hold rule: a sub-part faded in step 3 holds its step-3 opening value
+  (0, hidden) through steps 1–2, so "absent until its moment" needs no extra
+  declaration. Sub-parts never mentioned render normally.
+- Opacity 0 hides the mesh **and its edge lines** entirely — it is absence, not
+  a ghost. Values in between multiply any static `display.opacity`: a ghost
+  part at `display.opacity: 0.5` faded to 1 shows at 0.5.
+- **Opacity is display-only, always** — it never touches params, export,
+  `measure`, or `verify`, and Reset restores normal visibility. This is a
+  deliberate asymmetry with param `tracks`, where exporting while paused
+  exports the posed state (below): a pose is real param state, a fade is not.
+  Because it bypasses the param pipeline, a fade runs at frame rate even when
+  param tracks force worker-cadence rebuilds.
+- Fades compose with the cutaway: a half-faded surface is still sectioned by the
+  cut plane, though its hatch cap keeps full-strength opacity for the moment the
+  part is mid-fade.
+- A step may declare a `camera` and **no** `tracks`/`opacity` — an establishing
+  shot that swings the view while the model holds still. At least one step still
+  has to carry `tracks` or `opacity`, or the animation animates nothing; a
+  **pure-fade** animation, carrying only `opacity`, is perfectly legal. Note the
+  holding value is the nearest keyframe, not whatever the user last set: a
+  leading camera-only step shows the animation's opening pose, the same one
+  `t = 0` would show.
 - `loop` and `autoplay` must be literal booleans. Anything else is reported by
   lint and treated as `false` at runtime, so `loop: "false"` never means "loop".
 - Couple motions through `derive` (animate one master param; derive the rest),
@@ -196,8 +253,8 @@ Rules (all lint-enforced):
 - Playback pauses when the user edits any control; Reset restores the values
   the animation found. Because animated values are real params, exporting
   while paused exports the posed state — by design.
-- `autoplay: true` (optional, one animation at most) starts that animation on
-  first show and again on each view switch, until the user touches the
+- `autoplay: true` (optional, at most one animation **per view**) starts that
+  animation on first show and again on each view switch, until the user touches the
   transport — or anything writes params (`runtime.setParams` included) or
   calls a `runtime.animation` method; any of those disarms auto-start for the
   session. Lint: `animation-autoplay-invalid`. It is not armed when the
@@ -210,7 +267,13 @@ Rules (all lint-enforced):
 Headless: `partforge render <part> --animation open --at 0,0.5,1` renders
 tagged stills (`--at` is normalized over the animation's total duration, like
 the scrubber); `--step <index|label>` renders a step's end state; stills
-default to the governing camera cue's angle.
+default to the governing camera cue's angle, and apply opacity at the rendered
+`t`, so a faded frame renders faded. `--animation` searches every view: a name
+unique across the part implies its owning view and renders there, overriding
+the usual first-view default. If two views declare the same name the CLI stops
+and asks for the existing positional view argument
+(`partforge render <part> <view> --animation shared`) — there is no compound
+"view/name" syntax, and `--views` already means camera angles.
 
 ---
 
@@ -1525,10 +1588,13 @@ bring a section back under budget.
 `contacts` / `clearance` keys, which are not scalar view metrics; they are
 validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
 
-**Animations block** — static validation of `animations`, without executing
-`build`: `animations-not-object`, `animation-tracks-or-steps`,
+**Animations block** — static validation of each view's `animations` block,
+without executing `build`: `animation-not-in-view` (a top-level `animations`
+key, which the runtime ignores), `animations-not-object`,
+`animation-tracks-or-steps`,
 `animation-unknown-param`, `animation-param-not-numeric`,
 `animation-keyframes-invalid`, `animation-value-out-of-range`,
+`animation-opacity-unknown-part`, `animation-opacity-range`,
 `animation-duration-invalid`, `animation-loop-invalid`,
 `animation-step-label-duplicate`, `animation-easing-unknown`,
 `animation-camera-invalid`, `animation-description-invalid`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.48.0",
+  "version": "0.50.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

@@ -3,9 +3,14 @@
 // 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, stepIndexAt } from "./animation.js";
+// edit, minus the regen debounce. Returns null when NO view declares a
+// (valid) animation, so mount can wire it unconditionally.
+//
+// Animations belong to a VIEW: the bar shows the active view's set and hides
+// itself in a view that declares none, and every view switch resets the
+// outgoing animation first (see viewChanged). The host owns which view is
+// active — getView() is the driver's only window onto it.
+import { viewAnimations, createPlayback, stepIndexAt } from "./animation.js";
 import { createInfoPopover, attachInfo } from "./controls.js";
 
 function el(tag, className, text) {
@@ -92,49 +97,51 @@ function textSetter(element) {
   return (value) => { if (node.data !== value) node.data = value; };
 }
 
-export function attachAnimationControls(viewer, part, { container, applyValues, getParamValues }) {
+export function attachAnimationControls(viewer, part, { container, applyValues, getParamValues, getView }) {
   // 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;
+  let byView;
+  try { byView = viewAnimations(part); } catch { byView = new Map(); }
+  if (![...byView.values()].some((a) => a.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);
+  // `animations` is the ACTIVE view's set; it is re-pointed by viewChanged, and
+  // is empty (with a null current/playback) in a view that declares none.
+  const animsFor = (view) => byView.get(view) ?? [];
+  let animations = animsFor(getView());
+  let current = animations[0] ?? null;
+  let playback = current ? createPlayback(current) : null;
   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
+  // Autoplay: at most one animation PER VIEW declares it (lint-enforced), and
+  // each view's own gets its kick when that view becomes active. Armed until
+  // the user manually touches the transport — one touch disarms it for the
+  // whole session, every view included — 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 autoplayFor = (view) => animsFor(view).find((a) => a.autoplay) ?? null;
+  let autoplayArmed = [...byView.values()].some((set) => set.some((a) => a.autoplay)) && !reducedMotion;
   const disarmAutoplay = () => { autoplayArmed = false; };
 
   // --- DOM --------------------------------------------------------------------
   const bar = el("div", "pf-anim-bar");
   const info = createInfoPopover();
 
+  // The bar's DOM is built ONCE and re-dressed per view: which of the picker,
+  // the title and the pagers actually shows is syncStructure's call, because a
+  // view switch can move between a one-animation set and a many-animation one.
   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", "");
-  // Multi-animation parts page with ‹ › at the card's outer edges — whole
+  // Multi-animation views 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 prevAnimBtn = btn("pf-anim-page", "‹", "Previous animation");
+  const nextAnimBtn = btn("pf-anim-page", "›", "Next animation");
+  bar.append(prevAnimBtn, pick, title);
   const infoSlot = el("span", "pf-anim-info");
   const playBtn = btn("pf-anim-play", "▶", "Play animation");
   const scrubWrap = el("span", "pf-anim-scrub-wrap");
@@ -145,8 +152,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   scrub.setAttribute("aria-label", "Animation position");
   scrubWrap.append(scrub);
   const resetBtn = btn("pf-anim-reset", "↺", "Reset animation");
-  bar.append(infoSlot, playBtn, scrubWrap, resetBtn);
-  if (nextAnimBtn) bar.append(nextAnimBtn);
+  bar.append(infoSlot, playBtn, scrubWrap, resetBtn, nextAnimBtn);
   container.append(bar);
   // Chapter bubble: floats above the scrubber naming the chapter under the
   // pointer (hover) or playhead (scrub).
@@ -188,7 +194,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   let bubbleLabel = null;
   let bubbleWidth = 0;
   function showChapterBubble(fraction, { transient = false } = {}) {
-    if (current.steps.length <= 1) return;
+    if (!current || 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) {
@@ -224,7 +230,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     chapterBubble.classList.remove("pf-show");
   }
   const onWrapPointerMove = (e) => {
-    if (current.steps.length <= 1) return; // no chapters: no bubble, and no layout read
+    if (!current || current.steps.length <= 1) return; // no chapters: no bubble, and no layout read
     const rect = scrubWrap.getBoundingClientRect();
     if (!rect.width) return;
     hoverInside = true;
@@ -243,10 +249,25 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   scrubWrap.addEventListener("pointerleave", onWrapPointerLeave);
   scrubWrap.addEventListener("pointercancel", onWrapPointerLeave);
 
-  // Per-animation chrome: title, ⓘ description, pager labels, scrubber ticks.
+  // Per-view + per-animation chrome: which chooser shows, the picker's options,
+  // title, ⓘ description, pager labels, scrubber ticks. A view with no
+  // animations hides the whole bar rather than showing an empty transport.
   function syncStructure() {
-    title.textContent = current.label;
+    bar.style.display = current ? "" : "none";
     hideChapterBubble();
+    if (!current) return;
+    const paged = animations.length > 1;
+    pick.style.display = paged ? "" : "none";
+    title.style.display = paged ? "none" : "";
+    prevAnimBtn.style.display = paged ? "" : "none";
+    nextAnimBtn.style.display = paged ? "" : "none";
+    pick.replaceChildren(...animations.map((a) => {
+      const o = document.createElement("option");
+      o.value = a.name; o.textContent = a.label;
+      return o;
+    }));
+    pick.value = current.name;
+    title.textContent = current.label;
     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
@@ -321,6 +342,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   }
 
   function syncUi() {
+    if (!current) return; // a view with no animations has nothing to draw
     const { status, t, stepIndex } = playback.state();
     const playing = status === "playing" || status === "intro";
     scrub.value = String(Math.round(t * SCRUB_STEPS));
@@ -350,12 +372,20 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     console.warn("partforge: animation frame failed", err);
   }
   function apply(r) {
-    if (!r) return;
+    if (!r || !current) 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);
+      // Params go through applyValues (the slider path) only when the animation
+      // actually drives some: an opacity-only frame must neither snapshot nor
+      // write params, or it would dirty the regen loop for a display-only fade.
+      // First write for this run also remembers what the user's params were, so
+      // Reset can put them back.
+      if (Object.keys(r.values).length) {
+        if (snapshot == null) snapshot = getParamValues(current.trackedKeys);
+        applyValues(r.values);
+      }
+      // Opacity is display-only and lives entirely in the viewer — no param, no
+      // rebuild, nothing to snapshot; doReset drops the overrides wholesale.
+      for (const [n, v] of Object.entries(r.opacity ?? {})) viewer.setSubPartOpacity?.(n, v);
       if (r.cue) {
         viewer.tweenCameraTo(r.cue.view, {
           duration: tweenDuration,
@@ -376,12 +406,14 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // callback returns — a throw escaping from there stops the rAF chain and
   // freezes the viewer permanently instead of costing one frame.
   function guarded(produce) {
+    if (!playback) return; // active view has no animations: nothing to drive
     try { apply(produce()); } catch (err) { warnFrameFailure(err); }
   }
 
   function doReset() {
-    playback.reset();
+    playback?.reset();
     viewer.cancelCameraTween();
+    viewer.clearSubPartOpacities?.();
     if (snapshot) { applyValues(snapshot); snapshot = null; }
     syncUi();
   }
@@ -392,7 +424,6 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     doReset();
     current = next;
     playback = createPlayback(current);
-    if (animations.length > 1) pick.value = name;
     syncStructure();
     invalidateUi();
     syncUi();
@@ -404,11 +435,13 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // gating playback, settle the gate — cancel() never fires onComplete, so
   // without this the machine would sit in "intro" forever.
   const offOrbit = viewer.onCameraStart(() => {
+    if (!playback) return;
     playback.disarmCues();
     if (playback.state().status === "intro") guarded(() => playback.introDone());
   });
 
   const onPlayClick = () => {
+    if (!current) return;
     disarmAutoplay();
     const active = playback.state().status;
     if (active === "playing" || active === "intro") {
@@ -419,6 +452,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     }
   };
   const onScrub = () => {
+    if (!current) return;
     disarmAutoplay();
     const f = Number(scrub.value) / SCRUB_STEPS;
     showChapterBubble(f, { transient: true });
@@ -441,7 +475,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // "inside" the chapter, and PageDown would restart it forever instead of
   // walking back.
   const onScrubKeydown = (e) => {
-    if (current.steps.length <= 1) return;
+    if (!current || current.steps.length <= 1) return;
     if (e.key !== "PageUp" && e.key !== "PageDown") return;
     e.preventDefault();
     disarmAutoplay();
@@ -460,6 +494,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     guarded(() => playback.seek(target));
   };
   const cycleAnimation = (dir) => {
+    if (!current) return;
     disarmAutoplay();
     const i = animations.indexOf(current);
     selectAnimation(animations[(i + dir + animations.length) % animations.length].name);
@@ -468,8 +503,8 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   const onNextAnim = () => cycleAnimation(1);
   const onPick = () => { disarmAutoplay(); selectAnimation(pick.value); };
   const onResetClick = () => { disarmAutoplay(); doReset(); };
-  prevAnimBtn?.addEventListener("click", onPrevAnim);
-  nextAnimBtn?.addEventListener("click", onNextAnim);
+  prevAnimBtn.addEventListener("click", onPrevAnim);
+  nextAnimBtn.addEventListener("click", onNextAnim);
   playBtn.addEventListener("click", onPlayClick);
   scrub.addEventListener("input", onScrub);
   scrub.addEventListener("keydown", onScrubKeydown);
@@ -551,7 +586,8 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   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.
+    // something else. "Unknown" is judged against the ACTIVE view's set: an
+    // animation that exists in another view is not playable from here.
     play(name) {
       disarmAutoplay();
       if (name != null && !animations.some((a) => a.name === name)) {
@@ -564,7 +600,11 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     pause() { disarmAutoplay(); viewer.cancelCameraTween(); guarded(() => playback.pause()); },
     seek(t) { disarmAutoplay(); guarded(() => playback.seek(t)); },
     stop() { disarmAutoplay(); doReset(); },
-    state: () => ({ animation: current.name, ...playback.state() }),
+    state: () => ({
+      view: getView(),
+      animation: current?.name ?? null,
+      ...(playback ? playback.state() : { status: "idle", t: 0, stepIndex: 0 }),
+    }),
   };
 
   const handle = {
@@ -574,21 +614,41 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     notifyUserEdit() {
       disarmAutoplay();
       viewer.cancelCameraTween();
-      playback.userEdited();
+      playback?.userEdited();
       syncUi();
     },
-    // Mount calls this on first ready and on every view/tab switch.
+    // Mount calls this from the view-tab onChange, BEFORE it refreshes the
+    // view: the outgoing animation's params and opacity overrides must be
+    // restored before the incoming view composes its assembly.
+    viewChanged() {
+      doReset();
+      animations = animsFor(getView());
+      current = animations[0] ?? null;
+      playback = current ? createPlayback(current) : null;
+      syncStructure();
+      invalidateUi();
+      if (current) syncUi();
+    },
+    // Mount calls this on first ready and on every view/tab switch — it plays
+    // the ACTIVE view's autoplay animation, if that view declares one.
     autoplayKick() {
-      if (!autoplayArmed || !autoplayAnim) return;
-      if (current !== autoplayAnim) selectAnimation(autoplayAnim.name);
+      if (!autoplayArmed) return;
+      const target = autoplayFor(getView());
+      if (!target) return;
+      // selectAnimation resolves within the ACTIVE view's set, so a kick that
+      // arrives before viewChanged has re-pointed it finds nothing to select —
+      // degrade to a no-op rather than driving the outgoing view's playback.
+      if (current !== target) selectAnimation(target.name);
+      if (current !== target || !playback) return;
       const { status } = playback.state();
       if (status !== "playing" && status !== "intro") guarded(() => playback.play());
     },
     detach() {
       offFrame();
       offOrbit();
-      prevAnimBtn?.removeEventListener("click", onPrevAnim);
-      nextAnimBtn?.removeEventListener("click", onNextAnim);
+      viewer.clearSubPartOpacities?.();
+      prevAnimBtn.removeEventListener("click", onPrevAnim);
+      nextAnimBtn.removeEventListener("click", onNextAnim);
       playBtn.removeEventListener("click", onPlayClick);
       scrub.removeEventListener("input", onScrub);
       scrub.removeEventListener("keydown", onScrubKeydown);