partforge 0.167.0 → 0.168.0

package/README.md

@@ -187,11 +187,37 @@ 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.
 
+`mountPreview` takes presentation options (0.168.0+), each usable alone and
+each defaulting to the viewer above: `chrome: false` (no view cube, viewbar
+controls, view style, tooltips or play button), `background: "transparent"`
+(alpha-0 canvas, no grid) and `contactShadow: true` (a soft shadow under the
+part) — both CAD mode only, since realistic mode draws its own environment and
+ground — `zoom: false`
+and `pan: false` (a wheel then scrolls the page), `turntable: <degrees per
+second>` (a model with no playing animation turns until the first camera grab,
+never under `prefers-reduced-motion`), `fill: 0.8` (frame the model so its
+bounding box, as seen from the opening view, spans that fraction of the preview
+along its tighter axis — larger in a small card; with a turntable the model swept
+a full turn is framed, so it never clips as it turns and a round part still fills; the model is
+centred on its geometry, so a lopsided part turns about its hub), `camera: "default"` (drop the carried camera
+and projection and keep the file's own framing; a carried render mode and
+environment still apply) and `renderMode: "cad" | "realistic"` (the opening
+mode, over any carried one; it can change afterwards). An unknown option key
+throws. A baked animation always plays as authored — it
+loops, or plays once and holds its end pose. Every handle carries `drawn`, which
+resolves after the first frame showing the meshes, so a host can cross-fade from
+a still image.
+
 ```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;
+const card = mountPreview(cardStage, {                   // a landing-page card
+  glb, chrome: false, background: "transparent", contactShadow: true,
+  zoom: false, pan: false, turntable: 14, fill: 0.8, camera: "default", renderMode: "cad",
+});
+await card.drawn;                                        // the first frame is on the canvas
 ```
 
 Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.167.0",
+  "version": "0.168.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",

package/src/framework/mount-preview.js

@@ -30,6 +30,51 @@
 // file, with `animate: false`, or for a host with no #viewbar; the host can
 // still drive `handle.animation` (state / pause / resume / replay) itself.
 //
+// Presentation options (0.168.0), each usable alone; every default is the
+// viewer above, so a mount that names none is unchanged:
+//  - `chrome: false` — no view cube, no #viewbar controls, no view style, no
+//    tooltips, no play button and no `elements.chrome` wiring. A one-time
+//    animation still holds its end pose; there is just no replay button.
+//  - `background: "transparent"` — the canvas clears to alpha 0 with no theme
+//    background and no grid, so the host page shows through. CAD mode ONLY:
+//    realistic mode draws its own environment backdrop (pair it with
+//    `renderMode: "cad"` to open transparent).
+//  - `contactShadow: true` — the product shot's soft contact shadow under the
+//    part. CAD mode ONLY: realistic mode draws its own ground and shadow. Cast
+//    once, at showAssembly, from the meshes as the file stores them (the rest
+//    pose, before a player applies its first pose); a playing animation does
+//    not move it.
+//  - `zoom: false`, `pan: false` — those orbit gestures are off (a wheel then
+//    scrolls the page); orbiting stays on.
+//  - `turntable: <degrees per second>` (default 0, off) — a file with no
+//    playing animation (a still file, or `animate: false`) turns about the
+//    vertical off the viewer's frame loop. Never under reduced motion; the
+//    first camera grab — a canvas drag or the view cube — stops it for good.
+//    Dragging an animated model orbits the camera and the animation plays on.
+//  - `fill: <0 < f <= 1>` — the opening framing (and the viewer's reframe)
+//    places the camera, along the kept view direction, so the model's posed
+//    bounding box as projected on screen spans that fraction of the viewport
+//    along its limiting axis. A turning model is framed swept a full turn
+//    about the vertical (its farthest vertex from the axis), so the turntable
+//    never clips and a round part still fills. The model is centred on its
+//    horizontal vertex centroid (a lopsided part turns about its hub); a baked
+//    animation that moves parts outside the rest box can. Unset, the viewer's
+//    fixed framing distance, as before.
+//  - `camera: "default"` — the camera and projection of `viewerState` and of
+//    every setViewerState are dropped: the mount opens, and stays, at the
+//    file's own default framing. Their render mode and environment still apply.
+//  - `renderMode: "cad" | "realistic"` — the OPENING mode: applied at mount,
+//    over any carried render mode. After that it is an ordinary mode —
+//    setViewerState, renderMode.set and the view style control change it.
+//    Unset, the carried state decides, as before.
+//  Any other key throws (an option this version does not know is a host bug).
+//
+// `handle.drawn` resolves after the first frame that includes the meshes has
+// rendered (so a host can cross-fade from a still image without a flash). It
+// rejects with `ready`'s error when the file will not decode, and rejects if
+// the handle is disposed before that frame. A parked preview draws nothing, so
+// `drawn` waits for setActive(true).
+//
 // 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.
@@ -45,6 +90,66 @@ import { ENVIRONMENTS } from "./materials/environments.js";
 import { createPreviewPlayer } from "./preview-player.js";
 import { attachPreviewPlayButton } from "./preview-play-button.js";
 
+// A value the option does not know is a host bug: say so at the call rather
+// than quietly showing the default.
+function oneOf(name, value, allowed, fallback) {
+  if (value === undefined) return fallback;
+  if (!allowed.includes(value)) throw new TypeError(`mountPreview: ${name} must be ${allowed.map((a) => JSON.stringify(a)).join(" or ")}`);
+  return value;
+}
+function flag(name, value, fallback) {
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") throw new TypeError(`mountPreview: ${name} must be a boolean`);
+  return value;
+}
+const KNOWN_OPTIONS = new Set([
+  "glb", "elements", "viewerState", "animate",
+  "chrome", "background", "contactShadow", "zoom", "pan", "turntable", "fill", "camera", "renderMode",
+]);
+
+function presentation({ chrome, background, contactShadow, zoom, pan, turntable, fill, camera, renderMode }) {
+  if (fill !== undefined && !(typeof fill === "number" && fill > 0 && fill <= 1)) {
+    throw new TypeError("mountPreview: fill must be a number above 0 and at most 1");
+  }
+  if (turntable !== undefined && !(typeof turntable === "number" && Number.isFinite(turntable) && turntable >= 0)) {
+    throw new TypeError("mountPreview: turntable must be degrees per second, 0 or more");
+  }
+  return {
+    chrome: flag("chrome", chrome, true),
+    transparent: oneOf("background", background, ["theme", "transparent"], "theme") === "transparent",
+    contactShadow: flag("contactShadow", contactShadow, false),
+    zoom: flag("zoom", zoom, true),
+    pan: flag("pan", pan, true),
+    turntable: turntable ?? 0,
+    fill: fill ?? null,
+    defaultCamera: oneOf("camera", camera, ["carry", "default"], "carry") === "default",
+    renderMode: oneOf("renderMode", renderMode, ["cad", "realistic"], null),
+  };
+}
+
+// Turn the camera about the vertical at `degPerSec` until the first camera grab.
+// It turns through viewer.orbitBy, which itself announces a camera grab — so the
+// turntable's own steps are told apart from the user's by a flag held across
+// the call. Returns stop().
+function startTurntable(viewer, container, degPerSec) {
+  let turning = false, stopped = false;
+  const offFrame = viewer.onFrame((dt) => {
+    // orbitBy's rate: a drag the full stage height is a full turn.
+    const dx = ((degPerSec * dt) / 360) * Math.max(1, container.clientHeight || 1);
+    if (!(dx > 0)) return;
+    turning = true;
+    try { viewer.orbitBy(dx, 0); } finally { turning = false; }
+  });
+  const offGrab = viewer.onCameraStart(() => { if (!turning) stop(); });
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    offFrame();
+    offGrab();
+  }
+  return stop;
+}
+
 function previewPart({ meshes, view, meta }) {
   return {
     meta: { title: "Preview", ...(meta ?? {}) },
@@ -65,24 +170,43 @@ const relay = (listeners) => (event) => {
   }
 };
 
-export function mountPreview(container, { glb, elements = {}, viewerState = null, animate = true } = {}) {
+export function mountPreview(container, options = {}) {
   if (!container) throw new TypeError("mountPreview: a container element is required");
+  for (const key of Object.keys(options ?? {})) {
+    if (!KNOWN_OPTIONS.has(key)) throw new TypeError(`mountPreview: unknown option "${key}"`);
+  }
+  const { glb, elements = {}, viewerState = null, animate = true } = options ?? {};
+  const opts = presentation(options ?? {});
+  // A carried state as this mount applies it: under camera: "default" without
+  // its camera and projection (render mode and environment still carry).
+  const carry = (state) => {
+    if (!state || !opts.defaultCamera) return state ?? null;
+    const { camera: _camera, projection: _projection, ...rest } = state;
+    return rest;
+  };
   let disposed = false;
   let active = true;
-  let carried = viewerState ?? null; // applied once the viewer exists, and on every setViewerState
+  // Applied once the viewer exists, and on every setViewerState. The opening
+  // render mode, when one is named, wins over the carried one at mount only.
+  let carried = carry(viewerState);
+  if (opts.renderMode) carried = { ...(carried ?? {}), renderMode: opts.renderMode };
   let live = null;                   // { viewer, view } once the GLB has decoded
   let player = null;                 // the baked animation's player, once drawn
   const cleanups = [];
   const modeListeners = new Set();
   const envListeners = new Set();
   const lostListeners = new Set();
+  let resolveDrawn, rejectDrawn;
+  const drawn = new Promise((resolve, reject) => { resolveDrawn = resolve; rejectDrawn = reject; });
+  drawn.catch(() => {}); // the host awaits it; never an unhandled rejection
 
   // 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");
+    // Under camera: "default" the framing is the file's own: no projection either.
+    if (!opts.defaultCamera) 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()) {
@@ -94,18 +218,29 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     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 }));
+    const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const plays = !!decoded.animation && animate !== false;
+    const turns = !plays && opts.turntable > 0 && !reducedMotion;
+    const viewer = createViewer(container, previewPart({ ...decoded, view }), {
+      transparent: opts.transparent, contactShadow: opts.contactShadow, zoom: opts.zoom, pan: opts.pan,
+      // A turning model is framed swept a full turn, so no angle of it clips.
+      frameFill: opts.fill, frameSwept: turns,
+    });
     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());
+    let tooltip = null, toolbar = null, viewStyle = null;
+    if (opts.chrome) {
+      tooltip = createTooltipPresenter({ id: null });
+      const tip = tooltip;
+      cleanups.push(() => tip.dispose());
+      const viewcube = attachViewcubeControls(viewer, { stage: container });
+      cleanups.push(() => viewcube.detach());
+      toolbar = container.querySelector("#viewbar");
+      const style = viewStyle = attachViewStyleControls(viewer, { stage: container, toolbar, anchor: viewcube.element }, { tooltip });
+      cleanups.push(() => style.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)));
@@ -114,8 +249,9 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     live = { viewer, view };
     applyState(carried);
     if (!active) viewer.setActive(false);
-    if (decoded.animation && animate !== false) {
-      const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const offRendered = viewer.onRendered(() => { offRendered(); resolveDrawn(); });
+    cleanups.push(offRendered);
+    if (plays) {
       player = createPreviewPlayer(viewer, decoded.animation, { reducedMotion });
       const own = player;
       cleanups.push(() => own.dispose());
@@ -124,9 +260,11 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
         const playButton = attachPreviewPlayButton(own, { toolbar, before: viewStyle.element }, { tooltip });
         cleanups.push(() => playButton.detach());
       }
+    } else if (turns) {
+      cleanups.push(startTurntable(viewer, container, opts.turntable));
     }
   });
-  ready.catch(() => {}); // the host awaits it; never an unhandled rejection
+  ready.catch(rejectDrawn); // the host awaits it; never an unhandled rejection
 
   function getViewerState() {
     if (!live) return { camera: null, projection: "perspective", renderMode: "cad", ...carried, cutaway: null };
@@ -148,9 +286,11 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
 
   return {
     ready,
+    drawn,
     dispose() {
       if (disposed) return;
       disposed = true;
+      rejectDrawn(new Error("mountPreview: disposed before the preview was drawn")); // a no-op once drawn
       live = null;
       player = null; // `animation` answers null once disposed (the cleanup below disposes it)
       const errors = [];
@@ -167,7 +307,7 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     },
     getViewerState,
     setViewerState(next) {
-      carried = next ?? null;
+      carried = carry(next);
       applyState(carried);
     },
     setActive(next) {

package/src/framework/viewer.js

@@ -163,7 +163,22 @@ export function captureCurrentFromScene(
   }
 }
 
-export function createViewer(container, part) {
+// Options (all default to today's viewer): `transparent` clears the canvas to
+// alpha 0 in CAD mode (no theme background, no grid) so the host page shows
+// through — realistic mode keeps its environment backdrop; `contactShadow`
+// draws the product shot's soft contact shadow (contact-shadow.js, the mask
+// captures use) under the part in CAD mode, on the live scene; `zoom` / `pan`
+// false turn those OrbitControls gestures off (a wheel then scrolls the page).
+// `frameFill` (0 < f <= 1) changes how frameTo frames: the framed assembly's
+// posed bounding box, PROJECTED from the kept view direction, spans that
+// fraction of the viewport along its limiting axis, centred on the horizontal
+// vertex centroid; `frameSwept` frames the model swept a full turn about the
+// vertical instead (a turntable never clips).
+// Unset keeps the fixed r·2.6 + 6 distance. mountPreview's presentation
+// options are the caller.
+export function createViewer(container, part, {
+  transparent = false, contactShadow = false, zoom = true, pan = true, frameFill = null, frameSwept = false,
+} = {}) {
   const names = Object.keys(part.parts);
   // Membership for host-supplied names. subMesh, cadMats and part.parts are
   // plain objects, so "toString" or "constructor" would read as present on
@@ -172,7 +187,10 @@ export function createViewer(container, part) {
   const has = (name) => nameSet.has(name);
 
   // --- renderer / scene / camera --------------------------------------------
-  const renderer = new THREE.WebGLRenderer({ antialias: true, stencil: true });
+  const renderer = new THREE.WebGLRenderer(transparent
+    ? { antialias: true, stencil: true, alpha: true }
+    : { antialias: true, stencil: true });
+  if (transparent) renderer.setClearColor(0x000000, 0);
   renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
   container.appendChild(renderer.domElement);
 
@@ -188,7 +206,10 @@ export function createViewer(container, part) {
     dark:  { bg: part.meta?.background ?? CAD_DARK_THEME.bg, grid: [0x2c333d, 0x222831], line: CAD_DARK_THEME.line },
     light: { bg: CAD_LIGHT_THEME.bg, grid: [0xc4ccd6, 0xd6dce4], line: CAD_LIGHT_THEME.line },
   };
-  scene.background = new THREE.Color(THEME.dark.bg);
+  // CAD mode's backdrop and grid; a transparent viewer has neither.
+  const cadBackground = (mode) => (transparent ? null : new THREE.Color(THEME[mode].bg));
+  const cadGrid = !transparent;
+  scene.background = cadBackground("dark");
 
   let currentTheme = "dark";
   const themeListeners = new Set();
@@ -216,6 +237,8 @@ export function createViewer(container, part) {
 
   const controls = new OrbitControls(activeCamera, renderer.domElement);
   controls.enableDamping = true;
+  controls.enableZoom = zoom !== false;
+  controls.enablePan = pan !== false;
   // A finger a host gesture swallowed would otherwise stay "down" forever in
   // whatever it went down on — the controls (every later drag zooms), the view
   // cube, the cutaway handles, measure mode — so the guard watches the whole
@@ -253,6 +276,7 @@ export function createViewer(container, part) {
   const GRID_SIZE = 300, GRID_DIVS = 30;
   let floorY = 0; // world Y of the grid plane; set to the part's bbox bottom in frameTo
   let grid = new THREE.GridHelper(GRID_SIZE, GRID_DIVS, THEME.dark.grid[0], THEME.dark.grid[1]);
+  grid.visible = cadGrid;
   scene.add(grid);
 
   // --- material + part groups -----------------------------------------------
@@ -626,6 +650,8 @@ export function createViewer(container, part) {
     // bigger half of the answer the way the grid is in CAD: without it the far
     // plane cuts the disc's back edge off.
     if (realisticRig) _depthBounds.union(_groundBounds.setFromObject(realisticRig.ground));
+    // The CAD contact shadow reaches past the part by its blur margin.
+    if (liveShadow) _depthBounds.union(_groundBounds.setFromObject(liveShadow));
     if (_depthBounds.isEmpty()) return null;
     return {
       center: _depthBounds.getCenter(_depthCenter).toArray(),
@@ -962,6 +988,53 @@ export function createViewer(container, part) {
   // contact shadow: low-res while the plane is dragged, full once it settles —
   // the same schedule as a moving sub-part.
   cutaway.onChange?.(() => { if (realisticRig) shadowMovedAt = performance.now(); });
+
+  // --- the CAD contact shadow (the `contactShadow` option) -------------------
+  // The product shot's shadow (renderStyles' thumbnail style), on the live
+  // scene: the same CPU mask the captures cast, as a black alpha-mapped plane a
+  // hair under the part. CAD mode only — realistic brings its own ground and
+  // shadow. Computed ONCE per assembly — on showAssembly, from the pose on
+  // screen then (a preview's meshes as the file stores them — the rest pose,
+  // before its player applies a first pose) — and again on entering CAD. Never
+  // for animation frames: the mask is a CPU rasterization plus a new texture,
+  // and rebuilding it a few times a second while a preview played stalled the
+  // host page's main thread (a landing page's typing slowed ~25×). So a moving
+  // sub-part leaves its rest-pose shadow behind — accepted. A turntable needs no
+  // rebuild: it moves the camera, never a caster or the ground.
+  const LIVE_SHADOW = RENDER_STYLES.thumbnail.shadow;
+  let liveShadow = null;
+  function disposeLiveShadow() {
+    if (!liveShadow) return;
+    scene.remove(liveShadow);
+    liveShadow.geometry.dispose();
+    liveShadow.material.alphaMap.dispose();
+    liveShadow.material.dispose();
+    liveShadow = null;
+  }
+  const _liveShadowV = new THREE.Vector3();
+  function rebuildLiveShadow() {
+    disposeLiveShadow();
+    if (!contactShadow || renderMode !== "cad") return;
+    try {
+      const bounds = getVisibleWorldBounds();
+      if (bounds.isEmpty()) return;
+      const box = { min: bounds.min.toArray(), max: bounds.max.toArray() };
+      const meshes = castersNow().filter((m) => m.geometry?.attributes?.position).map((mesh) => {
+        mesh.updateWorldMatrix(true, false);
+        const pos = mesh.geometry.attributes.position;
+        const positions = new Float32Array(pos.count * 3);
+        for (let i = 0; i < pos.count; i++) _liveShadowV.fromBufferAttribute(pos, i).applyMatrix4(mesh.matrixWorld).toArray(positions, i * 3);
+        return { positions, indices: mesh.geometry.index?.array ?? null };
+      });
+      const mask = contactShadowMask(meshes, box, LIVE_SHADOW);
+      if (!mask) return;
+      liveShadow = buildContactShadowPlane(mask, LIVE_SHADOW);
+      scene.add(liveShadow);
+      requestRender();
+    } catch (e) {
+      console.warn("partforge: contact shadow failed", e);
+    }
+  }
   cutaway.onChange?.(() => requestRender());
 
   const livePixelRatio = (mode) =>
@@ -996,6 +1069,7 @@ export function createViewer(container, part) {
       scene.backgroundRotation.set(0, rig.rotationY ?? 0, 0);
       scene.environmentRotation.set(0, rig.rotationY ?? 0, 0);
       scene.add(rig.ground, rig.shadow.group, ...(rig.lights ?? []));
+      disposeLiveShadow();
       for (const l of Object.values(liveLights)) l.visible = false;
       grid.visible = false;
       renderer.toneMapping = THREE.NeutralToneMapping;
@@ -1030,16 +1104,17 @@ export function createViewer(container, part) {
     shadowMovedAt = null;
     attempt(() => {
       scene.environment = null;
-      scene.background = new THREE.Color(THEME[currentTheme].bg);
+      scene.background = cadBackground(currentTheme);
       scene.backgroundBlurriness = 0;
       scene.backgroundIntensity = 1;
       scene.backgroundRotation.set(0, 0, 0);
       scene.environmentRotation.set(0, 0, 0);
     });
     attempt(() => { for (const l of Object.values(liveLights)) l.visible = true; });
-    attempt(() => { grid.visible = true; });
+    attempt(() => { grid.visible = cadGrid; });
     for (const n of names) attempt(() => { if (baseMats[n] !== cadMats[n]) rebaseSubMaterial(n, cadMats[n]); else applySubOpacity(n); });
     if (live) attempt(() => applyPixelRatio("cad"));
+    if (contactShadow) attempt(rebuildLiveShadow);
     attempt(refreshFeatureLines);
     if (live) invalidateMaterialThumbnails();
     if (firstError) throw firstError;
@@ -1242,6 +1317,10 @@ export function createViewer(container, part) {
   // (setActive(false)) automatically halts playback too: no loop, no ticks.
   const frameListeners = new Set();
   function onFrame(cb) { frameListeners.add(cb); return () => frameListeners.delete(cb); }
+  // After a frame has actually DRAWN to the canvas (the loop renders on demand,
+  // so most frames draw nothing and call nobody). mountPreview's `drawn`.
+  const renderedListeners = new Set();
+  function onRendered(cb) { renderedListeners.add(cb); return () => renderedListeners.delete(cb); }
 
   // Fired at the end of every showAssembly, for hosts that need to react to
   // which sub-parts are visible (e.g. re-deriving a view style thumbnail).
@@ -1864,6 +1943,11 @@ export function createViewer(container, part) {
     }
     if (_box.isEmpty()) return;
     const center = _box.getCenter(new THREE.Vector3());
+    // A fill framing centres on the geometry, not its box: the horizontal
+    // vertex centroid (model x/y — the pivot stands model Z up) with the box's
+    // vertical centre. A lopsided part (a three-blade propeller) then turns
+    // about its hub instead of orbiting the middle of its box.
+    if (frameFill) horizontalCentroid(visibleNames, center);
     partsGroup.position.copy(center).multiplyScalar(-1); // centre assembly on the pivot
     const size = _box.getSize(new THREE.Vector3());
     // Drop the grid to the bottom of the bounding box (model Z -> world Y), so it reads
@@ -1871,6 +1955,7 @@ export function createViewer(container, part) {
     floorY = -size.z / 2;
     grid.position.y = floorY;
     const r = Math.max(size.x, size.y, size.z) || 12;
+    const fill = fillFraming(_box, visibleNames, center);
     // Keep the VIEW DIRECTION (target -> camera), not the camera's direction
     // from the origin: after a pan the target is off the origin, and scaling
     // the position about the origin would turn the view — which, in an ortho
@@ -1880,11 +1965,138 @@ export function createViewer(container, part) {
     _frameDir.copy(activeCamera.position).sub(controls.target);
     if (_frameDir.lengthSq() === 0) _frameDir.copy(activeCamera.position);
     if (_frameDir.lengthSq() === 0) _frameDir.set(1, 1, 1);
-    activeCamera.position.copy(_frameDir.normalize().multiplyScalar(r * 2.6 + 6));
+    _frameDir.normalize();
+    const filled = fill?.(_frameDir);
+    activeCamera.position.copy(_frameDir).multiplyScalar(filled ? filled.distance : r * 2.6 + 6);
     controls.target.set(0, 0, 0);
     // Framing under ortho is a frustum, not a distance — without this the
-    // reframe button moves the camera and nothing visibly changes.
-    if (projectionMode === "orthographic") syncOrthoToPerspectiveFraming();
+    // reframe button moves the camera and nothing visibly changes. A fill
+    // framing sizes the frustum to the projected box directly (the sync
+    // matches size at the surface under the screen centre, not the extent).
+    if (projectionMode === "orthographic") {
+      if (filled) {
+        applyOrthoFrustum({ halfH: filled.orthoHalfH, halfW: filled.orthoHalfH * filled.aspect });
+        orthoCamera.zoom = 1;
+        orthoCamera.updateProjectionMatrix();
+      } else {
+        syncOrthoToPerspectiveFraming();
+      }
+    }
+  }
+
+  // The `frameFill` framing. `size` is the posed box in the model frame; the
+  // assembly is centred on the pivot, so its world corners are the half-extents
+  // stood up by the pivot's rotation. With `frameSwept` the points are the
+  // model swept about the vertical through the box centre — two circles at the
+  // box's top and bottom whose radius is the farthest posed VERTEX from that
+  // axis (nudged out so the polygon contains the circle). Not the box's
+  // corners: those sit ~√2 farther out than a round part's rim, which framed a
+  // turning gear at little more than half the asked-for width. Returns a function of the unit view
+  // direction (target → camera) giving `{ distance, orthoHalfH, aspect }`:
+  //  - perspective: the distance, along that direction to the origin target,
+  //    at which the points' projected extent — the larger of (projected width /
+  //    viewport width, projected height / viewport height) — equals frameFill.
+  //    The extent only shrinks as the camera backs off, so it is bisected.
+  //  - orthographic: the half-height that gives the same extent.
+  // Null when unset, or when the container has no size yet (a hidden or
+  // unlaid-out stage): frameTo then falls back to the fixed distance, and the
+  // next reframe fills.
+  const SWEEP_SEGMENTS = 48;
+  const _sweepV = new THREE.Vector3();
+  // The farthest horizontal distance of any posed vertex of `names` from the
+  // vertical through `center` (model frame), in world units. Reads positions
+  // through BufferAttribute accessors, so normalized/quantized data is
+  // dequantized.
+  function sweepRadius(names, center) {
+    let max = 0;
+    for (const name of names) {
+      const pos = subCache[name]?.getAttribute("position");
+      if (!pos) continue;
+      const pose = subMesh[name].matrix;
+      for (let i = 0; i < pos.count; i++) {
+        _sweepV.fromBufferAttribute(pos, i).applyMatrix4(pose).sub(center).applyQuaternion(pivot.quaternion);
+        const d = Math.hypot(_sweepV.x, _sweepV.z);
+        if (d > max) max = d;
+      }
+    }
+    return max;
+  }
+  // Overwrite `center`'s model x/y with the mean posed vertex position of
+  // `names` (z untouched). A plain vertex mean: preview meshes are close enough
+  // to uniformly tessellated for it to land on the hub of a lopsided part.
+  function horizontalCentroid(names, center) {
+    let sx = 0, sy = 0, n = 0;
+    for (const name of names) {
+      const pos = subCache[name]?.getAttribute("position");
+      if (!pos) continue;
+      const pose = subMesh[name].matrix;
+      for (let i = 0; i < pos.count; i++) {
+        _sweepV.fromBufferAttribute(pos, i).applyMatrix4(pose);
+        sx += _sweepV.x; sy += _sweepV.y; n++;
+      }
+    }
+    if (n > 0) center.set(sx / n, sy / n, center.z);
+  }
+  function fillFraming(box, names, center) {
+    if (!frameFill) return null;
+    const w = container.clientWidth, h = container.clientHeight;
+    if (!(w > 0 && h > 0)) return null;
+    const aspect = w / h;
+    pivot.updateMatrix();
+    // The box corners about the framing centre (no longer the box's own centre).
+    let points = [];
+    for (const x of [box.min.x, box.max.x]) for (const y of [box.min.y, box.max.y]) for (const z of [box.min.z, box.max.z]) {
+      points.push(new THREE.Vector3(x, y, z).sub(center).applyQuaternion(pivot.quaternion));
+    }
+    if (frameSwept) {
+      const radius = sweepRadius(names, center) / Math.cos(Math.PI / SWEEP_SEGMENTS);
+      const ys = [Math.min(...points.map((p) => p.y)), Math.max(...points.map((p) => p.y))];
+      points = [];
+      for (let k = 0; k < SWEEP_SEGMENTS; k++) {
+        const a = (2 * Math.PI * k) / SWEEP_SEGMENTS;
+        for (const y of ys) points.push(new THREE.Vector3(radius * Math.cos(a), y, radius * Math.sin(a)));
+      }
+    }
+    if (points.every((p) => p.lengthSq() === 0)) return null;
+    const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2);
+    const tanH = tanV * aspect;
+    return (dir) => {
+      // The camera's basis for this view direction, `up` as the controls keep it.
+      const forward = dir.clone().negate();
+      const right = new THREE.Vector3().crossVectors(forward, activeCamera.up);
+      if (right.lengthSq() < 1e-12) right.set(1, 0, 0); // looking straight along up
+      right.normalize();
+      const upAxis = new THREE.Vector3().crossVectors(right, forward);
+      const xs = points.map((p) => p.dot(right)), ys = points.map((p) => p.dot(upAxis)), along = points.map((p) => p.dot(dir));
+      // `fill` is the projected SPAN: the larger of (projected width / viewport
+      // width, projected height / viewport height). The framing centre sits at
+      // the screen centre, though, and a lopsided part reaches farther one way
+      // than the other — so the camera also backs off until nothing leaves the
+      // viewport (|NDC| <= 1 on both axes). For a part about as symmetric as
+      // its centre, the span decides alone.
+      const span = (v) => Math.max(...v) - Math.min(...v);
+      const reach = (v) => Math.max(...v.map(Math.abs));
+      const orthoHalfH = Math.max(span(xs) / (2 * frameFill * aspect), span(ys) / (2 * frameFill), reach(xs) / aspect, reach(ys));
+      // How far over budget the projection is at distance d (<= 1 fits).
+      const over = (d) => {
+        let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity, r = 0;
+        for (let i = 0; i < points.length; i++) {
+          const z = d - along[i]; // depth in front of the camera
+          const nx = xs[i] / (z * tanH), ny = ys[i] / (z * tanV);
+          x0 = Math.min(x0, nx); x1 = Math.max(x1, nx); y0 = Math.min(y0, ny); y1 = Math.max(y1, ny);
+          r = Math.max(r, Math.abs(nx), Math.abs(ny));
+        }
+        return Math.max(Math.max(x1 - x0, y1 - y0) / (2 * frameFill), r); // NDC spans 2 per axis
+      };
+      const nearest = Math.max(...along);
+      let lo = nearest + 1e-6 * (1 + Math.abs(nearest)), hi = Math.max(lo * 2, 1);
+      while (over(hi) > 1 && hi < 1e9) hi *= 2;
+      for (let i = 0; i < 60; i++) {
+        const mid = (lo + hi) / 2;
+        if (over(mid) > 1) lo = mid; else hi = mid;
+      }
+      return { distance: hi, orthoHalfH, aspect };
+    };
   }
 
   // Show exactly the named sub-parts (from the cache). When `frame` is set, also
@@ -1906,6 +2118,7 @@ export function createViewer(container, part) {
     if (frame) frameTo(visibleNames);
     cutaway.setVisible(effectiveVisible());
     placeGround(); // realistic only: the ground comes to the part, and the shadow re-renders
+    if (contactShadow) rebuildLiveShadow(); // CAD only (a no-op in realistic)
     for (const cb of [...assemblyListeners]) {
       try { cb(); } catch (e) { console.warn("partforge: assembly listener failed", e); }
     }
@@ -1949,11 +2162,11 @@ export function createViewer(container, part) {
     const t = THEME[mode] ?? THEME.dark;
     // Realistic mode's backdrop belongs to the environment and its grid is off;
     // enterCad puts the theme's background back on the way out.
-    if (renderMode === "cad") scene.background = new THREE.Color(t.bg);
+    if (renderMode === "cad") scene.background = cadBackground(THEME[mode] ? mode : "dark");
     scene.remove(grid);
     grid = new THREE.GridHelper(GRID_SIZE, GRID_DIVS, t.grid[0], t.grid[1]);
     grid.position.y = floorY; // keep the floor at the bbox bottom across theme swaps
-    grid.visible = renderMode === "cad";
+    grid.visible = renderMode === "cad" && cadGrid;
     scene.add(grid);
     lineMaterial.color.set(t.line);
     for (const m of fadeLineMats.values()) m.color.set(t.line); // clones follow the theme
@@ -2756,6 +2969,9 @@ export function createViewer(container, part) {
     }
     renderWithBackdrop(scene, activeCamera);
     cutaway.renderOverlay(renderer, activeCamera);
+    for (const cb of [...renderedListeners]) {
+      try { cb(); } catch (e) { console.warn("partforge: rendered listener failed", e); }
+    }
   }
   renderer.setAnimationLoop(renderFrame);
 
@@ -3032,6 +3248,7 @@ export function createViewer(container, part) {
     controls.removeEventListener("start", onControlsStart);
     cameraStartListeners.clear();
     frameListeners.clear();
+    renderedListeners.clear();
     assemblyListeners.clear();
     themeListeners.clear();
     projectionListeners.clear();
@@ -3078,6 +3295,7 @@ export function createViewer(container, part) {
     fadeMats.clear();
     fadeLineMats.clear();
     disposeRealistic();
+    disposeLiveShadow();
     material.dispose();
     lineMaterial.dispose();
     grid.geometry.dispose();
@@ -3113,6 +3331,7 @@ export function createViewer(container, part) {
     renderMaterialThumbnail,
     invalidateMaterialThumbnails,
     onFrame,
+    onRendered,
     onAssemblyChange: (cb) => { assemblyListeners.add(cb); return () => assemblyListeners.delete(cb); },
     tweenCameraTo,
     getCameraCue,

package/types/index.d.ts

@@ -798,7 +798,7 @@ export interface PartRuntime {
 /** Mount a full parametric-part app from a `PartDefinition`. */
 export function mount(part: PartDefinition, options: MountOptions): PartRuntime;
 
-/** Options for `mountPreview`. */
+/** Options for `mountPreview`. Any other key throws a `TypeError`. */
 export interface MountPreviewOptions {
   /** A GLB from `partforge/gltf`'s `encodePreviewGlb`, or a runtime's `exportPreview()`. */
   glb: Uint8Array | ArrayBuffer;
@@ -808,12 +808,50 @@ export interface MountPreviewOptions {
   viewerState?: ViewerState | null;
   /** Play the file's baked animation once drawn (default true). The editor's own boot preview goes through mount(), not here. */
   animate?: boolean;
+  /** `false` (0.168.0+): no view cube, `#viewbar` controls, view style, tooltips, play button or `elements.chrome` wiring. Default true. */
+  chrome?: boolean;
+  /** `"transparent"` (0.168.0+): alpha-0 clear, no theme background, no grid. CAD mode only — realistic mode draws its own environment backdrop. Default `"theme"`. */
+  background?: "theme" | "transparent";
+  /** `true` (0.168.0+): a soft contact shadow under the part, cast once at showAssembly from the meshes as the file stores them (the rest pose, before a player applies its first pose); a playing animation does not move it. CAD mode only — realistic mode draws its own ground and shadow. Default false. */
+  contactShadow?: boolean;
+  /** `false` (0.168.0+): no wheel/pinch zoom (a wheel scrolls the page). Default true. */
+  zoom?: boolean;
+  /** `false` (0.168.0+): no pan. Default true. */
+  pan?: boolean;
+  /**
+   * Degrees per second (0.168.0+; default 0, off): a file with no playing animation
+   * turns about the vertical. Never under reduced motion; the first camera grab
+   * (a canvas drag or the view cube) stops it for good.
+   */
+  turntable?: number;
+  /**
+   * 0 < fill <= 1 (0.168.0+): the opening framing (and the viewer's reframe) puts the
+   * camera, along the opening view direction, so the model's bounding box as projected
+   * on screen spans this fraction of the viewport along its limiting axis. With a
+   * `turntable` (and no baked animation) the model swept a full turn is framed — its
+   * farthest vertex from the vertical axis, over the box's height — so the turn never
+   * clips and a round part still fills. With `fill` the model is centred on its
+   * horizontal vertex centroid (a lopsided part turns about its hub), and nothing
+   * leaves the viewport; a baked animation that moves parts outside the box may. Unset, the
+   * fixed framing distance.
+   */
+  fill?: number;
+  /** `"default"` (0.168.0+): drop the camera and projection of `viewerState` and `setViewerState`, so the mount keeps the file's own framing; their render mode and environment still apply. Default `"carry"`. */
+  camera?: "carry" | "default";
+  /** The opening render mode (0.168.0+): applied at mount, over any carried render mode; afterwards `setViewerState`, `renderMode.set` and the view style control change it as usual. Unset, the carried state decides. */
+  renderMode?: RenderMode;
 }
 
 /** 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>;
+  /**
+   * Resolves after the first frame that includes the meshes has rendered (0.168.0+) —
+   * for cross-fading from a still image. Rejects with `ready`'s error when the file
+   * will not decode, or when the handle is disposed first. Waits while parked.
+   */
+  drawn: Promise<void>;
   /** Full teardown. Idempotent. */
   dispose(): void;
   /** The view the file was written for (`null` until drawn, or when the file names none). */