partforge 0.168.0 → 0.169.0

package/README.md

@@ -198,16 +198,27 @@ 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
+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). An unknown option key
+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
@@ -218,6 +229,8 @@ const card = mountPreview(cardStage, {                   // a landing-page card
   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.168.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

@@ -49,17 +49,24 @@
 //  - `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.
+//    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. 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.
+//    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.
@@ -67,8 +74,32 @@
 //    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
@@ -105,9 +136,10 @@ function flag(name, value, fallback) {
 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 }) {
+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");
   }
@@ -124,30 +156,47 @@ function presentation({ chrome, background, contactShadow, zoom, pan, turntable,
     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. Returns stop().
-function startTurntable(viewer, container, degPerSec) {
-  let turning = false, stopped = false;
-  const offFrame = viewer.onFrame((dt) => {
+// 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; }
-  });
-  const offGrab = viewer.onCameraStart(() => { if (!turning) stop(); });
-  function stop() {
-    if (stopped) return;
-    stopped = true;
-    offFrame();
-    offGrab();
   }
-  return stop;
+  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 }) {
@@ -192,6 +241,8 @@ export function mountPreview(container, options = {}) {
   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();
@@ -220,11 +271,15 @@ export function mountPreview(container, options = {}) {
     const view = decoded.view ?? "preview";
     const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
     const plays = !!decoded.animation && animate !== false;
-    const turns = !plays && opts.turntable > 0 && !reducedMotion;
+    // 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: turns,
+      frameFill: opts.fill, frameSwept: sweeps,
     });
     cleanups.push(() => viewer.dispose());
     let tooltip = null, toolbar = null, viewStyle = null;
@@ -246,23 +301,70 @@ export function mountPreview(container, options = {}) {
     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);
     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) {
-      cleanups.push(startTurntable(viewer, container, opts.turntable));
+      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(rejectDrawn); // the host awaits it; never an unhandled rejection
 
@@ -293,6 +395,8 @@ export function mountPreview(container, options = {}) {
       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); }
@@ -305,6 +409,8 @@ export function mountPreview(container, options = {}) {
     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 = carry(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

@@ -1928,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();
 
@@ -1967,8 +1968,10 @@ export function createViewer(container, part, {
     if (_frameDir.lengthSq() === 0) _frameDir.set(1, 1, 1);
     _frameDir.normalize();
     const filled = fill?.(_frameDir);
-    activeCamera.position.copy(_frameDir).multiplyScalar(filled ? filled.distance : r * 2.6 + 6);
-    controls.target.set(0, 0, 0);
+    // 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. A fill
     // framing sizes the frustum to the projected box directly (the sync
@@ -2001,6 +2004,16 @@ export function createViewer(container, part, {
   // 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
@@ -2037,12 +2050,101 @@ export function createViewer(container, part, {
     }
     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]) {

package/types/index.d.ts

@@ -821,19 +821,28 @@ export interface MountPreviewOptions {
   /**
    * 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.
+   * (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. 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.
+   * 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"`. */
@@ -876,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>;