partforge 0.156.0 → 0.158.0

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/framework/process/cnc-router/descriptor.js

@@ -1,4 +1,5 @@
-// CNC routing — process module #2. Flat stock machined from ONE face: through cuts
+// CNC routing — process module #2. Flat stock machined from either face — the near
+// face (z = t, the default) or the far face (z = 0, per op `face: "far"`): through cuts
 // (profile), flat-floored pockets at a depth, drilled holes at a depth, and `extra`
 // operations the operator does with another tool after the flat milling. The
 // drawing is one layered DXF per piece, depth on the layer name and colour.
@@ -12,8 +13,9 @@ import {
 } from "../../sheet/constants.js";
 import { err } from "../../lint/finding.js";
 
-// The preview: the profile extruded to the thickness, each pocket cut `depth` down from
-// the machined face (z = t), each drill as a cylinder from the face to its depth —
+// The preview: the profile extruded to the thickness, each pocket cut `depth` into the
+// stock from its face (down from z = t on the near face, up from z = 0 on the far
+// face), each drill as a cylinder from its face to its depth —
 // through holes and through pockets (depth = thickness) clear BOTH faces by MARK_OVERCUT so no cap is coplanar with a face
 // (OCCT's coplanar booleans are fragile) — each extra solid subtracted as given, and
 // the reference grooves cut like a laser score. A tool whose region turned out empty
@@ -29,10 +31,14 @@ function routedPreview(k, s) {
   const tools = [
     ...pockets.map((pk) => orEmpty(() => (pk.depth >= t
       ? pk.region.extrude({ h: t + 2 * MARK_OVERCUT }).translate([0, 0, -MARK_OVERCUT])
-      : pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, t - pk.depth])))),
+      : pk.face === "far"
+        ? pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, -MARK_OVERCUT])
+        : pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, t - pk.depth])))),
     ...drills.map((dr) => (dr.through
       ? k.cylinder({ d: dr.d, h: t + 2 * MARK_OVERCUT }).translate([dr.at[0], dr.at[1], -MARK_OVERCUT])
-      : k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], t - dr.depth]))),
+      : dr.face === "far"
+        ? k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], -MARK_OVERCUT])
+        : k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], t - dr.depth]))),
     ...extra.map((x) => x.solid),
     ...s.grooves.map((g) => orEmpty(() => g.extrude({ h: MARK_DEPTH + MARK_OVERCUT }).translate([0, 0, t - MARK_DEPTH]))),
   ].filter(Boolean);
@@ -74,21 +80,21 @@ function routedFacts(s) {
   for (const pk of pockets) {
     if (pk.region.isEmpty()) { empty++; continue; }
     const [w, h] = sizeOf(pk.region);
-    pocketRows.push({ label: pk.label, depth: pk.depth, w: round2(w), h: round2(h), area: round2(pk.region.area()) });
+    pocketRows.push({ label: pk.label, depth: pk.depth, w: round2(w), h: round2(h), area: round2(pk.region.area()), face: pk.face });
     noteOutside(pk.region);
   }
-  // Drills grouped by (d, depth, through): one row per tool setting, labels joined.
+  // Drills grouped by (d, depth, through, face): one row per tool setting, labels joined.
   const drillGroups = new Map();
   for (const dr of drills) {
-    const key = `${dr.d}|${dr.depth}|${dr.through}`;
-    const g = drillGroups.get(key) ?? { labels: [], d: dr.d, depth: dr.depth, through: dr.through, count: 0 };
+    const key = `${dr.d}|${dr.depth}|${dr.through}|${dr.face}`;
+    const g = drillGroups.get(key) ?? { labels: [], d: dr.d, depth: dr.depth, through: dr.through, face: dr.face, count: 0 };
     g.count++;
     if (dr.label && !g.labels.includes(dr.label)) g.labels.push(dr.label);
     drillGroups.set(key, g);
     noteOutside(dr.shape);
   }
-  const drillRows = [...drillGroups.values()].map(({ labels, d, depth, through, count }) =>
-    ({ label: labels.length ? labels.join(", ") : null, d, depth, through, count }));
+  const drillRows = [...drillGroups.values()].map(({ labels, d, depth, through, count, face }) =>
+    ({ label: labels.length ? labels.join(", ") : null, d, depth, through, count, face }));
   // An extra op whose footprint resolved to nothing draws nothing: counted under
   // `empty` with the empty pockets, never a row (its size has no bounding box).
   const extraRows = [];
@@ -96,12 +102,25 @@ function routedFacts(s) {
     if (x.footprint.isEmpty()) { empty++; continue; }
     const [w, h] = sizeOf(x.footprint);
     noteOutside(x.footprint);
-    // How deep the op reaches below the machined face (z = t), within the stock. An
-    // empty solid has no bounding box and reaches nothing.
+    // How deep the op reaches into the stock from its face — below z = t on the near
+    // face, above z = 0 on the far face — within the stock. An empty solid has no
+    // bounding box and reaches nothing.
     const bb = x.solid.boundingBox();
-    const bottom = bb?.min?.[2];
-    const reach = Number.isFinite(bottom) ? t - bottom : 0;
-    extraRows.push({ label: x.label, method: x.method, w: round2(w), h: round2(h), maxDepth: round2(Math.max(0, Math.min(t, reach))) });
+    const bound = x.face === "far" ? bb?.max?.[2] : bb?.min?.[2];
+    const reach = Number.isFinite(bound) ? (x.face === "far" ? bound : t - bound) : 0;
+    extraRows.push({ label: x.label, method: x.method, w: round2(w), h: round2(h), maxDepth: round2(Math.max(0, Math.min(t, reach))), face: x.face });
+  }
+
+  // Breakthrough: a near pocket and a far pocket whose regions overlap and whose depths
+  // together exceed the stock — the router breaks through between them. Depths adding
+  // up to exactly the thickness are a deliberate opening and never counted.
+  const live = pockets.filter((pk) => !pk.region.isEmpty());
+  const near = live.filter((pk) => pk.face !== "far"), far = live.filter((pk) => pk.face === "far");
+  let breakthrough = 0;
+  for (const a of near) {
+    for (const b of far) {
+      if (a.depth + b.depth > t + 1e-6 && a.region.intersect(b.region).area() > LOSS_TOL_MM2) breakthrough++;
+    }
   }
 
   return {
@@ -112,7 +131,7 @@ function routedFacts(s) {
     at: { bridge: null, gap: null, marks: null, outside: null },
     readErrors: { bridge: null, gap: null, marks: null, marksArea: null },
     evaluated: true,
-    routed: { profile: { w: round2(flat[0]), h: round2(flat[1]) }, pockets: pocketRows, drills: drillRows, extra: extraRows, outside, empty },
+    routed: { profile: { w: round2(flat[0]), h: round2(flat[1]) }, pockets: pocketRows, drills: drillRows, extra: extraRows, outside, empty, breakthrough },
   };
 }
 
@@ -130,10 +149,13 @@ const METRICS = {
   routedPieces: { kind: "warn", doc: ROUTED_DOC_ID,
     extract: (s) => s.sheet?.pieces ?? null,
     hint: "the profile is not exactly one piece — a routed part must cut out as one region; join the pieces or split them into separate routedPart sub-parts" },
+  routedBreakthrough: { kind: "warn", doc: ROUTED_DOC_ID,
+    extract: (s) => s.sheet?.routed?.breakthrough ?? null,
+    hint: "a pocket on the near face and one on the far face overlap and together go deeper than the stock, so the router breaks through between them — make the overlap a through cut in `profile`, or lower one depth; if the opening is intended, set the two depths to add up to exactly the thickness" },
 };
 
 // ── lint ──────────────────────────────────────────────────────────────────────
-const DRILL_DEPTH_HINT = "A drill's depth is measured from the machined face; a depth at or past the stock thickness is a through hole. Lower the depth, raise the stock thickness control, or set depth to the thickness to drill through.";
+const DRILL_DEPTH_HINT = "A drill's depth is measured from the op's own face (near or far); a depth at or past the stock thickness is a through hole. Lower the depth, raise the stock thickness control, or set depth to the thickness to drill through.";
 const ROUTER_RULES = [{
   id: "routed-drill-depth",
   run: ({ part, p, d, deriveError }) => {
@@ -168,7 +190,7 @@ export const ROUTER = {
   preview: routedPreview,
   destinations: [{ id: "cnc-router", cutFormat: "dxf" }],
   facts: routedFacts,
-  checks: () => ({ routedOutside: "0", routedEmpty: "0", routedPieces: "1" }),
+  checks: () => ({ routedOutside: "0", routedEmpty: "0", routedPieces: "1", routedBreakthrough: "0" }),
   metrics: METRICS,
   lintRules: ROUTER_RULES,
 };

package/src/framework/process/cnc-router/export.js

@@ -6,10 +6,11 @@
 //
 // Colours: `ctx.palette` (drawing.js routedPalette, built by the kit over EVERY routed
 // piece) when given, so one depth is one colour across the kit; without it — a direct
-// call — the piece ranks its own depths. Each named layer also carries its `depth` (mm,
+// call — routedPalette over the piece alone. Each named layer also carries its `depth` (mm,
 // two decimals) and drills `through`, which the README's layer legend reads.
 import {
   refitRing, ringsOf, cutRings, drawingBounds, routedLayerName, depthToken, drillKey, ROUTED_COLORS,
+  routedPalette, FLIP_AXIS, mirrorRings,
 } from "../../export/drawing.js";
 import { KIT_OPTIONS_ERROR } from "../../export/formats.js";
 
@@ -18,57 +19,79 @@ const refitRegions = (regions) => regions.map((rg) => ({ outer: refitRing(rg.out
 const allRings = (regions) => { const r = ringsOf(regions); return [...r.outer, ...r.holes]; };
 const ringsOfShape = (shape) => allRings(refitRegions(shape.toContours())).map(closedPath);
 
-function drawing(s, o, k, ctx = {}) {
-  const label = ctx.label ?? s.label ?? "routed part";
-  if (o?.kerf > 0) throw new Error(`${KIT_OPTIONS_ERROR} kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0 ("${label}")`);
-  const nominal = refitRegions(s.profile.toContours());
-  if (nominal.length === 0) throw new Error(`cut kit: "${label}" has an empty profile — nothing to cut`);
-  const cut = cutRings(nominal);
-  const { pockets, drills, extra } = s.routed;
-
+// One face's operation layers: SECONDARY, then drills grouped by (d, depth, through) in
+// first-seen order, then pockets grouped by two-decimal depth, shallowest first. `place`
+// maps each layer's paths (identity for the near face, the flip's mirror for the far);
+// a far layer's id is prefixed `far-` and it carries `face: "far"` — a near layer has
+// no face key, so a one-sided piece draws exactly as before two-sided parts existed.
+function opLayers({ pockets, drills, extra }, palette, place) {
+  const tag = place ? { face: "far" } : {};
+  const id = (base) => (place ? `far-${base}` : base);
+  const at = place ?? ((paths) => paths);
   const layers = [];
-  const reference = [
-    ...s.score.lines.map(([a, b]) => ({ start: [a[0], a[1]], segments: [{ to: [b[0], b[1]] }], closed: false })),
-    ...s.score.shapes.flatMap(ringsOfShape),
-  ];
-  if (reference.length) layers.push({ id: "reference", name: "REFERENCE", ...ROUTED_COLORS.reference, paths: reference });
   const secondary = extra.flatMap((x) => ringsOfShape(x.footprint));
-  if (secondary.length) layers.push({ id: "secondary", name: "SECONDARY", ...ROUTED_COLORS.secondary, paths: secondary });
+  if (secondary.length) layers.push({ id: id("secondary"), name: place ? "FAR_SECONDARY" : "SECONDARY", ...ROUTED_COLORS.secondary, ...tag, paths: at(secondary) });
 
-  // Drills grouped by (d, depth, through) in first-seen order; each hole a closed ring
-  // of two exact arcs, which dxf.js writes as a CIRCLE.
-  const palette = ctx.palette ?? null;
+  // Each hole a closed ring of two exact arcs, which dxf.js writes as a CIRCLE.
   const drillGroups = new Map();
   drills.forEach((dr) => {
     const key = drillKey(dr);
-    const colour = palette?.drill.get(key) ?? ROUTED_COLORS.drill[drillGroups.size % ROUTED_COLORS.drill.length];
-    const g = drillGroups.get(key) ?? { id: `drill-${key}`, name: routedLayerName("drill", dr), ...colour,
-      depth: Number(depthToken(dr.depth)), through: dr.through, paths: [] };
-    g.paths.push(...ringsOfShape(dr.shape));
+    const g = drillGroups.get(key) ?? { id: id(`drill-${key}`), name: routedLayerName("drill", dr), ...palette.drill.get(key),
+      depth: Number(depthToken(dr.depth)), through: dr.through, ...tag, paths: [] };
+    g.paths.push(...at(ringsOfShape(dr.shape)));
     drillGroups.set(key, g);
   });
   layers.push(...drillGroups.values());
 
-  // Pockets grouped by two-decimal depth, shallowest layer first; an empty region draws nothing.
+  // An empty region draws nothing.
   const pocketGroups = new Map();
   for (const pk of pockets) {
     const paths = ringsOfShape(pk.region);
     if (paths.length === 0) continue;
     const key = depthToken(pk.depth);
-    const g = pocketGroups.get(key) ?? { id: `pocket-${key}`, name: routedLayerName("pocket", pk), depth: Number(key), paths: [] };
-    g.paths.push(...paths);
+    const g = pocketGroups.get(key) ?? { id: id(`pocket-${key}`), name: routedLayerName("pocket", pk), depth: Number(key), ...tag, paths: [] };
+    g.paths.push(...at(paths));
     pocketGroups.set(key, g);
   }
-  [...pocketGroups.values()].sort((a, b) => a.depth - b.depth).forEach((g, i) => {
-    const colour = palette?.pocket.get(depthToken(g.depth)) ?? ROUTED_COLORS.pocket[i % ROUTED_COLORS.pocket.length];
-    layers.push({ ...g, ...colour });
-  });
+  [...pocketGroups.values()].sort((a, b) => a.depth - b.depth)
+    .forEach((g) => layers.push({ ...g, ...palette.pocket.get(depthToken(g.depth)) }));
+  return layers;
+}
+
+function drawing(s, o, k, ctx = {}) {
+  const label = ctx.label ?? s.label ?? "routed part";
+  if (o?.kerf > 0) throw new Error(`${KIT_OPTIONS_ERROR} kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0 ("${label}")`);
+  const nominal = refitRegions(s.profile.toContours());
+  if (nominal.length === 0) throw new Error(`cut kit: "${label}" has an empty profile — nothing to cut`);
+  const cut = cutRings(nominal);
+  const { pockets, drills, extra } = s.routed;
+
+  const layers = [];
+  const reference = [
+    ...s.score.lines.map(([a, b]) => ({ start: [a[0], a[1]], segments: [{ to: [b[0], b[1]] }], closed: false })),
+    ...s.score.shapes.flatMap(ringsOfShape),
+  ];
+  if (reference.length) layers.push({ id: "reference", name: "REFERENCE", ...ROUTED_COLORS.reference, paths: reference });
+  // Near ops as they are; far ops (cut after the piece is turned over by the kit's flip)
+  // on their own `far-` layers, every ring mirrored about the piece's centre so the far
+  // face is drawn as the router sees it. One palette for both faces: a depth or drill
+  // setting is one colour whichever face it is on.
+  const palette = ctx.palette ?? routedPalette([s]);
+  const nb = drawingBounds([{ id: "cut-outer", paths: ringsOf(nominal).outer.map(closedPath) }]);
+  const axis = FLIP_AXIS[o?.flip ?? "left-right"];
+  const centre = axis === "x" ? (nb.min[0] + nb.max[0]) / 2 : (nb.min[1] + nb.max[1]) / 2;
+  const isFar = (op) => op.face === "far";
+  const near = opLayers({ pockets: pockets.filter((op) => !isFar(op)), drills: drills.filter((op) => !isFar(op)), extra: extra.filter((op) => !isFar(op)) }, palette);
+  const far = opLayers({ pockets: pockets.filter(isFar), drills: drills.filter(isFar), extra: extra.filter(isFar) }, palette,
+    (paths) => mirrorRings(paths, axis, centre));
+  layers.push(...near, ...far);
 
   if (cut.inner.length) layers.push({ id: "cut-inner", paths: cut.inner.map(closedPath) });
   layers.push({ id: "cut-outer", paths: cut.outer.map(closedPath) });
 
-  const nb = drawingBounds([{ id: "cut-outer", paths: ringsOf(nominal).outer.map(closedPath) }]);
-  return { layers, bounds: drawingBounds(layers), nominal: [nb.max[0] - nb.min[0], nb.max[1] - nb.min[1]], kerf: 0 };
+  const out = { layers, bounds: drawingBounds(layers), nominal: [nb.max[0] - nb.min[0], nb.max[1] - nb.min[1]], kerf: 0 };
+  if (far.length) out.farOutline = mirrorRings(ringsOf(nominal).outer, axis, centre).map(closedPath);
+  return out;
 }
 
 export default { drawing };

package/src/framework/sheet/routed-resolve.js

@@ -16,6 +16,13 @@ const depthOf = (sp, entry, who) => {
   if (!isNum(entry.depth) || entry.depth <= 0) throw fail(sp, `${who} depth must be a finite number > 0 (mm), got ${JSON.stringify(entry.depth)}`);
   return entry.depth;
 };
+// Which face an op is machined from: "near" (z = thickness, the default) or "far" (z = 0).
+const faceOf = (sp, entry, who) => {
+  const f = entry.face;
+  if (f === undefined || f === null) return "near";
+  if (f === "near" || f === "far") return f;
+  throw fail(sp, `${who} face must be "near" or "far", got ${JSON.stringify(f)}`);
+};
 const labelOf = (entry) => (typeof entry.label === "string" && entry.label.trim() ? entry.label.trim() : null);
 const list = (sp, fn, args, what, shape) => {
   if (!fn) return [];
@@ -26,7 +33,9 @@ const list = (sp, fn, args, what, shape) => {
 };
 
 // `base` is resolveSheet's ResolvedSheet so far (profile, thickness, score…); the
-// return value is merged onto it as `routed`.
+// return value is merged onto it as `routed`. Every op carries `face`: "near" (machined
+// from z = thickness, the default) or "far" (from z = 0, the stock flipped over); depth
+// is measured from that face either way.
 export function resolveRouted(k, sp, p, d, base) {
   const s = sp.sheet;
   const t = base.thickness;
@@ -35,8 +44,9 @@ export function resolveRouted(k, sp, p, d, base) {
     const who = name(e, i, "pocket");
     if (!e || typeof e !== "object" || e.region === null || e.region === undefined) throw fail(sp, `${who} needs a region (a Shape2D or profile)`);
     const depth = depthOf(sp, e, who);
+    const face = faceOf(sp, e, who);
     if (depth > t) throw fail(sp, `${who} is ${e.depth} mm deep in ${t} mm stock — a pocket may be at most the thickness; make it a through cut in \`profile\` if it should go through`);
-    return { region: k.shape2d(e.region), depth, label: labelOf(e) };
+    return { region: k.shape2d(e.region), depth, label: labelOf(e), face };
   });
 
   const drills = list(sp, s.drills, [p, d], "drills(p, d)", "{ at, d, depth }").map((e, i) => {
@@ -44,18 +54,20 @@ export function resolveRouted(k, sp, p, d, base) {
     if (!e || typeof e !== "object" || !isPoint(e.at)) throw fail(sp, `${who} needs at: [x, y]`);
     if (!isNum(e.d) || e.d <= 0) throw fail(sp, `${who} d must be a finite number > 0 (mm), got ${JSON.stringify(e.d)}`);
     const depth = depthOf(sp, e, who);
+    const face = faceOf(sp, e, who);
     const through = depth >= t;
-    return { shape: k.shape2d(circleRing(e.at, e.d / 2)), at: [e.at[0], e.at[1]], d: e.d, depth: through ? t : depth, through, label: labelOf(e) };
+    return { shape: k.shape2d(circleRing(e.at, e.d / 2)), at: [e.at[0], e.at[1]], d: e.d, depth: through ? t : depth, through, label: labelOf(e), face };
   });
 
   const extra = list(sp, s.extra, [k, p, d], "extra(k, p, d)", "{ solid, footprint, label, method }").map((e, i) => {
     const label = labelOf(e);
     if (!label) throw fail(sp, `extra op ${i + 1} needs a label — say what it is ("12° domino slot")`);
     const who = `extra op "${label}"`;
+    const face = faceOf(sp, e, who);
     if (typeof e.method !== "string" || !e.method.trim()) throw fail(sp, `${who} needs a method — say how the operator makes it ("table saw, blade tilted 12°")`);
     if (!isSolid(e.solid)) throw fail(sp, `${who} needs a solid — the geometry it removes, for the preview and the STEP`);
     if (e.footprint === null || e.footprint === undefined) throw fail(sp, `${who} needs a footprint — its outline on the machined face, for the drawing`);
-    return { solid: e.solid, footprint: k.shape2d(e.footprint), label, method: e.method.trim() };
+    return { solid: e.solid, footprint: k.shape2d(e.footprint), label, method: e.method.trim(), face };
   });
 
   return { pockets, drills, extra };

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/geometry.d.ts

@@ -338,12 +338,14 @@ export function sheetPart<P = ResolvedParams, D = Derived>(spec: SheetPartSpec<P
 
 // --- routed parts (docs/AUTHORING-PARTS.md "Routed parts") --------------------
 
-/** A flat-floored pocket machined `depth` mm down from the machined face. */
-export interface RoutedPocket { region: Shape2D | ProfileInput; depth: number; label?: string }
+/** Which face of the stock an op is machined from: `"near"` (z = thickness, the default) or `"far"` (z = 0). */
+export type RoutedFace = "near" | "far";
+/** A flat-floored pocket machined `depth` mm into the stock from its face. */
+export interface RoutedPocket { region: Shape2D | ProfileInput; depth: number; label?: string; face?: RoutedFace }
 /** A drilled hole; `depth` equal to the stock thickness drills through — deeper is a `routed-drill-depth` lint error. */
-export interface RoutedDrill { at: Point2; d: number; depth: number; label?: string }
+export interface RoutedDrill { at: Point2; d: number; depth: number; label?: string; face?: RoutedFace }
 /** An operation done with another tool after the flat milling: the solid is cut in the preview and the STEP, the footprint is drawn, label and method go in the README. */
-export interface RoutedExtra { solid: Solid; footprint: Shape2D | ProfileInput; label: string; method: string }
+export interface RoutedExtra { solid: Solid; footprint: Shape2D | ProfileInput; label: string; method: string; face?: RoutedFace }
 
 /**
  * What `routedPart` accepts: `sheetPart`'s stock, profile and pose, plus pockets,

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

@@ -67,6 +67,10 @@ export interface KitOptions {
   printFormat?: "stl" | "3mf";
   /** Whole number, 1–20. Default 1. */
   sets?: number;
+  /** Which way a two-sided board is turned over between sides — the axis far-side layers are mirrored about. Default `"left-right"`. */
+  flip?: "left-right" | "end-over-end";
+  /** Two-sided pieces: one layered file per piece (`"one-file"`, default), or a near file plus a `-far` file (`"two-files"`). */
+  twoSided?: "one-file" | "two-files";
 }
 
 /**
@@ -776,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. */
@@ -798,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>;
@@ -830,6 +842,8 @@ export const KIT_DEFAULTS: Readonly<{
   spacing: number;
   printFormat: "stl";
   sets: number;
+  flip: "left-right";
+  twoSided: "one-file";
 }>;
 
 /** Normalise kit options — defaults filled, `cutFormat` derived — or throw a `"cut kit options: …"` error. */