partforge 0.49.0 → 0.51.0

package/src/framework/mount.js

@@ -5,7 +5,7 @@ import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
-import { createTooltipPresenter } from "./tooltip.js";
+import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
 import { relevantParamKeys } from "./param-deps.js";
@@ -29,11 +29,17 @@ import { resolveDefaultView } from "./default-view.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView }) {
+// The default no-op tooltip binding, so a host can hold on to whatever
+// attachTooltips returned without caring whether this mount resolved one.
+const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {} };
+
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips }) {
   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,
@@ -58,6 +64,12 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // (partforge-cloud does, at the window level). Defaulted to a no-op so the
     // handle's shape never depends on whether this mount resolved a rail.
     setHostPane: setHostPane ?? (() => {}),
+    // Join host-owned chrome buttons to this mount's shared hover tooltip, so
+    // a host's own viewbar/rail-foot buttons match the built-in ones. Entries
+    // are [{ element, getLabel? }] (label falls back to the button's
+    // title/aria-label); returns { sync, hide, detach }. Same no-op default
+    // stance as setHostPane above.
+    attachTooltips: attachTooltips ?? (() => NOOP_TOOLTIP_BINDING),
   };
 }
 
@@ -114,6 +126,15 @@ function createCleanupStack() {
 //   runtime.setHostPane("rail");  // narrow layout only: show just the controls
 //                                 // rail ('stage' | 'rail'), suppressing the
 //                                 // built-in tab bar. null hands selection back.
+//   runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join the
+//                                 // mount's shared hover tooltip (the viewbar one).
+//                                 // Label = the button's title (or aria-label), or a
+//                                 // per-entry getLabel(); the title attribute is
+//                                 // absorbed while attached so it can't double up as a
+//                                 // native tooltip, and restored on detach. Returns
+//                                 // { sync, hide, detach } — call sync() after you
+//                                 // toggle a button's disabled state. Detached
+//                                 // automatically on dispose().
 //   runtime.setActive(false);     // park the viewer: stop the render loop and release
 //                                 // both large GPU allocations (the drawing buffer and
 //                                 // the cached capture target). For a host that hides the
@@ -122,13 +143,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
@@ -194,7 +222,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => cutawayChrome.detach());
     // Resizable/collapsible controls rail. No-ops when the host lays out the
     // framework itself (no #panel / no elements.rail).
-    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell });
+    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell, tooltip });
     cleanup.defer(() => railChrome.detach());
     // Narrow-layout pane tabs. Below RAIL_NARROW_BREAKPOINT the rail cannot sit
     // beside the viewer, so exactly one pane shows and this bar picks it. Same
@@ -239,6 +267,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);
       },
@@ -548,11 +581,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());
 
@@ -622,8 +658,19 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       }
     };
 
+    // Host chrome buttons joining the mount's shared tooltip (the one the
+    // viewbar and cutaway buttons already use). Bindings are detached by
+    // dispose() via the cleanup stack; a host detaching earlier is fine —
+    // attachButtonTooltips.detach is idempotent.
+    const attachHostTooltips = (entries) => {
+      const binding = attachButtonTooltips(tooltip, entries);
+      cleanup.defer(() => binding.detach());
+      return binding;
+    };
+
     return makeHandle({
       ready, dispose, viewer, setParams,
+      attachTooltips: attachHostTooltips,
       setHostPane: paneTabs.setHostPane,
       getView: view,                         // () => tabsCtl.current()
       setView: (name) => tabsCtl.select(name),

package/src/framework/rail.js

@@ -2,6 +2,7 @@ import {
   RAIL_DEFAULT_WIDTH, RAIL_MIN_WIDTH, RAIL_NARROW_BREAKPOINT,
   clampRailWidth, railMaxWidth, readRailPref, resolveRailDrag, writeRailPref,
 } from "./rail-state.js";
+import { attachButtonTooltips } from "./tooltip.js";
 
 const KEY_STEP = 16;
 const KEY_STEP_SHIFT = 64;
@@ -75,7 +76,11 @@ function safeStorage() {
 //
 // Everything is optional. With no rail this returns a no-op, so hosts that lay
 // the framework out themselves (see embed-test.html) are unaffected.
-export function attachRail({ rail, toggle, shell = rail?.parentElement, storage = safeStorage() } = {}) {
+//
+// `tooltip` is the mount's shared presenter (tooltip.js). With it, the toggle's
+// Hide/Show-controls label renders as the same anchored pf-hover-tip the
+// viewbar buttons use; without it, the label falls back to a native title.
+export function attachRail({ rail, toggle, shell = rail?.parentElement, storage = safeStorage(), tooltip } = {}) {
   if (!rail || !shell) {
     // No rail to resolve in this document: --pf-rail-w still defaults to 288px
     // from tokens.css, but nothing is reserving that space, so anything that
@@ -107,6 +112,12 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     toggle.replaceChildren(svg);
     toggleChevron = chevron;
   }
+  // Attached BEFORE the first apply() below writes an aria-label, so the
+  // binding's original-attribute capture (what its detach() restores) sees the
+  // host's own markup, not our first label.
+  const tooltipBinding = toggle && tooltip
+    ? attachButtonTooltips(tooltip, [{ element: toggle }])
+    : null;
 
   const seam = document.createElement("div");
   seam.className = "pf-rail-seam";
@@ -157,8 +168,11 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
       const label = collapsed ? "Show controls" : "Hide controls";
       toggle.setAttribute("aria-expanded", String(!collapsed));
       toggle.setAttribute("aria-label", label);
-      toggle.title = label;
+      // The shared tooltip reads the aria-label at show time, so a native
+      // title would double up as a second, competing tooltip.
+      if (!tooltipBinding) toggle.title = label;
       toggle.classList.toggle("on", collapsed);
+      tooltipBinding?.sync();
     }
     if (persist) writeRailPref(state, storage);
   }
@@ -324,6 +338,9 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
       shell.removeAttribute("data-pf-dragging");
       rail.removeAttribute("inert");
       root.style.removeProperty("--pf-rail-w");
+      // Before the attribute restore below: the binding's own detach rewrites
+      // title/aria-label from its capture, and ours must win.
+      tooltipBinding?.detach();
       if (toggle) {
         toggle.innerHTML = toggleOriginal.html;
         toggle.title = toggleOriginal.title;

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;
 }