partforge 0.48.0 → 0.50.0

package/src/framework/panel/info.js

@@ -20,6 +20,15 @@ export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight })
   return Math.max(8, glyphTop - 6 - popHeight);
 }
 
+// Popover left edge: aligned 8px left of the glyph when that fits, pulled
+// left so the popover's right edge keeps a 10px margin from the viewport
+// edge, and never past a 10px margin on the left (left margin wins when both
+// would be violated). Pure, for direct unit testing — happy-dom reports zero
+// layout metrics, same as popoverTop above.
+export function popoverLeft({ glyphLeft, popWidth, viewportWidth }) {
+  return Math.max(10, Math.min(glyphLeft - 8, viewportWidth - 10 - popWidth));
+}
+
 // One popover element per panel, shared by all its glyphs (only one open at a
 // time). Document-level dismiss listeners are registered per panel and removed
 // by panel.dispose().
@@ -51,7 +60,7 @@ export function createInfoPopover() {
       glyph.setAttribute("aria-expanded", "true");
       const r = glyph.getBoundingClientRect();
       pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
-      pop.style.left = `${Math.max(8, r.left - 8)}px`;
+      pop.style.left = `${popoverLeft({ glyphLeft: r.left, popWidth: pop.offsetWidth, viewportWidth: window.innerWidth })}px`;
     },
     dispose() {
       document.removeEventListener("click", onDocClick);

package/src/framework/panel/render.js

@@ -24,7 +24,7 @@ function indexNodes(nodes, map) {
   }
 }
 
-export function buildControls(root, parameters, params, onDirty) {
+export function buildControls(root, parameters, params, onDirty, onCommit) {
   const info = createInfoPopover();
   const tree = buildTree(desugar(parameters));
 
@@ -38,9 +38,11 @@ export function buildControls(root, parameters, params, onDirty) {
   const lastVisible = new Map();  // id -> previous `visible`, to detect a reveal
   const lastDisabled = new Map(); // id -> previous `disabled`, to skip a no-op input pass
   // Containers that own a disclosure: sections, and titled inner groups (the
-  // legacy "Advanced" fold). `label` is set only for the inner groups, whose
-  // button text carries the ▾/▴ instead of a chevron span.
-  const disclosures = new Map(); // id -> { body, button, label }
+  // legacy "Advanced" fold). Both share the same anatomy — a header row with
+  // the aria-carrying button and a text-free chevron span — so `el` (the
+  // section element / the fold wrapper) mirrors the disclosure with a
+  // `.collapsed` class and CSS draws the closed-band affordance off that.
+  const disclosures = new Map(); // id -> { body, button, el }
   indexNodes(tree, nodeById);
   let relevant = null;
 
@@ -62,7 +64,7 @@ export function buildControls(root, parameters, params, onDirty) {
       const open = state.get(id)?.open ?? true;
       d.body.classList.toggle("hidden", !open);
       d.button.setAttribute("aria-expanded", String(open));
-      if (d.label) d.button.textContent = open ? `${d.label} ▴` : `${d.label} ▾`;
+      d.el.classList.toggle("collapsed", !open);
     }
   };
 
@@ -112,6 +114,15 @@ export function buildControls(root, parameters, params, onDirty) {
 
   const onEdit = () => { applyState(); onDirty?.(); };
 
+  // A commit = the user FINISHED an interaction (slider released, box
+  // committed, checkbox ticked, preset applied). Distinct from onDirty, which
+  // fires on every input event mid-drag. Wrapped: a throwing host handler
+  // must never break the panel.
+  const commit = (keys) => {
+    if (!onCommit) return;
+    try { onCommit(keys); } catch { /* host's problem, not the panel's */ }
+  };
+
   // --- build ---------------------------------------------------------------
   //
   // TWO DIFFERENT THINGS USE `.hidden`, and conflating them is a real bug:
@@ -136,17 +147,24 @@ export function buildControls(root, parameters, params, onDirty) {
     const wrap = el("div", "adv-wrap");
     const body = el("div", "adv hidden");   // starts closed — legacy parity
     body.id = `pf-fold-${node.id.replaceAll("/", "-")}`;
-    const toggle = el("button", "adv-toggle", `${node.title} ▾`);
+    // Same row anatomy as a section header — title button (text-free of any
+    // arrow, same exact-textContent reasoning), chevron span on the right,
+    // whole row clickable — at the fold's subordinate scale.
+    const foldHeader = el("div", "adv-header");
+    const toggle = el("button", "adv-toggle");
+    toggle.type = "button";
+    toggle.append(el("span", "adv-name", node.title));
     toggle.setAttribute("aria-controls", body.id);
-    toggle.addEventListener("click", () => {
+    foldHeader.append(toggle, el("span", "chev"));
+    foldHeader.addEventListener("click", () => {
       const nowHidden = body.classList.toggle("hidden");
-      toggle.textContent = nowHidden ? `${node.title} ▾` : `${node.title} ▴`;
       toggle.setAttribute("aria-expanded", String(!nowHidden));
+      wrap.classList.toggle("collapsed", nowHidden);
     });
     for (const child of node.children) renderNode(child, body, sectionCtx);
-    wrap.append(toggle, body);
+    wrap.append(foldHeader, body);
     nodeEls.set(node.id, wrap);             // conditions act on the wrapper
-    disclosures.set(node.id, { body, button: toggle, label: node.title });
+    disclosures.set(node.id, { body, button: toggle, el: wrap });
     container.append(wrap);
   }
 
@@ -173,6 +191,7 @@ export function buildControls(root, parameters, params, onDirty) {
       Object.assign(params, bundle);
       for (const { key, sync } of rawSyncs.get(sectionCtx.id)) if (key in params) sync();
       onEdit();
+      commit(Object.keys(bundle));
     });
     // The section's controls need a handle on the picker to drop it to Custom
     // when one of them is edited. First picker in the section wins.
@@ -203,6 +222,7 @@ export function buildControls(root, parameters, params, onDirty) {
     };
     const widget = factory(node, params, {
       onChange: () => { markCustom(); onEdit(); },
+      onCommit: () => commit([node.key]),
       info,
     });
     nodeEls.set(node.id, widget.el);
@@ -233,12 +253,14 @@ export function buildControls(root, parameters, params, onDirty) {
     // because sectionByTitle-style lookups match `.sec-title` by exact
     // textContent === title (controls.test.js:210), and a text chevron here
     // would break that match.
-    title.append(el("span", "sec-name", section.title ?? ""), el("span", "chev"));
+    title.append(el("span", "sec-name", section.title ?? ""));
     header.append(title);
+    // Row order: title (flex:1), then ⓘ, then the chevron on the far right.
     // The ⓘ is a SIBLING of the button, never a child: attachInfo appends a
     // <button>, and a button nested in a button is invalid HTML that never
     // receives clicks.
     attachInfo(header, section.description, info);
+    header.append(el("span", "chev"));
     secEl.append(header);
 
     const body = el("div", "sec-body");
@@ -246,11 +268,15 @@ export function buildControls(root, parameters, params, onDirty) {
     title.setAttribute("aria-controls", body.id);
     secEl.append(body);
 
-    title.addEventListener("click", () => {
+    // The whole header row toggles: the title button's own click bubbles up
+    // here, the chevron and the empty row space hit it directly, and the ⓘ
+    // stops propagation in attachInfo. aria state stays on the title button.
+    header.addEventListener("click", () => {
       const nowHidden = body.classList.toggle("hidden");
       title.setAttribute("aria-expanded", String(!nowHidden));
+      secEl.classList.toggle("collapsed", nowHidden);
     });
-    disclosures.set(section.id, { body, button: title, label: null });
+    disclosures.set(section.id, { body, button: title, el: secEl });
 
     // `preset` is filled in when a preset node renders. Controls read it late, so
     // one appearing after them in the children array still works.

package/src/framework/panel/widgets/checkbox.js

@@ -14,7 +14,7 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeCheckbox(node, params, { onChange, info }) {
+export function makeCheckbox(node, params, { onChange, onCommit, info }) {
   const row = el("label", "feat");
   const box = document.createElement("input");
   box.type = "checkbox";
@@ -30,6 +30,7 @@ export function makeCheckbox(node, params, { onChange, info }) {
       params[node.key] = 0;
     }
     onChange?.();
+    onCommit?.();
   });
 
   const sync = () => { box.checked = params[node.key] > 0; };

package/src/framework/panel/widgets/numeric.js

@@ -19,7 +19,7 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeNumeric(node, params, { onChange, info }) {
+export function makeNumeric(node, params, { onChange, onCommit, info }) {
   const numeric = node.type === "number";
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -68,6 +68,7 @@ export function makeNumeric(node, params, { onChange, info }) {
       paintWarn();
       onChange?.();
     });
+    slider.addEventListener("change", () => onCommit?.());
     wrap.append(slider);
   }
 
@@ -124,6 +125,7 @@ export function makeNumeric(node, params, { onChange, info }) {
     if (slider) slider.value = log ? toPosSafe(v) : v;
     paintWarn();
     onChange?.();
+    onCommit?.();
   });
 
   const sync = () => {

package/src/framework/panel/widgets/select.js

@@ -23,7 +23,7 @@ function labeledRow(node, info) {
   return wrap;
 }
 
-export function makeSelect(node, params, { onChange, info }) {
+export function makeSelect(node, params, { onChange, onCommit, info }) {
   const wrap = labeledRow(node, info);
   const opts = normalizeOptions(node.options);
   const byString = new Map(opts.map((o) => [String(o.value), o.value]));
@@ -40,13 +40,14 @@ export function makeSelect(node, params, { onChange, info }) {
   select.addEventListener("change", () => {
     params[node.key] = byString.get(select.value);
     onChange?.();
+    onCommit?.();
   });
   wrap.append(select);
   const sync = () => { select.value = String(params[node.key]); };
   return { el: wrap, sync };
 }
 
-export function makeRadio(node, params, { onChange, info }) {
+export function makeRadio(node, params, { onChange, onCommit, info }) {
   const wrap = labeledRow(node, info);
   const opts = normalizeOptions(node.options);
   const seg = el("div", "seg");
@@ -58,6 +59,7 @@ export function makeRadio(node, params, { onChange, info }) {
       params[node.key] = o.value;
       paint();
       onChange?.();
+      onCommit?.();
     });
     seg.append(b);
     return { b, value: o.value };

package/src/framework/panel/widgets/text.js

@@ -9,7 +9,7 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeText(node, params, { onChange, info }) {
+export function makeText(node, params, { onChange, onCommit, info }) {
   const multiline = node.type === "textarea";
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -26,6 +26,7 @@ export function makeText(node, params, { onChange, info }) {
     params[node.key] = field.value;
     onChange?.();
   });
+  field.addEventListener("change", () => onCommit?.());
   wrap.append(field);
 
   const sync = () => { field.value = String(params[node.key] ?? ""); };

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