partforge 0.146.4 → 0.149.0

package/src/framework/mount.js

@@ -14,6 +14,8 @@ import { ENVIRONMENTS } from "./materials/environments.js";
 import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
 import { printFrameMatrix } from "./materials/print-frame.js";
 import { burnsFor, realisticDisplay, sheetFrameFor } from "./materials/sheet-look.js";
+import { pruneOverrides } from "./materials/overrides.js";
+import { subPartRows } from "./sub-part-list.js";
 import { buildControls } from "./controls.js";
 import { recordedRelevantKeys, subPartParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
@@ -39,7 +41,8 @@ import { createAnnotateMode } from "./annotate/annotate-mode.js";
 import { attachAnnotateControls } from "./annotate/annotate-controls.js";
 import { attachSketchToolbar } from "./annotate/sketch-toolbar.js";
 import { attachViewcubeControls } from "./viewcube/viewcube-controls.js";
-import { stageClearFor } from "./stage-clear.js";
+import { createPreviewGate } from "./preview-gate.js";
+import { observeViewbarClear } from "./viewbar-clear.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
@@ -69,9 +72,15 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, controlsFor, renderMode, environment, declaresMaterials, renderViews }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, controlsFor, renderMode, environment, declaresMaterials, renderViews, isPreviewActive, exportPreview, pendingCutaway, listSubParts, openAppearance, setDisplaySaveState }) {
   return {
     ready, dispose, setParams,
+    // Whether the `preview` GLB handed to mount() is on screen (see mount's
+    // preview block). A GETTER, read live: a host that copies the handle object
+    // freezes the value it had at that moment.
+    get previewActive() { return isPreviewActive?.() ?? false; },
+    // The view on screen as a preview GLB (partforge/gltf), poses baked in.
+    exportPreview: exportPreview ?? (() => Promise.reject(new Error("exportPreview: this mount cannot encode a preview"))),
     // Part-declared animation playback (spec 2026-08-02): animations are
     // VIEW-owned, so this is null only when NO view declares any.
     // { play(name?), pause(), seek(t), stop(), state() } — play(name) resolves
@@ -113,7 +122,9 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     getViewerState: () => ({
       camera: viewer.getCameraState(),
       projection: viewer.getProjection?.() ?? "perspective",
-      cutaway: viewer.getCutawayState?.() ?? null,
+      // A carried cutaway not yet restored (the preview holds it back) is still
+      // what the user last had: echo it, or a remount in that window drops it.
+      cutaway: pendingCutaway?.() ?? viewer.getCutawayState?.() ?? null,
       // The mode the user is headed for, not only the one on screen: a
       // realistic restore or switch still loading reads "realistic", so a
       // remount mid-load (the cloud remounts on every edit) doesn't drop it.
@@ -123,7 +134,29 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       // from meta.environment (or the default) would outrank the part's own
       // meta.environment on the next mount, masking an edit to it.
       ...(viewer.isEnvironmentChosen?.() ? { environment: viewer.getEnvironment() } : {}),
+      // Only while something is overridden: an empty map would be noise in a
+      // token hosts compare and store.
+      ...(() => { const d = viewer.getDisplayOverrides?.(); return d && Object.keys(d).length ? { display: d } : {}; })(),
     }),
+    // --- per-sub-part display overrides (spec 2026-10-13 part appearance controls) ---
+    // Live, no rebuild: appearance keys (material, colour, finish) merge over
+    // the authored `display` for every render; `hidden` and `opacity` are how
+    // the user is looking and never reach a material read, an export or a
+    // host's save. All of it rides getViewerState().display above.
+    setSubPartDisplay: (name, patch) => viewer.setSubPartDisplay?.(name, patch) ?? null,
+    getSubPartDisplay: (name) => viewer.getSubPartDisplayState?.(name) ?? null,
+    clearSubPartDisplay: (opts) => viewer.clearSubPartDisplay?.(opts),
+    onSubPartDisplayChange: (cb) => viewer.onDisplayChange?.(cb) ?? (() => {}),
+    // Every sub-part as a row (sub-part-list.js), for a host's own list; the
+    // active view unless `view` names another.
+    listSubParts: listSubParts ?? (() => []),
+    // Open the popover on the appearance card for `name`; false when there is
+    // no popover (a host with neither #viewbar nor a view cube stack).
+    openAppearance: openAppearance ?? (() => false),
+    // "saved" | "screen-only" | "blocked": the card's footer copy. A host that
+    // persists overrides into source says "saved"; one that cannot, for this
+    // sub-part, says "blocked"; the default is "screen-only".
+    setDisplaySaveState: setDisplaySaveState ?? (() => {}),
     // Every custom control's transient state (selection, a scroll position),
     // keyed by param, as plain JSON — the panel's twin of getViewerState. Hand
     // it back as mount()'s `panelState` and a remount comes up with the same
@@ -242,8 +275,10 @@ 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.141.0: a place()-able sub-part is delivered in its
-// canonical frame and posed by the viewer; pose-only edits never rebuild):
+// Embedding contract (0.147.0: a cached `preview` GLB is drawn before the kernel
+// boots and swapped in place by the first build; 0.141.0: a place()-able sub-part
+// is delivered in its canonical frame and posed by the viewer; pose-only edits
+// never rebuild):
 //   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
@@ -358,6 +393,15 @@ function createCleanupStack() {
 //                                         // switching the live view; "cad" is exactly captureViews(),
 //                                         // CAD in either live mode
 //   runtime.dispose();     // full teardown
+//   runtime.previewActive  // true while the `preview` GLB is on screen (decoded, not yet
+//                          // replaced by a whole live build): picking, hover labels,
+//                          // measure, sketch and cutaway wait; orbit, the view cube,
+//                          // the view style and the rail work
+//   await runtime.exportPreview();  // the view on screen as a preview GLB (Uint8Array,
+//                          // partforge/gltf), fast-path poses baked in. Rejects while
+//                          // previewActive, before the view is fully built (a pending
+//                          // rebuild counts), for a view other than the one on screen,
+//                          // and after dispose
 // 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
@@ -380,13 +424,20 @@ function createCleanupStack() {
 //                                         // payload is small, only that it is bounded.
 // viewerState: ViewerState               // a previous mount's runtime.getViewerState(), handed back to
 //                                         // resume the camera, projection, cutaway, render mode,
-//                                         // environment and per-style feature-line preferences
-//                                         // where that mount
+//                                         // environment, per-style feature-line preferences and
+//                                         // per-sub-part display overrides (`display`, pruned for
+//                                         // this part) where that mount
 //                                         // left them. For a host that applies edits by REMOUNTING: the
 //                                         // part changed, the user's view of it should not. Omit on a
 //                                         // first mount — the viewer then restores its own persisted
 //                                         // camera as before. Restore is best-effort per field: a pose
 //                                         // this part cannot support is dropped, never fatal.
+// preview: Uint8Array | ArrayBuffer      // a GLB from encodePreviewGlb / exportPreview, drawn before
+//                                         // the worker is ready and replaced sub-part by sub-part by
+//                                         // the first live build, camera kept. Only a file for the view
+//                                         // on screen is drawn, and only its sub-parts of that view; a
+//                                         // file for another view, or one that will not decode, is
+//                                         // logged once and ignored.
 // panelState: PanelState                 // a previous mount's runtime.getPanelState(): the transient
 //                                         // state of the part's custom controls (a selected tile), keyed
 //                                         // by param. Same remount story as viewerState; omit on a first
@@ -433,7 +484,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
                               fontCatalog,
                               imageCatalog,
                               onAssetUpload,
-                              viewerState,
+                              viewerState, preview,
                               files, panelState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
@@ -516,6 +567,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     cleanup.defer(() => ui.setStatus(""));
     cleanup.defer(() => ui.hideBusy());
 
+    // A cached preview (the `preview` option) is drawn before the kernel boots and
+    // held to the camera only — no feature ids, no live solids behind it — until
+    // the first whole live build replaces it. The gate is the flag, plus the
+    // chrome it disables meanwhile; picking and hover consult it per event. See
+    // the preview block just above `return makeHandle`.
+    const previewGate = createPreviewGate({
+      buttons: [els.chrome.cutaway, els.chrome.measure, els.chrome.annotate],
+    });
+
     // ?backend=occt|manifold forces the backend; otherwise it's re-detected per
     // regen with the live params (so a fillet dialed to 0 reverts to Manifold),
     // with a params-keyed latch for runtime needs-occt reroutes — see
@@ -569,6 +629,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     // 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.
+    // The popover's Parts section (attachViewStyleControls' `parts` seam) follows
+    // the active view; declared here because tabsCtl's onChange reads it.
+    const viewChangeListeners = new Set();
     const tabsCtl = createViewTabs(els.tabs, part, {
       onChange: (name) => {
         // FIRST: the outgoing animation restores its param snapshot, so the
@@ -581,6 +644,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // (and clear the posed ones' matrices) before anything else reads them.
         fastPath.apply(viewSubParts(part, view(), params));
         updateRelevance(); loop.kick(); animCtl?.autoplayKick();
+        for (const cb of [...viewChangeListeners]) { try { cb(name); } catch { /* listener's problem */ } }
         onViewChange?.(name);
       },
     });
@@ -705,6 +769,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // right rig first time rather than the default and then this one.
     const initialEnv = viewerState?.environment ?? loadEnvironment();
     if (initialEnv) viewer.setEnvironment(initialEnv);
+    // Carried display overrides, pruned for THIS part (materials/overrides.js):
+    // a renamed sub-part's entry goes, and an appearance key that now equals the
+    // authored value goes — which is how an owner's saved change self-cleans
+    // after the remount that applied it. Restored before the first showView so
+    // the first frame already draws the override, hidden pieces included.
+    for (const [name, override] of Object.entries(pruneOverrides(viewerState?.display, part))) {
+      viewer.setSubPartDisplay(name, override);
+    }
     // Realistic mode by the same precedence, requested HERE rather than on the
     // first accepted build: every mount has a fresh renderer, so the
     // environment loads again, and starting now runs that alongside the build
@@ -729,6 +801,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       stage: els.viewer,
       toolbar: els.viewer.querySelector("#viewbar"),
       anchor: viewcube.element,
+      // The Parts section's seam (view-style-controls.js); an older popover ignores it.
+      parts: {
+        list: () => subPartRows(part, { view: view(), params, overrides: viewer.getDisplayOverrides?.() ?? {} }),
+        setDisplay: (name, patch) => viewer.setSubPartDisplay(name, patch),
+        clear: (opts) => viewer.clearSubPartDisplay(opts),
+        onChange: (cb) => viewer.onDisplayChange?.(cb) ?? (() => {}),
+        onViewChange: (cb) => { viewChangeListeners.add(cb); return () => viewChangeListeners.delete(cb); },
+        getState: (name) => viewer.getSubPartDisplayState(name),
+      },
     }, { tooltip });
     cleanup.defer(() => viewStyle.detach());
     // setHidden takes one boolean, and there are two independent reasons to hide
@@ -755,21 +836,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // action rows can change. A hidden bar (ours or a host stylesheet's)
     // claims 0 — stage-clear.js has the why; the observer fires on the hide
     // itself, since the bar's box goes to zero.
-    const viewbarEl = els.viewer.querySelector("#viewbar");
-    if (viewbarEl && typeof ResizeObserver === "function") {
-      const publishViewbarClear = () => {
-        const clear = stageClearFor(els.viewer.getBoundingClientRect(), viewbarEl.getBoundingClientRect());
-        els.viewer.style.setProperty("--pf-viewbar-clear", `${clear}px`);
-      };
-      const viewbarObserver = new ResizeObserver(publishViewbarClear);
-      viewbarObserver.observe(viewbarEl);
-      viewbarObserver.observe(els.viewer);
-      publishViewbarClear();
-      cleanup.defer(() => {
-        viewbarObserver.disconnect();
-        els.viewer.style.removeProperty("--pf-viewbar-clear");
-      });
-    }
+    cleanup.defer(observeViewbarClear(els.viewer, els.viewer.querySelector("#viewbar")));
     // escapeScope: cutaway's Flip/Reset buttons are canvas SIBLINGS inside
     // #viewbar, not descendants of the canvas — attaching Escape to
     // viewer.domElement alone would leave a guarded Escape from those buttons
@@ -787,9 +854,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // active — measure's highlight + dims take the pointer; annotate's overlay
     // canvas takes it entirely.
     const syncHoverSuppression = () =>
-      hover.setSuppressed(measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false));
+      hover.setSuppressed(previewGate.isActive() || measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false));
     cleanup.defer(measureMode.onModeChange(syncHoverSuppression));
     if (annotateMode) cleanup.defer(annotateMode.onModeChange(syncHoverSuppression));
+    cleanup.defer(previewGate.onChange(syncHoverSuppression));
+    // Deferred AFTER the cutaway/measure/annotate chrome attached, so at dispose
+    // (LIFO) the gate hands the buttons back before those controls restore the
+    // host's own attributes.
+    cleanup.defer(() => previewGate.end());
 
     // Current selection context for the pickers: the active view + live params +
     // derived values. Shared by every pick mode below.
@@ -815,7 +887,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // resync on mode changes. The ?pick/?pickserver harnesses below are
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
-        suppressed: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
+        suppressed: () => previewGate.isActive() || measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
         onPick: (selection, anchor) => onPick({
           selection,
           label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
@@ -850,6 +922,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     let framedView = null; // the view the camera was last framed to (null until first show)
     let cameraRestored = false; // saved camera applied once, on the first frame after load
+    let cutawayRestored = false; // a carried cutaway, applied once — after any preview, never on one
 
     // Per-sub-part cache-validity tracker (Layer 1): view/version/caching change over
     // time, so they're passed as getters; params is a stable in-place-mutated object.
@@ -946,6 +1019,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // view doesn't flicker. If nothing's built yet, show nothing.
     // Show the assembly, framing the camera only the first time we show a given view
     // (initial load / tab switch) — never on a regenerate, so zoom/orbit are kept.
+    // A carried cutaway goes back on once, and never onto a cached preview: the
+    // section needs live solids to cut. `cam` is the pose to place again after
+    // it (an ortho face view's size is matched at the surface the cut decides).
+    function restoreCarriedCutaway(cam) {
+      cutawayRestored = true;
+      if (viewerState?.cutaway?.enabled && viewer.setCutawayState?.(viewerState.cutaway)) {
+        cutawayChrome.sync(); // the button was not what turned it on
+        if (cam) viewer.setCameraState(cam);
+      }
+    }
+
     function showView(needed) {
       const frame = view() !== framedView;
       viewer.showAssembly(needed, { frame });
@@ -959,26 +1043,23 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
           // only for a face-view camera, and this is the call that re-arms it.
           const cam = viewerState?.camera ?? loadCamera();
           if (cam) viewer.setCameraState(cam);
+          cameraRestored = true;
           // The cutaway goes back on AFTER the camera and only here, on the
           // first accepted build: enabling it needs the sub-parts registered
           // and real bounds to size the plane against, neither of which exists
           // until showAssembly above has run. (Its initial pose also reads the
           // camera direction, so a restore before the camera would seed the
-          // fallback pose from the wrong view.)
-          if (viewerState?.cutaway?.enabled && viewer.setCutawayState?.(viewerState.cutaway)) {
-            cutawayChrome.sync(); // the button was not what turned it on
-            // …and place the camera again now the section is back. An ortho
-            // face view's size is matched at the surface on screen, which the
-            // cut decides (the cap, or whatever survives it): the carried pose
-            // was taken WITH the cut, and the first placement above measured
-            // against the uncut part, so without this a sectioned face view
-            // changes zoom on every remount. Same pose, so a perspective
-            // camera does not move.
-            if (cam) viewer.setCameraState(cam);
-          }
-          cameraRestored = true;
+          // fallback pose from the wrong view.) A cached preview defers it to
+          // the live build below.
+          if (!previewGate.isActive()) restoreCarriedCutaway(cam);
         }
       }
+      if (cameraRestored && !cutawayRestored && !previewGate.isActive()) {
+        // The preview held the cut back and the live build is in. Re-place the
+        // camera the user is looking at NOW — they may have orbited the preview
+        // — not the carried one.
+        restoreCarriedCutaway(viewer.getCameraState());
+      }
     }
 
     // Frames the realistic look reads, for the geometry just delivered:
@@ -992,10 +1073,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     //  - sheet frames for the burn pass (materials/sheet-look.js): a laser sheet in a wood,
     //    mapped back into its canonical frame — from data, no probe.
     // Each describes the delivered mesh (which a later pose-only repair only moves).
-    const layerLined = new Set(Object.keys(part.parts).filter((n) => {
-      try { return resolveMaterial(realisticDisplay(part.parts[n])).params.pattern === "layer-lines"; } catch { return false; }
-    }));
-    const burning = new Set(Object.keys(part.parts).filter((n) => burnsFor(part.parts[n])));
+    // Which sub-parts need frames is read off the EFFECTIVE display at the time
+    // the frames are computed, not fixed at mount: a live material change (the
+    // Parts section) can turn a plain piece into a layer-lined print, and it
+    // must get its print frame without a rebuild. So every delivery's
+    // dispatch record is kept (one small object per sub-part), and computeFrames
+    // decides per name.
+    const effectiveSubPart = (n) => ({ ...part.parts[n], display: viewer.effectiveDisplayOf?.(n) ?? part.parts[n].display });
+    const isLayerLined = (n) => {
+      try { return resolveMaterial(realisticDisplay(effectiveSubPart(n))).params.pattern === "layer-lines"; } catch { return false; }
+    };
+    const isBurning = (n) => burnsFor(effectiveSubPart(n));
     // LAZY: a delivery only records the view and params its job was DISPATCHED with
     // (`dispatched`, set where the loop sends) — not the live ones, which a delivery shown
     // during playback was never built at; the viewer pulls the frames (computeFrames)
@@ -1004,20 +1092,32 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // snapshot keeps a late computation describing the mesh actually delivered.
     const printFrames = {};
     const sheetFrames = {};
-    const undrawnFrames = new Map(); // sub-part -> { at: { view, params } its delivered mesh was built at, frame }
+    const deliveredAt = new Map(); // sub-part -> { at: { view, params }, frame } of its delivered mesh (kept, not consumed)
+    const undrawnFrames = new Set(); // sub-part names whose frames are stale
+    // The (print, burn) pair each name's frames were last computed for. A display
+    // change re-stales a name only when its pair flips — hide, show, opacity and a
+    // swap between two layer-lined (or two burning) materials leave the frames
+    // valid, so a see-through drag in realistic mode never re-probes a placed piece.
+    const frameNeeds = new Map();
+    const needsKey = (n) => `${isLayerLined(n) ? 1 : 0}${isBurning(n) ? 1 : 0}`;
     // `meshes` are the reply's deliveries: each one's `frame` ("canonical" | "posed"; an older
     // worker sends none, so posed) rides beside the view/params so the frames describe it.
     function recordFrames(meshes) {
-      const wanted = meshes.filter((m) => layerLined.has(m.name) || burning.has(m.name));
-      if (!wanted.length) return;
-      for (const m of wanted) {
-        undrawnFrames.set(m.name, { at: dispatched.get(m.name) ?? null, frame: m.frame ?? "posed" }); // at null: built at params nobody recorded
+      for (const m of meshes) {
+        deliveredAt.set(m.name, { at: dispatched.get(m.name) ?? null, frame: m.frame ?? "posed" }); // at null: built at params nobody recorded
+        undrawnFrames.add(m.name);
       }
       viewer.invalidateFrames?.();
     }
     function computeFrames() {
       const resolvedFor = new Map(); // one resolveParams per delivery, not per sub-part
-      for (const [n, { at, frame }] of undrawnFrames) {
+      for (const n of undrawnFrames) {
+        const rec = deliveredAt.get(n);
+        if (!rec) continue;
+        const { at, frame } = rec;
+        const needPrint = isLayerLined(n), needBurn = isBurning(n);
+        frameNeeds.set(n, `${needPrint ? 1 : 0}${needBurn ? 1 : 0}`);
+        if (!needPrint && !needBurn) { delete sheetFrames[n]; continue; }
         if (at && !resolvedFor.has(at)) {
           try { resolvedFor.set(at, resolveParams(part, at.params)); } catch { resolvedFor.set(at, null); } // diagnosed by the build
         }
@@ -1029,8 +1129,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         if (!resolved) { delete sheetFrames[n]; continue; }
         // For a views-map sub-part the export pose is the build itself (plus a sheet pose), so a canonical
         // delivery's print frame is identity — no special case, the probe reads the compiled placement.
-        if (layerLined.has(n)) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved, frame });
-        if (burning.has(n)) {
+        if (needPrint) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved, frame });
+        if (needBurn) {
           const f = sheetFrameFor(part.parts[n], { ...resolved, frame });
           if (f) sheetFrames[n] = f; else delete sheetFrames[n];
         }
@@ -1038,10 +1138,26 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       undrawnFrames.clear();
       return { print: { ...printFrames }, sheet: { ...sheetFrames } };
     }
+    // A display change re-stales a delivered sub-part's frames when it changes
+    // WHICH frames that piece needs (frameNeeds above); a `null` event (a clear)
+    // re-checks every delivered name. computeFrames stays lazy (viewer.js
+    // syncFrames), so a CAD-only session still computes nothing.
+    cleanup.defer(viewer.onDisplayChange?.((evt) => {
+      let stale = false;
+      for (const n of evt?.name ? [evt.name] : deliveredAt.keys()) {
+        if (!deliveredAt.has(n) || undrawnFrames.has(n)) continue; // nothing drawn yet, or already stale
+        if (frameNeeds.get(n) === needsKey(n)) continue;
+        undrawnFrames.add(n);
+        stale = true;
+      }
+      if (stale) viewer.invalidateFrames?.();
+    }) ?? (() => {}));
     viewer.setFrameSource?.(computeFrames);
 
     // Sub-parts whose latest fresh delivery had zero triangles (see the `meshes` case).
     const emptySubParts = new Set();
+    // Any live delivery has landed. A preview decoded after this is dropped unseen.
+    let liveDelivered = false;
 
     function refreshView() {
       const needed = viewSubParts(part, view(), params);
@@ -1055,6 +1171,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       } else if (needed.every((n) => viewer.hasSubMesh(n))) {
         showView(needed); // stale but present — keep it visible during regenerate
         ui.setExportEnabled(false);
+      } else if (previewGate.isActive()) {
+        // A cached preview that covers only part of the view: show what it has.
+        showView(needed.filter((n) => viewer.hasSubMesh(n)));
+        ui.setExportEnabled(false);
       } else {
         viewer.hideAssembly();
         ui.setExportEnabled(false);
@@ -1086,6 +1206,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         case "meshes": {
           const fresh = loop.buildDone();
           if (fresh) { // stale results (params changed mid-build) are discarded
+            liveDelivered = true; // only a delivery that is applied beats a preview still decoding
             for (const m of data.meshes) {
               viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
               // The view its job was SENT for, and the frame the worker delivered
@@ -1112,6 +1233,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
             // forgetting on a disagreement would rebuild at the same params forever).
             fastPath.apply(data.meshes.map((m) => m.name), undefined, { fresh: true });
             recordFrames(data.meshes);
+            // The whole view is live: every sub-part the preview drew has just been
+            // replaced in place, so the tools it held back come back. Before
+            // refreshView, so showView restores a carried cutaway on this build.
+            if (previewGate.isActive() && missingParts().length === 0) previewGate.end();
             // A split dispatch answers in two meshes replies; the busy spinner
             // stays up until the view has everything (the other worker's job may
             // still be running — often OCCT, the slow one).
@@ -1459,12 +1584,81 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       return binding;
     };
 
+    // Set by the first cleanup to run at dispose (LIFO): late async work checks it.
+    let disposed = false;
+    cleanup.defer(() => { disposed = true; });
+
+    // The cached preview: a GLB from partforge/gltf, decoded off the worker path
+    // and drawn through setSubGeometry like any delivery — so the first live
+    // `meshes` reply replaces it in place, sub-part by sub-part, and showView
+    // keeps the camera (the view was already framed). Only a file for the view on
+    // screen is drawn, and only its sub-parts of that view; anything else — or a
+    // file that will not decode — is logged once and ignored.
+    if (preview != null) {
+      // Loaded on demand: the GLTFLoader and meshopt decoder behind it stay out
+      // of every bundle that never passes a preview.
+      import("./gltf/decode-preview.js").then(({ decodePreviewGlb }) => (
+        disposed ? null : decodePreviewGlb(preview)
+      )).then((decoded) => {
+        if (decoded == null) return;
+        const { view: previewView, meshes } = decoded;
+        if (disposed || liveDelivered) return; // live geometry always wins
+        const current = view();
+        if (previewView != null && previewView !== current) {
+          console.warn(`partforge: preview ignored — it shows view "${previewView}", the viewer opened on "${current}"`);
+          return;
+        }
+        const needed = viewSubParts(part, current, params);
+        const shown = meshes.filter((m) => needed.includes(m.name));
+        if (shown.length === 0) {
+          console.warn("partforge: preview ignored — none of its meshes is a sub-part of the view on screen");
+          return;
+        }
+        measureMode.setEnabled(false);
+        annotateMode?.setEnabled(false);
+        previewGate.start();
+        for (const m of shown) viewer.setSubGeometry(m.name, m);
+        refreshView();
+      }).catch((error) => {
+        if (!disposed) console.warn(`partforge: preview ignored — ${error?.message ?? error}`);
+      });
+    }
+
+    // runtime.exportPreview: the view on screen as a preview GLB — every sub-part's
+    // drawn mesh with its fast-path pose baked in, the posed meshes a headless
+    // buildView returns. Only the view on screen (no other view's meshes are held),
+    // only when it is fully built at the live params (missingParts covers both a
+    // first build and an edit still rebuilding), never a cached preview. The
+    // encoder loads on first use: a host that never exports never pays for it.
+    async function exportPreview({ view: wanted } = {}) {
+      if (disposed) throw new Error("exportPreview: this mount is disposed");
+      if (previewGate.isActive()) throw new Error("exportPreview: a cached preview is showing — wait for the first build");
+      const current = view();
+      if (wanted != null && wanted !== current) {
+        throw new Error(`exportPreview: "${wanted}" is not the view on screen ("${current}")`);
+      }
+      const needed = viewSubParts(part, current, params);
+      if (needed.length === 0 || missingParts().length > 0) {
+        throw new Error("exportPreview: the view on screen is not fully built");
+      }
+      const meshes = needed.map((name) => viewer.getSubMeshPayload(name)).filter(Boolean);
+      const { encodePreviewGlb } = await import("./gltf/encode-preview.js");
+      return encodePreviewGlb({ meshes, part, view: current });
+    }
+
     return makeHandle({
       ready, dispose, viewer, setParams,
+      isPreviewActive: () => previewGate.isActive(),
+      pendingCutaway: () => (!cutawayRestored ? viewerState?.cutaway ?? null : null),
+      exportPreview,
       attachTooltips: attachHostTooltips,
       setHostPane: paneTabs.setHostPane,
       setRailLayout: paneTabs.setRailLayout,
       getView: view,                         // () => tabsCtl.current()
+      // `opts` may be null from a host (a destructuring default covers only undefined).
+      listSubParts: (opts) => subPartRows(part, { view: opts?.view ?? view(), params, overrides: viewer.getDisplayOverrides?.() ?? {} }),
+      openAppearance: (name) => viewStyle.openCard?.(name) ?? false,
+      setDisplaySaveState: (state) => viewStyle.setSaveState?.(state),
       setView: (name) => tabsCtl.select(name),
       captureView,
       getPanelState: () => panelRef?.getState() ?? {},
@@ -1481,13 +1675,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       animation: animCtl?.runtime ?? null,
       measure: {
         isEnabled: measureMode.isEnabled,
-        setEnabled: measureMode.setEnabled,
+        // Held off while a cached preview shows (no feature ids to dimension).
+        setEnabled: (on) => { if (on && previewGate.isActive()) return; measureMode.setEnabled(on); },
         clearPins: measureMode.clearPins,
         pinCount: measureMode.pinCount,
       },
       annotate: annotateMode ? {
         isEnabled: annotateMode.isEnabled,
-        setEnabled: annotateMode.setEnabled,
+        setEnabled: (on) => { if (on && previewGate.isActive()) return; annotateMode.setEnabled(on); },
         undo: annotateMode.undo,
         clear: annotateMode.clear,
         strokeCount: annotateMode.strokeCount,