partforge 0.156.0 → 0.158.0

package/src/framework/gltf/encode-preview.js

@@ -33,7 +33,37 @@
 //  - each material from cadAppearance — the CAD look the viewer itself draws —
 //    and each node's extras carrying the sub-part's own `display` block, so a
 //    part-less viewer (mountPreview) can rebuild the exact look, realistic too
-//  - top-level extras { partforgeView, partforgeEncoder, partforgeMeta? }
+//  - top-level extras { partforgeView, partforgeEncoder, partforgeMeta?,
+//    partforgeAnimation? }
+//  - an `animation` (samplePreviewAnimation's output, version 4) adds:
+//      * every sampled sub-part node's rest TRS = rel(0), where
+//        rel(t) = M(t) · base⁻¹ carries the mesh from the pose baked into its
+//        positions to the pose at normalized time t. TRS is in the root's local
+//        frame, which is the part's Z-up model frame, so no frame change.
+//      * one glTF animation named anim.name, holding a LINEAR `translation` and
+//        `rotation` channel (input in SECONDS, t · totalDuration) for each
+//        sub-part whose rel(t) differs from rel(0) beyond 1e-6 — none at all
+//        when nothing moves (a camera-only animation). Consecutive quaternions
+//        share a hemisphere, so LINEAR blending never takes the long way round.
+//        An animated node's mesh sits on a child node (quantize() moves it
+//        there to keep the dequantization off the animated TRS); the writer
+//        gives that child the sub-part's name and the SAME extras as the
+//        animated node, so a reader that looks only one level up from a mesh
+//        (≤ 0.157) still names, styles and edges it, at the opening pose.
+//      * partforgeAnimation = { name, label, loop, duration (seconds), cues
+//        (verbatim), steps: [{ label, start (normalized), duration (seconds) }],
+//        animated (names with channels, mesh order), opacity: { <sub>: [[t, v],
+//        …] } } — t normalized, one pair per sample that names the sub-part (a
+//        sample that omits it contributes no pair; a reader interpolates).
+//    The samples are refused unless every pose is rigid (RᵀR = I, det = +1,
+//    within 1e-6 — geometry/pose.js's isRigid, which the sampler applies too),
+//    they run from t = 0 to t = 1, every sample poses the same sub-parts, and
+//    each of those (and each `base` entry) is one of `meshes`. A sampled
+//    sub-part whose mesh is present but EMPTY (its build() returned nothing) is
+//    dropped from the animation — it has no node — and the rest still plays.
+//    The channels are stored LOSSLESSLY: EXT_meshopt_compression's QUANTIZE
+//    method applies no meshopt filter (gltf-transform filters only under its
+//    FILTER method), so the float32 keyframes are byte-compressed, not rounded.
 //  - weld() → reorder() → quantize() → EXT_meshopt_compression ("medium",
 //    i.e. what meshopt({ level: "medium" }) does), 5–8 bytes a triangle, the
 //    recipe measured in partforge-cloud's local_glb_benchmark.md. The line
@@ -55,8 +85,11 @@ import { EXTMeshoptCompression, KHRMeshQuantization } from "@gltf-transform/exte
 import { quantize, reorder, weld } from "@gltf-transform/functions";
 import { MeshoptEncoder } from "meshoptimizer/encoder";
 import { cadAppearance, DISPLAY_KEYS } from "../materials/resolve.js";
+import { invertRigid, isRigid, mulMat4 } from "../geometry/pose.js";
 
-export const PREVIEW_ENCODER_VERSION = 3; // 2: feature edges as a LINES primitive; 3: sharing the surface's vertices
+// 2: feature edges as a LINES primitive; 3: sharing the surface's vertices;
+// 4: animation channels + partforgeAnimation extras
+export const PREVIEW_ENCODER_VERSION = 4;
 
 // −90° about X as [x, y, z, w]: model (x, y, z) → glTF (x, z, −y), the viewer's pivot.
 const Z_UP_TO_Y_UP = [-Math.SQRT1_2, 0, 0, Math.SQRT1_2];
@@ -278,10 +311,142 @@ function checkMesh(m, seen) {
   }
 }
 
-export async function encodePreviewGlb({ meshes, part = null, view = null } = {}) {
+// ── The baked animation (version 4) ─────────────────────────────────────────
+
+const MOVES_TOL = 1e-6;
+
+// Refuse what the file could not carry faithfully; returns the sampled names
+// that are drawn, in mesh order. `drawn` is the set of names with a non-empty
+// mesh. A name with NO mesh entry is refused (fail closed: the sampler and the
+// meshes disagree about the view); a name whose mesh is present but EMPTY (a
+// sub-part whose build() returned nothing) is dropped — it has no node to
+// animate, and the rest of the file still plays.
+function checkAnimation(animation, meshes, drawn) {
+  const { anim, samples, base } = animation;
+  if (!anim || typeof anim !== "object" || typeof anim.name !== "string") throw new TypeError("encodePreviewGlb: animation.anim must be a normalized animation");
+  if (!(Number.isFinite(anim.totalDuration) && anim.totalDuration > 0)) throw new Error("encodePreviewGlb: animation duration must be a positive number");
+  if (!base || typeof base !== "object") throw new TypeError("encodePreviewGlb: animation.base must map sub-parts to matrices");
+  if (!Array.isArray(samples) || samples.length < 2) throw new Error("encodePreviewGlb: animation samples must run from t = 0 to t = 1");
+  if (samples[0].t !== 0) throw new Error("encodePreviewGlb: animation samples must start at t = 0");
+  if (samples.at(-1).t !== 1) throw new Error("encodePreviewGlb: animation samples must end at t = 1");
+  for (let i = 1; i < samples.length; i++) {
+    if (!(samples[i].t > samples[i - 1].t)) throw new Error("encodePreviewGlb: animation sample times must increase");
+  }
+  const present = new Set(meshes.map((m) => m.name));
+  const sampled = new Set();
+  for (const s of samples) for (const name of Object.keys(s.poses ?? {})) sampled.add(name);
+  for (const name of [...sampled, ...Object.keys(base)]) {
+    if (!present.has(name)) throw new Error(`encodePreviewGlb: animation names "${name}", which has no mesh`);
+  }
+  const names = [...sampled].filter((name) => drawn.has(name));
+  for (const name of names) {
+    if (!isRigid(base[name])) {
+      if (base[name] == null) throw new Error(`encodePreviewGlb: animation has no base pose for "${name}"`);
+      throw new Error(`encodePreviewGlb: "${name}" base pose is not a rigid motion`);
+    }
+    for (const s of samples) {
+      const m = s.poses?.[name];
+      if (m == null) throw new Error(`encodePreviewGlb: animation sample at t=${s.t} has no pose for "${name}"`);
+      if (!isRigid(m)) throw new Error(`encodePreviewGlb: "${name}" pose at t=${s.t} is not a rigid motion`);
+    }
+  }
+  return meshes.map((m) => m.name).filter((name) => names.includes(name)); // names are unique (checkMesh)
+}
+
+// rel = M · base⁻¹: the motion from the baked pose to M.
+const relativePose = (m, base) => mulMat4(Array.from(m), invertRigid(Array.from(base)));
+
+// Unit quaternion [x, y, z, w] of a rigid matrix's rotation block (Shepperd).
+function quaternionOf(m) {
+  const at = (r, c) => m[c * 4 + r];
+  const trace = at(0, 0) + at(1, 1) + at(2, 2);
+  let q;
+  if (trace > 0) {
+    const s = Math.sqrt(trace + 1) * 2;
+    q = [(at(2, 1) - at(1, 2)) / s, (at(0, 2) - at(2, 0)) / s, (at(1, 0) - at(0, 1)) / s, s / 4];
+  } else if (at(0, 0) > at(1, 1) && at(0, 0) > at(2, 2)) {
+    const s = Math.sqrt(1 + at(0, 0) - at(1, 1) - at(2, 2)) * 2;
+    q = [s / 4, (at(0, 1) + at(1, 0)) / s, (at(0, 2) + at(2, 0)) / s, (at(2, 1) - at(1, 2)) / s];
+  } else if (at(1, 1) > at(2, 2)) {
+    const s = Math.sqrt(1 + at(1, 1) - at(0, 0) - at(2, 2)) * 2;
+    q = [(at(0, 1) + at(1, 0)) / s, s / 4, (at(1, 2) + at(2, 1)) / s, (at(0, 2) - at(2, 0)) / s];
+  } else {
+    const s = Math.sqrt(1 + at(2, 2) - at(0, 0) - at(1, 1)) * 2;
+    q = [(at(0, 2) + at(2, 0)) / s, (at(1, 2) + at(2, 1)) / s, s / 4, (at(1, 0) - at(0, 1)) / s];
+  }
+  const len = Math.hypot(...q);
+  return q.map((v) => v / len);
+}
+
+// Per sampled sub-part: the rest TRS (rel(0)) and, when it moves, the keyframes.
+function animationTracks(animation, names) {
+  const { samples, base } = animation;
+  const tracks = new Map();
+  for (const name of names) {
+    const rels = samples.map((s) => relativePose(s.poses[name], base[name]));
+    const moves = rels.some((r) => r.some((v, i) => Math.abs(v - rels[0][i]) > MOVES_TOL));
+    const rotations = [];
+    for (const r of rels) {
+      const q = quaternionOf(r);
+      const prev = rotations.at(-1);
+      if (prev && q[0] * prev[0] + q[1] * prev[1] + q[2] * prev[2] + q[3] * prev[3] < 0) for (let k = 0; k < 4; k++) q[k] = -q[k];
+      rotations.push(q);
+    }
+    tracks.set(name, {
+      rest: { translation: [rels[0][12], rels[0][13], rels[0][14]], rotation: rotations[0] },
+      keys: moves ? { translations: rels.map((r) => [r[12], r[13], r[14]]), rotations } : null,
+    });
+  }
+  return tracks;
+}
+
+// The glTF animation: one sampler pair per moving sub-part, sharing one input.
+// Returns the names that got channels.
+function writeAnimation(doc, buffer, nodesByName, animation, tracks) {
+  const moving = [...tracks].filter(([, track]) => track.keys);
+  if (!moving.length) return [];
+  const { anim, samples } = animation;
+  const times = doc.createAccessor().setType("SCALAR")
+    .setArray(Float32Array.from(samples, (s) => s.t * anim.totalDuration)).setBuffer(buffer);
+  const gltfAnimation = doc.createAnimation(anim.name);
+  for (const [name, { keys }] of moving) {
+    for (const [path, type, values] of [["translation", "VEC3", keys.translations], ["rotation", "VEC4", keys.rotations]]) {
+      const sampler = doc.createAnimationSampler().setInput(times).setInterpolation("LINEAR")
+        .setOutput(doc.createAccessor().setType(type).setArray(Float32Array.from(values.flat())).setBuffer(buffer));
+      gltfAnimation.addSampler(sampler).addChannel(doc.createAnimationChannel()
+        .setTargetNode(nodesByName.get(name)).setTargetPath(path).setSampler(sampler));
+    }
+  }
+  return moving.map(([name]) => name);
+}
+
+// The partforgeAnimation extra: everything a viewer needs beyond the channels.
+function animationExtras(animation, animated, drawn) {
+  const { anim, samples } = animation;
+  const opacity = {};
+  for (const s of samples) {
+    for (const [name, v] of Object.entries(s.opacity ?? {})) {
+      if (drawn.has(name) && Number.isFinite(v)) (opacity[name] ??= []).push([s.t, v]);
+    }
+  }
+  return {
+    name: anim.name,
+    label: anim.label ?? null,
+    loop: !!anim.loop,
+    duration: anim.totalDuration,
+    cues: anim.cues ?? [],
+    opacity,
+    steps: (anim.steps ?? []).map((step, i) => ({ label: step.label ?? null, start: anim.stepStarts[i], duration: step.duration })),
+    animated,
+  };
+}
+
+export async function encodePreviewGlb({ meshes, part = null, view = null, animation = null } = {}) {
   if (!Array.isArray(meshes) || meshes.length === 0) throw new TypeError("encodePreviewGlb: meshes must be a non-empty array");
   const seen = new Set();
   for (const m of meshes) checkMesh(m, seen);
+  const drawn = new Set(meshes.filter((m) => m.positions.length > 0).map((m) => m.name));
+  const tracks = animation ? animationTracks(animation, checkAnimation(animation, meshes, drawn)) : null;
   try {
     await (encoderReady ??= MeshoptEncoder.ready);
   } catch (error) {
@@ -297,13 +462,9 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
   const root = doc.createNode("partforge").setRotation(Z_UP_TO_Y_UP);
   scene.addChild(root);
   const meta = metaExtras(part?.meta);
-  doc.getRoot().setExtras({
-    partforgeView: viewName,
-    partforgeEncoder: PREVIEW_ENCODER_VERSION,
-    ...(meta ? { partforgeMeta: meta } : {}),
-  });
 
   const pending = []; // { mesh, surface, edges } — line primitives to add after quantize()
+  const nodesByName = new Map();
   for (const m of meshes) {
     if (m.positions.length === 0) continue; // glTF forbids a zero-count accessor
     // Copies throughout: setArray keeps the array it is handed, and the
@@ -326,11 +487,23 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
     const mesh = doc.createMesh(m.name).addPrimitive(prim);
     if (m.edges?.length) pending.push({ mesh, surface: prim, edges: Float32Array.from(m.edges) });
     const extras = displayExtras(display);
-    root.addChild(doc.createNode(m.name)
+    const node = doc.createNode(m.name)
       .setMesh(mesh)
-      .setExtras(extras ? { partforgeSubPart: m.name, partforgeDisplay: extras } : { partforgeSubPart: m.name }));
+      .setExtras(extras ? { partforgeSubPart: m.name, partforgeDisplay: extras } : { partforgeSubPart: m.name });
+    const rest = tracks?.get(m.name)?.rest;
+    if (rest) node.setTranslation(rest.translation).setRotation(rest.rotation); // before the fallback's `before` snapshot
+    nodesByName.set(m.name, node);
+    root.addChild(node);
   }
   if (root.listChildren().length === 0) throw new Error("encodePreviewGlb: every mesh was empty");
+  // Channels before quantize(), which then keeps the dequantization off the animated nodes.
+  const animated = tracks ? writeAnimation(doc, buffer, nodesByName, animation, tracks) : null;
+  doc.getRoot().setExtras({
+    partforgeView: viewName,
+    partforgeEncoder: PREVIEW_ENCODER_VERSION,
+    ...(meta ? { partforgeMeta: meta } : {}),
+    ...(tracks ? { partforgeAnimation: animationExtras(animation, animated, drawn) } : {}),
+  });
 
   // The surfaces alone through weld + reorder: their vertex arrays are final after this.
   await doc.transform(weld(), reorder({ encoder: MeshoptEncoder, target: "size" }));
@@ -371,6 +544,19 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
 
   await doc.transform(quantize());
 
+  // quantize() moves an animated node's mesh onto a new, unnamed child (the
+  // dequantization must not ride the animated TRS). Name that child and give it
+  // the SAME extras as the sub-part node: a reader that looks only at the
+  // mesh's own node or its immediate parent (partforge ≤ 0.157's decoder) then
+  // still finds the sub-part's name, look and edges; the current decoder's
+  // ancestor walk finds identical values one level sooner.
+  for (const [name, node] of nodesByName) {
+    if (node.getMesh()) continue;
+    for (const child of node.listChildren()) {
+      if (child.getMesh()) child.setName(name).setExtras({ ...node.getExtras() });
+    }
+  }
+
   // The fallback lines: float positions mapped into the frame quantize() left the
   // mesh in. quantize() folds the mesh's offset and scale into the node holding it
   // (or a new child node), so a vertex q now draws at after·q where it drew p at

package/src/framework/mount-preview.js

@@ -11,7 +11,19 @@
 // sub-part's display only — no sheet stock, no layer-line print frames (a
 // residual of the format). CAD feature edges come from the file (encoder
 // version 2, sharing the surface's vertices since version 3); a version-1 file
-// decodes with none. The decoder loads on demand (it carries the
+// decodes with none.
+//
+// A file that carries a baked autoplay animation (encoder version 4) plays it
+// once drawn, through preview-player.js — poses, opacities and camera cues off
+// the viewer's own frame loop, still with no part code. `animate: false` shows
+// the opening pose and no player (the editor's own boot preview goes through
+// mount(), not here). Under prefers-reduced-motion the player never starts: the
+// file's opening pose, every sub-part opaque, nothing moves. Parking
+// (setActive(false)) stops the viewer's frame loop, and the player's clock with
+// it, so a parked preview is a paused one. `handle.animation` is null once
+// disposed.
+//
+// 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.
 import "./app.css";
@@ -23,6 +35,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";
 
 function previewPart({ meshes, view, meta }) {
   return {
@@ -44,12 +57,13 @@ const relay = (listeners) => (event) => {
   }
 };
 
-export function mountPreview(container, { glb, elements = {}, viewerState = null } = {}) {
+export function mountPreview(container, { glb, elements = {}, viewerState = null, animate = true } = {}) {
   if (!container) throw new TypeError("mountPreview: a container element is required");
   let disposed = false;
   let active = true;
   let carried = viewerState ?? null; // applied once the viewer exists, and on every setViewerState
   let live = null;                   // { viewer, view } once the GLB has decoded
+  let player = null;                 // the baked animation's player, once drawn
   const cleanups = [];
   const modeListeners = new Set();
   const envListeners = new Set();
@@ -92,6 +106,13 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
     live = { viewer, view };
     applyState(carried);
     if (!active) viewer.setActive(false);
+    if (decoded.animation && animate !== false) {
+      const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+      player = createPreviewPlayer(viewer, decoded.animation, { reducedMotion });
+      const own = player;
+      cleanups.push(() => own.dispose());
+      player.start();
+    }
   });
   ready.catch(() => {}); // the host awaits it; never an unhandled rejection
 
@@ -119,6 +140,7 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
       if (disposed) return;
       disposed = true;
       live = null;
+      player = null; // `animation` answers null once disposed (the cleanup below disposes it)
       const errors = [];
       while (cleanups.length) {
         try { cleanups.pop()(); } catch (error) { errors.push(error); }
@@ -127,6 +149,10 @@ export function mountPreview(container, { glb, elements = {}, viewerState = null
       if (errors.length > 1) throw new AggregateError(errors, "partforge mountPreview cleanup failed");
     },
     getView: () => live?.view ?? null,
+    // null before ready, for a still file, with animate: false, and once disposed.
+    get animation() {
+      return player ? { state: player.state, pause: player.pause, resume: player.resume } : null;
+    },
     getViewerState,
     setViewerState(next) {
       carried = next ?? null;

package/src/framework/mount.js

@@ -43,6 +43,7 @@ import { attachAnnotateControls } from "./annotate/annotate-controls.js";
 import { attachSketchToolbar } from "./annotate/sketch-toolbar.js";
 import { attachViewcubeControls } from "./viewcube/viewcube-controls.js";
 import { createPreviewGate } from "./preview-gate.js";
+import { samplePreviewAnimation } from "./preview-animation.js";
 import { observeViewbarClear } from "./viewbar-clear.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
@@ -281,8 +282,11 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.147.0: a cached `preview` GLB is drawn before the kernel
-// boots and swapped in place by the first build; 0.141.0: a place()-able sub-part
+// Embedding contract (0.158.0: a preview GLB may carry its view's autoplay
+// animation — mount({ preview }) draws its opening pose and does not play it,
+// mountPreview plays it unless `animate: false`, and exportPreview bakes it only
+// when every track is place-only; 0.147.0: a cached `preview` GLB is drawn before
+// the kernel boots and swapped in place by the first build; 0.141.0: a place()-able sub-part
 // is delivered in its canonical frame and posed by the viewer; pose-only edits
 // never rebuild):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload, onViewChange });
@@ -404,7 +408,9 @@ function createCleanupStack() {
 //                          // measure, sketch and cutaway wait; orbit, the view cube,
 //                          // the view style and the rail work
 //   await runtime.exportPreview();  // the view on screen as a preview GLB (Uint8Array,
-//                          // partforge/gltf), fast-path poses baked in. Rejects while
+//                          // partforge/gltf), fast-path poses baked in, plus the
+//                          // view's autoplay animation when every track is
+//                          // place-only. Rejects while
 //                          // previewActive, before the view is fully built (a pending
 //                          // rebuild counts), for a view other than the one on screen,
 //                          // and after dispose
@@ -443,7 +449,10 @@ function createCleanupStack() {
 //                                         // the first live build, camera kept. Only a file for the view
 //                                         // on screen is drawn, and only its sub-parts of that view; a
 //                                         // file for another view, or one that will not decode, is
-//                                         // logged once and ignored.
+//                                         // logged once and ignored. A file that carries the view's
+//                                         // baked autoplay animation (encoder version 4) is drawn
+//                                         // in its opening pose and never played here (playing it is
+//                                         // mountPreview's); the first live build replaces it.
 // panelState: PanelState                 // a previous mount's runtime.getPanelState(): the transient
 //                                         // state of the part's custom controls (a selected tile), keyed
 //                                         // by param. Same remount story as viewerState; omit on a first
@@ -1718,7 +1727,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // buildView returns. Only the view on screen (no other view's meshes are held),
     // only when it is fully built at the live params (missingParts covers both a
     // first build and an edit still rebuilding), never a cached preview. The
-    // encoder loads on first use: a host that never exports never pays for it.
+    // view's autoplay animation rides along as channels when every track is
+    // place-only (samplePreviewAnimation decides; otherwise the file is still).
+    // The encoder loads on first use: a host that never exports never pays for it.
     async function exportPreview({ view: wanted } = {}) {
       if (disposed) throw new Error("exportPreview: this mount is disposed");
       if (previewGate.isActive()) throw new Error("exportPreview: a cached preview is showing — wait for the first build");
@@ -1731,8 +1742,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         throw new Error("exportPreview: the view on screen is not fully built");
       }
       const meshes = needed.map((name) => viewer.getSubMeshPayload(name)).filter(Boolean);
+      // The view's autoplay animation, sampled at the params the meshes above were
+      // built at. Build reads come from the cache's stamps; null (no stamp, or an
+      // every-param stamp) is unknown, so the animation is left out.
+      const animation = samplePreviewAnimation(part, current, params, {
+        buildReads: (name) => (cache.hasStamp(name) ? cache.readsOf(name) : null),
+      });
       const { encodePreviewGlb } = await import("./gltf/encode-preview.js");
-      return encodePreviewGlb({ meshes, part, view: current });
+      return encodePreviewGlb({ meshes, part, view: current, ...(animation ? { animation } : {}) });
     }
 
     return makeHandle({

package/src/framework/oracle/build.js

@@ -1,12 +1,22 @@
-import { viewSubParts, resolveParams, buildPosed } from "../part-model.js";
+import { viewSubParts, resolveParams, resolveParamsAttributed, recordedParams, buildPosed } from "../part-model.js";
+import { newReadSink, expandReads } from "../read-recorder.js";
+import { placeOf } from "../sub-part-views.js";
 
 // Build every sub-part of a view in its display (assembly) pose with the given
 // Manifold kernel, returning live solids + copied-out meshes. Mirrors the
 // `generate` path in jobs.js, but keeps solids LIVE (does NOT call
 // kernel.cleanup()) so callers can read exact solid facts (volume/genus/empty)
 // before they free the kernel. Meshes are JS-owned arrays and survive cleanup.
-export function buildView(kernel, part, view, params = {}, { reads } = {}) {
+//
+// `reads` (a read sink) records every param the whole view read, build AND place.
+// `readsBySubPart` (a Map) is filled with name → the expanded params that
+// sub-part's build() read, place() reads EXCLUDED — the same split jobs.js's
+// displayWithReads makes: build runs on per-sub-part recorded p/d, place on the
+// view's own p/d (never the sub-part's recorder), so a pose-only param (a lid
+// angle read only in place()) never looks like a rebuild.
+export function buildView(kernel, part, view, params = {}, { reads, readsBySubPart } = {}) {
   const { p, d } = resolveParams(part, params, undefined, reads);
+  const attribution = readsBySubPart ? resolveParamsAttributed(part, params).attribution : undefined;
   // Cache round for the whole view. The name is the ORACLE's, deliberately not the
   // display sub-part names the generate path brackets under: a distinct partition
   // still reuses those solids (the cache indexes entries by content hash across
@@ -18,8 +28,25 @@ export function buildView(kernel, part, view, params = {}, { reads } = {}) {
   kernel.beginSubPart?.(`oracle:view:${view}`);
   try {
     return viewSubParts(part, view, p).map((name) => {
-      const solid = buildPosed(kernel, part, name, { purpose: "display", view, p, d });
+      const solid = readsBySubPart
+        ? buildRecorded(kernel, part, name, view, p, d, attribution, readsBySubPart)
+        : buildPosed(kernel, part, name, { purpose: "display", view, p, d });
       return { name, solid, mesh: solid.toMesh() };
     });
   } finally { kernel.endSubPart?.(); }
 }
+
+// buildPosed split in two: build() on recorded p/d (a fresh sink per sub-part),
+// place() on the p/d the view resolved — so place reads land only in the
+// view-level `reads` sink, never in the sub-part's.
+function buildRecorded(kernel, part, name, view, p, d, attribution, readsBySubPart) {
+  const sp = part.parts[name];
+  const sink = newReadSink();
+  sink.attribution = attribution;
+  const rec = recordedParams({ p, d }, sink);
+  const built = sp.build(kernel, rec.p, rec.d);
+  const place = placeOf(sp);
+  const solid = place ? place(built, { view, purpose: "display", p, d }) : built;
+  readsBySubPart.set(name, expandReads(sink));
+  return solid;
+}

package/src/framework/preview-animation.js

@@ -0,0 +1,128 @@
+// Bakeability + sampling for the preview GLB's animation. The cached
+// preview stores one view's meshes posed at the default params; this module
+// decides whether that view's AUTOPLAY animation can be carried in the same file
+// faithfully, and if so samples the place() matrices along its timeline. Turning
+// the samples into glTF channels is the encoder's job, not this module's.
+//
+// Rulings:
+//   - Bakeable means EVERY tracked param is place-only for every shown sub-part:
+//     the build reads none of them (`buildReads`, supplied by the caller, which
+//     already holds the mesh cache's read sets), and at every sample the place
+//     probe is trusted with a CANONICAL base hash — a rigid matrix over the mesh
+//     the file already holds. A reshaping place() (scale/mirror/union) is not a
+//     rigid motion, so a matrix track could not reproduce it.
+//   - The shown sub-part set must not change along the timeline: a mesh that
+//     comes and goes with a tracked param (`enabled`) is not in the file to show.
+//     Opacity fades are display-only and ride the samples beside the poses.
+//   - Fail CLOSED: unknown build reads (null), any failed check and any throw
+//     return null — the preview then simply has no animation. Never throws.
+//   - The output always passes the encoder's own refusals (checkAnimation in
+//     gltf/encode-preview.js): a finite, positive duration (and finite step
+//     durations and starts), finite sample times, and every pose rigid by the
+//     same isRigid test. Anything else is
+//     null here, so an odd animation costs the preview its motion, never the
+//     whole file (an encoder throw would leave the forge with no preview).
+//   - Sample times are normalized t in [0, 1]: both ends, every step boundary,
+//     every track and opacity keyframe mapped to global t, plus a
+//     PREVIEW_SAMPLE_HZ grid over the real duration. Over PREVIEW_SAMPLE_CAP the
+//     GRID thins; keyframe and boundary times are never dropped, since they are
+//     where the motion turns.
+//
+// Imports only the pure framework leaves below, so the partforge/oracle entry's
+// closure stays DOM-, three- and node:-free (test/oracle-entry.test.js).
+import { viewAnimations, evaluate } from "./animation.js";
+import { probePoses } from "./pose-probe.js";
+import { CANONICAL } from "./pose-probe-core.js";
+import { viewSubParts } from "./part-model.js";
+import { composePose, isRigid } from "./geometry/pose.js";
+
+export const PREVIEW_SAMPLE_HZ = 30;
+export const PREVIEW_SAMPLE_CAP = 600;
+
+const EPS = 1e-9;
+
+// Sorted, deduped normalized sample times for one animation.
+function sampleTimes(anim) {
+  const fixed = [0, 1, ...anim.stepStarts];
+  anim.steps.forEach((step, i) => {
+    const start = anim.stepStarts[i], span = step.duration / anim.totalDuration;
+    for (const field of ["tracks", "opacity"]) {
+      for (const kf of Object.values(step[field] ?? {})) {
+        if (!Array.isArray(kf)) continue;
+        for (const frame of kf) {
+          const u = Array.isArray(frame) ? Number(frame[0]) : NaN;
+          if (Number.isFinite(u)) fixed.push(Math.min(1, Math.max(0, start + u * span)));
+        }
+      }
+    }
+  });
+  const keep = dedupe(fixed);
+  // Interior grid points j/n, 0 < j < n; thinned so the total fits the cap.
+  let n = Math.round(anim.totalDuration * PREVIEW_SAMPLE_HZ);
+  n = Math.max(1, Math.min(n, PREVIEW_SAMPLE_CAP - keep.length + 1));
+  const grid = [];
+  for (let j = 1; j < n; j++) grid.push(j / n);
+  return dedupe([...keep, ...grid]);
+}
+
+function dedupe(times) {
+  const out = [];
+  for (const t of [...times].sort((a, b) => a - b)) if (!out.length || t - out.at(-1) > EPS) out.push(t);
+  // Both ends stay exact: a near-duplicate must not displace 0 or 1.
+  out[0] = 0;
+  out[out.length - 1] = 1;
+  return out;
+}
+
+// Place matrices for every shown sub-part, or null if any is not place-only.
+function placePoses(part, view, p, shown) {
+  const probes = probePoses(part, view, p, { scope: "place" });
+  const poses = {};
+  for (const name of shown) {
+    const entry = probes.get(name);
+    if (!entry?.trusted || entry.baseHash !== CANONICAL) return null;
+    const m = Array.from(composePose(entry.pose));
+    if (!isRigid(m)) return null; // e.g. a rotate about a zero-length axis
+    poses[name] = m;
+  }
+  return poses;
+}
+
+const sameSet = (a, b) => a.length === b.length && a.every((name) => b.includes(name));
+
+export function samplePreviewAnimation(part, view, params = {}, { buildReads } = {}) {
+  try {
+    const anim = viewAnimations(part).get(view)?.find((a) => a.autoplay) ?? null;
+    if (!anim || typeof buildReads !== "function") return null;
+    if (!(Number.isFinite(anim.totalDuration) && anim.totalDuration > 0)) return null;
+    // A NaN step duration normalizes to a total of 1 (animation.js's `|| 1`),
+    // so the steps are checked too: the file's step list must be real numbers.
+    if (!anim.steps.every((s) => Number.isFinite(s.duration) && s.duration >= 0)) return null;
+    if (!anim.stepStarts.every(Number.isFinite)) return null;
+    // Layered over the defaults here (not only inside the probe) so `enabled`
+    // sees the same params the build and place() do.
+    const p0 = { ...part.defaults, ...params };
+    const shown = viewSubParts(part, view, p0);
+    const base = placePoses(part, view, p0, shown);
+    if (!base) return null;
+    for (const name of shown) {
+      const reads = buildReads(name);
+      if (!reads) return null;
+      if (anim.trackedKeys.some((key) => reads.has(key))) return null;
+    }
+    const samples = [];
+    const times = sampleTimes(anim);
+    if (!times.every(Number.isFinite)) return null;
+    for (const t of times) {
+      const { values, opacity } = evaluate(anim, t);
+      const p = { ...p0, ...values };
+      if (!sameSet(viewSubParts(part, view, p), shown)) return null;
+      const poses = placePoses(part, view, p, shown);
+      if (!poses) return null;
+      samples.push({ t, poses, opacity });
+    }
+    return { anim, samples, base };
+  } catch {
+    return null;
+  }
+}