partforge 0.44.0 → 0.45.0

package/bin/cli.js

@@ -159,15 +159,35 @@ const commands = {
     try {
       const part = await loadPart(partPath, usage);
       const baseParams = flags.params ? JSON.parse(flags.params) : {};
+      // `--params '[1,2]'` or '42' parses fine and then merges into nothing, so the
+      // flag silently does nothing. Only an object can carry param overrides.
+      if (baseParams === null || typeof baseParams !== "object" || Array.isArray(baseParams)) {
+        die(`--params takes a JSON object of param overrides\n${usage}`);
+      }
       const outDir = flags.out || "render";
       const views = flags.views ? flags.views.split(",") : undefined;
-      // Usage check BEFORE the kernel: a flag typo shouldn't pay a WASM boot.
-      if (!flags.animation && (flags.at || flags.step)) {
+      // Usage checks BEFORE the kernel: a flag typo shouldn't pay a WASM boot.
+      // Test `=== undefined`, not falsiness: `--animation ""` is a flag the user
+      // passed and got wrong (an unset shell variable, typically), not one they
+      // omitted, and silently rendering a non-animation still hides the mistake.
+      if (flags.animation !== undefined && flags.animation.trim() === "") {
+        die(`--animation needs an animation name\n${usage}`);
+      }
+      if (flags.animation === undefined && (flags.at || flags.step)) {
         die(`--at/--step require --animation\n${usage}`);
       }
+      if (flags.at != null && flags.step != null) {
+        die(`--at and --step are alternatives — pass one, not both\n${usage}`);
+      }
+      // Own-key test: `part.views?.["constructor"]` resolves through
+      // Object.prototype and would sail past a plain lookup, straight back into
+      // the background-only render this guard exists to stop.
+      if (view !== undefined && !Object.hasOwn(part.views ?? {}, view)) {
+        die(`unknown view "${view}" (have: ${Object.keys(part.views ?? {}).join(", ") || "none"})\n${usage}`);
+      }
       const kernel = await bootKernel(part);
 
-      if (!flags.animation) {
+      if (flags.animation === undefined) {
         const files = await renderViews(kernel, part, view, { views, out: outDir, params: baseParams });
         for (const f of files) console.log(`wrote ${f}`);
         process.exit(0);
@@ -196,11 +216,29 @@ const commands = {
         // step's camera instead of this step's own.
         frames = [{ t: end, cueT: anim.stepStarts[idx], tag: `${flags.animation}-step${idx + 1}` }];
       } else {
-        const ts = (flags.at ?? "1").split(",").map(Number);
+        // Split first and reject blanks: Number("") is 0, so "0.2,,0.8" would
+        // otherwise slip a silent extra frame at t=0 past the range check.
+        const raw = (flags.at ?? "1").split(",");
+        const ts = raw.map((s) => (s.trim() === "" ? Number.NaN : Number(s)));
         if (!ts.length || ts.some((t) => !Number.isFinite(t) || t < 0 || t > 1)) {
           die(`--at takes comma-separated positions in 0..1\n${usage}`);
         }
-        frames = ts.map((t) => ({ t, tag: `${flags.animation}-t${String(Math.round(t * 100)).padStart(3, "0")}` }));
+        // The tag is the only thing distinguishing one frame's file from another.
+        // Two decimals suits the usual `--at 0,0.5,1`, but a dense request like
+        // 0.001,0.004 collides and the later render would silently overwrite the
+        // earlier — one file for two frames asked for. Widen the tag just enough
+        // for THIS request instead of refusing it: ordinary runs keep their
+        // familiar t000/t050/t100 names, dense ones get one file each.
+        const tagsAt = (decimals) =>
+          ts.map((t) => String(Math.round(t * 10 ** decimals)).padStart(decimals + 1, "0"));
+        let decimals = 2;
+        while (decimals < 6 && new Set(tagsAt(decimals)).size !== ts.length) decimals++;
+        const tags = tagsAt(decimals);
+        if (new Set(tags).size !== ts.length) {
+          // No precision separates them: the same position was listed twice.
+          die(`--at lists the same position more than once\n${usage}`);
+        }
+        frames = ts.map((t, i) => ({ t, tag: `${flags.animation}-t${tags[i]}` }));
       }
       for (const frame of frames) {
         const { values } = evaluate(anim, frame.t);

package/docs/AUTHORING-PARTS.md

@@ -167,6 +167,13 @@ Rules (all lint-enforced):
   inside the owning control's min/max (the engine applies them unclamped).
 - Params not tracked anywhere keep their current values; a param tracked in
   one step holds its nearest keyframe value while other steps play.
+- A step may declare a `camera` and **no** `tracks` — an establishing shot that
+  swings the view while the model holds still. At least one step still has to
+  carry tracks, or the animation animates nothing. Note the holding value is the
+  nearest keyframe, not whatever the user last set: a leading camera-only step
+  shows the animation's opening pose, the same one `t = 0` would show.
+- `loop` and `autoplay` must be literal booleans. Anything else is reported by
+  lint and treated as `false` at runtime, so `loop: "false"` never means "loop".
 - Couple motions through `derive` (animate one master param; derive the rest),
   not by tracking dependent params separately.
 - `camera` cues use the seven canonical angles (`iso front back top bottom
@@ -484,6 +491,12 @@ choosing a preset updates both numeric and text fields.
 Every `key` used must exist in `defaults`. `src/parts/demo.js` is the worked example for
 everything below.
 
+A feature's `on` is **required and must be greater than 0** — it is the real value the
+parameter takes when the box is ticked (a diameter, a count), and the panel reads
+`> 0` as "enabled", so there is nothing sensible to fall back to. `partforge lint`
+reports a missing or non-positive one as `features-requires-on`. A `toggles` entry is
+the exception: its `on` is just a flag and defaults to 1.
+
 **Standalone toggles** (a plain on/off checkbox, no accompanying sliders): add a
 `toggles` array to a preset section — shown below the preset picker, outside the
 Advanced fold, so it stays visible:
@@ -791,6 +804,27 @@ Copy `demo.html` and change the title, the panel heading, and the `<script src>`
 workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
 `"occt"` for STEP — handled for you).
 
+**View control (the mount handle).** For an embedder driving the view tabs from its own UI
+instead of (or in addition to) the built-in `#part` bar:
+
+- `runtime.getView() → string` — the active view name; never null once the runtime is ready
+  (mount resolves a default before first build — see "Which view the viewer opens on" above).
+- `runtime.setView(name) → boolean` — switch tabs programmatically, the same path as clicking
+  a tab. Returns `false` (and leaves the active tab untouched) for a name the part doesn't
+  declare in `views`; `true` otherwise, including when `name` is already active.
+- `await runtime.captureView(viewName?, opts?) → Promise<string | null>` — a JPEG data URL of
+  `viewName` rendered offscreen (falling back to the resolved default view — see
+  `resolveDefaultView` / `default-view.js` — when `viewName` is omitted or names a view the
+  part doesn't declare). Never disturbs the active tab, the live camera, or the on-screen
+  scene; `opts` forwards to the underlying render (size, quality, angle). Resolves `null` on
+  failure rather than throwing (a build error, a part with no sub-parts in that view, a
+  disposed runtime).
+
+Pass `onViewChange(name)` to `mount()` to be told the active view: it fires once
+synchronously during mount with the initial resolved view (before `runtime.ready` settles),
+then again on every subsequent change — a tab click or a `setView` call — always with the
+new view name.
+
 **Headless export (the mount handle).** The `#download*` buttons above are the built-in,
 view-bound export UI. An embedder that wants its own export UI (e.g. a "pick which parts,
 pick a format" modal) can skip those buttons and drive export off the handle `mount()`
@@ -1083,9 +1117,10 @@ previously didn't; that's the fix working as intended, not a regression.
 `missing-views`, `part-view-unknown` (all errors); `view-unused`,
 `default-view-ambiguous` (warnings).
 
-**Parameter schema** — `features-requires-sliders`, `control-key-not-in-defaults`,
-`preset-key-not-in-defaults` (errors); `slider-range-excludes-default`,
-`unknown-control-field`, `duplicate-control-key`, `default-not-exposed` (warnings).
+**Parameter schema** — `features-requires-sliders`, `features-requires-on`,
+`control-key-not-in-defaults`, `preset-key-not-in-defaults` (errors);
+`slider-range-excludes-default`, `unknown-control-field`, `duplicate-control-key`,
+`default-not-exposed` (warnings).
 
 **Kernel API**, found by executing `build()` against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -100,7 +100,7 @@
     "@fontsource-variable/geist-mono": "^5.3.0",
     "happy-dom": "^20.10.6",
     "playwright": "^1.49.0",
-    "typescript": "^7.0.2",
+    "typescript": "^5.9.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"
   }

package/src/framework/animation-controls.js

@@ -112,6 +112,11 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // propagate would take the other listeners down with it. Warn once, then
   // stay quiet so a bad frame can't flood the console 60x a second.
   let frameFailureWarned = false;
+  function warnFrameFailure(err) {
+    if (frameFailureWarned) return;
+    frameFailureWarned = true;
+    console.warn("partforge: animation frame failed", err);
+  }
   function apply(r) {
     if (!r) return;
     try {
@@ -124,18 +129,24 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
           duration: tweenDuration,
           // An intro cue gates playback until the tween settles; mid-timeline
           // cues overlap playback and need no completion signal.
-          onComplete: r.status === "intro" ? () => apply(playback.introDone()) : undefined,
+          onComplete: r.status === "intro" ? () => guarded(() => playback.introDone()) : undefined,
         });
       }
       syncUi();
     } catch (err) {
-      if (!frameFailureWarned) {
-        frameFailureWarned = true;
-        console.warn("partforge: animation frame failed", err);
-      }
+      warnFrameFailure(err);
     }
   }
 
+  // Every transport entry point goes through here so the STATE-MACHINE call is
+  // inside the guard too, not just apply(). playback.tick() is evaluated in the
+  // render loop, and three re-arms requestAnimationFrame only after the frame
+  // callback returns — a throw escaping from there stops the rAF chain and
+  // freezes the viewer permanently instead of costing one frame.
+  function guarded(produce) {
+    try { apply(produce()); } catch (err) { warnFrameFailure(err); }
+  }
+
   function doReset() {
     playback.reset();
     viewer.cancelCameraTween();
@@ -154,14 +165,14 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     syncUi();
   }
 
-  const offFrame = viewer.onFrame((dt) => apply(playback.tick(dt)));
+  const offFrame = viewer.onFrame((dt) => guarded(() => playback.tick(dt)));
   // User orbit: the viewer has already cancelled any cue tween (its own
   // "start" handler); disarm the remaining cues, and if an intro tween was
   // gating playback, settle the gate — cancel() never fires onComplete, so
   // without this the machine would sit in "intro" forever.
   const offOrbit = viewer.onCameraStart(() => {
     playback.disarmCues();
-    if (playback.state().status === "intro") apply(playback.introDone());
+    if (playback.state().status === "intro") guarded(() => playback.introDone());
   });
 
   const onPlayClick = () => {
@@ -169,14 +180,14 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     const active = playback.state().status;
     if (active === "playing" || active === "intro") {
       viewer.cancelCameraTween();
-      apply(playback.pause());
+      guarded(() => playback.pause());
     } else {
-      apply(playback.play());
+      guarded(() => playback.play());
     }
   };
-  const onScrub = () => { disarmAutoplay(); apply(playback.seek(Number(scrub.value) / 1000)); };
-  const onPrev = () => { disarmAutoplay(); apply(playback.stepPrev()); };
-  const onNext = () => { disarmAutoplay(); apply(playback.stepNext()); };
+  const onScrub = () => { disarmAutoplay(); guarded(() => playback.seek(Number(scrub.value) / 1000)); };
+  const onPrev = () => { disarmAutoplay(); guarded(() => playback.stepPrev()); };
+  const onNext = () => { disarmAutoplay(); guarded(() => playback.stepNext()); };
   const onPick = () => { disarmAutoplay(); selectAnimation(pick.value); };
   const onResetClick = () => { disarmAutoplay(); doReset(); };
   playBtn.addEventListener("click", onPlayClick);
@@ -200,10 +211,10 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
         return;
       }
       if (name) selectAnimation(name);
-      apply(playback.play());
+      guarded(() => playback.play());
     },
-    pause() { disarmAutoplay(); viewer.cancelCameraTween(); apply(playback.pause()); },
-    seek(t) { disarmAutoplay(); apply(playback.seek(t)); },
+    pause() { disarmAutoplay(); viewer.cancelCameraTween(); guarded(() => playback.pause()); },
+    seek(t) { disarmAutoplay(); guarded(() => playback.seek(t)); },
     stop() { disarmAutoplay(); doReset(); },
     state: () => ({ animation: current.name, ...playback.state() }),
   };
@@ -223,7 +234,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
       if (!autoplayArmed || !autoplayAnim) return;
       if (current !== autoplayAnim) selectAnimation(autoplayAnim.name);
       const { status } = playback.state();
-      if (status !== "playing" && status !== "intro") apply(playback.play());
+      if (status !== "playing" && status !== "intro") guarded(() => playback.play());
     },
     detach() {
       offFrame();

package/src/framework/animation.js

@@ -13,6 +13,32 @@ export const EASINGS = {
 };
 export const DEFAULT_EASING = "ease-in-out";
 
+// Look easings up by OWN key only. `EASINGS[name]` / `name in EASINGS` would walk
+// the prototype chain, so "toString" resolves to a function that silently returns
+// garbage and "__proto__" resolves to a non-function that throws — mid-frame, from
+// inside the render loop. Lint applies the same test, so an unknown easing is an
+// authoring error there and a quiet fall back to the default here.
+export const easingFor = (name) =>
+  (Object.hasOwn(EASINGS, name) ? EASINGS[name] : EASINGS[DEFAULT_EASING]);
+
+// A track value has to be a non-empty keyframe array to be evaluable. Lint reports
+// anything else as `animation-keyframes-invalid`; this predicate is what keeps the
+// runtime total when a part reaches it unlinted, and it must stay the single rule
+// both segmentsFor and trackedKeys agree on — if they disagree, evaluate() is asked
+// for a key that has no segment and throws.
+const usableKeyframes = (kf) => Array.isArray(kf) && kf.length > 0;
+
+// t is clamped to [0,1]. Only an unorderable t (NaN, or anything that coerces to
+// it, such as a host calling seek() with no argument) folds to 0 — ±Infinity is
+// ordered and clamps normally. NaN has to be caught rather than clamped because
+// it fails every comparison: `Math.min(1, Math.max(0, NaN))` is still NaN, and an
+// unclamped NaN leaves `t >= 1` permanently false, so playback could never reach
+// `done` and every later cue test would silently fail.
+const clampT = (t) => {
+  const n = Number(t);
+  return Number.isNaN(n) ? 0 : Math.min(1, Math.max(0, n));
+};
+
 // Normalize one animations-map entry to the canonical shape every consumer
 // (playback, transport UI, lint, CLI) works against: a step list (a bare
 // `tracks` form becomes one anonymous step), normalized step starts, and the
@@ -39,10 +65,18 @@ export function normalizeAnimation(name, spec) {
   if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera }];
   else if (Array.isArray(spec.camera)) cues = spec.camera.map(([t, view]) => ({ t, view }));
   else cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera }] : []));
-  const trackedKeys = [...new Set(steps.flatMap((s) => Object.keys(s.tracks)))];
+  const trackedKeys = [...new Set(steps.flatMap((s) =>
+    Object.entries(s.tracks).filter(([, kf]) => usableKeyframes(kf)).map(([key]) => key)))];
   return {
     name, label: spec.label ?? name, description: spec.description ?? null,
-    loop: !!spec.loop, autoplay: !!spec.autoplay, steps, stepStarts, totalDuration, cues, trackedKeys,
+    // Fail CLOSED on both flags: only a literal `true` turns them on. Coercing
+    // with `!!` reads `loop: "false"` as "loop forever", which is the worst
+    // available reading of that typo, and nothing downstream would catch it —
+    // lint reports non-booleans, but a part can mount in a browser without ever
+    // having been linted. An invalid flag therefore does the quiet thing here and
+    // is reported there.
+    loop: spec.loop === true, autoplay: spec.autoplay === true,
+    steps, stepStarts, totalDuration, cues, trackedKeys,
   };
 }
 
@@ -52,7 +86,7 @@ export function normalizeAnimations(part) {
 
 // Step containing t. Boundaries belong to the LATER step, and t clamps to [0,1].
 export function stepIndexAt(anim, t) {
-  const tc = Math.min(1, Math.max(0, t));
+  const tc = clampT(t);
   let idx = 0;
   for (let i = 0; i < anim.stepStarts.length; i++) if (tc >= anim.stepStarts[i]) idx = i;
   return idx;
@@ -71,7 +105,7 @@ function segmentsFor(anim, key) {
   const out = [];
   anim.steps.forEach((step, i) => {
     const kf = step.tracks[key];
-    if (!kf) return;
+    if (!usableKeyframes(kf)) return;
     const start = anim.stepStarts[i];
     const end = i + 1 < anim.steps.length ? anim.stepStarts[i + 1] : 1;
     out.push({ start, end, keyframes: kf, easing: step.easing });
@@ -94,12 +128,16 @@ function interpKeyframes(kf, u) {
 
 function evaluateTrack(anim, key, t) {
   const segs = segmentsFor(anim, key);
+  // trackedKeys and segmentsFor share usableKeyframes, so a tracked key always
+  // has a segment. Guard anyway: this runs inside the render loop, where a throw
+  // costs the whole viewer, not just the frame.
+  if (!segs.length) return undefined;
   let prev = null;
   for (const seg of segs) {
     if (t < seg.start) break;
     if (t <= seg.end) {
       const span = seg.end - seg.start || 1;
-      const local = (EASINGS[seg.easing] ?? EASINGS[DEFAULT_EASING])((t - seg.start) / span);
+      const local = easingFor(seg.easing)((t - seg.start) / span);
       return interpKeyframes(seg.keyframes, local);
     }
     prev = seg;
@@ -112,7 +150,7 @@ function evaluateTrack(anim, key, t) {
 // Evaluate the whole animation at normalized position t ∈ [0,1] (over the
 // TOTAL duration — the same t the scrubber, seek(t), and the CLI's --at use).
 export function evaluate(anim, t) {
-  const tc = Math.min(1, Math.max(0, t));
+  const tc = clampT(t);
   const values = {};
   for (const key of anim.trackedKeys) values[key] = evaluateTrack(anim, key, tc);
   return { stepIndex: stepIndexAt(anim, tc), values };
@@ -131,6 +169,7 @@ export function createPlayback(anim) {
   let t = 0;
   let armed = true;       // user orbit disarms cues until reset/replay
   let firedCueT = -1;     // cues with t <= firedCueT already fired this run
+  let pendingCueT = null; // cue handed to an in-flight intro tween, not yet settled
   let stopAt = null;      // stepNext/playStep pause playback on reaching this t
 
   const snapshot = (cue = null) => ({ t, status, ...evaluate(anim, t), cue });
@@ -144,7 +183,11 @@ export function createPlayback(anim) {
 
   function begin() {
     const cue = governingCue();
-    if (cue) { firedCueT = Math.max(firedCueT, cue.t); status = "intro"; }
+    // The cue is NOT counted as fired yet — only introDone() retires it. Pausing
+    // mid-intro cancels the tween and drops its completion callback, so a cue
+    // retired here would never be re-issued on resume and the camera would stay
+    // stranded wherever the cancelled sweep left it.
+    if (cue) { pendingCueT = cue.t; status = "intro"; }
     else status = "playing";
     return snapshot(cue);
   }
@@ -157,17 +200,23 @@ export function createPlayback(anim) {
   }
   function pause() {
     if (status === "playing" || status === "intro") status = "paused";
+    pendingCueT = null; // an unsettled intro cue is abandoned, so resume re-issues it
     return snapshot();
   }
   function introDone() {
-    if (status === "intro") status = "playing";
+    if (status === "intro") {
+      if (pendingCueT != null) firedCueT = Math.max(firedCueT, pendingCueT);
+      status = "playing";
+    }
+    pendingCueT = null;
     return snapshot();
   }
   function seek(v) {
-    t = Math.min(1, Math.max(0, v));
+    t = clampT(v);
     status = "paused";
     stopAt = null;
     firedCueT = -1; // a later play() re-honors the cue governing the new position
+    pendingCueT = null;
     return snapshot();
   }
   function playStep(i) {
@@ -175,6 +224,7 @@ export function createPlayback(anim) {
     t = anim.stepStarts[idx];
     stopAt = idx + 1 < anim.steps.length ? anim.stepStarts[idx + 1] : 1;
     firedCueT = -1;
+    pendingCueT = null;
     return begin();
   }
   function stepNext() {
@@ -185,7 +235,7 @@ export function createPlayback(anim) {
     return playStep(Math.max(0, stepIndexAt(anim, t) - 1));
   }
   function reset() {
-    t = 0; status = "idle"; stopAt = null; firedCueT = -1; armed = true;
+    t = 0; status = "idle"; stopAt = null; firedCueT = -1; pendingCueT = null; armed = true;
     return snapshot();
   }
   function disarmCues() { armed = false; }
@@ -194,10 +244,14 @@ export function createPlayback(anim) {
   function tick(dt) {
     if (status !== "playing" || !(dt > 0)) return null;
     t += dt / anim.totalDuration;
-    if (anim.loop) {
-      if (t >= 1) t -= Math.floor(t);
-    } else if (stopAt != null && t >= stopAt) {
+    // A pending step boundary outranks looping. Lint rejects loop on a stepped
+    // animation, so the two rarely coexist — but when they do, an explicit
+    // "play this step" must still stop where it was told to, rather than being
+    // swallowed by the wrap and running forever.
+    if (stopAt != null && t >= stopAt) {
       t = stopAt; stopAt = null; status = "paused";
+    } else if (anim.loop) {
+      if (t >= 1) t -= Math.floor(t);
     } else if (t >= 1) {
       t = 1; status = "done";
     }

package/src/framework/capture-build.js

@@ -0,0 +1,59 @@
+// Correlated one-shot geometry builds for captureView — a private channel that
+// does NOT go through the regen loop. Same shape as export-controller's pending
+// Map (export-controller.js): allocate a jobId, resolve when the matching
+// reply arrives. Pure — no DOM, no worker; `send` is injected.
+export function createCaptureBuild({ send }) {
+  let nextId = 1;
+  let disposed = false;
+  const pending = new Map(); // jobId -> resolve
+
+  function request({ subparts, view, params, backend }) {
+    // After teardown the workers are gone, so a fresh send would post to a terminated
+    // worker (a silent no-op) and its promise would hang forever. Resolve null instead
+    // — captureView's documented "disposed runtime resolves null" contract.
+    if (disposed) return Promise.resolve(null);
+    // String-namespaced ("cap-N") so a capture jobId can never collide with
+    // export-controller's numeric jobIds — both share the same worker message
+    // space, and exportCtl.handleMessage does a raw pending.get(m.jobId) before
+    // checking type, so a colliding id could otherwise settle the wrong promise.
+    const jobId = `cap-${nextId++}`;
+    return new Promise((resolve) => {
+      pending.set(jobId, resolve);
+      // cache:true so the worker reuses its per-sub-part geometry memo (the
+      // expensive CSG); only the per-view place() + meshing re-run.
+      send({ type: "capture-generate", jobId, subparts, view, params, cache: true }, backend);
+    });
+  }
+
+  // Returns true iff this message was a reply this controller owns (so the
+  // caller — mount.js's onWorkerMessage — can skip it entirely). Keyed on
+  // membership in `pending` first: the namespaced jobId guarantees another
+  // channel's message never matches, so a hit here is always ours. A failed
+  // build (the worker's shared catch posts a generic error/needs-occt, jobId
+  // intact) resolves to null rather than leaving the caller hanging forever —
+  // captureView treats null as "capture failed, skip".
+  function handleMessage(data) {
+    const jobId = data?.jobId;
+    if (jobId == null || !pending.has(jobId)) return false;
+    if (data.type === "capture-meshes") {
+      pending.get(jobId)(data.meshes);
+    } else if (data.type === "error" || data.type === "needs-occt") {
+      pending.get(jobId)(null);
+    } else {
+      return false;
+    }
+    pending.delete(jobId);
+    return true;
+  }
+
+  // Teardown / worker death: settle every in-flight request to null instead
+  // of leaving its promise permanently pending (a caller awaiting captureView
+  // across a viewer dispose must still get an answer, even a negative one).
+  function dispose() {
+    disposed = true;
+    for (const resolve of pending.values()) resolve(null);
+    pending.clear();
+  }
+
+  return { request, handleMessage, dispose };
+}

package/src/framework/jobs.js

@@ -80,6 +80,27 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const transfer = meshes.flatMap((m) =>
         [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
       post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.() }, transfer);
+    } else if (msg.type === "capture-generate") {
+      // A private, job-correlated one-shot channel for captureView — builds a
+      // (possibly non-active) view's meshes off the regen loop, so it can never
+      // race or clobber live state. Same per-sub-part build+cache-round as
+      // `generate` above (cache:true reuses the worker's geometry memo), but no
+      // isStale/superseded polling — there's nothing to supersede a one-shot.
+      const useCache = msg.cache !== false;
+      const meshes = [];
+      for (const name of msg.subparts) {
+        if (useCache) kernel.beginSubPart?.(name);
+        try {
+          const m = posed(name, "display").toMesh({ quality: "preview" });
+          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges, featureIds: m.featureIds, features: m.features });
+        } finally {
+          if (useCache) kernel.endSubPart?.();
+          kernel.cleanup?.();
+        }
+      }
+      const captureTransfer = meshes.flatMap((m) =>
+        [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
+      post({ type: "capture-meshes", jobId: msg.jobId, meshes }, captureTransfer);
     } else if (msg.type === "export-stl") {
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");

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

@@ -84,14 +84,26 @@ export const ANIMATION_RULES = [
             `animations.${name}.steps`));
           continue;
         }
-        rawSteps(a).forEach((s, i) => {
-          const path = hasSteps ? `animations.${name}.steps[${i}].tracks` : `animations.${name}.tracks`;
-          if (!isPlainObject(s.tracks) || Object.keys(s.tracks).length === 0) {
-            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.",
-              path));
-          }
+        const steps = rawSteps(a);
+        const trackful = (s) => isPlainObject(s.tracks) && Object.keys(s.tracks).length > 0;
+        if (!steps.some(trackful)) {
+          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`));
+          continue;
+        }
+        steps.forEach((s, i) => {
+          if (trackful(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
+          // must not reject what plays correctly.
+          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`));
         });
       }
       return out;
@@ -201,12 +213,31 @@ export const ANIMATION_RULES = [
   },
   {
     id: "animation-loop-invalid",
-    run: ({ part }) => animEntries(part)
-      .filter(([, a]) => a.loop === true && Array.isArray(a.steps) && a.steps.length > 1)
-      .map(([name]) => 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`)),
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, a] 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
+        // silently means `false`. That is the safe default but not an obvious one,
+        // so the author has to hear about it here rather than wonder why `loop: 1`
+        // does nothing.
+        if (typeof a.loop !== "boolean") {
+          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`));
+          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`));
+        }
+      }
+      return out;
+    },
   },
   {
     id: "animation-step-label-duplicate",
@@ -235,7 +266,11 @@ export const ANIMATION_RULES = [
     run: ({ part }) => {
       const out = [];
       const check = (easing, path) => {
-        if (easing !== undefined && !(easing in EASINGS)) {
+        // Own-key test, not `in`: `"toString" in EASINGS` is true, so `in` would
+        // wave through every Object.prototype member. The runtime (easingFor)
+        // applies the same test and falls back to the default, so these names are
+        // caught here rather than silently mis-animating or throwing mid-frame.
+        if (easing !== undefined && !Object.hasOwn(EASINGS, easing)) {
           out.push(err("animation-easing-unknown",
             `unknown easing "${easing}"`,
             `Use one of: ${Object.keys(EASINGS).join(", ")}.`,
@@ -258,7 +293,7 @@ export const ANIMATION_RULES = [
         const stepCameras = Array.isArray(a.steps)
           ? a.steps.map((s, i) => [s?.camera, i]).filter(([c]) => c !== undefined && c !== null)
           : [];
-        if (a.camera !== undefined && stepCameras.length) {
+        if (a.camera != null && stepCameras.length) {
           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.",
@@ -272,7 +307,9 @@ export const ANIMATION_RULES = [
               `animations.${name}.steps[${i}].camera`));
           }
         }
-        if (a.camera === undefined) continue;
+        // An explicit `camera: null` is "no camera", which is how
+        // normalizeAnimation reads it — not a malformed value to report.
+        if (a.camera == null) continue;
         if (typeof a.camera === "string") {
           if (badName(a.camera)) {
             out.push(err("animation-camera-invalid",

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

@@ -83,6 +83,28 @@ export const SCHEMA_RULES = [
       return out;
     },
   },
+  {
+    id: "features-requires-on",
+    run: ({ part }) => {
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        if (!sectionRenders(sec)) return;
+        arr(sec?.features).forEach((f, i) => {
+          // The panel treats "enabled" as `params[key] > 0`, so `on` has to be a
+          // positive number: a missing one writes undefined (NaN in the build),
+          // and 0 or a negative writes a value the panel reads straight back as
+          // "still off", leaving a checkbox that won't stay ticked.
+          if (f && !f.hidden && !(typeof f.on === "number" && f.on > 0)) {
+            out.push(err("features-requires-on",
+              `section "${sec.id ?? si}" feature ${i}${f.key ? ` ("${f.key}")` : ""} has no positive numeric \`on\` value`,
+              "Ticking a feature's checkbox writes `on` into the feature's own parameter, so a missing one writes `undefined` and the build reads it as NaN. Unlike a `toggles` entry — a plain flag that falls back to 1 — a feature's `on` is the real value the parameter takes when enabled (a diameter, a count), so there is no safe default to guess. It must be greater than 0, because the panel reads `> 0` as \"enabled\". Give the feature the value it should switch on to.",
+              `parameters[${si}].features[${i}]`));
+          }
+        });
+      });
+      return out;
+    },
+  },
   {
     id: "control-key-not-in-defaults",
     run: ({ part }) => {

package/src/framework/mount.js

@@ -23,16 +23,24 @@ import { attachPickToggle, attachHoverLabels, attachPicker, formatSelection } fr
 import { createPickRequestClient, resolvePickServerUrl, PICK_SERVER_DEFAULT_URL } from "./pick-request/index.js";
 import { exportablePartNames, partLabel } from "./export-select.js";
 import { createExportController, backendForFormat } from "./export-controller.js";
+import { createCaptureBuild } from "./capture-build.js";
 import { attachAnimationControls } from "./animation-controls.js";
+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 }) {
+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() }.
     animation: animation ?? null,
+    // Active view name (never null once mounted). See onViewChange for the push side.
+    getView,
+    // Programmatic tab switch; false for a name the part doesn't declare.
+    setView,
+    // Offscreen render of a named view (default when omitted, or on an unknown name).
+    captureView,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
     // Park/unpark the viewer: stops the render loop and frees the drawing
@@ -82,10 +90,17 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.44.0):
-//   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
+// Embedding contract (0.45.0):
+//   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload, onViewChange });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
+//   runtime.getView();     // active view name (string), never null once mounted
+//   runtime.setView("lid");       // switch tab programmatically; returns false (and leaves the
+//                                 // active tab untouched) for a name the part doesn't declare
+//   await runtime.captureView();  // JPEG data URL of the DEFAULT view rendered offscreen (pass
+//                                 // a name for a specific view, falling back to the default for
+//                                 // an unknown one), never disturbing the active tab or the live
+//                                 // scene; null on failure (never throws)
 //   runtime.captureCurrent({ size: 2048 });  // one offscreen render of the user's current
 //                                         // framing (live camera pose + viewport aspect) at the
 //                                         // given long-edge resolution → JPEG data URL, or null
@@ -121,10 +136,13 @@ function createCleanupStack() {
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
+// 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.
 // 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,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange,
                               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);
@@ -214,10 +232,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // View tabs (generated from part.views) + live params. A tab switch shows the
     // cached assembly instantly if it's current, else auto-builds what's missing.
     const tabsCtl = createViewTabs(els.tabs, part, {
-      onChange: () => { pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick(); },
+      onChange: (name) => {
+        pendingPosed.clear(); cutawayChrome.reset(); refreshView(); updateRelevance(); loop.kick(); animCtl?.autoplayKick();
+        onViewChange?.(name);
+      },
     });
     cleanup.defer(() => tabsCtl.detach());
     const view = () => tabsCtl.current();
+    // Tell the embedder the starting tab exactly once, synchronously, so a host
+    // (partforge-cloud) never has to poll getView() to learn where we opened.
+    onViewChange?.(tabsCtl.current());
     const params = { ...part.defaults };
 
     // Current selection context for the pickers: the active view + live params +
@@ -364,6 +388,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     function onWorkerMessage({ data }) {
       // Headless exportParts() correlation: consume its own replies first.
       if (exportCtl.handleMessage(data, onDownload)) return;
+      // captureView's off-loop build channel: consume its replies before the
+      // live `meshes` case — capture-meshes must never touch live cache/display.
+      if (captureBuild.handleMessage(data)) return;
       switch (data.type) {
         case "ready":
           loop.ready(); // auto-build the default view (keeps the busy spinner up)
@@ -444,6 +471,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
     cleanup.defer(() => service.terminate());
 
+    const captureBuild = createCaptureBuild({ send: (msg, backend) => service.send(msg, backend) });
+    cleanup.defer(() => captureBuild.dispose());
+
     const exportCtl = createExportController({
       send: (msg, backend) => service.send(msg, backend),
       currentView: () => view(),
@@ -558,9 +588,31 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.dispose();
     }
 
+    // Off-loop offscreen thumbnail: builds `viewName` (or the part's resolved
+    // default when omitted/unknown) via captureBuild's correlated channel, then
+    // renders it in a throwaway scene via viewer.renderMeshPayloads. Never
+    // touches the active tab, getView(), or the live scene — best-effort: any
+    // failure, including a resolved-null from a worker build failure (4A
+    // settles rather than throwing), returns null.
+    const captureView = async (viewName, opts = {}) => {
+      try {
+        const target = (viewName && part.views?.[viewName]) ? viewName : resolveDefaultView(part);
+        const subparts = viewSubParts(part, target, params);
+        if (!subparts.length) return null;
+        const meshes = await captureBuild.request({ subparts, view: target, params, backend: backendFor() });
+        if (!meshes || !meshes.length) return null; // 4A resolves null on a worker build failure
+        return viewer.renderMeshPayloads(meshes, { size: 640, quality: 0.8, angle: "iso", ...opts });
+      } catch {
+        return null; // best-effort: a failed thumbnail never breaks the caller
+      }
+    };
+
     return makeHandle({
       ready, dispose, viewer, setParams,
       setHostPane: paneTabs.setHostPane,
+      getView: view,                         // () => tabsCtl.current()
+      setView: (name) => tabsCtl.select(name),
+      captureView,
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),

package/src/framework/view-tabs.js

@@ -48,6 +48,19 @@ export function createViewTabs(el, part, { onChange }) {
 
   return {
     current: () => view,
+    // Programmatic switch — the click path without the click. Used by an
+    // embedder (mount's handle.setView) to change tabs from outside the DOM.
+    // Returns false for a name that isn't a tab so callers can validate.
+    select: (name) => {
+      if (name === view) return true; // already active — nothing to do
+      const btn = [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === name);
+      if (!btn) return false;
+      view = name;
+      saveView(partKey, view);
+      setActive(btn);
+      onChange(view);
+      return true;
+    },
     detach: () => {
       el.removeEventListener("click", onClick);
       if (generated) el.innerHTML = ""; // we generated these buttons; hand-written markup stays

package/src/framework/viewer-lighting.js

@@ -3,8 +3,15 @@ import * as THREE from "three";
 const KEY_COLOR = 0xffffff, KEY_INTENSITY = 1.45;
 const FILL_COLOR = 0xe5efff, FILL_INTENSITY = 0.65;
 
+// The persistent sky/ground ambient. Shared with the offscreen thumbnail path
+// (viewer.js renderMeshPayloads), which builds its own throwaway scene and so needs
+// the same hemisphere fill to avoid rendering faces outside the key/fill cones near-black.
+export function createHemisphereLight() {
+  return new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+}
+
 export function addViewerLights(scene) {
-  const hemisphere = new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+  const hemisphere = createHemisphereLight();
   const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
   key.position.set(8, 14, 10);
   const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);

package/src/framework/viewer.js

@@ -6,7 +6,7 @@ import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
 import { createCameraTween } from "./camera-tween.js";
-import { addViewerLights, captureLightPoses, createCaptureLights } from "./viewer-lighting.js";
+import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
 // three renders into a render target in the LINEAR working colour space: as of r184
@@ -427,7 +427,8 @@ export function createViewer(container, part) {
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
   function renderOffscreen({ position, up, target },
-                           { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9 } = {}) {
+                           { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9 } = {},
+                           renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
       ? (_rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, RT_OPTIONS))
@@ -451,7 +452,7 @@ export function createViewer(container, part) {
     scene.add(capKey, capKey.target, capFill, capFill.target);
     try {
       renderer.setRenderTarget(rt);
-      renderer.render(scene, cam);
+      renderer.render(renderScene, cam);
       // render() resolves the multisample renderbuffer into the target texture, so this
       // reads antialiased pixels.
       renderer.readRenderTargetPixels(rt, 0, 0, width, height, buf);
@@ -510,6 +511,76 @@ export function createViewer(container, part) {
     });
   }
 
+  // Offscreen render of an arbitrary mesh set (a non-active view), for thumbnails.
+  // Assembles a THROWAWAY scene mirroring the live pivot convention, frames it from a
+  // canonical angle, renders through the parameterized renderOffscreen, and disposes
+  // everything. Never touches the live scene, camera, subMesh, or subCache. `payloads`
+  // is the worker's [{name, positions, normals, indices, …}] array — placement is
+  // already baked into shared-frame coords, so meshes are NOT recentred.
+  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8 } = {}) {
+    if (disposed) return null; // same guard as captureCurrent/captureCanonicalViews — never touch a torn-down renderer
+    const tmpScene = new THREE.Scene();
+    const tmpPivot = new THREE.Group();
+    tmpPivot.rotation.x = -Math.PI / 2; // model Z (CAD up) -> vertical, same as live pivot
+    tmpScene.add(tmpPivot);
+
+    const built = [];
+    for (const payload of payloads) {
+      const geo = buildGeometry(payload); // shared-frame coords, NOT recentred
+      const mesh = new THREE.Mesh(geo, materialFor(payload.name));
+      tmpPivot.add(mesh);
+      built.push(mesh);
+    }
+
+    // Frame in WORLD space, AFTER the pivot rotation. The meshes are built in model
+    // coords but rendered rotated by tmpPivot, so a model-space bbox centre would aim
+    // the camera at the wrong point — an off-origin part would render off-centre or blank.
+    tmpPivot.updateMatrixWorld(true);
+    const box = new THREE.Box3().setFromObject(tmpPivot);
+    const center = box.getCenter(new THREE.Vector3()).toArray();
+    const radius = box.getSize(new THREE.Vector3()).length() / 2 || 1;
+    const pose = cameraPoseForView(angle, { center, radius });
+
+    // Light the throwaway scene ourselves: renderOffscreen's own key/fill (and the
+    // persistent hemisphere) live in the LIVE scene, which is never rendered here — so
+    // without our own ambient + camera-relative key/fill it comes back near-black.
+    const hemi = createHemisphereLight();
+    const capLights = createCaptureLights();
+    const poses = captureLightPoses(pose);
+    capLights.key.position.set(poses.key[0], poses.key[1], poses.key[2]);
+    capLights.fill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
+    for (const light of [capLights.key, capLights.fill]) {
+      light.target.position.set(pose.target[0], pose.target[1], pose.target[2]);
+    }
+    tmpScene.add(hemi, capLights.key, capLights.key.target, capLights.fill, capLights.fill.target);
+
+    // Feature-edge lines, so the thumbnail carries the same hole/seam/chamfer outlines the
+    // live viewer shows. A dedicated LineMaterial at the render resolution (the live one is
+    // sized to the on-screen canvas); added after framing so it can't perturb the bbox.
+    const lineMat = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 });
+    lineMat.resolution.set(size, size);
+    for (const mesh of built) {
+      const edges = mesh.geometry.userData.edges;
+      if (edges) tmpPivot.add(new LineSegments2(edges, lineMat));
+    }
+
+    try {
+      // fov matches the live camera (and captureViews/captureCurrent) — cameraPoseForView's
+      // distance is tuned to it, so a narrower fov would crop long, thin parts.
+      return renderOffscreen(pose, { width: size, height: size, fov: camera.fov, quality }, tmpScene);
+    } finally {
+      for (const mesh of built) {
+        mesh.geometry.userData.edges?.dispose();
+        mesh.geometry.dispose();
+        if (mesh.material !== material) mesh.material.dispose(); // clone only — never the shared singleton
+      }
+      lineMat.dispose();
+      hemi.dispose?.();
+      capLights.key.dispose?.();
+      capLights.fill.dispose?.();
+    }
+  }
+
   // --- render loop ----------------------------------------------------------
   // The tween is applied after controls.update() so the cue wins the frame, and
   // the frame listeners run before render so a playback frame draws its own pose.
@@ -523,7 +594,13 @@ export function createViewer(container, part) {
       camera.position.fromArray(tw.position);
       controls.target.fromArray(tw.target);
     }
-    for (const cb of [...frameListeners]) cb(dt);
+    // Per-listener guard, because three re-arms requestAnimationFrame only AFTER
+    // this callback returns (WebGLAnimation.onAnimationFrame): a listener that
+    // throws would stop the rAF chain outright and freeze the viewer for good, not
+    // just skip a frame. Containment belongs here rather than in every subscriber.
+    for (const cb of [...frameListeners]) {
+      try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
+    }
     if (cutaway.isEnabled) cutaway.updateForCamera();
     renderer.render(scene, camera);
     cutaway.renderOverlay(renderer, camera);
@@ -662,6 +739,7 @@ export function createViewer(container, part) {
     frame,
     captureCanonicalViews,
     captureCurrent,
+    renderMeshPayloads,
     onFrame,
     tweenCameraTo,
     cancelCameraTween,

package/src/framework/worker.js

@@ -110,7 +110,11 @@ export function runWorker(part) {
           await handle(kernel, job.part, job.data, gated, { isStale });
         } catch (err) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
-          postMessage({ type: "error", message: String(err?.message || err) });
+          // Carry the job's jobId when it has one (capture/export are correlated by it):
+          // a boot failure hitting kernelFor here must reach the right controller, or a
+          // correlated caller (captureView, exportParts) would hang instead of settling.
+          const jobId = job.data?.jobId;
+          postMessage({ type: "error", message: String(err?.message || err), ...(jobId != null ? { jobId } : {}) });
         }
       }
     } finally {

package/types/index.d.ts

@@ -5,14 +5,11 @@
 // their geometry helpers from "partforge/geometry".
 
 import type { BackendName } from "./kernel.js";
-import type { ParamValue, PartDefinition } from "./part.js";
+import type { CanonicalView, ParamValue, PartDefinition } from "./part.js";
 
 export * from "./kernel.js";
 export * from "./part.js";
 
-/** A canonical capture angle. */
-export type CanonicalView = "iso" | "front" | "back" | "left" | "right" | "top" | "bottom";
-
 /** Which pane a narrow layout shows. `null` hands selection back to partforge. */
 export type HostPane = "stage" | "rail" | null;
 
@@ -110,6 +107,8 @@ export interface MountOptions {
   onPick?: (event: PickEvent) => void;
   /** Receive exported bytes instead of partforge's own DOM download. */
   onDownload?: (file: DownloadPayload) => void;
+  /** The active view (tab) name — emitted once on mount, then on every change. */
+  onViewChange?: (view: string) => void;
   /** @deprecated alias for `elements.viewer`. */
   container?: HTMLElement | null;
   /** @deprecated alias for `elements.controls`. */
@@ -134,6 +133,15 @@ export interface CaptureCurrentOptions {
   quality?: number;
 }
 
+export interface CaptureViewOptions {
+  /** Square render resolution in px. Default 640. */
+  size?: number;
+  /** JPEG quality, 0..1. Default 0.8. */
+  quality?: number;
+  /** Canonical angle to render from. Default `"iso"`. */
+  angle?: CanonicalView | string;
+}
+
 /** Where playback is: idle, swinging the camera to an intro cue, playing, or paused. */
 export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
 
@@ -190,6 +198,17 @@ export interface PartRuntime {
    * when disposed or nothing is built yet. Never throws.
    */
   captureCurrent(opts?: CaptureCurrentOptions): string | null;
+  /** The active view (tab) name. Never null once mounted. */
+  getView(): string;
+  /** Switch the active view; `false` if the part declares no such view. Persists per part for the session. */
+  setView(name: string): boolean;
+  /**
+   * Render a named view OFFSCREEN → a `data:image/jpeg;base64,…` string, or `null` on
+   * failure (a build error, a view with no sub-parts, or a disposed runtime). Omit
+   * `viewName` — or pass an unknown one — to render the part's DEFAULT view. Never
+   * disturbs the active tab, the live camera, or the on-screen scene.
+   */
+  captureView(viewName?: string, opts?: CaptureViewOptions): Promise<string | null>;
   /**
    * Park/unpark the viewer: stops the render loop and releases the drawing
    * buffer and cached capture target. For a host that hides the canvas without

package/types/part.d.ts

@@ -297,11 +297,18 @@ export type Easing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
 export type Keyframes = Array<[number, number]>;
 
 /**
- * A camera cue angle: one of the seven canonical angles (`CanonicalView` in the
- * app entry — `"iso" | "front" | "back" | "top" | "bottom" | "left" | "right"`).
- * Cues fire during play only; scrubbing never moves the camera.
+ * The seven angles the viewer can frame a part from. Defined here rather than in
+ * the app entry so `CameraCue` can be the real union without an import cycle —
+ * the app entry re-exports it under its own name.
  */
-export type CameraCue = string;
+export type CanonicalView = "iso" | "front" | "back" | "left" | "right" | "top" | "bottom";
+
+/**
+ * A camera cue angle. `partforge lint` rejects anything outside the canonical
+ * seven (`animation-camera-invalid`), so the type says so too. Cues fire during
+ * play only; scrubbing never moves the camera.
+ */
+export type CameraCue = CanonicalView;
 
 /** One step of a multi-step animation. Steps play in order; prev/next navigate them. */
 export interface AnimationStep {
@@ -310,31 +317,31 @@ export interface AnimationStep {
   /** Seconds. Step durations are relative — they set each step's share of the timeline. */
   duration: number;
   easing?: Easing;
-  /** Param key -> keyframes. A param tracked nowhere keeps its current value. */
-  tracks: Record<string, Keyframes>;
+  /**
+   * 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.
+   */
+  tracks?: Record<string, Keyframes>;
   /** Swing the camera to this angle when the step begins. */
   camera?: CameraCue;
 }
 
 /**
- * One named animation: pure keyframe data over EXISTING params. Declare either
- * `tracks` (one anonymous step) or `steps`, never both. See
- * docs/AUTHORING-PARTS.md "Animations".
+ * The fields both animation forms share. Exported so a host can extend it —
+ * `AnimationSpec` itself is a union and cannot be `extends`-ed.
  */
-export interface AnimationSpec {
+export interface AnimationSpecCommon {
   /** Shown in the transport bar's picker. Defaults to the animation's key. */
   label?: string;
   /** CommonMark, shown behind the ⓘ glyph. */
   description?: string;
-  /** Seconds. Required in the single-step (`tracks`) form. */
-  duration?: number;
   easing?: Easing;
   /** Wrap continuously. Single-step animations only. */
   loop?: boolean;
-  /** The single-step form: param key -> keyframes. */
-  tracks?: Record<string, Keyframes>;
-  /** The multi-step form. */
-  steps?: AnimationStep[];
   /**
    * One mechanism per animation: an angle (an intro cue at t=0), a
    * `[[t, angle], …]` cue list, or per-step `camera` names.
@@ -350,6 +357,27 @@ export interface AnimationSpec {
   autoplay?: boolean;
 }
 
+/**
+ * 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.
+ */
+export type AnimationSpec =
+  | (AnimationSpecCommon & {
+      /** Seconds — the whole animation's duration in the single-phase form. */
+      duration: number;
+      /** Param key -> keyframes. */
+      tracks: Record<string, Keyframes>;
+      steps?: never;
+    })
+  | (AnimationSpecCommon & {
+      /** The multi-step form; each step carries its own relative `duration`. */
+      steps: AnimationStep[];
+      tracks?: never;
+      duration?: never;
+    });
+
 // --- the part itself --------------------------------------------------------
 
 /**