partforge 0.169.1 → 0.171.0

package/README.md

@@ -199,12 +199,14 @@ 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`
 (0.169.0+: the animation or turntable waits at its first frame until
-`handle.motion.start()`). An unknown option key
+`handle.motion.start()`), and `edgeWidth` / `edgeOpacity` (0.170.0+: the CAD
+edge lines' width in CSS pixels, default 1, and opacity, default 1 — a small
+card reads the default lines as heavy). 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.169.1",
+  "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.
@@ -81,6 +83,10 @@
 //    `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.
+//  - `edgeWidth` (0.170.0; CSS px, 0 < w <= 8, default 1) and `edgeOpacity`
+//    (0.170.0; 0 < o <= 1, default 1) — the CAD feature edge lines' thickness
+//    and strength. A small preview card reads the default 1 px lines as heavy;
+//    0.5 px is one device pixel on a 2x screen. Fixed for the mount.
 //  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
@@ -118,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
@@ -136,10 +142,16 @@ function flag(name, value, fallback) {
 const KNOWN_OPTIONS = new Set([
   "glb", "elements", "viewerState", "animate",
   "chrome", "background", "contactShadow", "zoom", "pan", "turntable", "fill", "camera", "renderMode",
-  "autostart",
+  "autostart", "edgeWidth", "edgeOpacity",
 ]);
 
-function presentation({ chrome, background, contactShadow, zoom, pan, turntable, fill, camera, renderMode, autostart }) {
+function presentation({ chrome, background, contactShadow, zoom, pan, turntable, fill, camera, renderMode, autostart, edgeWidth, edgeOpacity }) {
+  if (edgeWidth !== undefined && !(typeof edgeWidth === "number" && edgeWidth > 0 && edgeWidth <= 8)) {
+    throw new TypeError("mountPreview: edgeWidth must be a number of CSS pixels above 0 and at most 8");
+  }
+  if (edgeOpacity !== undefined && !(typeof edgeOpacity === "number" && edgeOpacity > 0 && edgeOpacity <= 1)) {
+    throw new TypeError("mountPreview: edgeOpacity must be a number above 0 and at most 1");
+  }
   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");
   }
@@ -157,6 +169,8 @@ function presentation({ chrome, background, contactShadow, zoom, pan, turntable,
     defaultCamera: oneOf("camera", camera, ["carry", "default"], "carry") === "default",
     renderMode: oneOf("renderMode", renderMode, ["cad", "realistic"], null),
     autostart: flag("autostart", autostart, true),
+    edgeWidth: edgeWidth ?? 1,
+    edgeOpacity: edgeOpacity ?? 1,
   };
 }
 
@@ -280,6 +294,9 @@ 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());
     let tooltip = null, toolbar = null, viewStyle = null;

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

@@ -176,8 +176,17 @@ export function captureCurrentFromScene(
 // vertical instead (a turntable never clips).
 // Unset keeps the fixed r·2.6 + 6 distance. mountPreview's presentation
 // options are the caller.
+// `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, framePoses = null,
 } = {}) {
   const names = Object.keys(part.parts);
   // Membership for host-supplied names. subMesh, cadMats and part.parts are
@@ -328,7 +337,9 @@ export function createViewer(container, part, {
 
   // CAD-style feature edge lines (anti-aliased "fat" lines), one per sub-part.
   const EDGE_ANGLE = 35; // deg — last-ditch threshold for payloads with no kernel edge data
-  const lineMaterial = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 }); // ~10% lighter, 1 px
+  const lineMaterial = new LineMaterial({ // ~10% lighter, 1 px by default
+    color: THEME.dark.line, linewidth: edgeWidth, transparent: edgeOpacity < 1, opacity: edgeOpacity,
+  });
   lineMaterial.resolution.set(1, 1); // real size set by resize() below
   const subLines = Object.fromEntries(
     names.map((n) => [n, new LineSegments2(new LineSegmentsGeometry(), lineMaterial)])
@@ -466,7 +477,7 @@ export function createViewer(container, part, {
       mesh.material = fm;
       const flm = fadeLineMatFor(name);
       const so = effectiveDisplayOf(name).opacity ?? 1;
-      flm.opacity = so > 0 ? fade / so : 0; // lines fade by the multiplier alone
+      flm.opacity = so > 0 ? (fade / so) * edgeOpacity : 0; // lines fade by the multiplier alone
       lines.material = flm;
     }
     mesh.visible = meshVisible;
@@ -2050,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) {
@@ -2066,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 };
   }
 
@@ -2560,7 +2615,7 @@ export function createViewer(container, part, {
             if (lines.material === fadeLineMats.get(n)) lines.material = lineMaterial;
           } else {
             const f = fadeMatFor(n); f.opacity = fade; mesh.material = f;
-            const fl = fadeLineMatFor(n); fl.opacity = staticOpacity > 0 ? fade / staticOpacity : 0; lines.material = fl;
+            const fl = fadeLineMatFor(n); fl.opacity = staticOpacity > 0 ? (fade / staticOpacity) * edgeOpacity : 0; lines.material = fl;
           }
           mesh.visible = meshVisible; lines.visible = linesVisible && meshVisible;
         },

package/types/index.d.ts

@@ -830,6 +830,13 @@ export interface MountPreviewOptions {
    * angle 0) until `motion.start()`. `drawn` resolves on a frame showing that pose.
    */
   autostart?: boolean;
+  /**
+   * 0.170.0+: the CAD feature edge lines' width in CSS pixels, 0 < w <= 8 (default 1).
+   * A small preview card reads the default as heavy; 0.5 is one device pixel at 2x.
+   */
+  edgeWidth?: number;
+  /** 0.170.0+: the CAD feature edge lines' opacity, 0 < o <= 1 (default 1). */
+  edgeOpacity?: number;
   /**
    * 0 < fill <= 1 (0.168.0+): the opening framing (and the viewer's reframe) puts the
    * camera, along the opening view direction, so the model's bounding box as projected
@@ -839,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.
    */