partforge 0.157.0 → 0.158.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.157.0",
+  "version": "0.158.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/geometry/pose.js

@@ -91,3 +91,23 @@ export function rotateNormals(normals, m) {
     normals[i + 2] = m[2] * x + m[6] * y + m[10] * z;
   }
 }
+
+// Whether a column-major mat4 is a rigid motion within `tol`: finite, affine
+// (last row 0 0 0 1), an orthonormal 3x3 block (RᵀR = I) with det = +1 — no
+// scale, shear or mirror. The preview GLB's encoder refuses any other pose, and
+// the sampler (preview-animation.js) applies the same test so its output never
+// trips that refusal.
+export function isRigid(m, tol = 1e-6) {
+  if (!Array.isArray(m) && !ArrayBuffer.isView(m)) return false;
+  if (m.length !== 16 || !Array.prototype.every.call(m, Number.isFinite)) return false;
+  if (Math.abs(m[3]) > tol || Math.abs(m[7]) > tol || Math.abs(m[11]) > tol || Math.abs(m[15] - 1) > tol) return false;
+  const col = (c) => [m[c * 4], m[c * 4 + 1], m[c * 4 + 2]];
+  const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+  const cols = [col(0), col(1), col(2)];
+  for (let i = 0; i < 3; i++) {
+    for (let j = 0; j < 3; j++) if (Math.abs(dot(cols[i], cols[j]) - (i === j ? 1 : 0)) > tol) return false;
+  }
+  const [a, b, c] = cols;
+  const det = a[0] * (b[1] * c[2] - b[2] * c[1]) - b[0] * (a[1] * c[2] - a[2] * c[1]) + c[0] * (a[1] * b[2] - a[2] * b[1]);
+  return Math.abs(det - 1) <= tol;
+}

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

@@ -24,9 +24,25 @@
 // which the viewer reads as "no feature edges" (never undefined, which would
 // make it derive lines by angle).
 //
+// The baked animation (encoder version 4) comes back as `animation`, null for a
+// file without the partforgeAnimation extra (every version 1–3 file):
+// { ...the extra (name, label, loop, duration, cues, opacity, steps, animated),
+//   tracks: { <sub>: { times, translations, rotations } }, rest: { <sub>: mat16 } }.
+// `times` are seconds; `translations` xyz triples and `rotations` xyzw quads are
+// the node's TRS keyframes, which the writer expresses in the root's LOCAL frame
+// — the part's Z-up MODEL frame — so they need no conversion (positions do: they
+// go through the node's world matrix, root rotation included). Only sub-parts
+// that move have a track; `rest[name]` is the column-major mat4 of a track's
+// first keyframe (t = 0), the pose already baked into that sub-part's
+// positions — meshes decode at the OPENING pose. Channels are read off the raw
+// glTF JSON and resolved through the parser, never by AnimationClip track name
+// (three sanitizes node names). An animated sub-part's mesh sits on an unnamed
+// child of its node (quantize() moves it there), so a mesh's sub-part is found
+// by walking up to the nearest node carrying partforgeSubPart.
+//
 // Rejects on anything that is not a decodable GLB; the callers (mount's
 // `preview`, mountPreview) decide what a failure means for them.
-import { Matrix3, Matrix4, Vector3 } from "three";
+import { Matrix3, Matrix4, Quaternion, Vector3 } from "three";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
 
@@ -64,16 +80,72 @@ function metaOf(extras) {
   return Object.keys(out).length ? out : null;
 }
 
-// The object standing for a glTF node: the object itself when its node had one
-// primitive, else the Group GLTFLoader made for a multi-primitive mesh — the
-// one carrying the node's extras / name (a primitive's own Mesh has neither).
+// The object standing for a glTF node: the nearest of the object and its
+// ancestors (below the scene root) carrying the writer's partforgeSubPart — an
+// animated sub-part's mesh sits one or two levels under it (quantize()'s unnamed
+// child, then GLTFLoader's Group for a multi-primitive mesh). Failing that, the
+// object itself when its node had one primitive, else the Group GLTFLoader made
+// for a multi-primitive mesh — the one carrying the node's extras / name (a
+// primitive's own Mesh has neither).
 function nodeObjectOf(obj) {
+  for (let o = obj; o && o.parent; o = o.parent) {
+    if (typeof o.userData?.partforgeSubPart === "string") return o;
+  }
   const own = obj.userData ?? {};
   if ("partforgeSubPart" in own || "name" in own) return obj;
   const parent = obj.parent;
   return parent?.isGroup && parent.userData && ("partforgeSubPart" in parent.userData || "name" in parent.userData) ? parent : obj;
 }
 
+// The sub-part key a node object stands for: the writer's own record of the key,
+// then the unsanitized glTF node name.
+function subPartNameOf(node) {
+  const { partforgeSubPart, name } = node.userData ?? {};
+  return typeof partforgeSubPart === "string" ? partforgeSubPart : (name ?? node.name);
+}
+
+// An accessor's elements as a Float32Array of `size` components each, through
+// getX/getY/getZ/getW so a normalized output would be denormalized (this writer
+// stores the channels as plain float32; the guard is for any other writer).
+function readComponents(attr, size) {
+  const out = new Float32Array(attr.count * size);
+  const get = [attr.getX, attr.getY, attr.getZ, attr.getW].slice(0, size);
+  for (let i = 0; i < attr.count; i++) for (let k = 0; k < size; k++) out[i * size + k] = get[k].call(attr, i);
+  return out;
+}
+
+// The baked animation (see the header): the partforgeAnimation extra plus the
+// first glTF animation's channels as model-frame keyframes per sub-part.
+async function readAnimation(gltf) {
+  const extra = gltf.userData?.partforgeAnimation;
+  if (!extra || typeof extra !== "object") return null;
+  const tracks = {};
+  const rest = {};
+  const def = gltf.parser.json.animations?.[0];
+  for (const channel of def?.channels ?? []) {
+    const path = channel.target?.path;
+    if ((path !== "translation" && path !== "rotation") || channel.target.node === undefined) continue;
+    const sampler = def.samplers[channel.sampler];
+    const node = await gltf.parser.getDependency("node", channel.target.node);
+    const [input, output] = await Promise.all([
+      gltf.parser.getDependency("accessor", sampler.input),
+      gltf.parser.getDependency("accessor", sampler.output),
+    ]);
+    const track = (tracks[subPartNameOf(nodeObjectOf(node))] ??= { times: null, translations: null, rotations: null });
+    track.times ??= readComponents(input, 1);
+    if (path === "translation") track.translations = readComponents(output, 3);
+    else track.rotations = readComponents(output, 4);
+  }
+  for (const [name, track] of Object.entries(tracks)) {
+    const t = track.translations ?? new Float32Array(3);
+    const r = track.rotations ?? Float32Array.of(0, 0, 0, 1);
+    rest[name] = new Matrix4()
+      .compose(new Vector3(t[0], t[1], t[2]), new Quaternion(r[0], r[1], r[2], r[3]).normalize(), new Vector3(1, 1, 1))
+      .toArray();
+  }
+  return { ...extra, tracks, rest };
+}
+
 // Line segments as endpoint pairs in model frame: an indexed LINES primitive
 // expanded back to pairs. Version 3's position attribute is the SURFACE's
 // (GLTFLoader hands both objects the same BufferAttribute), so only the
@@ -137,10 +209,9 @@ export async function decodePreviewGlb(bytes) {
     const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
     const count = surfaceVertexCount(position, geometry.index);
     const node = nodeObjectOf(obj);
-    const { partforgeSubPart, partforgeDisplay, name: originalName } = node.userData;
+    const { partforgeDisplay } = node.userData;
     const payload = {
-      // The writer's own record of the key, then the unsanitized glTF node name.
-      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? node.name),
+      name: subPartNameOf(node),
       positions: readVec3(position, toModel, false, count),
       normals: normal ? readVec3(normal, normalMatrix, true, count) : null,
       indices,
@@ -166,5 +237,6 @@ export async function decodePreviewGlb(bytes) {
     view: typeof extras.partforgeView === "string" ? extras.partforgeView : null,
     meta: metaOf(extras),
     meshes,
+    animation: await readAnimation(gltf),
   };
 }

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;
+  }
+}

package/src/framework/preview-player.js

@@ -0,0 +1,161 @@
+// The preview player: plays the autoplay animation a preview GLB carries
+// (decoded by gltf/decode-preview.js) off the viewer's own frame loop, with no
+// part code running. The live driver (animation-controls.js) moves params and
+// rebuilds; here every animated sub-part's motion is already baked as
+// model-frame keyframes, so a frame is a pose per sub-part and nothing more.
+//
+// Timing, cues and looping are not reimplemented: createPlayback (animation.js)
+// runs on a synthetic normalized animation with no tracked params and no
+// opacity keys, so its snapshot contributes only status, t and the cue to fire.
+// The player turns that t into poses and opacities itself.
+//
+// Three rules (spec §3):
+//  - A looping animation wraps; a once-through one rests at its end pose and
+//    the player does nothing further each frame.
+//  - A user orbit disarms the remaining camera cues and never pauses the
+//    motion (mid-intro it releases the intro gate, so playback still starts).
+//  - Reduced motion means no player: start() writes nothing — no pose, no
+//    opacity, no ground hold, no cue — so the visitor sees exactly what the
+//    file draws without a player (the opening pose, every sub-part opaque; an
+//    opacity fade-in must not leave a sub-part hidden for good).
+import { createPlayback } from "./animation.js";
+import { invertRigid, mulMat4 } from "./geometry/pose.js";
+
+// A frame after a stall (a hidden tab, a long GC) advances at most this many
+// seconds, so the motion resumes where it was rather than jumping.
+export const MAX_FRAME_DT = 0.1;
+const INTRO_TWEEN_SECONDS = 0.6;
+
+// Spherical interpolation between two unit quaternions [x, y, z, w].
+export function slerp(a, b, u) {
+  let [bx, by, bz, bw] = b;
+  let cos = a[0] * bx + a[1] * by + a[2] * bz + a[3] * bw;
+  if (cos < 0) { cos = -cos; bx = -bx; by = -by; bz = -bz; bw = -bw; } // shortest arc
+  let wa = 1 - u, wb = u;
+  if (cos < 0.9995) {
+    const theta = Math.acos(cos), s = Math.sin(theta);
+    wa = Math.sin((1 - u) * theta) / s;
+    wb = Math.sin(u * theta) / s;
+  }
+  const q = [wa * a[0] + wb * bx, wa * a[1] + wb * by, wa * a[2] + wb * bz, wa * a[3] + wb * bw];
+  const len = Math.hypot(q[0], q[1], q[2], q[3]) || 1;
+  return q.map((c) => c / len);
+}
+
+// Column-major mat16 for rotation q followed by translation p.
+export function quatToMat4([x, y, z, w], [px, py, pz]) {
+  const xx = x * x, yy = y * y, zz = z * z, xy = x * y, xz = x * z, yz = y * z, wx = w * x, wy = w * y, wz = w * z;
+  return [
+    1 - 2 * (yy + zz), 2 * (xy + wz), 2 * (xz - wy), 0,
+    2 * (xy - wz), 1 - 2 * (xx + zz), 2 * (yz + wx), 0,
+    2 * (xz + wy), 2 * (yz - wx), 1 - 2 * (xx + yy), 0,
+    px, py, pz, 1,
+  ];
+}
+
+// The keyframed transform at `seconds`: translation lerped, rotation slerped
+// between the bracketing keyframes, held before the first and after the last.
+export function sampleTrack({ times, translations, rotations }, seconds) {
+  const n = times.length;
+  const tr = (i) => [translations[i * 3], translations[i * 3 + 1], translations[i * 3 + 2]];
+  const rot = (i) => [rotations[i * 4], rotations[i * 4 + 1], rotations[i * 4 + 2], rotations[i * 4 + 3]];
+  if (n === 1 || seconds <= times[0]) return quatToMat4(rot(0), tr(0));
+  if (seconds >= times[n - 1]) return quatToMat4(rot(n - 1), tr(n - 1));
+  let i = 0;
+  while (i < n - 2 && seconds >= times[i + 1]) i++;
+  const u = (seconds - times[i]) / (times[i + 1] - times[i] || 1);
+  const a = tr(i), b = tr(i + 1);
+  return quatToMat4(slerp(rot(i), rot(i + 1), u), [0, 1, 2].map((k) => a[k] + (b[k] - a[k]) * u));
+}
+
+// Linear opacity over [[t, v], …] keyframes in normalized t, clamped at the ends.
+export function sampleOpacity(keys, t) {
+  if (t <= keys[0][0]) return keys[0][1];
+  for (let i = 1; i < keys.length; i++) {
+    const [t1, v1] = keys[i];
+    if (t <= t1) {
+      const [t0, v0] = keys[i - 1];
+      return v0 + (v1 - v0) * ((t - t0) / (t1 - t0 || 1));
+    }
+  }
+  return keys[keys.length - 1][1];
+}
+
+export function createPreviewPlayer(viewer, animation, { reducedMotion = false } = {}) {
+  const { duration, tracks, rest, opacity = {} } = animation;
+  const steps = animation.steps ?? [];
+  const playback = createPlayback({
+    name: animation.name,
+    loop: animation.loop,
+    totalDuration: duration,
+    cues: animation.cues ?? [],
+    steps: steps.map((s) => ({ label: s.label, duration: s.duration, easing: "linear", tracks: {}, opacity: {}, camera: null })),
+    stepStarts: steps.map((s) => s.start),
+    trackedKeys: [],
+    opacityKeys: [],
+  });
+  // Pose = keyframed transform with the rest transform taken out: the mesh
+  // 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;
+
+  function apply(t) {
+    const seconds = t * duration;
+    for (const [name, track] of Object.entries(tracks)) viewer.setSubPose(name, mulMat4(sampleTrack(track, seconds), restInverse[name]));
+    for (const [name, keys] of Object.entries(opacity)) if (keys?.length) viewer.setSubPartOpacity(name, sampleOpacity(keys, t));
+  }
+
+  // A snapshot from play(): an intro cue tweens and gates playback until it lands.
+  function honorIntro(snap) {
+    if (snap.status !== "intro" || !snap.cue) return;
+    viewer.tweenCameraTo(snap.cue.view, {
+      duration: INTRO_TWEEN_SECONDS,
+      onComplete: () => { if (!disposed) playback.introDone(); },
+    });
+  }
+
+  function onFrame(dt) {
+    const snap = playback.tick(Math.min(dt, MAX_FRAME_DT));
+    if (!snap) return; // not playing: intro, paused, or done — the last poses stand
+    apply(snap.t);
+    if (snap.cue) viewer.tweenCameraTo(snap.cue.view, { duration: snap.cue.sweep ?? INTRO_TWEEN_SECONDS });
+  }
+
+  function onOrbit() {
+    playback.disarmCues();
+    if (playback.state().status === "intro") playback.introDone();
+  }
+
+  return {
+    start() {
+      if (started || disposed) return;
+      started = true;
+      if (reducedMotion) return;
+      apply(0);
+      viewer.holdGround(true);
+      offFrame = viewer.onFrame(onFrame);
+      offOrbit = viewer.onCameraStart(onOrbit);
+      honorIntro(playback.play());
+    },
+    pause() {
+      if (!disposed) playback.pause();
+    },
+    resume() {
+      if (disposed || playback.state().status !== "paused") return;
+      honorIntro(playback.play());
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      if (!offFrame) return; // never played (not started, or reduced motion): nothing to undo
+      offFrame(); offOrbit();
+      offFrame = offOrbit = null;
+      viewer.holdGround(false);
+    },
+    state() {
+      const { status, t } = playback.state();
+      return { status, t };
+    },
+  };
+}

package/src/oracle.js

@@ -17,6 +17,9 @@
 export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
 export { meshVolume, bboxSize, bounds, meshArea } from "./framework/oracle/mesh.js";
 export { buildView } from "./framework/oracle/build.js";
+// Preview animation — whether a view's autoplay animation is place-only, and its
+// sampled place() matrices, for the cached preview GLB (partforge/gltf) to bake.
+export { samplePreviewAnimation, PREVIEW_SAMPLE_HZ, PREVIEW_SAMPLE_CAP } from "./framework/preview-animation.js";
 export { measure } from "./framework/oracle/measure.js";
 export { verify } from "./framework/oracle/verify.js";
 // Change tracking — the `inspect` job's opt-in "what changed since my last

package/types/gltf.d.ts

@@ -1,6 +1,9 @@
 // partforge/gltf — the cached-preview writer. Worker-safe: no three.js, no DOM.
 
 import type { SubPartDefinition } from "./part.js";
+import type { PreviewAnimationInput } from "./oracle.js";
+
+export type { PreviewAnimationInput };
 
 /** The slice of a part `encodePreviewGlb` reads; any `PartDefinition` satisfies it, so does a plain object. */
 export interface PreviewPart {
@@ -38,9 +41,19 @@ export interface EncodePreviewInput {
   part?: PreviewPart | null;
   /** The view these meshes show; names the scene and lands in the file's extras as `partforgeView`. */
   view?: string | null;
+  /**
+   * The view's autoplay animation as `samplePreviewAnimation` returns it (encoder
+   * version 4). Each sampled sub-part's node gets a rest transform `rel(0)` and,
+   * when it moves, LINEAR `translation` + `rotation` channels in seconds, where
+   * `rel(t) = M(t) · base⁻¹`; the top-level extras gain `partforgeAnimation`
+   * `{ name, label, loop, duration, cues, opacity, steps, animated }`. Refused
+   * (throws) for a non-rigid pose, samples not running from t = 0 to t = 1, a
+   * sample missing a sub-part another has, or a sub-part with no mesh.
+   */
+  animation?: PreviewAnimationInput | null;
 }
 
-/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges; 3: edges as indices into the surface's vertices). */
+/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges; 3: edges as indices into the surface's vertices; 4: animation channels + partforgeAnimation extras). */
 export const PREVIEW_ENCODER_VERSION: number;
 
 /** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */

package/types/index.d.ts

@@ -780,6 +780,8 @@ export interface MountPreviewOptions {
   elements?: { chrome?: { reframe?: HTMLElement | null; theme?: HTMLElement | null } };
   /** A previous runtime's `getViewerState()`; `cutaway` is ignored (a preview has no live solid). */
   viewerState?: ViewerState | null;
+  /** Play the file's baked animation once drawn (default true). The editor's own boot preview goes through mount(), not here. */
+  animate?: boolean;
 }
 
 /** The handle `mountPreview()` returns. Every method is safe before `ready` settles. */
@@ -802,6 +804,12 @@ export interface PreviewRuntime {
   setHostPane(pane: HostPane): void;
   /** Accepted and ignored — there is no rail. */
   setRailLayout(layout: HostRailLayout): void;
+  /** The baked animation's controls: `null` before `ready`, for a still file, or with `animate: false`. */
+  readonly animation: {
+    state(): { status: "idle" | "intro" | "playing" | "paused" | "done"; t: number };
+    pause(): void;
+    resume(): void;
+  } | null;
   renderMode: {
     get(): RenderMode;
     set(mode: RenderMode): Promise<RenderMode>;

package/types/oracle.d.ts

@@ -5,6 +5,7 @@
 // report/mask/gap types a caller needs to annotate results. The semantic mesh
 // oracle (`describe`) is its own closed package now — its types ship with it, and
 // the direction of this seam is what lets that package consume these helpers.
+import type { CameraCue, Easing, Keyframes, ParamValue, PartDefinition } from "./part.js";
 export type { GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid } from "./testing.js";
 export {
   // measurement + verification
@@ -29,3 +30,80 @@ export {
   annotationRay, rayPlane,
   type AnnotationRay, type RayPlaneHit, type PlaneSpec,
 } from "./testing.js";
+
+/** One step of a normalized animation (every optional field filled in). */
+export interface NormalizedAnimationStep {
+  /** `null` for the single anonymous step of a bare-`tracks` animation. */
+  label: string | null;
+  duration: number;
+  easing: Easing;
+  tracks: Record<string, Keyframes>;
+  opacity: Record<string, Keyframes>;
+  camera: CameraCue | null;
+}
+
+/** A camera cue on the normalized timeline: fires at `t`, sweeping for `sweep` seconds. */
+export interface NormalizedAnimationCue {
+  t: number;
+  view: CameraCue;
+  /** Seconds; `null` for a lone intro angle. */
+  sweep: number | null;
+}
+
+/** An animation in the canonical shape every consumer (playback, lint, CLI, preview) works against. */
+export interface NormalizedAnimation {
+  name: string;
+  label: string;
+  description: string | null;
+  loop: boolean;
+  autoplay: boolean;
+  steps: NormalizedAnimationStep[];
+  /** Each step's start as normalized t. */
+  stepStarts: number[];
+  /** Seconds. */
+  totalDuration: number;
+  cues: NormalizedAnimationCue[];
+  /** Params any step tracks. */
+  trackedKeys: string[];
+  /** Sub-parts any step fades. */
+  opacityKeys: string[];
+}
+
+/** One sampled instant of a baked preview animation. */
+export interface PreviewAnimationSample {
+  /** Normalized time in [0, 1]. */
+  t: number;
+  /** Sub-part name → column-major model-frame place matrix (16 numbers). */
+  poses: Record<string, number[]>;
+  /** Sub-part name → opacity 0–1; `{}` when the animation declares no fades. */
+  opacity: Record<string, number>;
+}
+
+/** What `samplePreviewAnimation` returns for a bakeable autoplay animation. */
+export interface PreviewAnimationInput {
+  anim: NormalizedAnimation;
+  /** Sorted by `t`; the first has `t === 0`, the last `t === 1`. */
+  samples: PreviewAnimationSample[];
+  /** Sub-part name → place matrix at the params handed in. */
+  base: Record<string, number[]>;
+}
+
+/** Sampling grid rate over the animation's real duration, in Hz. */
+export const PREVIEW_SAMPLE_HZ: 30;
+/** Most samples one preview animation carries; the grid thins, keyframe times never do. */
+export const PREVIEW_SAMPLE_CAP: 600;
+
+/**
+ * Decide whether the view's autoplay animation can be baked into the preview
+ * GLB — every tracked param place-only (the build reads none, and place() is a
+ * rigid motion at every sample) and the shown sub-parts constant — and if so
+ * sample the place matrices along its timeline. `buildReads(name)` returns the
+ * param keys that sub-part's build read, or `null` when unknown. Returns `null`
+ * when there is no autoplay animation or any check fails; never throws.
+ */
+export function samplePreviewAnimation(
+  part: PartDefinition,
+  view: string,
+  params?: Record<string, ParamValue>,
+  options?: { buildReads: (name: string) => ReadonlySet<string> | null },
+): PreviewAnimationInput | null;

package/types/testing.d.ts

@@ -11,6 +11,12 @@ import type { Derived, FontSource, PartDefinition, ResolvedParams } from "./part
 import type { KitOptions } from "./index.js";
 
 export type { Derived, GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid };
+// Declared in oracle.d.ts (its own surface); testing.js re-exports all of oracle.js.
+export {
+  samplePreviewAnimation, PREVIEW_SAMPLE_HZ, PREVIEW_SAMPLE_CAP,
+  type PreviewAnimationInput, type PreviewAnimationSample, type NormalizedAnimation,
+  type NormalizedAnimationStep, type NormalizedAnimationCue,
+} from "./oracle.js";
 
 // --- kernels ----------------------------------------------------------------
 
@@ -184,12 +190,17 @@ export function meshGaps(built: BuiltSubPart[], opts?: { bvhCache?: Map<Mesh, BV
 /**
  * Build every sub-part of a view in its display pose. Keeps solids LIVE (does
  * NOT call `kernel.cleanup()`) so callers can read exact solid facts first.
+ *
+ * `readsBySubPart`, when given, is filled with each sub-part's name → the params
+ * its `build()` read (expanded through derived values). `place()` reads are
+ * excluded, so a pose-only param never reads as a rebuild.
  */
 export function buildView(
   kernel: GeometryKernel,
   part: PartDefinition,
   view: string,
   params?: ResolvedParams,
+  opts?: { readsBySubPart?: Map<string, string[]> },
 ): BuiltSubPart[];
 
 // --- mesh math --------------------------------------------------------------