partforge 0.44.0 → 0.46.0

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
@@ -166,7 +166,7 @@ export function createViewer(container, part) {
   }
 
   // CAD-style feature edge lines (anti-aliased "fat" lines), one per sub-part.
-  const EDGE_ANGLE = 35; // deg — OCCT fallback threshold (Manifold supplies seam-aware edges)
+  const EDGE_ANGLE = 35; // deg — last-ditch threshold for payloads with no kernel edge data
   const lineMaterial = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 }); // ~10% lighter, 1 px
   lineMaterial.resolution.set(1, 1); // real size set by resize() below
   const subLines = Object.fromEntries(
@@ -246,10 +246,10 @@ export function createViewer(container, part) {
   controls.addEventListener("start", onControlsStart);
   function onCameraStart(cb) { cameraStartListeners.add(cb); return () => cameraStartListeners.delete(cb); }
 
-  // Smooth shading within CREASE_ANGLE of a shared edge, hard edge past it — so the
-  // round body and helical groove read smooth while bore rims, drum faces, and
-  // groove walls stay crisp. Lower = more hard edges; raise toward Math.PI/3 for
-  // softer. (Worker normals are ignored; we recompute per the crease threshold.)
+  // Fallback creasing for payloads with no kernel normals. Both backends now
+  // ship authoritative normals (Manifold: policy-aware crease pass; OCCT:
+  // analytic B-rep normals), so this path is last-ditch only — it must not be
+  // "improved" in lieu of fixing a backend that stopped sending normals.
   const CREASE_ANGLE = Math.PI / 6; // 30°
 
   // --- geometry builder -----------------------------------------------------
@@ -262,20 +262,23 @@ export function createViewer(container, part) {
     const triCount = triangles ?? (indices ? indices.length : positions.length / 3) / 3;
     let out;
     if (normals?.length) {
-      // kernel-computed normals (Manifold) — smooth within a surface, hard at cut seams
+      // kernel-computed normals (both backends) — smooth within a surface, hard at cut seams
       geo.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
       geo.computeBoundingBox();
       out = geo;
     } else {
-      // fallback (no kernel normals, e.g. OCCT): crease from the triangle soup
+      // fallback (payload with no kernel normals — no current backend does this): crease from the triangle soup
       out = toCreasedNormals(geo, CREASE_ANGLE);
       out.computeBoundingBox();
     }
     out.userData.triangles = triCount;
     if (featureIds) { out.userData.featureIds = featureIds; out.userData.features = features; }
-    // feature edge lines: Manifold supplies seam-aware segments; else derive by angle
+    // feature edge lines: kernel-supplied segments are authoritative — an EMPTY
+    // array means "this solid has no feature edges" (e.g. a lone sphere), so
+    // draw none rather than falling back. Only a payload with NO edge data at
+    // all (edges === undefined; no current backend does this) derives by angle.
     const lg = new LineSegmentsGeometry();
-    if (edges?.length) lg.setPositions(edges);
+    if (edges) lg.setPositions(edges); // edges is already a well-formed (possibly zero-length) Float32Array
     else lg.fromEdgesGeometry(new THREE.EdgesGeometry(out, EDGE_ANGLE));
     out.userData.edges = lg;
     return out;
@@ -427,7 +430,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 +455,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 +514,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 +597,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 +742,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/src/testing/render.js

@@ -86,8 +86,8 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
 
     for (const m of meshes) {
       const P = m.positions, N = m.normals, ind = m.indices;
-      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle) with
-      // per-vertex normals; OCCT meshes are indexed and carry no normals.
+      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle);
+      // OCCT meshes are indexed. Both carry per-vertex normals.
       const triCount = ind?.length ? ind.length / 3 : P.length / 9;
       for (let t = 0; t < triCount; t++) {
         const ai = ind?.length ? ind[t * 3] * 3 : t * 9;

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