partforge 0.49.0 → 0.50.0

package/src/framework/viewer.js

@@ -177,6 +177,115 @@ export function createViewer(container, part) {
     partsGroup.add(l);
   }
 
+  // --- animated per-sub-part opacity (display-only) ---------------------------
+  // Overrides from the animation driver (spec 2026-08-10-per-view-animations):
+  // absent = normal, 0 = fully hidden (mesh AND lines), 0<v<1 = faded on cloned
+  // materials. Never touches geometry, params, or exports — this is the display
+  // half of "fade a part in, then animate it into place".
+  const animOpacity = new Map();     // name -> value in [0, 1)
+  const baseMats = Object.fromEntries(names.map((n) => [n, subMesh[n].material]));
+  const fadeMats = new Map();        // name -> lazily cloned MeshStandardMaterial
+  const fadeLineMats = new Map();    // name -> lazily cloned LineMaterial
+  const fadeUnregisters = new Map(); // fade material -> its cutaway unregister fn
+  let lastShown = [];                // names last passed to showAssembly
+
+  const effectiveVisible = () => lastShown.filter((n) => (animOpacity.get(n) ?? 1) > 0);
+
+  // A fade clone is a material the cutaway does not own, so it has to be told
+  // about the clipping plane explicitly — otherwise a mid-fade part renders
+  // un-sectioned while its stencil caps and cut-face outline keep drawing.
+  // registerClippableMaterial syncs immediately, so a clone created while the
+  // cutaway is already on picks up the current state.
+  //
+  // Known cosmetic remainder, accepted: the hatch cap keeps its full-strength
+  // opacity while the surface above it fades, because the cap derives its
+  // colour/opacity from the base material at refreshSourceMaterial time. A part
+  // at opacity 0 drops out of the cutaway's visible set entirely, so the cap
+  // only over-reads during the transient middle of a fade; re-deriving cap
+  // opacity per frame would cost a material rebuild for a state that lasts
+  // under a second.
+  function fadeMatFor(name) {
+    let m = fadeMats.get(name);
+    if (!m) {
+      m = baseMats[name].clone();
+      m.transparent = true;
+      m.depthWrite = false;
+      fadeUnregisters.set(m, cutaway.registerClippableMaterial(m));
+      fadeMats.set(name, m);
+    }
+    return m;
+  }
+  function fadeLineMatFor(name) {
+    let m = fadeLineMats.get(name);
+    if (!m) {
+      m = lineMaterial.clone();
+      m.transparent = true;
+      m.resolution.copy(lineMaterial.resolution);
+      fadeUnregisters.set(m, cutaway.registerClippableMaterial(m));
+      fadeLineMats.set(name, m);
+    }
+    return m;
+  }
+
+  // Re-derive one sub-part's material + visibility from (shown, override).
+  function applySubOpacity(name) {
+    const mesh = subMesh[name], lines = subLines[name];
+    if (!mesh) return;
+    const shown = lastShown.includes(name);
+    const v = animOpacity.get(name);
+    if (v === undefined) {
+      // Restore ONLY from our own fade clone. showAssembly runs on every regen
+      // (mount.js's refreshView) without disabling the cutaway, and an enabled
+      // cutaway has swapped these onto its clipped clones
+      // (createSectionRenderSet.setEnabled) — an unconditional write here would
+      // silently drop clipping on every sub-part on the next param edit.
+      const hadFade = mesh.material === fadeMats.get(name);
+      if (hadFade) mesh.material = baseMats[name];
+      if (lines.material === fadeLineMats.get(name)) lines.material = lineMaterial;
+      // We just took the mesh off our clone, so an enabled cutaway must get the
+      // chance to re-claim it onto its clipped clone — the base material we
+      // wrote above carries no plane, and nothing else would put it back until
+      // the next cutaway toggle or theme change. Guarded on hadFade so the
+      // every-regen showAssembly path stays a no-op for un-faded sub-parts.
+      if (hadFade) cutaway.resyncSubpart(name);
+      mesh.visible = shown;
+      lines.visible = shown;
+      return;
+    }
+    if (v <= 0) {
+      mesh.visible = false;
+      lines.visible = false;
+      return;
+    }
+    const staticOpacity = part.parts[name].display?.opacity ?? 1;
+    const fm = fadeMatFor(name);
+    fm.opacity = staticOpacity * v;
+    mesh.material = fm;
+    const flm = fadeLineMatFor(name);
+    flm.opacity = v;
+    lines.material = flm;
+    mesh.visible = shown;
+    lines.visible = shown;
+  }
+
+  function setSubPartOpacity(name, value) {
+    if (!subMesh[name]) return;
+    const wasZero = (animOpacity.get(name) ?? 1) <= 0;
+    if (value == null || !(value < 1)) animOpacity.delete(name); // null/undefined/NaN/>=1 clear
+    else animOpacity.set(name, Math.max(0, value));
+    applySubOpacity(name);
+    const isZero = (animOpacity.get(name) ?? 1) <= 0;
+    if (wasZero !== isZero) cutaway.setVisible(effectiveVisible());
+  }
+
+  function clearSubPartOpacities() {
+    if (!animOpacity.size) return;
+    const touched = [...animOpacity.keys()];
+    animOpacity.clear();
+    for (const n of touched) applySubOpacity(n);
+    cutaway.setVisible(effectiveVisible());
+  }
+
   // The cutaway plane lives in world space, so its initial/reset bounds must
   // include the pivot rotation and the per-view recentering transform —
   // mesh.matrixWorld carries both. Union each visible mesh's own
@@ -347,17 +456,19 @@ export function createViewer(container, part) {
   // frame the camera to them — done only on the initial show and on view (tab)
   // changes, NOT on regeneration, so a user's zoom/orbit survives editing params.
   function showAssembly(visibleNames, { frame = false } = {}) {
-    for (const [name, mesh] of Object.entries(subMesh)) {
-      const on = visibleNames.includes(name);
-      if (on) {
-        mesh.geometry = subCache[name]; // cached geometries reused, not disposed
+    lastShown = [...visibleNames];
+    for (const name of names) {
+      if (visibleNames.includes(name)) {
+        subMesh[name].geometry = subCache[name]; // cached geometries reused, not disposed
         subLines[name].geometry = subCache[name].userData.edges;
+        applySubOpacity(name); // shown, but an active 0-override keeps it hidden
+      } else {
+        subMesh[name].visible = false;
+        subLines[name].visible = false;
       }
-      mesh.visible = on;
-      subLines[name].visible = on;
     }
     if (frame) frameTo(visibleNames);
-    cutaway.setVisible(visibleNames);
+    cutaway.setVisible(effectiveVisible());
   }
 
   // Re-frame whatever is currently visible (the reframe button).
@@ -365,8 +476,22 @@ export function createViewer(container, part) {
     frameTo(names.filter((n) => subMesh[n].visible && subCache[n]));
   }
 
+  // Call after anything that rewrites sub-part materials out from under us.
+  // The cutaway assigns mesh.material itself — the clipped clone on enable, the
+  // captured original on disable, and a freshly re-cloned pair on every
+  // refreshSourceMaterial (which setTheme drives) — so a live fade has to be
+  // re-asserted on top or a PAUSED mid-fade part sticks at full opacity. A
+  // playing animation would self-heal on its next frame; a paused one has no
+  // next frame. Only the calls that reassign materials need this: flip and
+  // reset move the plane and nothing else.
+  function reassertLiveFades() {
+    for (const n of animOpacity.keys()) applySubOpacity(n);
+  }
+
   function setCutawayEnabled(on) {
-    return cutaway.setEnabled(on);
+    const result = cutaway.setEnabled(on);
+    reassertLiveFades();
+    return result;
   }
 
   // Swap the scene background, grid, and edge-line colors for the given theme.
@@ -378,10 +503,13 @@ export function createViewer(container, part) {
     grid.position.y = floorY; // keep the floor at the bbox bottom across theme swaps
     scene.add(grid);
     lineMaterial.color.set(t.line);
+    for (const m of fadeLineMats.values()) m.color.set(t.line); // clones follow the theme
     cutaway.setTheme(mode, t.line);
+    reassertLiveFades(); // setTheme re-clones every section's materials and reassigns them
   }
 
   function hideAssembly() {
+    lastShown = [];
     for (const m of Object.values(subMesh)) m.visible = false;
     for (const l of Object.values(subLines)) l.visible = false;
     cutaway.setVisible([]);
@@ -399,6 +527,7 @@ export function createViewer(container, part) {
     camera.aspect = w / h;
     camera.updateProjectionMatrix();
     lineMaterial.resolution.set(w, h); // fat lines need the viewport size for px width
+    for (const m of fadeLineMats.values()) m.resolution.set(w, h); // clones need it too
     cutaway.setViewportSize(w, h, renderer.getPixelRatio());
   }
   const ro = new ResizeObserver(resize);
@@ -720,9 +849,22 @@ export function createViewer(container, part) {
     for (const n of names) {
       const g = subCache[n];
       if (g) { g.userData.edges?.dispose(); g.dispose(); subCache[n] = null; }
-      subMesh[n].material?.dispose();
+      // baseMats[n], not subMesh[n].material: an active fade override has swapped
+      // the mesh onto a clone, and the base material would otherwise leak.
+      baseMats[n]?.dispose();
       subMesh[n].geometry?.dispose(); // the initial empty BufferGeometry, if never replaced
     }
+    // Hand the fade clones back before freeing them. cutaway.dispose() above has
+    // already restored their original clippingPlanes and emptied its registry,
+    // so these unregister closures find no entry and return without touching a
+    // disposed cutaway. They still earn their place: they release this map's
+    // hold on the registry's unregister closures rather than leaving it to GC.
+    for (const off of fadeUnregisters.values()) off();
+    fadeUnregisters.clear();
+    for (const m of fadeMats.values()) m.dispose();
+    for (const m of fadeLineMats.values()) m.dispose();
+    fadeMats.clear();
+    fadeLineMats.clear();
     material.dispose();
     lineMaterial.dispose();
     grid.geometry.dispose();
@@ -737,6 +879,8 @@ export function createViewer(container, part) {
     hideAssembly,
     setSubGeometry,
     setSubPose,
+    setSubPartOpacity,
+    clearSubPartOpacities,
     hasSubMesh,
     subTriangles,
     frame,
@@ -756,6 +900,8 @@ export function createViewer(container, part) {
     camera,
     domElement: renderer.domElement,
     _subMeshes: subMesh,
+    __subMesh: (n) => subMesh[n],   // test hooks (cf. attachAnimationControls' __viewer)
+    __subLines: (n) => subLines[n],
     flashPoint,
     cutawaySupported: () => cutaway.isSupported,
     cutawayEnabled: () => cutaway.isEnabled,

package/src/parts/hinged-box.js

@@ -1,7 +1,10 @@
 // Animation reference part — a box with a hinged lid. Worked example for
-// docs/AUTHORING-PARTS.md "Animations": pose-only animated params (lidAngle,
-// lidLift) driven through place(), an intro camera + markdown description on
-// `open`, a looping `cycle`, and a stepped `assemble` with per-step cameras.
+// docs/AUTHORING-PARTS.md "Animations": animations are VIEW-OWNED (declared
+// under `views.box.animations`, so the transport bar belongs to that view),
+// they drive pose-only params (lidAngle, lidLift) through place(), and
+// `assemble` opens with an OPACITY fade that brings the lid in from nothing
+// before any motion. Also shown: an intro camera + markdown description on
+// `open`, a looping autoplay `cycle`, and per-step cameras on `assemble`.
 export default {
   meta: { title: "Hinged Box", units: "mm" },
   parameters: [
@@ -58,30 +61,43 @@ export default {
           : s.rotate(-p.lidAngle, [0, p.depth, p.height], [1, 0, 0]).translate([0, 0, p.lidLift]),
     },
   },
-  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",
-      duration: 1.2,
-      tracks: { lidAngle: [[0, 0], [1, 110]] },
-    },
-    cycle: {
-      label: "Open / close",
-      duration: 2.4,
-      loop: true,
-      easing: "linear",
-      autoplay: true,
-      tracks: { lidAngle: [[0, 0], [0.5, 110], [1, 0]] },
-    },
-    assemble: {
-      label: "Assemble",
-      description: "How the parts come together: the lid drops onto the base, then swings open to check hinge clearance.",
-      steps: [
-        { 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]] } },
-      ],
+  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",
+          duration: 1.2,
+          tracks: { lidAngle: [[0, 0], [1, 110]] },
+        },
+        cycle: {
+          label: "Open / close",
+          duration: 2.4,
+          loop: true,
+          easing: "linear",
+          autoplay: true,
+          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: [
+            // The lidLift hold-track pins the lift at 40 while the lid fades in,
+            // so step 2's drop starts from where the fade showed it. Without it
+            // the lift would hold step 2's FIRST keyframe — also 40 — but
+            // stating it makes the pose explicit and survives a retune of step 2.
+            { label: "Lid appears", camera: "iso", duration: 0.8,
+              opacity: { lid: [[0, 0], [1, 1]] },
+              tracks: { lidLift: [[0, 40], [1, 40]] } },
+            { 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]] } },
+          ],
+        },
+      },
     },
   },
   verify: {

package/src/testing/render.js

@@ -32,21 +32,50 @@ const norm = (a) => { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0]
 // rasterizer (orthographic, z-buffered, Lambert-shaded, with depth-tested edge
 // overlays). No native module, no browser. Returns the written file paths.
 // pngjs is lazy-imported so importing the testing barrel for measure never loads it.
+//
+// `opacity` is a Record<subPartName, number> (an animation's evaluate() output,
+// typically): a sub-part at 0 is skipped entirely — faces AND edges — but it
+// still counts toward the SCENE BOUNDS, so a part crossing 0 cannot silently
+// reframe the still. Framing is a property of the pose, not of what happens to
+// be visible: without that, `--at 0,0.5,1` over a fade drew the same base at
+// three different scales and the sequence read as a zoom.
+// Values in (0,1) fade by PRE-BLENDING that part's shaded base and edge
+// colours toward the background. That is a z-buffered approximation: a faded
+// part still fully occludes whatever is behind it, because real transparency
+// needs back-to-front sorting this rasterizer does not do. Stills only need to
+// read as faded, so the approximation is the contract, not a stopgap.
 export async function renderViews(kernel, part, view = Object.keys(part.views)[0], {
   views = ["iso", "front", "top"], out = "render", size = [800, 600], edges = true, params = {}, tag = "",
+  opacity = {},
 } = {}) {
   const { PNG } = await import("pngjs");
   const [W, H] = size;
-  const meshes = buildView(kernel, part, view, params).map((b) => b.mesh); // copied out
+  // Sub-part names are kept alongside the meshes: opacity is keyed by name.
+  // Own-key lookups only — a part named "constructor" must not inherit a value
+  // off Object.prototype and vanish from the render.
+  const opacityOf = (name) => {
+    if (!Object.hasOwn(opacity ?? {}, name)) return 1;
+    const v = Number(opacity[name]);
+    return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 1; // a junk value renders solid
+  };
+  const built = buildView(kernel, part, view, params) // copied out
+    .map((b) => ({ name: b.name, mesh: b.mesh }));
 
-  // scene bounds over all sub-parts (positions are JS-owned; safe after cleanup)
+  // Scene bounds over EVERY built sub-part, visible or not (positions are
+  // JS-owned; safe after cleanup). Opacity is deliberately NOT consulted here —
+  // see the note above on why a fade must not move the camera.
   const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
-  for (const m of meshes) {
+  for (const { mesh: m } of built) {
     const b = bounds(m.positions);
     for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], b.min[i]); hi[i] = Math.max(hi[i], b.max[i]); }
   }
+  // kernel.cleanup() walks the backend's own tracked list, not this array, so
+  // dropping the hidden sub-parts afterwards frees nothing and skips nothing.
   kernel.cleanup?.();
 
+  // …and only the visible ones are rasterized: faces AND edges below iterate this.
+  const meshes = built.filter(({ name }) => opacityOf(name) > 0);
+
   const center = [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2];
   const radius = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) / 2 || 5;
 
@@ -84,7 +113,12 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
     for (let i = 0; i < W * H; i++) { color[i * 3] = bg[0]; color[i * 3 + 1] = bg[1]; color[i * 3 + 2] = bg[2]; }
     const zbuf = new Float32Array(W * H).fill(-Infinity); // larger depth = nearer camera
 
-    for (const m of meshes) {
+    for (const { name, mesh: m } of meshes) {
+      // Pre-blend toward the background: the fade is baked into the material
+      // colour before shading, so no per-pixel compositing (and no depth sort)
+      // is needed. See the note on renderViews for why that is enough here.
+      const v = opacityOf(name);
+      const faded = v < 1 ? base.map((c, i) => Math.round(c * v + bg[i] * (1 - v))) : base;
       const P = m.positions, N = m.normals, ind = m.indices;
       // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle);
       // OCCT meshes are indexed. Both carry per-vertex normals.
@@ -109,16 +143,18 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
           const I0 = Math.min(1, ambient + diffuse * Math.abs((nx * light[0] + ny * light[1] + nz * light[2]) / L));
           inten = [I0, I0, I0];
         }
-        rasterTri(sp, inten, base, color, zbuf, W, H);
+        rasterTri(sp, inten, faded, color, zbuf, W, H);
       }
     }
 
     if (edges) {
-      for (const m of meshes) {
+      for (const { name, mesh: m } of meshes) {
         const E = m.edges;
         if (!E?.length) continue;
+        const v = opacityOf(name);
+        const fadedEdge = v < 1 ? edgeColor.map((c, i) => Math.round(c * v + bg[i] * (1 - v))) : edgeColor;
         for (let i = 0; i < E.length; i += 6)
-          drawLine(project([E[i], E[i + 1], E[i + 2]]), project([E[i + 3], E[i + 4], E[i + 5]]), edgeColor, color, zbuf, W, H, bias);
+          drawLine(project([E[i], E[i + 1], E[i + 2]]), project([E[i + 3], E[i + 4], E[i + 5]]), fadedEdge, color, zbuf, W, H, bias);
       }
     }
 

package/types/index.d.ts

@@ -146,8 +146,13 @@ export interface CaptureViewOptions {
 export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
 
 export interface AnimationState {
-  /** The selected animation's key. */
-  animation: string;
+  /** The active view (tab) name — animations belong to a view. */
+  view: string;
+  /**
+   * The selected animation's key, or `null` while the active view declares no
+   * animations. Switching views re-selects that view's first animation.
+   */
+  animation: string | null;
   status: AnimationStatus;
   /** Position on the timeline, 0..1 over the animation's total duration. */
   t: number;
@@ -158,12 +163,16 @@ export interface AnimationState {
 /**
  * Part-declared animation playback — the same engine the viewer's transport bar
  * drives. Playback writes real params, so exporting while paused exports the
- * posed state, and any user or host param edit pauses it.
+ * posed state, and any user or host param edit pauses it. An animation's
+ * `opacity` tracks are the exception: display-only, never written to params and
+ * never visible to export.
  */
 export interface AnimationRuntime {
   /**
-   * Play, optionally switching to a named animation first. An unknown name
-   * warns and does nothing rather than playing whatever is selected.
+   * Play, optionally switching to a named animation first. The name resolves
+   * within the ACTIVE view — an animation declared by another view is not
+   * playable from here. An unknown name warns and does nothing rather than
+   * playing whatever is selected.
    */
   play(name?: string): void;
   pause(): void;
@@ -239,8 +248,9 @@ export interface PartRuntime {
    */
   setHostPane(pane: HostPane): void;
   /**
-   * Part-declared animation playback, or `null` when the part declares no
-   * `animations` block.
+   * Part-declared animation playback, or `null` when NO view declares an
+   * `animations` block. Non-null while any view does — including while the
+   * active view has none, where `state().animation` reads `null`.
    */
   animation: AnimationRuntime | null;
 }

package/types/part.d.ts

@@ -308,6 +308,14 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
 
 export interface ViewDefinition {
   label: string;
+  /**
+   * Named animations belonging to this view — keyframe data driving this view's
+   * params and sub-part opacity over time. See `AnimationSpec` below; the
+   * transport bar shows one view's animations at a time, and `play(name)`
+   * resolves within the active view. Animations live ONLY here: a top-level
+   * `part.animations` is a lint error and is ignored at runtime.
+   */
+  animations?: Record<string, AnimationSpec>;
 }
 
 // --- the verify block -------------------------------------------------------
@@ -430,12 +438,20 @@ export interface AnimationStep {
   /**
    * Param key -> keyframes. A param tracked nowhere keeps its current value.
    *
-   * Optional so a step can move only the camera — an establishing shot that
-   * holds the pose while the view swings round. `partforge lint` still requires
-   * that at least one step in the animation carries tracks, which is a
-   * whole-animation rule the type system can't express per step.
+   * Optional so a step can carry only `opacity`, or move only the camera — an
+   * establishing shot that holds the pose while the view swings round.
+   * `partforge lint` still requires that at least one step in the animation
+   * carries `tracks` or `opacity`, which is a whole-animation rule the type
+   * system can't express per step.
    */
   tracks?: Record<string, Keyframes>;
+  /**
+   * Sub-part name → opacity keyframes (values 0–1; 0 = fully hidden, mesh and
+   * edge lines both; multiplies any static `display.opacity`). Same keyframe
+   * rules as `tracks`; the same hold rule applies across steps. Display-only:
+   * never affects params, export, measure, or verify.
+   */
+  opacity?: Record<string, Keyframes>;
   /** Swing the camera to this angle when the step begins. */
   camera?: CameraCue;
 }
@@ -460,7 +476,7 @@ export interface AnimationSpecCommon {
   /**
    * Start this animation automatically on first show and again on each view
    * switch, until the user touches the transport. At most one animation per
-   * part may set this; `partforge lint` enforces it
+   * VIEW may set this; `partforge lint` enforces it
    * (`animation-autoplay-invalid`). Not armed when the browser reports
    * `prefers-reduced-motion: reduce`.
    */
@@ -468,10 +484,12 @@ export interface AnimationSpecCommon {
 }
 
 /**
- * An animation is EITHER single-phase (`tracks` + `duration`) OR stepped
- * (`steps`) — never both, never neither. `partforge lint` enforces that
- * (`animation-tracks-or-steps`), and the union says the same thing, so a block
- * carrying both is rejected before it ever reaches lint.
+ * An animation is EITHER single-phase (`tracks` and/or `opacity`, plus a
+ * `duration`) OR stepped (`steps`) — never both, never neither. `partforge
+ * lint` enforces that (`animation-tracks-or-steps`), and the union says the
+ * same thing, so a block carrying both is rejected before it ever reaches lint.
+ * The first two arms are the two ways to satisfy "at least one of
+ * `tracks`/`opacity`".
  */
 export type AnimationSpec =
   | (AnimationSpecCommon & {
@@ -479,12 +497,22 @@ export type AnimationSpec =
       duration: number;
       /** Param key -> keyframes. */
       tracks: Record<string, Keyframes>;
+      /** Sub-part name -> opacity keyframes (see AnimationStep.opacity). */
+      opacity?: Record<string, Keyframes>;
+      steps?: never;
+    })
+  | (AnimationSpecCommon & {
+      duration: number;
+      tracks?: Record<string, Keyframes>;
+      /** An opacity-only animation is legal — a pure fade. */
+      opacity: Record<string, Keyframes>;
       steps?: never;
     })
   | (AnimationSpecCommon & {
       /** The multi-step form; each step carries its own relative `duration`. */
       steps: AnimationStep[];
       tracks?: never;
+      opacity?: never;
       duration?: never;
     });
 
@@ -510,10 +538,8 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   derive?: DeriveSpec<P, D>;
   /** Named sub-parts; each builds exactly one solid. */
   parts: Record<string, SubPartDefinition<P, D>>;
-  /** The view tabs. A view is a set of sub-parts. */
+  /** The view tabs. A view is a set of sub-parts, and owns its own `animations`. */
   views: Record<string, ViewDefinition>;
   /** Self-verification, co-located with the schema. */
   verify?: VerifyBlock<P, D>;
-  /** Named animations: keyframe data driving existing params over time. */
-  animations?: Record<string, AnimationSpec>;
 }

package/types/testing.d.ts

@@ -358,5 +358,13 @@ export function renderViews(
     size?: [number, number];
     edges?: boolean;
     params?: ResolvedParams;
+    /** Frame suffix in the written filename (`<part>-<view>-<angle>-<tag>.png`). */
+    tag?: string;
+    /**
+     * Per-sub-part opacity, keyed by sub-part name (an animation `evaluate()`
+     * result). `0` omits the sub-part entirely; `0 < v < 1` fades it toward the
+     * background. Absent keys render solid.
+     */
+    opacity?: Record<string, number>;
   },
 ): Promise<string[]>;