partforge 0.146.4 → 0.147.0

package/README.md

@@ -169,6 +169,31 @@ Parking releases both large GPU allocations — the drawing buffer and the cache
 unchanged, so a host can still take a build screenshot of a hidden viewer; the
 first capture after parking just re-allocates its target.
 
+**Show a cached preview while the kernel boots (0.147.0+).** `partforge/gltf`'s
+`encodePreviewGlb({ meshes, part, view })` writes one view's posed display
+meshes as a small GLB — welded, quantized and meshopt-compressed, one node per
+sub-part, Y-up, millimetres — in Node, a page or a worker, and
+`runtime.exportPreview()` encodes the view on screen with it. Hand the file back
+as `mount()`'s `preview` and the viewer draws it before the worker is ready, then
+swaps each sub-part for the live build in place without re-framing;
+`runtime.previewActive` is true in between, while picking, measure, sketch and
+cutaway wait for the live build. A file for another view, or one that will not
+decode, is logged and ignored (a file written without a view is drawn on
+sub-part name match alone). `mountPreview(container, { glb, elements,
+viewerState })` is the kernel-free form — the same viewer, view cube, view style
+and theme, with no part, no worker and no rail — for a page that only shows a
+model (CAD look exact; realistic mode uses each sub-part's display only — no sheet
+stock, no layer-line frames). Previews carry no edge lines, textures or patterns.
+`resolveDefaultView(part)` (main entry and `partforge/testing`) names the view
+`mount()` opens on, so a preview built headlessly matches it.
+
+```js
+const glb = await runtime.exportPreview();               // Uint8Array: the view on screen
+mount(part, { createWorker, elements, preview: glb });   // drawn at once, replaced by the build
+const shown = mountPreview(stage, { glb });              // no kernel at all
+await shown.ready;
+```
+
 Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,
 `#panel` for `rail`, `#status`/`#busy`/`#phase`, `#part`,
 `#download`/`#download-step`/`#download-3mf`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.146.4",
+  "version": "0.147.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",
@@ -62,6 +62,10 @@
       "types": "./types/panel-values.d.ts",
       "default": "./src/panel-values.js"
     },
+    "./gltf": {
+      "types": "./types/gltf.d.ts",
+      "default": "./src/gltf.js"
+    },
     "./tokens.css": "./src/framework/tokens.css",
     "./chrome.css": "./src/framework/chrome.css"
   },
@@ -90,6 +94,9 @@
       ],
       "panel-values": [
         "./types/panel-values.d.ts"
+      ],
+      "gltf": [
+        "./types/gltf.d.ts"
       ]
     }
   },
@@ -120,10 +127,14 @@
     }
   },
   "dependencies": {
+    "@gltf-transform/core": "^4.5.1",
+    "@gltf-transform/extensions": "^4.5.1",
+    "@gltf-transform/functions": "^4.5.1",
     "dompurify": "^3.4.11",
     "fflate": "^0.8.3",
     "manifold-3d": "^3.5.1",
     "marked": "^18.0.5",
+    "meshoptimizer": "^1.3.0",
     "opentype.js": "^2.0.0",
     "paper": "^0.12.18",
     "pngjs": "^7.0.0",

package/src/framework/default-view.js

@@ -5,10 +5,13 @@
 // declaration order, so every part written before this existed resolves to the view
 // it has always opened on.
 //
-// Pure: no DOM, no storage, no kernel, no build. The headless surfaces (measure /
-// verify / renderViews) deliberately do NOT use this — they stay on
+// Pure: no DOM, no storage, no kernel, no build. partforge's own headless surfaces
+// (measure / verify / renderViews) deliberately do NOT use this — they stay on
 // Object.keys(part.views)[0], where a mechanically obvious rule matters more than a
-// convenient one.
+// convenient one. It is exported (main entry and partforge/testing, 0.147.0) for a
+// host that must open the SAME view mount() does — a cached preview built off the
+// viewer has to match the live build it is swapped for. The signature is (part): it
+// reads part.defaults, never caller params.
 import { inView } from "./sub-part-views.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);

package/src/framework/gltf/decode-preview.js

@@ -0,0 +1,89 @@
+// The cached-preview reader (main thread): a GLB written by encode-preview.js,
+// decoded with three's GLTFLoader + MeshoptDecoder and turned back into the
+// viewer's own mesh payloads — { name, positions, normals, indices, triangles,
+// edges } in the part's Z-up MODEL frame — so a preview is drawn through
+// viewer.setSubGeometry exactly like a worker delivery. Everything after that
+// (the pivot, the per-sub-part CAD material, framing, the cutaway, captures)
+// is the viewer's existing code.
+//
+// Why payloads and not the loaded scene graph: the file's root node carries the
+// −90° about X that stands Z-up on end, and the viewer's pivot carries the same
+// rotation; parenting the glTF root under the pivot would turn the part twice.
+// Undoing the root here hands the viewer geometry in the frame it already owns.
+//
+// Rejects on anything that is not a decodable GLB; the callers (mount's
+// `preview`, mountPreview) decide what a failure means for them.
+import { Matrix3, Matrix4, Vector3 } from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
+
+// The writer's root rotation (−90° about X), inverted: glTF Y-up → model Z-up.
+const Y_UP_TO_Z_UP = new Matrix4().makeRotationX(Math.PI / 2);
+
+function toArrayBuffer(bytes) {
+  if (bytes instanceof ArrayBuffer) return bytes;
+  if (ArrayBuffer.isView(bytes)) return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  throw new TypeError("decodePreviewGlb: the preview must be a Uint8Array or an ArrayBuffer");
+}
+
+// Read a (possibly quantized, normalized) vec3 attribute out as Float32, transformed.
+function readVec3(attr, matrix, isNormal) {
+  const out = new Float32Array(attr.count * 3);
+  const v = new Vector3();
+  for (let i = 0; i < attr.count; i++) {
+    v.fromBufferAttribute(attr, i); // denormalizes a KHR_mesh_quantization attribute
+    if (isNormal) v.applyMatrix3(matrix).normalize();
+    else v.applyMatrix4(matrix);
+    out[i * 3] = v.x;
+    out[i * 3 + 1] = v.y;
+    out[i * 3 + 2] = v.z;
+  }
+  return out;
+}
+
+function metaOf(extras) {
+  const m = extras?.partforgeMeta;
+  if (!m || typeof m !== "object") return null;
+  const out = {};
+  if (Number.isInteger(m.background)) out.background = m.background;
+  if (typeof m.environment === "string") out.environment = m.environment;
+  return Object.keys(out).length ? out : null;
+}
+
+export async function decodePreviewGlb(bytes) {
+  const data = toArrayBuffer(bytes);
+  const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+  const gltf = await loader.parseAsync(data, "");
+  gltf.scene.updateMatrixWorld(true);
+  const meshes = [];
+  const toModel = new Matrix4();
+  const normalMatrix = new Matrix3();
+  gltf.scene.traverse((obj) => {
+    if (!obj.isMesh) return;
+    const geometry = obj.geometry;
+    const position = geometry.getAttribute("position");
+    if (!position || position.count === 0) return;
+    toModel.multiplyMatrices(Y_UP_TO_Z_UP, obj.matrixWorld);
+    normalMatrix.getNormalMatrix(toModel);
+    const normal = geometry.getAttribute("normal");
+    const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
+    const { partforgeSubPart, partforgeDisplay, name: originalName } = obj.userData;
+    meshes.push({
+      // The writer's own record of the key, then the unsanitized glTF node name.
+      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? obj.name),
+      positions: readVec3(position, toModel, false),
+      normals: normal ? readVec3(normal, normalMatrix, true) : null,
+      indices,
+      triangles: (indices ? indices.length : position.count) / 3,
+      edges: new Float32Array(0), // previews carry no feature edges (v1)
+      display: partforgeDisplay && typeof partforgeDisplay === "object" ? partforgeDisplay : null,
+    });
+    geometry.dispose();
+  });
+  const extras = gltf.userData ?? {};
+  return {
+    view: typeof extras.partforgeView === "string" ? extras.partforgeView : null,
+    meta: metaOf(extras),
+    meshes,
+  };
+}

package/src/framework/gltf/encode-preview.js

@@ -0,0 +1,142 @@
+// The cached-preview writer behind `partforge/gltf`: one view's POSED display
+// meshes (the payloads the viewer, the worker's `meshes` reply and the oracle's
+// buildView all hold) as a small GLB a viewer can show before the kernel boots.
+//
+// The file, which a reader may rely on:
+//  - one node + mesh + primitive per sub-part, all three named by the sub-part
+//    key; POSITION + NORMAL (+ indices when the kernel sent them)
+//  - every sub-part node under ONE root node, "partforge", rotated −90° about X:
+//    partforge models Z-up in millimetres and glTF is Y-up. Units stay mm — the
+//    file is for partforge's own viewer; metres would only matter for AR.
+//  - each material from cadAppearance — the CAD look the viewer itself draws —
+//    and each node's extras carrying the sub-part's own `display` block, so a
+//    part-less viewer (mountPreview) can rebuild the exact look, realistic too
+//  - top-level extras { partforgeView, partforgeEncoder, partforgeMeta? }
+//  - weld() → quantize() → meshopt({ level: "medium" }): 5–8 bytes a triangle,
+//    the recipe measured in partforge-cloud's local_glb_benchmark.md
+// Not encoded (v1): feature edges, textures, patterns.
+//
+// Runs in Node, a page and a Web Worker: no three.js, no DOM, no Blob
+// (test/gltf-layering.test.js). Deterministic: the same input writes the same
+// bytes, and nothing here mutates the input (exportPreview passes the viewer's
+// live buffers). Bump PREVIEW_ENCODER_VERSION whenever the bytes for the same
+// input change — downstream caches key on it.
+import { Document, Logger, WebIO } from "@gltf-transform/core";
+import { EXTMeshoptCompression, KHRMeshQuantization } from "@gltf-transform/extensions";
+import { meshopt, quantize, weld } from "@gltf-transform/functions";
+import { MeshoptEncoder } from "meshoptimizer/encoder";
+import { cadAppearance, DISPLAY_KEYS } from "../materials/resolve.js";
+
+export const PREVIEW_ENCODER_VERSION = 1;
+
+// −90° about X as [x, y, z, w]: model (x, y, z) → glTF (x, z, −y), the viewer's pivot.
+const Z_UP_TO_Y_UP = [-Math.SQRT1_2, 0, 0, Math.SQRT1_2];
+
+let encoderReady = null; // MeshoptEncoder's wasm, awaited once per process
+
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+function baseColorFactor(hex, opacity) {
+  return [(hex >> 16) & 255, (hex >> 8) & 255, hex & 255].map((v) => srgbToLinear(v / 255)).concat(opacity);
+}
+
+// The display block as plain data (resolve.js's own keys, primitive values only).
+function displayExtras(display) {
+  if (!display || typeof display !== "object") return null;
+  const out = {};
+  for (const key of DISPLAY_KEYS) {
+    const v = display[key];
+    if (typeof v === "string" || (typeof v === "number" && Number.isFinite(v))) out[key] = v;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+// The two meta fields createViewer reads (background, environment).
+function metaExtras(meta) {
+  if (!meta || typeof meta !== "object") return null;
+  const out = {};
+  if (Number.isInteger(meta.background)) out.background = meta.background;
+  if (typeof meta.environment === "string") out.environment = meta.environment;
+  return Object.keys(out).length ? out : null;
+}
+
+function checkMesh(m, seen) {
+  if (!m || typeof m.name !== "string" || !m.name) throw new TypeError("encodePreviewGlb: every mesh needs a non-empty string name");
+  if (seen.has(m.name)) throw new Error(`encodePreviewGlb: two meshes are named "${m.name}"`);
+  seen.add(m.name);
+  if (!ArrayBuffer.isView(m.positions)) throw new TypeError(`encodePreviewGlb: "${m.name}" positions must be a typed array`);
+  const indexed = m.indices != null && m.indices.length > 0;
+  if (m.positions.length % (indexed ? 3 : 9) !== 0) {
+    throw new Error(`encodePreviewGlb: "${m.name}" positions are not whole ${indexed ? "vertices" : "triangles"}`);
+  }
+  if (indexed && m.indices.length % 3 !== 0) throw new Error(`encodePreviewGlb: "${m.name}" indices are not whole triangles`);
+  if (m.normals != null && m.normals.length > 0 && m.normals.length !== m.positions.length) {
+    throw new Error(`encodePreviewGlb: "${m.name}" normals do not match its positions`);
+  }
+  if (indexed) {
+    const vertexCount = m.positions.length / 3;
+    for (let i = 0; i < m.indices.length; i++) {
+      if (!(m.indices[i] < vertexCount)) {
+        throw new Error(`encodePreviewGlb: "${m.name}" indices reference a vertex that does not exist`);
+      }
+    }
+  }
+}
+
+export async function encodePreviewGlb({ meshes, part = null, view = null } = {}) {
+  if (!Array.isArray(meshes) || meshes.length === 0) throw new TypeError("encodePreviewGlb: meshes must be a non-empty array");
+  const seen = new Set();
+  for (const m of meshes) checkMesh(m, seen);
+  try {
+    await (encoderReady ??= MeshoptEncoder.ready);
+  } catch (error) {
+    encoderReady = null; // a failed wasm load must not be cached: a later call retries
+    throw error;
+  }
+
+  const viewName = typeof view === "string" && view ? view : null;
+  const doc = new Document();
+  doc.setLogger(new Logger(Logger.Verbosity.SILENT));
+  const buffer = doc.createBuffer();
+  const scene = doc.createScene(viewName ?? "preview");
+  const root = doc.createNode("partforge").setRotation(Z_UP_TO_Y_UP);
+  scene.addChild(root);
+  const meta = metaExtras(part?.meta);
+  doc.getRoot().setExtras({
+    partforgeView: viewName,
+    partforgeEncoder: PREVIEW_ENCODER_VERSION,
+    ...(meta ? { partforgeMeta: meta } : {}),
+  });
+
+  for (const m of meshes) {
+    if (m.positions.length === 0) continue; // glTF forbids a zero-count accessor
+    // Copies throughout: setArray keeps the array it is handed, and the
+    // transforms below rewrite it.
+    const prim = doc.createPrimitive().setAttribute(
+      "POSITION", doc.createAccessor().setType("VEC3").setArray(new Float32Array(m.positions)).setBuffer(buffer));
+    if (m.normals?.length) {
+      prim.setAttribute("NORMAL", doc.createAccessor().setType("VEC3").setArray(new Float32Array(m.normals)).setBuffer(buffer));
+    }
+    if (m.indices?.length) {
+      prim.setIndices(doc.createAccessor().setType("SCALAR").setArray(new Uint32Array(m.indices)).setBuffer(buffer));
+    }
+    const display = part?.parts?.[m.name]?.display;
+    const look = cadAppearance(display);
+    prim.setMaterial(doc.createMaterial(m.name)
+      .setBaseColorFactor(baseColorFactor(look.color, look.opacity))
+      .setMetallicFactor(look.metalness)
+      .setRoughnessFactor(look.roughness)
+      .setAlphaMode(look.opacity < 1 ? "BLEND" : "OPAQUE"));
+    const extras = displayExtras(display);
+    root.addChild(doc.createNode(m.name)
+      .setMesh(doc.createMesh(m.name).addPrimitive(prim))
+      .setExtras(extras ? { partforgeSubPart: m.name, partforgeDisplay: extras } : { partforgeSubPart: m.name }));
+  }
+  if (root.listChildren().length === 0) throw new Error("encodePreviewGlb: every mesh was empty");
+
+  await doc.transform(weld(), quantize(), meshopt({ encoder: MeshoptEncoder, level: "medium" }));
+  const io = new WebIO()
+    .registerExtensions([EXTMeshoptCompression, KHRMeshQuantization])
+    .registerDependencies({ "meshopt.encoder": MeshoptEncoder });
+  io.setLogger(new Logger(Logger.Verbosity.SILENT));
+  return io.writeBinary(doc);
+}

package/src/framework/mount-preview.js

@@ -0,0 +1,157 @@
+// mountPreview: the kernel-free viewer. A cached preview GLB (partforge/gltf) in
+// the SAME viewer mount() uses — scene, camera, lights, materials, the view cube,
+// the view style and the theme — with no part source, no worker, no rail, no
+// export and no picking. For a page that only shows a model (partforge-cloud's
+// public forge page).
+//
+// createViewer needs a part's sub-part names at construction, so the viewer is
+// built once the GLB has decoded, from a synthetic part: one sub-part per glTF
+// mesh, carrying the `display` block the writer stored beside it, and the file's
+// background/environment meta. The CAD look is exact; realistic mode uses each
+// sub-part's display only — no sheet stock, no layer-line print frames (a v1
+// residual alongside "no edges"). The decoder loads on demand (it carries the
+// GLTFLoader and meshopt), so a bundle that never mounts a preview never ships it.
+// Hence `ready`. Every handle method is safe before it resolves.
+import "./app.css";
+import { createViewer } from "./viewer.js";
+import { attachViewerControls } from "./viewer-controls.js";
+import { attachViewcubeControls } from "./viewcube/viewcube-controls.js";
+import { attachViewStyleControls } from "./view-style-controls.js";
+import { observeViewbarClear } from "./viewbar-clear.js";
+import { createTooltipPresenter } from "./tooltip.js";
+import { isFaceAlignedState } from "./projection.js";
+import { ENVIRONMENTS } from "./materials/environments.js";
+
+function previewPart({ meshes, view, meta }) {
+  return {
+    meta: { title: "Preview", ...(meta ?? {}) },
+    defaults: {},
+    parameters: [],
+    views: { [view]: { label: view } },
+    parts: Object.fromEntries(meshes.map((m) => [m.name, {
+      label: m.name,
+      views: [view],
+      ...(m.display ? { display: m.display } : {}),
+    }])),
+  };
+}
+
+const relay = (listeners) => (event) => {
+  for (const cb of [...listeners]) {
+    try { cb(event); } catch (error) { console.warn("partforge: preview listener failed", error); }
+  }
+};
+
+export function mountPreview(container, { glb, elements = {}, viewerState = null } = {}) {
+  if (!container) throw new TypeError("mountPreview: a container element is required");
+  let disposed = false;
+  let active = true;
+  let carried = viewerState ?? null; // applied once the viewer exists, and on every setViewerState
+  let live = null;                   // { viewer, view } once the GLB has decoded
+  const cleanups = [];
+  const modeListeners = new Set();
+  const envListeners = new Set();
+  const lostListeners = new Set();
+
+  // Same precedence mount() uses: projection first (orthographic only for a
+  // face-view camera), then the camera, then environment and render mode.
+  function applyState(s) {
+    if (!s || !live) return;
+    const { viewer } = live;
+    viewer.setProjection(s.projection === "orthographic" && isFaceAlignedState(s.camera) ? "orthographic" : "perspective");
+    if (s.camera) viewer.setCameraState(s.camera);
+    if (typeof s.environment === "string") viewer.setEnvironment(s.environment);
+    if ((s.renderMode === "cad" || s.renderMode === "realistic") && s.renderMode !== viewer.getRenderMode()) {
+      viewer.setRenderMode(s.renderMode);
+    }
+  }
+
+  const ready = import("./gltf/decode-preview.js").then(({ decodePreviewGlb }) => decodePreviewGlb(glb)).then((decoded) => {
+    if (disposed) return;
+    if (decoded.meshes.length === 0) throw new Error("mountPreview: the preview holds no meshes");
+    const view = decoded.view ?? "preview";
+    const viewer = createViewer(container, previewPart({ ...decoded, view }));
+    cleanups.push(() => viewer.dispose());
+    const tooltip = createTooltipPresenter({ id: null });
+    cleanups.push(() => tooltip.dispose());
+    const viewcube = attachViewcubeControls(viewer, { stage: container });
+    cleanups.push(() => viewcube.detach());
+    const toolbar = container.querySelector("#viewbar");
+    const viewStyle = attachViewStyleControls(viewer, { stage: container, toolbar, anchor: viewcube.element }, { tooltip });
+    cleanups.push(() => viewStyle.detach());
+    cleanups.push(observeViewbarClear(container, toolbar));
+    const chrome = attachViewerControls(viewer, elements.chrome ?? {}, { tooltip });
+    cleanups.push(() => chrome.detach());
+    cleanups.push(viewer.onRenderModeChange(relay(modeListeners)));
+    cleanups.push(viewer.onEnvironmentChange(relay(envListeners)));
+    cleanups.push(viewer.onContextLost(relay(lostListeners)));
+    for (const m of decoded.meshes) viewer.setSubGeometry(m.name, m);
+    viewer.showAssembly(decoded.meshes.map((m) => m.name), { frame: true });
+    live = { viewer, view };
+    applyState(carried);
+    if (!active) viewer.setActive(false);
+  });
+  ready.catch(() => {}); // the host awaits it; never an unhandled rejection
+
+  function getViewerState() {
+    if (!live) return { camera: null, projection: "perspective", renderMode: "cad", ...carried, cutaway: null };
+    const v = live.viewer;
+    return {
+      camera: v.getCameraState(),
+      projection: v.getProjection?.() ?? "perspective",
+      cutaway: null, // a preview has no live solid to section
+      renderMode: v.isRealisticPending?.() ? "realistic" : v.getRenderMode?.() ?? "cad",
+      ...(v.isEnvironmentChosen?.() ? { environment: v.getEnvironment() } : {}),
+    };
+  }
+
+  // A method that needs the viewer waits for it; a failed decode answers the default.
+  const whenLive = async (fn, fallback) => {
+    try { await ready; } catch { return fallback; }
+    return live ? fn(live.viewer) : fallback;
+  };
+
+  return {
+    ready,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      live = null;
+      const errors = [];
+      while (cleanups.length) {
+        try { cleanups.pop()(); } catch (error) { errors.push(error); }
+      }
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) throw new AggregateError(errors, "partforge mountPreview cleanup failed");
+    },
+    getView: () => live?.view ?? null,
+    getViewerState,
+    setViewerState(next) {
+      carried = next ?? null;
+      applyState(carried);
+    },
+    setActive(next) {
+      active = next !== false;
+      live?.viewer.setActive(active);
+    },
+    onContextLost(listener) {
+      lostListeners.add(listener);
+      return () => lostListeners.delete(listener);
+    },
+    // No rail to place or pick: accepted so a host relaying mount()'s sticky state
+    // can send it here unchanged.
+    setHostPane: () => {},
+    setRailLayout: () => {},
+    renderMode: {
+      get: () => live?.viewer.getRenderMode() ?? carried?.renderMode ?? "cad",
+      set: (mode) => whenLive((v) => v.setRenderMode(mode), "cad"),
+      onChange: (cb) => { modeListeners.add(cb); return () => modeListeners.delete(cb); },
+    },
+    environment: {
+      get: () => live?.viewer.getEnvironment() ?? carried?.environment ?? "studio",
+      set: (id) => whenLive((v) => v.setEnvironment(id), "studio"),
+      onChange: (cb) => { envListeners.add(cb); return () => envListeners.delete(cb); },
+      list: () => Object.values(ENVIRONMENTS).map(({ id, label }) => ({ id, label })),
+    },
+  };
+}

package/src/framework/mount.js

@@ -39,7 +39,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 +70,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 }) {
   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 +120,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.
@@ -242,8 +251,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 +369,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
@@ -387,6 +407,12 @@ function createCleanupStack() {
 //                                         // 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 +459,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 +542,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
@@ -755,21 +790,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 +808,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 +841,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 +876,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 +973,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 +997,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:
@@ -1042,6 +1077,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     // 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 +1092,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 +1127,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 +1154,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,8 +1505,73 @@ 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,
@@ -1481,13 +1592,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,

package/src/framework/preview-gate.js

@@ -0,0 +1,37 @@
+// Whether a cached preview (mount's `preview` option) is on screen, and the
+// chrome it holds off meanwhile. A preview mesh has no feature ids and no live
+// solid behind it, so the modes that read those — cutaway, measure, sketch —
+// wait for the live build; picking and hover ask isActive() per event. Each
+// button gets back exactly the `disabled` it had (a host may disable one for its
+// own reasons, and that must survive the round trip).
+export function createPreviewGate({ buttons = [] } = {}) {
+  let active = false;
+  const held = []; // { el, wasDisabled }
+  const listeners = new Set();
+  const announce = () => {
+    for (const cb of [...listeners]) cb(active);
+  };
+  return {
+    isActive: () => active,
+    start() {
+      if (active) return;
+      active = true;
+      for (const el of buttons) {
+        if (!el) continue;
+        held.push({ el, wasDisabled: el.disabled });
+        el.disabled = true;
+      }
+      announce();
+    },
+    end() {
+      if (!active) return;
+      active = false;
+      for (const { el, wasDisabled } of held.splice(0)) el.disabled = wasDisabled;
+      announce();
+    },
+    onChange(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+  };
+}

package/src/framework/viewbar-clear.js

@@ -0,0 +1,23 @@
+// Publish the viewbar's vertical claim as --pf-viewbar-clear on the stage, so
+// chrome.css can stack the view cube on top of it without hardcoding a height
+// that cutaway/measure/annotate 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. Shared by mount() and
+// mountPreview(). Returns a dispose; a no-op without a bar or a ResizeObserver.
+import { stageClearFor } from "./stage-clear.js";
+
+export function observeViewbarClear(stage, viewbar) {
+  if (!viewbar || typeof ResizeObserver !== "function") return () => {};
+  const publish = () => {
+    const clear = stageClearFor(stage.getBoundingClientRect(), viewbar.getBoundingClientRect());
+    stage.style.setProperty("--pf-viewbar-clear", `${clear}px`);
+  };
+  const observer = new ResizeObserver(publish);
+  observer.observe(viewbar);
+  observer.observe(stage);
+  publish();
+  return () => {
+    observer.disconnect();
+    stage.style.removeProperty("--pf-viewbar-clear");
+  };
+}

package/src/framework/viewer.js

@@ -1642,6 +1642,39 @@ export function createViewer(container, part) {
   const hasSubMesh = (name) => !!subCache[name];
   const subTriangles = (name) => subCache[name]?.userData.triangles ?? 0;
 
+  // The geometry drawn for one sub-part, as a fresh worker-style payload with its
+  // fast-path pose (setSubPose) baked in — the posed mesh a headless buildView
+  // would return. Copies: the caller (exportPreview → partforge/gltf) may keep or
+  // transfer them. null when nothing has been delivered under that name.
+  const _payloadV = new THREE.Vector3();
+  const _payloadNormal = new THREE.Matrix3();
+  function getSubMeshPayload(name) {
+    const geo = subCache[name];
+    if (!geo) return null;
+    const pose = subMesh[name].matrix; // identity unless the fast path posed it
+    _payloadNormal.getNormalMatrix(pose);
+    const pos = geo.getAttribute("position");
+    const positions = new Float32Array(pos.count * 3);
+    for (let i = 0; i < pos.count; i++) {
+      _payloadV.fromBufferAttribute(pos, i).applyMatrix4(pose).toArray(positions, i * 3);
+    }
+    const nor = geo.getAttribute("normal");
+    let normals = null;
+    if (nor) {
+      normals = new Float32Array(nor.count * 3);
+      for (let i = 0; i < nor.count; i++) {
+        _payloadV.fromBufferAttribute(nor, i).applyMatrix3(_payloadNormal).normalize().toArray(normals, i * 3);
+      }
+    }
+    return {
+      name,
+      positions,
+      normals,
+      indices: geo.index ? Uint32Array.from(geo.index.array) : null,
+      triangles: geo.userData.triangles ?? (geo.index ? geo.index.count : pos.count) / 3,
+    };
+  }
+
   // --- show / hide assembly -------------------------------------------------
   const _box = new THREE.Box3();
   const _posedBox = new THREE.Box3();
@@ -2727,6 +2760,7 @@ export function createViewer(container, part) {
     clearSubPartOpacities,
     hasSubMesh,
     subTriangles,
+    getSubMeshPayload,
     frame,
     captureCanonicalViews,
     captureCurrent,

package/src/gltf.js

@@ -0,0 +1,6 @@
+// partforge/gltf — the cached-preview writer. One view's posed display meshes as a
+// small GLB (see src/framework/gltf/encode-preview.js for the file's contract).
+// Worker-safe: no three.js, no DOM, so it runs in Node (a server-side preview job),
+// a page (runtime.exportPreview) and a Web Worker alike. Read the files back with
+// mount()'s `preview` option or mountPreview(), both on the main entry.
+export { encodePreviewGlb, PREVIEW_ENCODER_VERSION } from "./framework/gltf/encode-preview.js";

package/src/index.js

@@ -3,8 +3,13 @@
 // must NOT be imported from a part's build functions — those run in a Web Worker.
 // Part build functions import geometry helpers from "partforge/geometry" instead.
 export { mount } from "./framework/index.js";
+// The kernel-free viewer for a cached preview GLB (partforge/gltf): no part, no worker.
+export { mountPreview } from "./framework/mount-preview.js";
 export { viewSubParts } from "./framework/part-model.js";
 // The cut & print kit's options surface, for a host that draws its own options screen
 // (partforge-cloud's coupling test reads KIT_OPTIONS_ERROR from here). export/formats.js
 // is import-free, so this adds nothing to the app bundle but a few constants.
 export { EXPORT_FORMATS, KIT_OPTIONS_ERROR, KIT_DEFAULTS, validateKitOptions } from "./framework/export/formats.js";
+// Which view mount() opens on — for a host that builds a part outside the viewer
+// (a cached preview, a server-side render) and must agree with it.
+export { resolveDefaultView } from "./framework/default-view.js";

package/src/testing.js

@@ -11,6 +11,7 @@ export { createManifoldKernel } from "./framework/geometry/manifold-backend.js";
 export { bootManifoldKernel } from "./testing/manifold.js";
 export { handle } from "./framework/jobs.js";
 export { viewSubParts } from "./framework/part-model.js";
+export { resolveDefaultView } from "./framework/default-view.js";
 export { resolveDerived } from "./framework/derive.js";
 export { relevantParamKeys, RELEVANT_ALL } from "./framework/param-deps.js";
 export { assemblyOverlaps } from "./framework/assembly.js";

package/types/gltf.d.ts

@@ -0,0 +1,40 @@
+// partforge/gltf — the cached-preview writer. Worker-safe: no three.js, no DOM.
+
+import type { SubPartDefinition } from "./part.js";
+
+/** The slice of a part `encodePreviewGlb` reads; any `PartDefinition` satisfies it, so does a plain object. */
+export interface PreviewPart {
+  parts?: Record<string, { display?: SubPartDisplay }>;
+  meta?: { background?: number; environment?: string };
+}
+
+type SubPartDisplay = NonNullable<SubPartDefinition["display"]>;
+
+/** One sub-part's posed display mesh — the shape the viewer, the worker's `meshes` reply and `buildView` hold. */
+export interface PreviewMesh {
+  /** The sub-part key; names the glTF node, mesh and material. */
+  name: string;
+  /** xyz triples in millimetres, Z-up, already posed. */
+  positions: Float32Array;
+  normals?: Float32Array | null;
+  /** Absent for a non-indexed soup (Manifold); OCCT sends indices. */
+  indices?: Uint32Array | null;
+  triangles?: number;
+  /** Ignored: feature edges are not encoded in this version. */
+  edges?: Float32Array | null;
+}
+
+export interface EncodePreviewInput {
+  /** At least one; a zero-length mesh gets no node. */
+  meshes: PreviewMesh[];
+  /** Read for `parts[name].display` (materials) and `meta.background` / `meta.environment`. */
+  part?: PreviewPart | null;
+  /** The view these meshes show; names the scene and lands in the file's extras as `partforgeView`. */
+  view?: string | null;
+}
+
+/** Bumped whenever the encoder writes different bytes for the same input. */
+export const PREVIEW_ENCODER_VERSION: number;
+
+/** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */
+export function encodePreviewGlb(input: EncodePreviewInput): Promise<Uint8Array>;

package/types/index.d.ts

@@ -243,6 +243,17 @@ export interface MountOptions {
    * dropped, never fatal.
    */
   viewerState?: ViewerState | null;
+  /**
+   * A cached preview GLB (from `partforge/gltf`'s `encodePreviewGlb`, or a previous
+   * runtime's `exportPreview()`) drawn before the worker is ready and replaced in
+   * place, sub-part by sub-part, by the first live build — the camera is kept.
+   * Only a file for the view the viewer opens on is drawn, and only meshes named
+   * for that view's sub-parts; a file for another view, or one that will not
+   * decode, is logged once and ignored. A file written without a view (no `view`
+   * given to `encodePreviewGlb`) is drawn on sub-part name match alone, for any view.
+   * Carries no edge lines.
+   */
+  preview?: Uint8Array | ArrayBuffer | null;
   /**
    * A previous mount's `runtime.getPanelState()`: the transient state of the
    * part's custom controls (a selected tile), keyed by param. Same remount
@@ -613,6 +624,22 @@ export interface PartRuntime {
    * view-cube click, Reframe, or an animation cue).
    */
   getViewerState(): ViewerState;
+  /**
+   * True while the `preview` GLB is on screen: from the moment it decodes until a
+   * build delivers the whole view (a build error leaves it on). Picking, hover
+   * labels, measure, sketch and cutaway wait meanwhile; orbit, zoom, pan, the view
+   * cube, the view style and the rail work. Read it from the runtime each time —
+   * a copy of the handle freezes it.
+   */
+  readonly previewActive: boolean;
+  /**
+   * The view on screen as a preview GLB (`partforge/gltf`'s format), every
+   * sub-part posed exactly as drawn — what a later `mount({ preview })` shows
+   * before its kernel boots. Rejects while `previewActive`, before the view is
+   * fully built at the current params (a pending rebuild counts), for a `view`
+   * other than the one on screen, and after `dispose()`.
+   */
+  exportPreview(opts?: { view?: string }): Promise<Uint8Array>;
   /** Every custom control's non-empty transient state, keyed by param. Hand back as `panelState`. */
   getPanelState(): PanelState;
   /** What custom controls reported failing this mount, in order. */
@@ -698,6 +725,52 @@ export interface PartRuntime {
 /** Mount a full parametric-part app from a `PartDefinition`. */
 export function mount(part: PartDefinition, options: MountOptions): PartRuntime;
 
+/** Options for `mountPreview`. */
+export interface MountPreviewOptions {
+  /** A GLB from `partforge/gltf`'s `encodePreviewGlb`, or a runtime's `exportPreview()`. */
+  glb: Uint8Array | ArrayBuffer;
+  /** Optional viewer buttons, wired as `mount()` wires them; `#viewbar` inside the container is found by id. */
+  elements?: { chrome?: { reframe?: HTMLElement | null; theme?: HTMLElement | null } };
+  /** A previous runtime's `getViewerState()`; `cutaway` is ignored (a preview has no live solid). */
+  viewerState?: ViewerState | null;
+}
+
+/** The handle `mountPreview()` returns. Every method is safe before `ready` settles. */
+export interface PreviewRuntime {
+  /** Resolves once the GLB is drawn; rejects when it will not decode or holds no meshes. */
+  ready: Promise<void>;
+  /** Full teardown. Idempotent. */
+  dispose(): void;
+  /** The view the file was written for (`null` until drawn, or when the file names none). */
+  getView(): string | null;
+  /** Camera, projection, render mode and environment; `cutaway` is always `null`. */
+  getViewerState(): ViewerState;
+  /** Apply a state (camera, projection, render mode, environment) now, or once drawn. */
+  setViewerState(state: ViewerState | null): void;
+  /** Park/unpark the viewer, as `PartRuntime.setActive`. */
+  setActive(active: boolean): void;
+  /** WebGL context loss. Returns an unsubscribe. */
+  onContextLost(listener: () => void): () => void;
+  /** Accepted and ignored — there is no rail. */
+  setHostPane(pane: HostPane): void;
+  /** Accepted and ignored — there is no rail. */
+  setRailLayout(layout: HostRailLayout): void;
+  renderMode: {
+    get(): RenderMode;
+    set(mode: RenderMode): Promise<RenderMode>;
+    onChange(cb: (e: RenderModeEvent) => void): () => void;
+  };
+  environment: {
+    get(): string;
+    set(id: string): Promise<string>;
+    onChange(cb: (id: string) => void): () => void;
+    list(): Array<{ id: string; label: string }>;
+  };
+}
+
+/** A kernel-free viewer for a cached preview GLB: the viewer, view cube, view style and theme — no part, no worker, no rail. */
+export function mountPreview(container: HTMLElement, options: MountPreviewOptions): PreviewRuntime;
+
 /** Every format `exportParts` can write in this version (`runtime.listExportFormats()` returns copies). */
 export const EXPORT_FORMATS: ReadonlyArray<ExportFormatInfo>;
 
@@ -729,3 +802,10 @@ export function viewSubParts(
   params: Record<string, ParamValue>,
 ): string[];
 
+/**
+ * The view `mount()` opens on: a view flagged `default: true`, else the one
+ * placing the most sub-parts at the part's defaults (ties keep declaration
+ * order). `null` for a part with no views. Exported so a host building a part
+ * outside the viewer — a cached preview — opens the same view.
+ */
+export function resolveDefaultView(part: PartDefinition): string | null;

package/types/testing.d.ts

@@ -869,3 +869,6 @@ export function annotationRay(
 ): AnnotationRay;
 /** Intersect a ray with a plane; null on parallel / behind-origin misses. */
 export function rayPlane(ray: AnnotationRay, plane: PlaneSpec): RayPlaneHit | null;
+
+/** The view `mount()` opens on (see the main entry's declaration). */
+export function resolveDefaultView(part: PartDefinition): string | null;