partforge 0.146.4 → 0.149.0

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/materials/overrides.js

@@ -0,0 +1,120 @@
+// src/framework/materials/overrides.js
+// The viewer-side override of a sub-part's appearance, and the viewing state
+// beside it. Pure: no three, no DOM (lint purity scans this folder).
+//
+// Two kinds of key, deliberately separate (spec A.1):
+//   - APPEARANCE keys merge over the authored `display` into effective(), which
+//     every material read uses — CAD, realistic, the throwaway thumbnail scene.
+//     A host may persist these into source.
+//   - VIEWING keys (`hidden`, `opacity`) are how the user is LOOKING. They never
+//     reach effective(), exports, lint or declaresMaterials, and no host saves
+//     them. `opacity` MULTIPLIES an authored display.opacity (the arithmetic
+//     animation opacity already uses), so a ghost can be faded further but not
+//     made solid from here.
+import { DISPLAY_KEYS, OVERRIDE_RANGES } from "./resolve.js";
+
+export const APPEARANCE_OVERRIDE_KEYS = DISPLAY_KEYS.filter((k) => k !== "opacity");
+export const VIEWING_KEYS = ["hidden", "opacity"];
+export const MIN_USER_OPACITY = 0.05;
+
+const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isColor = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+
+// Only known keys survive; `null` is the "clear this key" value and survives
+// as-is. Bad values are DROPPED (not clamped) where clamping would invent a
+// choice: a non-string material, a colour out of range. Numeric overrides clamp
+// to OVERRIDE_RANGES exactly as resolve.js clamps authored ones. `opacity`
+// floors at MIN_USER_OPACITY and reads >= 1 as a clear; `hidden` must be a real
+// boolean (a host's "false" string would otherwise read as truthy and hide the
+// part), anything else is dropped.
+export function sanitizeDisplayPatch(patch) {
+  if (!isObject(patch)) return {};
+  const out = {};
+  for (const [key, v] of Object.entries(patch)) {
+    if (v === null) {
+      if (APPEARANCE_OVERRIDE_KEYS.includes(key) || VIEWING_KEYS.includes(key)) out[key] = null;
+      continue;
+    }
+    if (key === "material") { if (typeof v === "string" && v.length > 0) out.material = v; continue; }
+    if (key === "color") { if (isColor(v)) out.color = v; continue; }
+    if (key === "hidden") { if (typeof v === "boolean") out.hidden = v; continue; }
+    if (key === "opacity") {
+      if (!finite(v)) continue;
+      out.opacity = v >= 1 ? null : Math.max(MIN_USER_OPACITY, v);
+      continue;
+    }
+    if (key in OVERRIDE_RANGES) {
+      if (!finite(v)) continue;
+      const [lo, hi] = OVERRIDE_RANGES[key];
+      out[key] = Math.min(hi, Math.max(lo, v));
+    }
+  }
+  return out;
+}
+
+// Merge a SANITIZED patch over the current override. `hidden: false` and
+// `opacity: null` (or >= 1) are clears like any other null. Returns null when nothing is
+// left, so a Map entry can be deleted rather than kept empty.
+export function mergeOverride(current, patch) {
+  const next = { ...(isObject(current) ? current : {}) };
+  for (const [key, v] of Object.entries(patch ?? {})) {
+    if (v === null || (key === "hidden" && v === false) || (key === "opacity" && v >= 1)) delete next[key];
+    else next[key] = v;
+  }
+  return Object.keys(next).length ? next : null;
+}
+
+// The display every material read sees: authored, with the override's
+// APPEARANCE keys on top. Viewing keys are never in it.
+export function effectiveDisplay(authored, override) {
+  const out = isObject(authored) ? { ...authored } : {};
+  if (!isObject(override)) return out;
+  for (const key of APPEARANCE_OVERRIDE_KEYS) if (key in override) out[key] = override[key];
+  return out;
+}
+
+export function isAppearanceNoop(authored, override) {
+  if (!isObject(override)) return true;
+  const a = isObject(authored) ? authored : {};
+  return APPEARANCE_OVERRIDE_KEYS.every((key) => !(key in override) || override[key] === a[key]);
+}
+
+// A carried map, made safe for THIS part (spec A.4): names the part no longer
+// declares go; appearance keys that now equal the authored value go (an owner's
+// saved change self-cleans this way); every kept entry is re-sanitized, since
+// the token came from a host; empties go.
+export function pruneOverrides(map, part) {
+  const out = {};
+  if (!isObject(map)) return out;
+  for (const [name, raw] of Object.entries(map)) {
+    // Own names only: `parts` is a plain object, so "toString" or "constructor"
+    // would otherwise read as declared sub-parts and be replayed into the viewer.
+    const parts = part?.parts;
+    if (!isObject(parts) || !Object.hasOwn(parts, name)) continue;
+    const sp = parts[name];
+    if (!sp) continue;
+    const clean = mergeOverride(null, sanitizeDisplayPatch(raw));
+    if (!clean) continue;
+    const authored = isObject(sp.display) ? sp.display : {};
+    for (const key of APPEARANCE_OVERRIDE_KEYS) if (key in clean && clean[key] === authored[key]) delete clean[key];
+    if (Object.keys(clean).length) out[name] = clean;
+  }
+  return out;
+}
+
+// The one visibility decision viewer.js's applySubOpacity makes, as a pure
+// function of its inputs. `anim` is the animation driver's opacity (undefined =
+// none), `user` the viewing override's (undefined = none). `fade` is null when
+// the mesh should sit on its base material, else the fade clone's opacity.
+export function subPartVisibility({ shown, anim, user, hidden, renderMode, staticOpacity = 1 }) {
+  const off = { meshVisible: false, linesVisible: false, fade: null };
+  if (!shown || hidden) return off;
+  const a = anim === undefined ? 1 : anim;
+  const u = user === undefined ? 1 : user;
+  const v = a * u;
+  if (v <= 0) return off;
+  const linesVisible = renderMode === "cad";
+  if (v >= 1) return { meshVisible: true, linesVisible, fade: null };
+  return { meshVisible: true, linesVisible, fade: staticOpacity * v };
+}

package/src/framework/materials/thumb-cache.js

@@ -0,0 +1,33 @@
+// Keys and bounds for the appearance card's sphere thumbnails. A tile depicts
+// the PRESET, tinted: finish overrides (and see-through) are neither in the key
+// nor in the render — re-rendering 25 spheres on every slider tick would make
+// the card unusable, and a render that read them would cache one part's finish
+// under a key every other part shares. thumbDisplay is what the render builds
+// from, so it can depend on exactly what the key holds.
+//
+// An UNTINTABLE preset (brass, oak, ...) draws its own colour whatever the
+// part's colour is, so its colour is dropped from both the render and the key:
+// every part shares one sphere for it, and a colour pick re-renders only the
+// tintable tiles. No material (and an unknown id) counts as tintable.
+import { PRESETS } from "./presets.js";
+
+const CAP = 120;
+const tintable = (material) =>
+  typeof material !== "string" || !Object.hasOwn(PRESETS, material) || PRESETS[material].tintable === true;
+export function thumbDisplay(display) {
+  const out = { material: display?.material };
+  if (display?.color !== undefined && tintable(display?.material)) out.color = display.color;
+  return out;
+}
+export function createMaterialThumbCache() {
+  const map = new Map();
+  return {
+    key: (display, env, theme, mode) => {
+      const look = thumbDisplay(display);
+      return `${look.material ?? ""}|${look.color ?? ""}|${env}|${theme}|${mode}`;
+    },
+    get(k) { const v = map.get(k); if (v !== undefined) { map.delete(k); map.set(k, v); } return v; },
+    set(k, url) { map.delete(k); map.set(k, url); if (map.size > CAP) map.delete(map.keys().next().value); },
+    clear() { map.clear(); },
+  };
+}

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