partforge 0.167.0 → 0.169.0

package/README.md

@@ -187,11 +187,50 @@ 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, and it
+turns about its hub; a model that is not turning has its on-screen outline centred, since 0.169.0), `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), and `autostart: false`
+(0.169.0+: the animation or turntable waits at its first frame until
+`handle.motion.start()`). 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.
+
+`handle.motion` (0.169.0+; `null` before `ready` and once disposed) drives that
+motion: `start()` begins a waiting one (idempotent), `restart()` puts the model
+back as it opened — the opening camera framing, the animation from its start or
+the turntable turning again — and starts it, `state` is `"waiting"`,
+`"playing"`, `"stopped"` (a drag stopped the turntable, or nothing moves) or
+`"finished"` (a play-once animation ended), and `onChange(cb)` hears each change.
+Under `prefers-reduced-motion` nothing moves and `restart()` only resets the
+camera; a turntable mount is framed for its full turn either way.
+
 ```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
+// With autostart: false the card waits at that frame: fade it in, then
+// card.motion.start(); a "replay" button calls card.motion.restart().
 ```
 
 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.169.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,82 @@
 // 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 (until
+//    `motion.restart()`). 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, centred on its horizontal
+//    vertex centroid (a lopsided part turns about its hub). A model that is
+//    not turning (a still, or a playing animation — framed on its first
+//    pose) is fitted by its posed VERTICES and its silhouette centred on
+//    screen (0.169.0): the target moves in the screen plane so the projected
+//    outline's bounding box is centred, spanning `fill`. A baked animation
+//    that moves parts outside its first pose's outline can leave the frame.
+//    Unset, the viewer's fixed framing distance, as before.
+//    The swept framing follows the configuration, not reduced motion (0.169.0):
+//    a turntable mount is framed swept even when reduced motion keeps it still.
+//  - `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.
+//  - `autostart: false` (0.169.0; default true) — the motion (a playing
+//    animation, or the turntable) is set up but WAITS: the model is drawn at
+//    the animation's first pose (the t = 0 pose a started player draws first)
+//    and at turntable angle 0, and nothing moves until `handle.motion.start()`.
+//    `drawn` resolves on a frame showing exactly that pose, so a host can
+//    cross-fade from a still of it and then say go. A waiting animation's play
+//    button reads Play.
+//  Any other key throws (an option this version does not know is a host bug).
+//
+// `handle.motion` (0.169.0; null before ready and once disposed, present for
+// every decoded file) drives the motion whatever `autostart` said:
+//  - `start()` begins a waiting motion. Idempotent; a no-op once started, under
+//    reduced motion, or with nothing to move.
+//  - `restart()` puts the model back as it opened and starts it: the camera
+//    returns to the opening framing (showAssembly's framing at mount — the
+//    file's default view direction at the fill distance, before any carried
+//    camera — so a visitor's orbit is undone), the animation replays from
+//    t = 0 (intro cue included) or the turntable turns again from there,
+//    re-armed so the next grab stops it again. Under reduced motion it only
+//    resets the camera (the pose already is t = 0).
+//  - `state` — "waiting" | "playing" | "stopped" (a turntable stopped by a
+//    grab, an animation paused from its button, reduced motion, or nothing to
+//    move) | "finished" (a play-once animation resting at its end pose).
+//  - `onChange(cb)` → unsubscribe: hears each state change.
+// `handle.animation` is unchanged.
+//
+// `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 +121,84 @@ 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",
+  "autostart",
+]);
+
+function presentation({ chrome, background, contactShadow, zoom, pan, turntable, fill, camera, renderMode, autostart }) {
+  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),
+    autostart: flag("autostart", autostart, true),
+  };
+}
+
+// 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. It begins "waiting" (angle 0, nothing moves) until start(); the
+// first grab — while waiting or turning — stops it for good; restart() re-arms
+// it and turns again from wherever the camera is now (the host has just put it
+// back). `onChange` hears every phase change.
+function createTurntable(viewer, container, degPerSec, onChange) {
+  let turning = false, phase = "waiting", offFrame = null;
+  const set = (next) => { if (next !== phase) { phase = next; onChange(); } };
+  function step(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; }
+  }
+  function halt() { offFrame?.(); offFrame = null; }
+  const offGrab = viewer.onCameraStart(() => {
+    if (turning || phase === "stopped") return;
+    halt();
+    set("stopped");
+  });
+  return {
+    phase: () => phase,
+    start() {
+      if (phase !== "waiting") return;
+      offFrame = viewer.onFrame(step);
+      set("playing");
+    },
+    restart() {
+      halt();
+      offFrame = viewer.onFrame(step);
+      set("playing");
+    },
+    dispose() { halt(); offGrab(); },
+  };
+}
+
 function previewPart({ meshes, view, meta }) {
   return {
     meta: { title: "Preview", ...(meta ?? {}) },
@@ -65,24 +219,45 @@ 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
+  let motion = null;                 // handle.motion, once the GLB has decoded
+  const motionListeners = new Set();
   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,39 +269,104 @@ 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;
+    // Framing follows the configuration, not reduced motion: a turntable mount
+    // is framed swept whether or not it is allowed to turn, so every visitor
+    // sees the model at the same size and centre.
+    const sweeps = !plays && opts.turntable > 0;
+    const turns = sweeps && !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: sweeps,
+    });
     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)));
     for (const m of decoded.meshes) viewer.setSubGeometry(m.name, m);
     viewer.showAssembly(decoded.meshes.map((m) => m.name), { frame: true });
+    // The opening framing restart() returns to: the file's default view
+    // direction at the fill distance, before any carried camera.
+    const opening = viewer.getCameraState();
     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);
+    let turntable = null;
+    let lastMotionState = null;
+    const motionState = () => {
+      if (player && !reducedMotion) {
+        if (!player.started()) return "waiting";
+        const { status } = player.state();
+        return status === "done" ? "finished" : status === "playing" || status === "intro" ? "playing" : "stopped";
+      }
+      return turntable ? turntable.phase() : "stopped";
+    };
+    const motionChanged = () => {
+      if (disposed) return;
+      const now = motionState();
+      if (now === lastMotionState) return;
+      lastMotionState = now;
+      relay(motionListeners)(now);
+    };
+    if (plays) {
       player = createPreviewPlayer(viewer, decoded.animation, { reducedMotion });
       const own = player;
       cleanups.push(() => own.dispose());
-      player.start();
+      cleanups.push(own.onChange(motionChanged));
+      if (opts.autostart) player.start();
+      else player.prime(); // drawn at the first frame, waiting for motion.start()
       if (!reducedMotion && toolbar) {
         const playButton = attachPreviewPlayButton(own, { toolbar, before: viewStyle.element }, { tooltip });
         cleanups.push(() => playButton.detach());
       }
+    } else if (turns) {
+      const own = turntable = createTurntable(viewer, container, opts.turntable, motionChanged);
+      cleanups.push(() => own.dispose());
+      if (opts.autostart) turntable.start();
     }
+    lastMotionState = motionState();
+    motion = {
+      get state() { return motionState(); },
+      start() {
+        if (disposed) return;
+        if (player) player.start(); // a no-op once started or under reduced motion
+        else turntable?.start();
+        motionChanged();
+      },
+      restart() {
+        if (disposed) return;
+        viewer.cancelCameraTween();
+        viewer.setCameraState(opening);
+        if (player) player.restart(); // nothing under reduced motion: the pose is already t = 0
+        else turntable?.restart();
+        motionChanged();
+      },
+      onChange(cb) {
+        if (disposed) return () => {};
+        motionListeners.add(cb);
+        return () => motionListeners.delete(cb);
+      },
+    };
   });
-  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,11 +388,15 @@ 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)
+      motion = null;
+      motionListeners.clear();
       const errors = [];
       while (cleanups.length) {
         try { cleanups.pop()(); } catch (error) { errors.push(error); }
@@ -165,9 +409,11 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     get animation() {
       return player ? { state: player.state, pause: player.pause, resume: player.resume, replay: player.replay } : null;
     },
+    // null before ready and once disposed; present for every decoded file.
+    get motion() { return motion; },
     getViewerState,
     setViewerState(next) {
-      carried = next ?? null;
+      carried = carry(next);
       applyState(carried);
     },
     setActive(next) {

package/src/framework/preview-play-button.js

@@ -5,7 +5,8 @@
 //
 // Three states, read off the player's onChange notifications (never polled):
 //   - Pause  while playing or during the intro camera tween;
-//   - Play   while paused — resumes from the pose it froze at;
+//   - Play   while paused — resumes from the pose it froze at — or while a
+//            mount with `autostart: false` waits at its first frame (starts it);
 //   - Replay once a one-time animation has finished at its end pose — plays it
 //            again from the start, camera cues included. A looping animation
 //            never gets here.
@@ -30,7 +31,7 @@ const STATES = {
 };
 
 // What a click does for a given player status.
-const actionFor = (status) => (status === "paused" ? "play" : status === "done" ? "replay" : "pause");
+const actionFor = (status) => (status === "paused" || status === "idle" ? "play" : status === "done" ? "replay" : "pause");
 
 export function attachPreviewPlayButton(player, { toolbar, before = null }, { tooltip = null } = {}) {
   const button = document.createElement("button");
@@ -58,7 +59,7 @@ export function attachPreviewPlayButton(player, { toolbar, before = null }, { to
 
   const onClick = () => {
     if (action === "pause") player.pause();
-    else if (action === "play") player.resume();
+    else if (action === "play") { if (player.state().status === "idle") player.start(); else player.resume(); }
     else player.replay();
   };
   button.addEventListener("click", onClick);

package/src/framework/preview-player.js

@@ -26,6 +26,12 @@
 // re-honors an abandoned intro or sweep on the next play(). An orbit while
 // paused stays paused. onChange(cb) reports every status change, so a control
 // never polls.
+//
+// A host that wants the model to WAIT at its first frame (mountPreview's
+// `autostart: false`, 0.169.0) calls prime() instead of start(): the t = 0 pose
+// and opacity are drawn — exactly what start() draws first — and nothing
+// advances until start(). restart() plays again from t = 0 from any state
+// (waiting, playing, paused, done), re-arming the cues and the intro.
 import { createPlayback } from "./animation.js";
 import { invertRigid, mulMat4 } from "./geometry/pose.js";
 
@@ -106,7 +112,7 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
   // already sits at its t = 0 placement, so the identity pose is the rest pose.
   const restInverse = Object.fromEntries(Object.keys(tracks).map((name) => [name, invertRigid(rest[name])]));
 
-  let offFrame = null, offOrbit = null, started = false, disposed = false;
+  let offFrame = null, offOrbit = null, started = false, disposed = false, held = false;
   const listeners = new Set();
   let lastStatus = playback.state().status;
 
@@ -151,13 +157,24 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
     if (playback.state().status === "intro") { playback.introDone(); notify(); }
   }
 
-  return {
+  // The t = 0 pose and opacity, with the ground held for what moves next.
+  function firstFrame() {
+    apply(0);
+    if (!held) { viewer.holdGround(true); held = true; }
+  }
+
+  const player = {
+    // Draw the first frame and wait there (no-op under reduced motion, once
+    // started, or once disposed).
+    prime() {
+      if (started || disposed || reducedMotion) return;
+      firstFrame();
+    },
     start() {
       if (started || disposed) return;
       started = true;
       if (reducedMotion) return;
-      apply(0);
-      viewer.holdGround(true);
+      firstFrame();
       offFrame = viewer.onFrame(onFrame);
       offOrbit = viewer.onCameraStart(onOrbit);
       honorIntro(playback.play());
@@ -185,6 +202,20 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
       honorIntro(playback.play());
       notify();
     },
+    // From any state: back to t = 0 (pose, opacity, cues re-armed) and play,
+    // its intro cue included. Starts a player that was waiting. Nothing under
+    // reduced motion — the file's own opening pose is already the t = 0 pose.
+    restart() {
+      if (disposed || reducedMotion) return;
+      if (!started) { player.start(); return; }
+      viewer.cancelCameraTween();
+      playback.reset();
+      apply(0);
+      honorIntro(playback.play());
+      notify();
+    },
+    // True once start() has run (under reduced motion too).
+    started: () => started,
     onChange(cb) {
       if (disposed) return () => {};
       listeners.add(cb);
@@ -194,11 +225,10 @@ export function createPreviewPlayer(viewer, animation, { reducedMotion = false }
       if (disposed) return;
       disposed = true;
       listeners.clear();
-      if (!offFrame) return; // never played (not started, or reduced motion): nothing to undo
-      offFrame(); offOrbit();
-      offFrame = offOrbit = null;
-      viewer.holdGround(false);
+      if (offFrame) { offFrame(); offOrbit(); offFrame = offOrbit = null; }
+      if (held) { held = false; viewer.holdGround(false); } // primed or played
     },
     state: snapshotState,
   };
+  return player;
 }

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).
@@ -1849,6 +1928,7 @@ export function createViewer(container, part) {
 
   // --- show / hide assembly -------------------------------------------------
   const _box = new THREE.Box3();
+  const _origin = new THREE.Vector3();
   const _posedBox = new THREE.Box3();
   const _frameDir = new THREE.Vector3();
 
@@ -1864,6 +1944,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 +1956,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 +1966,239 @@ 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));
-    controls.target.set(0, 0, 0);
+    _frameDir.normalize();
+    const filled = fill?.(_frameDir);
+    // A silhouette-centred fill framing aims off the pivot: the target moves in
+    // the screen plane (and the camera with it, keeping the view direction).
+    controls.target.copy(filled?.offset ?? _origin);
+    activeCamera.position.copy(_frameDir).multiplyScalar(filled ? filled.distance : r * 2.6 + 6).add(controls.target);
     // 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.
+  //
+  // Without `frameSwept` (0.169.0) the points are the posed mesh VERTICES, not
+  // the box corners, and the framing is silhouette-centred: the result also
+  // carries `offset`, a world-space shift of the target (and the camera with
+  // it) in the screen plane that centres the vertices' projected bounding box,
+  // and the distance makes that box span frameFill along its limiting axis.
+  // Box-centred framing put an obliquely-viewed wide flat part low on screen —
+  // its near-bottom corner projects far past the far-top one — and fitted
+  // corners that no vertex reaches. The swept framing keeps the target on the
+  // pivot, so a turntable still turns about the hub.
+  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);
+  }
+  // Every posed vertex of `names` about `center`, stood up by the pivot, as
+  // flat x/y/z arrays (world units, pivot-relative).
+  function posedVertices(names, center) {
+    let n = 0;
+    for (const name of names) n += subCache[name]?.getAttribute("position")?.count ?? 0;
+    const px = new Float64Array(n), py = new Float64Array(n), pz = new Float64Array(n);
+    let k = 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++, k++) {
+        _sweepV.fromBufferAttribute(pos, i).applyMatrix4(pose).sub(center).applyQuaternion(pivot.quaternion);
+        px[k] = _sweepV.x; py[k] = _sweepV.y; pz[k] = _sweepV.z;
+      }
+    }
+    return { px, py, pz, n };
+  }
+
+  // The silhouette-centred fill framing of posed vertices (see above).
+  function centredFraming({ px, py, pz, n }, aspect) {
+    if (n === 0) return null;
+    let any = false;
+    for (let i = 0; i < n && !any; i++) any = px[i] !== 0 || py[i] !== 0 || pz[i] !== 0;
+    if (!any) return null;
+    const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2);
+    const tanH = tanV * aspect;
+    const xs = new Float64Array(n), ys = new Float64Array(n), along = new Float64Array(n);
+    return (dir) => {
+      const forward = dir.clone().negate();
+      const right = new THREE.Vector3().crossVectors(forward, activeCamera.up);
+      if (right.lengthSq() < 1e-12) right.set(1, 0, 0);
+      right.normalize();
+      const upAxis = new THREE.Vector3().crossVectors(right, forward);
+      let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity, nearest = -Infinity;
+      for (let i = 0; i < n; i++) {
+        xs[i] = px[i] * right.x + py[i] * right.y + pz[i] * right.z;
+        ys[i] = px[i] * upAxis.x + py[i] * upAxis.y + pz[i] * upAxis.z;
+        along[i] = px[i] * dir.x + py[i] * dir.y + pz[i] * dir.z;
+        if (xs[i] < x0) x0 = xs[i]; if (xs[i] > x1) x1 = xs[i];
+        if (ys[i] < y0) y0 = ys[i]; if (ys[i] > y1) y1 = ys[i];
+        if (along[i] > nearest) nearest = along[i];
+      }
+      // Orthographic: centre the extent exactly; the half-height that fits it.
+      const orthoHalfH = Math.max((x1 - x0) / (2 * frameFill * aspect), (y1 - y0) / (2 * frameFill)) || 1;
+      const orthoOffset = right.clone().multiplyScalar((x0 + x1) / 2).addScaledVector(upAxis, (y0 + y1) / 2);
+      if (projectionMode === "orthographic") {
+        const d = Math.max(nearest, 0) + Math.max(x1 - x0, y1 - y0) * 2 + 6;
+        return { distance: d, orthoHalfH, aspect, offset: orthoOffset };
+      }
+      // Perspective: the projected box, the target shifted (tx, ty) in the
+      // screen plane, the camera at distance d along `dir`.
+      let tx = (x0 + x1) / 2, ty = (y0 + y1) / 2;
+      const ext = (d) => {
+        let a0 = Infinity, a1 = -Infinity, b0 = Infinity, b1 = -Infinity;
+        for (let i = 0; i < n; i++) {
+          const z = d - along[i];
+          const nx = (xs[i] - tx) / (z * tanH), ny = (ys[i] - ty) / (z * tanV);
+          if (nx < a0) a0 = nx; if (nx > a1) a1 = nx;
+          if (ny < b0) b0 = ny; if (ny > b1) b1 = ny;
+        }
+        return [a0, a1, b0, b1];
+      };
+      const over = (d) => { const [a0, a1, b0, b1] = ext(d); return Math.max(a1 - a0, b1 - b0) / (2 * frameFill); };
+      const fit = () => {
+        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 < 48; i++) {
+          const mid = (lo + hi) / 2;
+          if (over(mid) > 1) lo = mid; else hi = mid;
+        }
+        return hi;
+      };
+      let d = fit();
+      // Recentre and refit: the shift moves each vertex's NDC by 1/depth, so a
+      // few rounds converge.
+      for (let round = 0; round < 8; round++) {
+        const [a0, a1, b0, b1] = ext(d);
+        const cx = (a0 + a1) / 2, cy = (b0 + b1) / 2;
+        if (Math.abs(cx) < 1e-5 && Math.abs(cy) < 1e-5) break;
+        tx += cx * d * tanH;
+        ty += cy * d * tanV;
+        d = fit();
+      }
+      return { distance: d, orthoHalfH, aspect, offset: right.multiplyScalar(tx).addScaledVector(upAxis, ty) };
+    };
+  }
+
+  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();
+    if (!frameSwept) return centredFraming(posedVertices(names, center), aspect);
+    // 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 +2220,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 +2264,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 +3071,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 +3350,7 @@ export function createViewer(container, part) {
     controls.removeEventListener("start", onControlsStart);
     cameraStartListeners.clear();
     frameListeners.clear();
+    renderedListeners.clear();
     assemblyListeners.clear();
     themeListeners.clear();
     projectionListeners.clear();
@@ -3078,6 +3397,7 @@ export function createViewer(container, part) {
     fadeMats.clear();
     fadeLineMats.clear();
     disposeRealistic();
+    disposeLiveShadow();
     material.dispose();
     lineMaterial.dispose();
     grid.geometry.dispose();
@@ -3113,6 +3433,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,59 @@ 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 until `motion.restart()`.
+   */
+  turntable?: number;
+  /**
+   * `false` (0.169.0+; default true): the motion — a playing animation or the
+   * turntable — waits at its first frame (the animation's t = 0 pose, turntable
+   * angle 0) until `motion.start()`. `drawn` resolves on a frame showing that pose.
+   */
+  autostart?: boolean;
+  /**
+   * 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, centred on its horizontal vertex centroid (a
+   * lopsided part turns about its hub). Without a turntable (0.169.0+) the posed mesh
+   * vertices are fitted and their on-screen outline is centred (the target moves in the
+   * screen plane), spanning `fill`; a baked animation that moves parts outside its first
+   * pose's outline may leave the frame. Unset, the
+   * fixed framing distance. Since 0.169.0 a turntable mount is framed swept under reduced
+   * motion too, so every visitor sees the same framing.
+   */
+  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). */
@@ -838,6 +885,25 @@ export interface PreviewRuntime {
     /** Play a finished one-time animation again from the start (its camera cues included); a no-op unless `state().status` is `"done"`. */
     replay(): void;
   } | null;
+  /**
+   * The motion — baked animation or turntable — (0.169.0+): `null` before `ready` and
+   * once disposed; present for every decoded file.
+   */
+  readonly motion: {
+    /** Begin a waiting motion. Idempotent; a no-op once started, under reduced motion, or with nothing to move. */
+    start(): void;
+    /**
+     * Put the model back as it opened and start it: the opening camera framing (the
+     * file's default view direction, before any carried camera), the animation from
+     * t = 0 or the turntable turning again (re-armed). Under reduced motion it only
+     * resets the camera.
+     */
+    restart(): void;
+    /** `"stopped"`: a turntable stopped by a grab, a paused animation, reduced motion, or nothing to move. */
+    readonly state: "waiting" | "playing" | "stopped" | "finished";
+    /** Each state change. Returns an unsubscribe. */
+    onChange(cb: (state: "waiting" | "playing" | "stopped" | "finished") => void): () => void;
+  } | null;
   renderMode: {
     get(): RenderMode;
     set(mode: RenderMode): Promise<RenderMode>;