partforge 0.170.0 → 0.171.0

package/README.md

@@ -199,7 +199,7 @@ 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
+turns about its hub; a model that is not turning has its on-screen outline centred, since 0.169.0, and a playing animation is framed over every pose it passes through, since 0.171.0, so a part that swings out never leaves the frame), `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`

package/package.json

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

@@ -59,11 +59,13 @@
 //    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.
+//    not turning (a still, or a playing animation) 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 playing animation is fitted over EVERY pose it passes
+//    through (0.171.0; each part's outermost points at each keyframe), so a
+//    part that swings out of its first pose's outline stays in frame — the
+//    outline of all its poses together spans `fill`.
 //    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.
@@ -122,7 +124,7 @@ import { observeViewbarClear } from "./viewbar-clear.js";
 import { createTooltipPresenter } from "./tooltip.js";
 import { isFaceAlignedState } from "./projection.js";
 import { ENVIRONMENTS } from "./materials/environments.js";
-import { createPreviewPlayer } from "./preview-player.js";
+import { createPreviewPlayer, animationPoses } 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
@@ -292,6 +294,8 @@ export function mountPreview(container, options = {}) {
       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,
+      // An animation is framed over every pose it passes through (0.171.0).
+      framePoses: plays ? animationPoses(decoded.animation) : null,
       edgeWidth: opts.edgeWidth, edgeOpacity: opts.edgeOpacity,
     });
     cleanups.push(() => viewer.dispose());

package/src/framework/preview-player.js

@@ -95,6 +95,30 @@ export function sampleOpacity(keys, t) {
   return keys[keys.length - 1][1];
 }
 
+// The poses an animation passes through, for framing it whole: one
+// { name → pose } map per sampled time, each pose the matrix `apply` would hand
+// setSubPose (keyframed transform with the rest taken out). The times are every
+// keyframe of every track and the midpoint of each gap between them (a rotation
+// can bulge past both its keyframes on the way), thinned evenly to at most
+// `max`, with t = 0 and the end always kept. A baked file samples densely, so
+// that is close to every frame it draws. Untracked sub-parts are left out of
+// every map (they sit at rest).
+export function animationPoses(animation, { max = 128 } = {}) {
+  const { tracks = {}, rest = {} } = animation ?? {};
+  const names = Object.keys(tracks);
+  if (!names.length) return [];
+  const restInverse = Object.fromEntries(names.map((name) => [name, invertRigid(rest[name])]));
+  const all = new Set([0]);
+  for (const name of names) for (const t of tracks[name].times) if (Number.isFinite(t)) all.add(t);
+  const keys = [...all].sort((x, y) => x - y);
+  let times = keys.flatMap((t, i) => (i === 0 ? [t] : [(keys[i - 1] + t) / 2, t]));
+  if (times.length > max) {
+    const step = (times.length - 1) / (max - 1);
+    times = Array.from({ length: max }, (_, i) => times[Math.round(i * step)]);
+  }
+  return times.map((seconds) => Object.fromEntries(names.map((name) => [name, mulMat4(sampleTrack(tracks[name], seconds), restInverse[name])])));
+}
+
 export function createPreviewPlayer(viewer, animation, { reducedMotion = false } = {}) {
   const { duration, tracks, rest, opacity = {} } = animation;
   const steps = animation.steps ?? [];

package/src/framework/viewer.js

@@ -179,9 +179,14 @@ export function captureCurrentFromScene(
 // `edgeWidth` (CSS px, default 1) and `edgeOpacity` (0 < o <= 1, default 1)
 // style the CAD feature edge lines; a small preview reads them as heavy at the
 // default. Fades multiply into the opacity rather than replacing it.
+// `framePoses` (with `frameFill`, not `frameSwept`) is a list of
+// { sub-part name → pose matrix } maps — the poses an animation passes through
+// (preview-player's animationPoses) — and the fill framing then fits the model
+// in every one of them as well as as shown, so a part that swings out of its
+// first pose's outline stays in frame.
 export function createViewer(container, part, {
   transparent = false, contactShadow = false, zoom = true, pan = true, frameFill = null, frameSwept = false,
-  edgeWidth = 1, edgeOpacity = 1,
+  edgeWidth = 1, edgeOpacity = 1, framePoses = null,
 } = {}) {
   const names = Object.keys(part.parts);
   // Membership for host-supplied names. subMesh, cadMats and part.parts are
@@ -2056,11 +2061,54 @@ export function createViewer(container, part, {
     }
     if (n > 0) center.set(sx / n, sy / n, center.z);
   }
+  // A sub-part's outermost vertices along SUPPORT_DIRECTIONS (deduplicated, in
+  // its delivered frame): the points that decide its outline from any angle, to
+  // within a sliver. Framing the extra `framePoses` reads these, not every
+  // vertex, so a long animation of a dense model frames in a few milliseconds.
+  const SUPPORT_DIRECTIONS = (() => {
+    const out = [], n = 64, golden = Math.PI * (3 - Math.sqrt(5));
+    for (let i = 0; i < n; i++) {
+      const y = 1 - (2 * (i + 0.5)) / n, r = Math.sqrt(1 - y * y), a = golden * i;
+      out.push([r * Math.cos(a), y, r * Math.sin(a)]);
+    }
+    return out;
+  })();
+  const supportCache = new WeakMap();
+  function supportPoints(geometry) {
+    let points = supportCache.get(geometry);
+    if (points) return points;
+    const pos = geometry.getAttribute("position");
+    const best = SUPPORT_DIRECTIONS.map(() => -Infinity), at = SUPPORT_DIRECTIONS.map(() => -1);
+    for (let i = 0; i < (pos?.count ?? 0); i++) {
+      _sweepV.fromBufferAttribute(pos, i);
+      for (let k = 0; k < SUPPORT_DIRECTIONS.length; k++) {
+        const [dx, dy, dz] = SUPPORT_DIRECTIONS[k];
+        const d = _sweepV.x * dx + _sweepV.y * dy + _sweepV.z * dz;
+        if (d > best[k]) { best[k] = d; at[k] = i; }
+      }
+    }
+    points = [...new Set(at.filter((i) => i >= 0))].map((i) => new THREE.Vector3().fromBufferAttribute(pos, i));
+    supportCache.set(geometry, points);
+    return points;
+  }
+  const _framePose = new THREE.Matrix4();
   // Every posed vertex of `names` about `center`, stood up by the pivot, as
-  // flat x/y/z arrays (world units, pivot-relative).
+  // flat x/y/z arrays (world units, pivot-relative) — plus, with `framePoses`,
+  // each sub-part's support points in every one of those poses.
   function posedVertices(names, center) {
     let n = 0;
     for (const name of names) n += subCache[name]?.getAttribute("position")?.count ?? 0;
+    const extra = [];
+    for (const poses of framePoses ?? []) {
+      for (const name of names) {
+        if (!subCache[name]) continue;
+        const pose = poses[name] ? _framePose.fromArray(poses[name]) : subMesh[name].matrix;
+        for (const p of supportPoints(subCache[name])) {
+          extra.push(p.clone().applyMatrix4(pose).sub(center).applyQuaternion(pivot.quaternion));
+        }
+      }
+    }
+    n += extra.length;
     const px = new Float64Array(n), py = new Float64Array(n), pz = new Float64Array(n);
     let k = 0;
     for (const name of names) {
@@ -2072,6 +2120,7 @@ export function createViewer(container, part, {
         px[k] = _sweepV.x; py[k] = _sweepV.y; pz[k] = _sweepV.z;
       }
     }
+    for (const p of extra) { px[k] = p.x; py[k] = p.y; pz[k] = p.z; k++; }
     return { px, py, pz, n };
   }
 

package/types/index.d.ts

@@ -846,8 +846,9 @@ export interface MountPreviewOptions {
    * 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
+   * screen plane), spanning `fill`; a playing baked animation (0.171.0+) is fitted over
+   * every pose it passes through, so a part that swings out of its first pose's outline
+   * stays in frame and all its poses together span `fill`. 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.
    */