partforge 0.48.0 → 0.50.0

package/src/framework/lint/rules-animations.js

@@ -1,9 +1,15 @@
-// Group 5 — the `animations` block (spec 2026-08-02-model-animation-design.md).
+// Group 5 — the per-view `animations` blocks (specs
+// 2026-08-02-model-animation-design.md, 2026-08-10-per-view-animations.md).
 // Everything but the last rule is static data validation: the block is pure
 // keyframe data by design, so lint can hold every track to the schema without
 // executing author code. `animation-track-rebuilds` is the exception — it runs
 // the geometry-free pose probe to classify each track as pose-only or
 // geometry-rebuilding, and reports the latter at the note tier.
+//
+// Animations are VIEW-OWNED: each block lives at `views.<view>.animations`, and
+// every finding path says so. A legacy top-level `animations` key is ignored by
+// the runtime, so `animation-not-in-view` reports it as a hard error rather than
+// letting the author wonder why nothing plays.
 import { err, note } from "./finding.js";
 import { EASINGS } from "../animation.js";
 import { CANONICAL_VIEWS } from "../view-angles.js";
@@ -14,14 +20,23 @@ import { controlNodes } from "../panel/model.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 
-// [name, spec] pairs, only when the block is well-shaped enough to walk.
-const animEntries = (part) =>
-  isPlainObject(part?.animations)
-    ? Object.entries(part.animations).filter(([, a]) => isPlainObject(a))
-    : [];
+// [{ view, name, a, base }] entries, only when blocks are well-shaped enough to
+// walk; `base` is the finding-path prefix `views.<view>.animations.<name>`.
+const animEntries = (part) => {
+  const out = [];
+  if (!isPlainObject(part?.views)) return out;
+  for (const [view, v] of Object.entries(part.views)) {
+    if (!isPlainObject(v) || !isPlainObject(v.animations)) continue;
+    for (const [name, a] of Object.entries(v.animations)) {
+      if (isPlainObject(a)) out.push({ view, name, a, base: `views.${view}.animations.${name}` });
+    }
+  }
+  return out;
+};
 
 // Steps in normalized-adjacent form for rule walks (does NOT validate — each
-// rule checks its own slice). A bare-tracks animation is one anonymous step.
+// rule checks its own slice). A bare-tracks animation is one anonymous step;
+// the spread carries `tracks` AND `opacity` through unchanged.
 const rawSteps = (a) => (Array.isArray(a.steps) ? a.steps.filter(isPlainObject) : [{ ...a, label: null }]);
 
 // The control descriptor ranges, for value-in-range checks. Walks the shared
@@ -48,54 +63,75 @@ const validKeyframes = (kf) =>
   && kf.every((e, i) => i === 0 || e[0] > kf[i - 1][0]);
 
 export const ANIMATION_RULES = [
+  {
+    // Clean break, not a deprecation: viewAnimations() reads only
+    // `views.<v>.animations`, so a top-level block animates nothing at all.
+    id: "animation-not-in-view",
+    run: ({ part }) => (part?.animations === undefined ? [] : [
+      err("animation-not-in-view",
+        "`animations` moved into views — a top-level block is ignored at runtime",
+        "Declare each animation under its owning view: `views.<name>.animations = { <anim>: { … } }`. The transport bar shows only the active view's animations.",
+        "animations"),
+    ]),
+  },
   {
     id: "animations-not-object",
     run: ({ part }) => {
-      if (part?.animations === undefined) return [];
-      if (!isPlainObject(part.animations)) {
-        return [err("animations-not-object", "`animations` is not a plain object",
-          "Declare animations as `animations: { <name>: { duration, tracks } }` — see docs/AUTHORING-PARTS.md \"Animations\".",
-          "animations")];
+      const out = [];
+      if (!isPlainObject(part?.views)) return out;
+      for (const [view, v] of Object.entries(part.views)) {
+        if (!isPlainObject(v) || v.animations === undefined) continue;
+        if (!isPlainObject(v.animations)) {
+          out.push(err("animations-not-object", `view "${view}" \`animations\` is not a plain object`,
+            "Declare animations as `views.<name>.animations = { <anim>: { duration, tracks } }` — see docs/AUTHORING-PARTS.md \"Animations\".",
+            `views.${view}.animations`));
+          continue;
+        }
+        for (const [name, a] of Object.entries(v.animations)) {
+          if (isPlainObject(a)) continue;
+          out.push(err("animations-not-object", `animation "${name}" is not a plain object`,
+            "Each animations entry must be an object with `duration` + `tracks`/`opacity`, or `steps`.",
+            `views.${view}.animations.${name}`));
+        }
       }
-      return Object.entries(part.animations)
-        .filter(([, a]) => !isPlainObject(a))
-        .map(([name]) => err("animations-not-object", `animation "${name}" is not a plain object`,
-          "Each animations entry must be an object with `duration` + `tracks`, or `steps`.",
-          `animations.${name}`));
+      return out;
     },
   },
   {
     id: "animation-tracks-or-steps",
     run: ({ part }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
-        const hasTracks = a.tracks !== undefined;
+      for (const { name, a, base } of animEntries(part)) {
+        // A single-phase animation may drive params (`tracks`), sub-part
+        // opacity, or both — either one puts it in the non-stepped form.
+        const hasSingle = a.tracks !== undefined || a.opacity !== undefined;
         const hasSteps = a.steps !== undefined;
-        if (hasTracks === hasSteps) {
+        if (hasSingle === hasSteps) {
           out.push(err("animation-tracks-or-steps",
-            `animation "${name}" must have exactly one of \`tracks\` or \`steps\``,
-            "A single-phase animation declares `tracks` directly; a stepped one declares `steps: [{ label, duration, tracks }]`. Never both, never neither.",
-            `animations.${name}`));
+            `animation "${name}" must have exactly one of \`tracks\`/\`opacity\` or \`steps\``,
+            "A single-phase animation declares `tracks` and/or `opacity` with a `duration`; a stepped one declares `steps: […]`. Never both forms, never neither.",
+            base));
           continue;
         }
         if (hasSteps && (!Array.isArray(a.steps) || a.steps.length === 0 || !a.steps.every(isPlainObject))) {
           out.push(err("animation-tracks-or-steps",
             `animation "${name}" has an empty or malformed \`steps\` array`,
             "`steps` must be a non-empty array of `{ label, duration, tracks }` objects.",
-            `animations.${name}.steps`));
+            `${base}.steps`));
           continue;
         }
         const steps = rawSteps(a);
-        const trackful = (s) => isPlainObject(s.tracks) && Object.keys(s.tracks).length > 0;
-        if (!steps.some(trackful)) {
+        const animated = (s) => (isPlainObject(s.tracks) && Object.keys(s.tracks).length > 0)
+          || (isPlainObject(s.opacity) && Object.keys(s.opacity).length > 0);
+        if (!steps.some(animated)) {
           out.push(err("animation-tracks-or-steps",
             `animation "${name}" animates nothing`,
-            "At least one step needs a non-empty `tracks` object mapping a param key to keyframes.",
-            hasSteps ? `animations.${name}.steps` : `animations.${name}.tracks`));
+            "At least one step needs a non-empty `tracks` object (param key → keyframes) or a non-empty `opacity` object (sub-part key → keyframes).",
+            hasSteps ? `${base}.steps` : `${base}.tracks`));
           continue;
         }
         steps.forEach((s, i) => {
-          if (trackful(s)) return;
+          if (animated(s)) return;
           // A camera-only step is legal: it holds the pose and just moves the
           // camera — an establishing shot before the motion starts. The runtime
           // emits its cue and evaluate() holds the surrounding values, so lint
@@ -103,27 +139,29 @@ export const ANIMATION_RULES = [
           if (hasSteps && s.camera != null) return;
           out.push(err("animation-tracks-or-steps",
             `animation "${name}"${hasSteps ? ` step ${i}` : ""} has no tracks`,
-            "Every step needs a non-empty `tracks` object mapping a param key to keyframes — or, for a step that only moves the camera, a `camera` angle.",
-            hasSteps ? `animations.${name}.steps[${i}].tracks` : `animations.${name}.tracks`));
+            "Every step needs a non-empty `tracks` object (param key → keyframes) or an `opacity` object (sub-part key → keyframes) — or, for a step that only moves the camera, a `camera` angle.",
+            hasSteps ? `${base}.steps[${i}].tracks` : `${base}.tracks`));
         });
       }
       return out;
     },
   },
   {
+    // `tracks` only — opacity keys name SUB-PARTS, not params, and are checked
+    // by animation-opacity-unknown-part instead.
     id: "animation-unknown-param",
     run: ({ part }) => {
       if (!isPlainObject(part?.defaults)) return [];
       const known = new Set(Object.keys(part.defaults));
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         rawSteps(a).forEach((s, i) => {
           for (const key of Object.keys(isPlainObject(s.tracks) ? s.tracks : {})) {
             if (!known.has(key)) {
               out.push(err("animation-unknown-param",
                 `animation "${name}" tracks "${key}", which is not in \`defaults\``,
                 `Animations drive existing params — add "${key}" to \`defaults\` (and a control for it), or correct the key.`,
-                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+                `${base}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
             }
           }
         });
@@ -136,14 +174,14 @@ export const ANIMATION_RULES = [
     run: ({ part }) => {
       if (!isPlainObject(part?.defaults)) return [];
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         rawSteps(a).forEach((s, i) => {
           for (const key of Object.keys(isPlainObject(s.tracks) ? s.tracks : {})) {
             if (key in part.defaults && typeof part.defaults[key] !== "number") {
               out.push(err("animation-param-not-numeric",
                 `animation "${name}" tracks "${key}", whose default is not a number`,
                 "v1 animations interpolate numeric params only — text/choice params cannot be keyframed.",
-                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+                `${base}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
             }
           }
         });
@@ -152,17 +190,21 @@ export const ANIMATION_RULES = [
     },
   },
   {
+    // Keyframe SHAPE is the same contract for both fields, so one rule owns it.
+    // Opacity's extra constraint (values in 0..1) is animation-opacity-range's,
+    // and it only walks tracks this rule has already accepted.
     id: "animation-keyframes-invalid",
     run: ({ part }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         rawSteps(a).forEach((s, i) => {
-          for (const [key, kf] of Object.entries(isPlainObject(s.tracks) ? s.tracks : {})) {
-            if (!validKeyframes(kf)) {
+          for (const field of ["tracks", "opacity"]) {
+            for (const [key, kf] of Object.entries(isPlainObject(s[field]) ? s[field] : {})) {
+              if (validKeyframes(kf)) continue;
               out.push(err("animation-keyframes-invalid",
-                `animation "${name}" track "${key}" has invalid keyframes`,
+                `animation "${name}" ${field === "opacity" ? "opacity track" : "track"} "${key}" has invalid keyframes`,
                 "Keyframes are `[[t, value], …]` with finite numbers, at least two entries, `t` strictly ascending from exactly 0 to exactly 1.",
-                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+                `${base}${a.steps ? `.steps[${i}]` : ""}.${field}.${key}`));
             }
           }
         });
@@ -175,7 +217,7 @@ export const ANIMATION_RULES = [
     run: ({ part }) => {
       const ranges = paramRanges(part);
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         rawSteps(a).forEach((s, i) => {
           for (const [key, kf] of Object.entries(isPlainObject(s.tracks) ? s.tracks : {})) {
             const r = ranges.get(key);
@@ -185,7 +227,7 @@ export const ANIMATION_RULES = [
                 out.push(err("animation-value-out-of-range",
                   `animation "${name}" track "${key}" keyframe value ${v}, outside the control's range ${r.min ?? "-∞"}..${r.max ?? "∞"}`,
                   "Keyframe values are applied as-is (the engine does not clamp) — widen the control's range or move the keyframe inside it.",
-                  `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+                  `${base}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
                 break; // one finding per track
               }
             }
@@ -195,17 +237,58 @@ export const ANIMATION_RULES = [
       return out;
     },
   },
+  {
+    id: "animation-opacity-unknown-part",
+    run: ({ part }) => {
+      const out = [];
+      for (const { view, name, a, base } of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const key of Object.keys(isPlainObject(s.opacity) ? s.opacity : {})) {
+            const sub = isPlainObject(part?.parts) ? part.parts[key] : undefined;
+            const inView = isPlainObject(sub) && Array.isArray(sub.views) && sub.views.includes(view);
+            if (!inView) {
+              out.push(err("animation-opacity-unknown-part",
+                `animation "${name}" fades "${key}", which is not a sub-part of view "${view}"`,
+                `Opacity tracks name sub-parts of the owning view — add "${view}" to \`parts.${key}.views\`, or correct the key.`,
+                `${base}${a.steps ? `.steps[${i}]` : ""}.opacity.${key}`));
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-opacity-range",
+    run: ({ part }) => {
+      const out = [];
+      for (const { name, a, base } of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const [key, kf] of Object.entries(isPlainObject(s.opacity) ? s.opacity : {})) {
+            if (!validKeyframes(kf)) continue; // keyframes rule already reported it
+            if (kf.some(([, v]) => v < 0 || v > 1)) {
+              out.push(err("animation-opacity-range",
+                `animation "${name}" opacity track "${key}" has values outside 0..1`,
+                "Opacity is 0 (fully hidden) to 1 (normal); it multiplies any static `display.opacity`.",
+                `${base}${a.steps ? `.steps[${i}]` : ""}.opacity.${key}`));
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
   {
     id: "animation-duration-invalid",
     run: ({ part }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         rawSteps(a).forEach((s, i) => {
           if (!(typeof s.duration === "number" && Number.isFinite(s.duration) && s.duration > 0)) {
             out.push(err("animation-duration-invalid",
               `animation "${name}"${a.steps ? ` step ${i}` : ""} has no positive \`duration\``,
               "Every animation (or step) needs a finite `duration` in seconds, greater than 0.",
-              `animations.${name}${a.steps ? `.steps[${i}]` : ""}.duration`));
+              `${base}${a.steps ? `.steps[${i}]` : ""}.duration`));
           }
         });
       }
@@ -216,7 +299,7 @@ export const ANIMATION_RULES = [
     id: "animation-loop-invalid",
     run: ({ part }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         if (a.loop === undefined) continue;
         // Type first, like `autoplay`. The runtime fails closed (normalizeAnimation
         // reads `spec.loop === true`), so a truthy non-boolean does NOT loop — it
@@ -227,14 +310,14 @@ export const ANIMATION_RULES = [
           out.push(err("animation-loop-invalid",
             `animation "${name}" has a non-boolean \`loop\``,
             "`loop` must be `true` or `false`. Any other truthy value still loops at runtime, so it cannot be left to mean something else.",
-            `animations.${name}.loop`));
+            `${base}.loop`));
           continue; // one error per field: the check below assumes a real boolean
         }
         if (a.loop && Array.isArray(a.steps) && a.steps.length > 1) {
           out.push(err("animation-loop-invalid",
             `animation "${name}" sets \`loop: true\` on a multi-step animation`,
             "Loop is for continuous single-phase motion (gears). A stepped sequence replays via the transport instead — drop `loop` or collapse to one step.",
-            `animations.${name}.loop`));
+            `${base}.loop`));
         }
       }
       return out;
@@ -244,7 +327,7 @@ export const ANIMATION_RULES = [
     id: "animation-step-label-duplicate",
     run: ({ part }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         if (!Array.isArray(a.steps)) continue;
         const seen = new Set();
         a.steps.forEach((s, i) => {
@@ -254,7 +337,7 @@ export const ANIMATION_RULES = [
             out.push(err("animation-step-label-duplicate",
               `animation "${name}" repeats the step label "${label}"`,
               "Step labels identify steps in the transport UI and the CLI's `--step <label>` — make each unique.",
-              `animations.${name}.steps[${i}].label`));
+              `${base}.steps[${i}].label`));
           }
           seen.add(label);
         });
@@ -278,9 +361,9 @@ export const ANIMATION_RULES = [
             path));
         }
       };
-      for (const [name, a] of animEntries(part)) {
-        check(a.easing, `animations.${name}.easing`);
-        if (Array.isArray(a.steps)) a.steps.forEach((s, i) => check(s?.easing, `animations.${name}.steps[${i}].easing`));
+      for (const { a, base } of animEntries(part)) {
+        check(a.easing, `${base}.easing`);
+        if (Array.isArray(a.steps)) a.steps.forEach((s, i) => check(s?.easing, `${base}.steps[${i}].easing`));
       }
       return out;
     },
@@ -290,7 +373,7 @@ export const ANIMATION_RULES = [
     run: ({ part }) => {
       const out = [];
       const badName = (v) => typeof v !== "string" || !CANONICAL_VIEWS.includes(v);
-      for (const [name, a] of animEntries(part)) {
+      for (const { name, a, base } of animEntries(part)) {
         const stepCameras = Array.isArray(a.steps)
           ? a.steps.map((s, i) => [s?.camera, i]).filter(([c]) => c !== undefined && c !== null)
           : [];
@@ -298,14 +381,14 @@ export const ANIMATION_RULES = [
           out.push(err("animation-camera-invalid",
             `animation "${name}" mixes an animation-level \`camera\` with per-step cameras`,
             "One camera mechanism per animation: either the animation-level name/cue-list, or per-step names — not both.",
-            `animations.${name}.camera`));
+            `${base}.camera`));
         }
         for (const [cam, i] of stepCameras) {
           if (badName(cam)) {
             out.push(err("animation-camera-invalid",
               `animation "${name}" step ${i} camera "${cam}" is not a canonical angle`,
               `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
-              `animations.${name}.steps[${i}].camera`));
+              `${base}.steps[${i}].camera`));
           }
         }
         // An explicit `camera: null` is "no camera", which is how
@@ -316,7 +399,7 @@ export const ANIMATION_RULES = [
             out.push(err("animation-camera-invalid",
               `animation "${name}" camera "${a.camera}" is not a canonical angle`,
               `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
-              `animations.${name}.camera`));
+              `${base}.camera`));
           }
         } else if (Array.isArray(a.camera)) {
           const cues = a.camera;
@@ -327,13 +410,13 @@ export const ANIMATION_RULES = [
             out.push(err("animation-camera-invalid",
               `animation "${name}" has an invalid camera cue list`,
               `Cues are \`[[t, angle], …]\` with t strictly ascending in 0..1 and angles from: ${CANONICAL_VIEWS.join(", ")}.`,
-              `animations.${name}.camera`));
+              `${base}.camera`));
           }
         } else {
           out.push(err("animation-camera-invalid",
             `animation "${name}" \`camera\` is neither an angle name nor a cue list`,
             "Use a canonical angle string, or `[[t, angle], …]` cues.",
-            `animations.${name}.camera`));
+            `${base}.camera`));
         }
       }
       return out;
@@ -342,11 +425,11 @@ export const ANIMATION_RULES = [
   {
     id: "animation-description-invalid",
     run: ({ part }) => animEntries(part)
-      .filter(([, a]) => a.description !== undefined && typeof a.description !== "string")
-      .map(([name]) => err("animation-description-invalid",
+      .filter(({ a }) => a.description !== undefined && typeof a.description !== "string")
+      .map(({ name, base }) => err("animation-description-invalid",
         `animation "${name}" \`description\` is not a string`,
         "The description is CommonMark shown behind the ⓘ glyph — supply a string or omit it.",
-        `animations.${name}.description`)),
+        `${base}.description`)),
   },
   {
     // note tier: performance shape, not correctness. A track whose param feeds
@@ -355,7 +438,7 @@ export const ANIMATION_RULES = [
     id: "animation-track-rebuilds",
     run: ({ part, p }) => {
       const out = [];
-      for (const [name, a] of animEntries(part)) {
+      for (const { view, name, a, base } of animEntries(part)) {
         const steps = rawSteps(a);
         // value range per key: the min and max across every keyframe value the
         // key ever takes, over every step that tracks it — not just the first
@@ -377,14 +460,14 @@ export const ANIMATION_RULES = [
         }
         for (const [key, [v0, v1]] of valueRange) {
           if (typeof part?.defaults?.[key] !== "number") continue; // other rules own that
-          const cls = classifyTrack(part, p, key, v0, v1);
+          const cls = classifyTrack(part, p, key, v0, v1, view);
           if (cls === "pose") continue;
           out.push(note("animation-track-rebuilds",
             cls === "rebuild"
               ? `animation "${name}" track "${key}" rebuilds geometry — playback is best-effort, not frame-rate`
               : `animation "${name}" track "${key}" cannot use the pose fast path (untrusted probe) — playback is best-effort`,
             "Frame-rate playback needs the param to feed only rigid placement (translate/rotate in `place()` or at the end of `build`). If that's the intent, restructure so the param never feeds a geometry op, a query, or a function selector; if geometry morphing is the intent, this is expected.",
-            `animations.${name}`));
+            base));
         }
       }
       return out;
@@ -394,49 +477,51 @@ export const ANIMATION_RULES = [
     id: "animation-autoplay-invalid",
     run: ({ part }) => {
       const out = [];
-      let first = null;
-      for (const [name, a] of animEntries(part)) {
+      // Autoplay is scoped to the view that owns it: the transport bar shows one
+      // view's animations at a time, so two views may each auto-start their own.
+      const firstByView = new Map();
+      for (const { view, name, a, base } of animEntries(part)) {
         if (a.autoplay !== undefined && typeof a.autoplay !== "boolean") {
           out.push(err("animation-autoplay-invalid",
             `animation "${name}" \`autoplay\` is not a boolean`,
-            "Use `autoplay: true` on the one animation that should start on its own.",
-            `animations.${name}.autoplay`));
+            "Use `autoplay: true` on the one animation in each view that should start on its own.",
+            `${base}.autoplay`));
           continue;
         }
         if (a.autoplay !== true) continue;
-        if (first == null) { first = name; continue; }
+        if (!firstByView.has(view)) { firstByView.set(view, name); continue; }
         out.push(err("animation-autoplay-invalid",
-          `animations "${first}" and "${name}" both declare \`autoplay\``,
-          "Only one animation can auto-start — remove `autoplay` from all but one.",
-          `animations.${name}.autoplay`));
+          `animations "${firstByView.get(view)}" and "${name}" both declare \`autoplay\` in view "${view}"`,
+          "Only one animation per view can auto-start — remove `autoplay` from all but one.",
+          `${base}.autoplay`));
       }
       return out;
     },
   },
 ];
 
-// Classify one animated param by probing every sub-part it can show, at the
-// track's two endpoint values: identical trusted baseHashes at both ends →
-// the param only re-poses ("pose"); differing hashes → real geometry
-// ("rebuild"); any untrusted probe → "untrusted" (the fast path will decline
-// it at runtime too). Mirrors the runtime trust model in pose-probe-core.js.
-function classifyTrack(part, p, key, v0, v1) {
+// Classify one animated param by probing every sub-part the OWNING view can
+// show, at the track's two endpoint values: identical trusted baseHashes at
+// both ends → the param only re-poses ("pose"); differing hashes → real
+// geometry ("rebuild"); any untrusted probe → "untrusted" (the fast path will
+// decline it at runtime too). Mirrors the runtime trust model in
+// pose-probe-core.js. Sub-parts outside the owning view cannot be moved by this
+// animation, so probing them would only manufacture false notes.
+function classifyTrack(part, p, key, v0, v1, view) {
   let result = "pose";
-  for (const view of Object.keys(isPlainObject(part?.views) ? part.views : {})) {
-    for (const sp of Object.values(isPlainObject(part?.parts) ? part.parts : {})) {
-      if (!Array.isArray(sp?.views) || !sp.views.includes(view)) continue;
-      const probes = [];
-      for (const v of [v0, v1]) {
-        const pv = { ...p, [key]: v };
-        let dv;
-        try { dv = resolveDerived(part, pv) ?? {}; } catch { return "untrusted"; }
-        try { if (sp.enabled && !sp.enabled(pv)) { probes.push(null); continue; } } catch { return "untrusted"; }
-        probes.push(probeSubPartPose(sp, { view, purpose: "display", p: pv, d: dv }));
-      }
-      if (probes.some((x) => x && !x.trusted)) return "untrusted";
-      const [a, b] = probes;
-      if (a && b && a.baseHash !== b.baseHash) result = "rebuild";
+  for (const sp of Object.values(isPlainObject(part?.parts) ? part.parts : {})) {
+    if (!Array.isArray(sp?.views) || !sp.views.includes(view)) continue;
+    const probes = [];
+    for (const v of [v0, v1]) {
+      const pv = { ...p, [key]: v };
+      let dv;
+      try { dv = resolveDerived(part, pv) ?? {}; } catch { return "untrusted"; }
+      try { if (sp.enabled && !sp.enabled(pv)) { probes.push(null); continue; } } catch { return "untrusted"; }
+      probes.push(probeSubPartPose(sp, { view, purpose: "display", p: pv, d: dv }));
     }
+    if (probes.some((x) => x && !x.trusted)) return "untrusted";
+    const [a, b] = probes;
+    if (a && b && a.baseHash !== b.baseHash) result = "rebuild";
   }
   return result;
 }

package/src/framework/mount.js

@@ -32,8 +32,10 @@ import { resolveDefaultView } from "./default-view.js";
 export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView }) {
   return {
     ready, dispose, setParams,
-    // Part-declared animation playback (spec 2026-08-02): null when the part
-    // declares no animations. { play(name?), pause(), seek(t), stop(), state() }.
+    // Part-declared animation playback (spec 2026-08-02): animations are
+    // VIEW-owned, so this is null only when NO view declares any.
+    // { play(name?), pause(), seek(t), stop(), state() } — play(name) resolves
+    // within the ACTIVE view's set, and state() reports that view.
     animation: animation ?? null,
     // Active view name (never null once mounted). See onViewChange for the push side.
     getView,
@@ -122,13 +124,20 @@ function createCleanupStack() {
 //                                 // loop would otherwise render a hidden pane forever.
 //                                 // Captures still work while parked (they re-allocate).
 //                                 // setActive(true) restores it. Safe after dispose().
-//   runtime.animation?.play("open");  // part-declared animation playback: null when the
-//                                 // part declares no animations, else
+//   runtime.animation?.play("open");  // part-declared animation playback: animations are
+//                                 // VIEW-owned, so this is null only when NO view
+//                                 // declares any, else
 //                                 // { play(name?), pause(), seek(t), stop(), state() }.
-//                                 // play() with an unknown name warns and does nothing;
-//                                 // any user/host param edit pauses playback. A part's
-//                                 // `autoplay: true` animation self-starts on first show
-//                                 // and each view switch until the user touches the
+//                                 // play(name) resolves within the ACTIVE view's set —
+//                                 // an unknown name (including one declared by a
+//                                 // different view) warns and does nothing; state()
+//                                 // reports the view it applies to. Switching views
+//                                 // restores the outgoing animation's params, then
+//                                 // presents the incoming view's own set (empty in a
+//                                 // view that declares none). Any user/host param edit
+//                                 // pauses playback. A view's `autoplay: true` animation
+//                                 // self-starts when that view is first shown and on
+//                                 // each switch to it, until the user touches the
 //                                 // transport — no runtime call needed for that part.
 //   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
 //                                 // OS gave up — surface it rather than showing a dead
@@ -139,10 +148,16 @@ function createCleanupStack() {
 // onViewChange fires once synchronously during mount with the initial resolved
 // view (before ready), then again on every subsequent view change (user click
 // or a programmatic setView) — always the new view name.
+// onParamsCommit({ changed, params })   // the user FINISHED editing a panel control (slider
+//                                         // released, box committed, checkbox ticked, preset
+//                                         // applied): `changed` lists the keys written, `params`
+//                                         // is a snapshot copy. Never fired by setParams or
+//                                         // animation playback — hosts call setParams from their
+//                                         // own undo/reset, and firing here would loop.
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -233,6 +248,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // cached assembly instantly if it's current, else auto-builds what's missing.
     const tabsCtl = createViewTabs(els.tabs, part, {
       onChange: (name) => {
+        // FIRST: the outgoing animation restores its param snapshot, so the
+        // incoming view composes its assembly from un-animated params. Anything
+        // that reads params (refreshView / updateRelevance / the loop kick) must
+        // run after it. autoplayKick stays LAST — it starts the new view's own.
+        animCtl?.viewChanged();
         pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick();
         onViewChange?.(name);
       },
@@ -487,7 +507,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const panel = buildControls(els.controls, part.parameters, params, () => {
       animCtl?.notifyUserEdit();
       onParamChange();
-    });
+    }, onParamsCommit
+      ? (changed) => onParamsCommit({ changed, params: { ...params } })
+      : undefined);
     cleanup.defer(() => panel.dispose());
     const updateRelevance = () => {
       // A throwing derive() must not break every slider drag — mount's pick
@@ -540,11 +562,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       loop.kick();
     }
 
-    // Animation transport + driver (no-op null when the part declares none).
+    // Animation transport + driver (null when NO view declares animations).
+    // Animations are view-owned: `getView` is how the driver knows which view's
+    // set is live, both at attach and after every `viewChanged()`.
     animCtl = attachAnimationControls(viewer, part, {
       container: els.viewer,
       applyValues: applyAnimationValues,
       getParamValues: (keys) => Object.fromEntries(keys.map((k) => [k, params[k]])),
+      getView: view,
     });
     if (animCtl) cleanup.defer(() => animCtl.detach());