@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/paperfold/engine.ts

@@ -0,0 +1,852 @@
+import { getPath, phaseSpans, type PaperFoldConfig } from './config';
+import { LAYOUT_FOR, PANELS, PHASES, type AspectRatio, type HandId, type PanelId, type PhaseId } from './controls';
+import { ease } from '../promo/easing';
+import { mixHex, rgba, seeded } from '../promo/engine';
+
+/**
+ * **The paper-fold engine — a pure function from (config, frame, size) to everything on screen.** No
+ * clock, no unseeded randomness, no DOM: the same config, seed and frame always give the same state, so
+ * Remotion can render frames in any order and in parallel, and the live player and the video agree.
+ * The renderer (`PaperFoldFrame`) only draws what this returns.
+ *
+ * **The fold model.** The sheet is three rigid panels hinged at two creases — a kinematic chain. A
+ * fold is a rotation about its crease line (y = crease, z = 0 in the sheet's own frame) by the crease's
+ * dihedral angle; the panel on the moving side (`direction`) turns with it, the panel that stays put
+ * (the anchor) does not, and a panel beyond a moving panel is carried along. Each panel's full pose is
+ * a 4×4 matrix: sheet pose · hinge rotations · the camera's perspective. The renderer hands that
+ * matrix to CSS `matrix3d`, so the panel — its colour, texture and live text — is drawn in true
+ * perspective, turning about the exact crease line. Nothing is scaled to fake a fold.
+ *
+ * Depth is explicit: panels are painted back to front by the depth of their centres, and each hand's
+ * body and gripping finger are slotted in relative to the panel they hold. Lighting is Lambertian on
+ * each panel's normal; a closing crease darkens its valley and shades the panel it closes over.
+ *
+ * Frames here are authored 60 fps motion frames; `outputFrameToMotion` maps an output frame (at
+ * canvas.fps, after motion.speed) onto them.
+ */
+export const MOTION_FPS = 60;
+export { mixHex, rgba, seeded };
+
+const clamp = (v: number, lo = 0, hi = 1) => (v < lo ? lo : v > hi ? hi : v);
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+const RAD = Math.PI / 180;
+const TAU = Math.PI * 2;
+
+type Obj = Record<string, unknown>;
+function reader(cfg: PaperFoldConfig) {
+  return {
+    n: (p: string) => getPath(cfg, p) as number,
+    s: (p: string) => getPath(cfg, p) as string,
+    b: (p: string) => getPath(cfg, p) as boolean,
+    list: <T = Obj>(p: string) => (getPath(cfg, p) as T[]) ?? [],
+  };
+}
+
+/* ─── 4×4 matrices (row-major, column vectors: p' = M · p) ────────────────────────────────────── */
+export type Mat = number[];
+export type Vec3 = [number, number, number];
+const I = (): Mat => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+export function mul(a: Mat, b: Mat): Mat {
+  const o = new Array<number>(16);
+  for (let r = 0; r < 4; r++) for (let c = 0; c < 4; c++) {
+    o[r * 4 + c] = a[r * 4]! * b[c]! + a[r * 4 + 1]! * b[4 + c]! + a[r * 4 + 2]! * b[8 + c]! + a[r * 4 + 3]! * b[12 + c]!;
+  }
+  return o;
+}
+const chain = (...ms: Mat[]) => ms.reduce((acc, m) => mul(acc, m), I());
+const translate = (x: number, y: number, z = 0): Mat => [1, 0, 0, x, 0, 1, 0, y, 0, 0, 1, z, 0, 0, 0, 1];
+const scale3 = (x: number, y: number): Mat => [x, 0, 0, 0, 0, y, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+/** About the x axis. With y down and z toward the viewer, a positive turn brings a point below the axis toward the viewer. */
+const rotX = (a: number): Mat => { const c = Math.cos(a), s = Math.sin(a); return [1, 0, 0, 0, 0, c, -s, 0, 0, s, c, 0, 0, 0, 0, 1]; };
+const rotY = (a: number): Mat => { const c = Math.cos(a), s = Math.sin(a); return [c, 0, s, 0, 0, 1, 0, 0, -s, 0, c, 0, 0, 0, 0, 1]; };
+/** In the picture plane; positive is clockwise on screen (as CSS rotate). */
+const rotZ = (a: number): Mat => { const c = Math.cos(a), s = Math.sin(a); return [c, -s, 0, 0, s, c, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; };
+const skew = (ax: number, ay: number): Mat => [1, Math.tan(ax), 0, 0, Math.tan(ay), 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+/** A viewer at distance d on the z axis, looking at (vx, vy): w = 1 − z/d (CSS perspective). */
+const perspectiveAt = (vx: number, vy: number, d: number): Mat => chain(translate(vx, vy), [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, -1 / d, 1], translate(-vx, -vy));
+/** A turn of `a` radians about the horizontal line y = yc (z = 0): the hinge of a crease. */
+const hinge = (yc: number, a: number): Mat => chain(translate(0, yc), rotX(a), translate(0, -yc));
+export function apply(m: Mat, p: Vec3): [number, number, number, number] {
+  const [x, y, z] = p;
+  return [
+    m[0]! * x + m[1]! * y + m[2]! * z + m[3]!, m[4]! * x + m[5]! * y + m[6]! * z + m[7]!,
+    m[8]! * x + m[9]! * y + m[10]! * z + m[11]!, m[12]! * x + m[13]! * y + m[14]! * z + m[15]!,
+  ];
+}
+/** A point through a projective matrix, onto the picture. */
+export function project(m: Mat, p: Vec3): [number, number] {
+  const [x, y, , w] = apply(m, p);
+  const ww = Math.max(w, 1e-3);
+  return [x / ww, y / ww];
+}
+const r4 = (v: number) => Math.round(v * 1e4) / 1e4;
+/** CSS `matrix3d(...)` (column-major) of a row-major matrix. */
+export function cssMatrix(m: Mat): string {
+  const o: number[] = [];
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o.push(m[r * 4 + c]!);
+  // The perspective row (w) is tiny (≈ 1/distance): keep it at full precision, never in exponent form.
+  return `matrix3d(${o.map((v, i) => (i === 3 || i === 7 || i === 11 ? v.toFixed(12) : String(r4(v)))).join(', ')})`;
+}
+const cross = (a: Vec3, b: Vec3): Vec3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const norm3 = (v: Vec3): Vec3 => { const l = Math.hypot(v[0], v[1], v[2]) || 1; return [v[0] / l, v[1] / l, v[2] / l]; };
+const dot3 = (a: Vec3, b: Vec3) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const linear = (m: Mat, v: Vec3): Vec3 => [m[0]! * v[0] + m[1]! * v[1] + m[2]! * v[2], m[4]! * v[0] + m[5]! * v[1] + m[6]! * v[2], m[8]! * v[0] + m[9]! * v[1] + m[10]! * v[2]];
+
+/* ─── time ────────────────────────────────────────────────────────────────────────────────────── */
+export type PhaseSpan = { id: PhaseId; label: string; start: number; end: number };
+export type Timeline = { phases: Record<PhaseId, PhaseSpan>; order: PhaseSpan[]; end: number; length: number; speed: number };
+
+export function timeline(cfg: PaperFoldConfig): Timeline {
+  const { n, s } = reader(cfg);
+  const order = phaseSpans(cfg).map((p) => ({ id: p.id as PhaseId, label: p.label, start: p.start, end: p.end }));
+  const phases = Object.fromEntries(order.map((p) => [p.id, p])) as Record<PhaseId, PhaseSpan>;
+  const end = Math.max(...order.map((p) => p.end));
+  const speed = n('motion.speed');
+  // `length` is in authored frames: the part of the timeline the video shows.
+  const length = s('canvas.durationMode') === 'fixed' ? (n('canvas.durationFrames') * MOTION_FPS * speed) / n('canvas.fps') : end;
+  return { phases, order, end, length, speed };
+}
+
+/** Output frames for one play of the video at canvas.fps. */
+export function outputDuration(cfg: PaperFoldConfig): number {
+  const { n, s } = reader(cfg);
+  if (s('canvas.durationMode') === 'fixed') return n('canvas.durationFrames');
+  return Math.max(1, Math.round(((timeline(cfg).end / n('motion.speed')) * n('canvas.fps')) / MOTION_FPS));
+}
+/** The authored motion frame an output frame shows. */
+export function outputFrameToMotion(cfg: PaperFoldConfig, frame: number): number {
+  return (frame * MOTION_FPS * (getPath(cfg, 'motion.speed') as number)) / (getPath(cfg, 'canvas.fps') as number);
+}
+/** The output frame that shows an authored motion frame (the inverse of outputFrameToMotion, rounded). */
+export function motionToOutputFrame(cfg: PaperFoldConfig, motion: number): number {
+  return Math.round((motion * (getPath(cfg, 'canvas.fps') as number)) / (MOTION_FPS * (getPath(cfg, 'motion.speed') as number)));
+}
+
+/** The phase playing at motion frame `t` (the last phase that has started), and how far into it. */
+export function phaseAt(tl: Timeline, t: number): { id: PhaseId; label: string; progress: number } {
+  let cur = tl.order[0]!;
+  for (const p of tl.order) if (t >= p.start && p.end > p.start) cur = p;
+  return { id: cur.id, label: cur.label, progress: cur.end > cur.start ? clamp((t - cur.start) / (cur.end - cur.start)) : 1 };
+}
+
+/** Representative motion frames of the seven stages (the render tests and the reference comparison use them). */
+export function stageFrames(cfg: PaperFoldConfig) {
+  const { phases: p, end } = timeline(cfg);
+  const mid = (id: PhaseId) => (p[id].start + p[id].end) / 2;
+  const at = (id: PhaseId, f: number) => p[id].start + (p[id].end - p[id].start) * f;
+  return {
+    OPEN: p.topFold.start - 1 > 0 ? p.topFold.start - 1 : 0,
+    TOP_FOLD: mid('topFold'),
+    TOP_FOLD_BEGIN: p.topFold.start + (p.topFold.end - p.topFold.start) * 0.2,
+    TOP_FOLD_DEEPEST: p.topFold.end,
+    BOTTOM_FOLD: mid('bottomFold'),
+    BOTTOM_FOLD_BEGIN: p.bottomFold.start + (p.bottomFold.end - p.bottomFold.start) * 0.2,
+    FOLDED_HOLD: mid('foldedHold'),
+    BOTTOM_UNFOLD: mid('bottomUnfold'),
+    UNFOLD_BEGIN: p.bottomUnfold.start + (p.bottomUnfold.end - p.bottomUnfold.start) * 0.2,
+    TOP_UNFOLD: mid('topUnfold'),
+    FINAL_OPEN: Math.max(0, end - 1),
+    // The quality-check set: fractions of the top fold, the peaks, halfway through the whole unfold.
+    TOP_FOLD_25: at('topFold', 0.25),
+    TOP_FOLD_75: at('topFold', 0.75),
+    TOP_FOLD_PEAK: p.topFold.end,
+    BOTTOM_FOLD_PEAK: p.bottomFold.end,
+    FULLY_FOLDED: mid('foldedHold'),
+    UNFOLD_50: (p.bottomUnfold.start + p.topUnfold.end) / 2,
+  };
+}
+
+/* ─── folds ───────────────────────────────────────────────────────────────────────────────────── */
+type FoldCfg = {
+  id: 'top' | 'bottom'; enabled: boolean; direction: 'down' | 'up'; side: 'inward' | 'outward';
+  startAngle: number; peakAngle: number; endAngle: number; startScale: number; peakScale: number; endScale: number;
+  edgeLift: number; edgeLiftSize: number; curvature: number; perspective: number; translationX: number; translationY: number; rotationZ: number;
+  delayFrames: number; durationFrames: number; easing: string; unfoldDelayFrames: number; unfoldDurationFrames: number; unfoldEasing: string;
+  shadowIntensity: number; creaseIntensity: number;
+};
+export type FoldState = {
+  id: 'top' | 'bottom';
+  /** The crease's dihedral angle (deg). */
+  angle: number;
+  /** Signed: positive = the fronts close (a valley on the front). */
+  dihedral: number;
+  /** How far toward its peak the fold is (0 = open, 1 = at the peak). */
+  amount: number;
+  /** 0‥1‥0 while the fold or unfold is moving (a half sine), else 0. */
+  activity: number;
+  phase: 'before' | 'folding' | 'folded' | 'unfolding' | 'after' | 'off' | 'manual';
+  scale: number; perspective: number; tx: number; ty: number; rz: number;
+  /** How far the gripped free edge curls ahead of the fold (deg): it lifts first, then the panel folds over. */
+  lift: number;
+};
+/** The edge lift over a fold's progress `p` (0‥1, linear): it rises first and is flat again by 75%. */
+const liftAt = (f: FoldCfg, p: number) => f.edgeLift * Math.max(0, Math.sin(Math.PI * clamp(p / 0.75)));
+
+/**
+ * The folds posed by FOLD PROGRESS (motion.foldProgress, 0‥1) instead of the timeline: the first half
+ * folds the top crease from flat (0°) to its peak, the second half the bottom crease; a single enabled
+ * fold takes the whole range. 0 is the paper completely flat, 1 completely folded.
+ */
+export function manualFolds(folds: FoldCfg[], progress: number): FoldState[] {
+  const on = folds.map((f) => f.enabled);
+  const both = on[0] && on[1];
+  return folds.map((f, k) => {
+    const sigma = f.side === 'inward' ? 1 : -1;
+    const a = !f.enabled ? 0 : both ? clamp(progress * 2 - k) : clamp(progress);
+    const e = ease(f.easing, a, f.durationFrames);
+    const angle = lerp(0, f.peakAngle, e);
+    return {
+      id: f.id, angle, dihedral: sigma * angle, amount: e, activity: 0, phase: 'manual' as const,
+      scale: lerp(1, f.peakScale, e), perspective: lerp(1, f.perspective, e), tx: f.translationX * e, ty: f.translationY * e, rz: f.rotationZ * e,
+      lift: liftAt(f, a),
+    };
+  });
+}
+
+export function foldState(f: FoldCfg, foldSpan: PhaseSpan, unfoldSpan: PhaseSpan, t: number): FoldState {
+  const sigma = f.side === 'inward' ? 1 : -1;
+  if (!f.enabled) return { id: f.id, angle: f.startAngle, dihedral: sigma * f.startAngle, amount: 0, activity: 0, phase: 'off', scale: 1, perspective: 1, tx: 0, ty: 0, rz: 0, lift: 0 };
+  const pf = clamp((t - foldSpan.start) / Math.max(1e-6, foldSpan.end - foldSpan.start));
+  const pu = clamp((t - unfoldSpan.start) / Math.max(1e-6, unfoldSpan.end - unfoldSpan.start));
+  const ef = ease(f.easing, pf, f.durationFrames), eu = ease(f.unfoldEasing, pu, f.unfoldDurationFrames);
+  const unfolding = t >= unfoldSpan.start;
+  let angle: number, amount: number, sc: number;
+  if (!unfolding) {
+    angle = lerp(f.startAngle, f.peakAngle, ef);
+    amount = ef;
+    sc = lerp(f.startScale, f.peakScale, ef);
+  } else {
+    angle = lerp(f.peakAngle, f.endAngle, eu);
+    amount = f.peakAngle === f.startAngle ? 1 - eu : clamp((angle - f.startAngle) / (f.peakAngle - f.startAngle), -0.5, 1.5);
+    sc = lerp(f.peakScale, f.endScale, eu);
+  }
+  angle = clamp(angle, -110, 180);
+  const moving = (!unfolding && pf > 0 && pf < 1) ? Math.sin(Math.PI * pf) : (unfolding && pu > 0 && pu < 1) ? Math.sin(Math.PI * pu) : 0;
+  const phase = t < foldSpan.start ? 'before' : pf < 1 ? 'folding' : !unfolding ? 'folded' : pu < 1 ? 'unfolding' : 'after';
+  return {
+    id: f.id, angle, dihedral: sigma * angle, amount, activity: moving, phase,
+    scale: sc, perspective: lerp(1, f.perspective, clamp(amount, 0, 1.2)), tx: f.translationX * amount, ty: f.translationY * amount, rz: f.rotationZ * amount,
+    // The gripped edge lifts ahead of the fold (linear progress, so it leads the eased turn), and again as it unfolds.
+    lift: !unfolding ? (pf > 0 && pf < 1 ? liftAt(f, pf) : 0) : (pu > 0 && pu < 1 ? liftAt(f, 1 - pu) : 0),
+  };
+}
+
+/* ─── layout ──────────────────────────────────────────────────────────────────────────────────── */
+export type Layout = {
+  width: number; height: number; unit: number; pu: number;
+  shape: 'portrait' | 'landscape' | 'square';
+  paper: { width: number; height: number; pivotX: number; pivotY: number };
+  /** Crease y positions in the sheet (px), top then bottom. */
+  creases: [number, number];
+  panels: Record<PanelId, { y0: number; y1: number; height: number }>;
+  logo: { x: number; y: number; scale: number };
+  cta: { x: number; y: number; scale: number };
+  backgroundType: { scale: number; x: number; y: number };
+  handScale: number;
+};
+
+export function layout(cfg: PaperFoldConfig, width: number, height: number): Layout {
+  const { n, s } = reader(cfg);
+  const shape = LAYOUT_FOR[s('canvas.aspectRatio') as AspectRatio] ?? 'portrait';
+  const L = `layout.${shape}`;
+  const unit = Math.min(width, height) / 1080;
+  const PH = n(`${L}.paper.height`) * height;
+  const PW = PH * n('paper.aspect');
+  const c0 = n('creases.0.position') * PH, c1 = n('creases.1.position') * PH;
+  const safe = n('canvas.safeArea') * Math.min(width, height);
+  const inside = (v: number, size: number) => clamp(v, safe / size, 1 - safe / size);
+  return {
+    width, height, unit, pu: PW / 1000, shape,
+    paper: { width: PW, height: PH, pivotX: n(`${L}.paper.x`) * width, pivotY: n(`${L}.paper.y`) * height },
+    creases: [c0, c1],
+    panels: { top: { y0: 0, y1: c0, height: c0 }, middle: { y0: c0, y1: c1, height: c1 - c0 }, bottom: { y0: c1, y1: PH, height: PH - c1 } },
+    logo: { x: inside(n(`${L}.logo.x`), width) * width, y: inside(n(`${L}.logo.y`), height) * height, scale: n(`${L}.logo.scale`) },
+    cta: { x: inside(n(`${L}.cta.x`), width) * width, y: inside(n(`${L}.cta.y`), height) * height, scale: n(`${L}.cta.scale`) },
+    backgroundType: { scale: n(`${L}.backgroundType.scale`), x: n(`${L}.backgroundType.x`) * unit, y: n(`${L}.backgroundType.y`) * unit },
+    handScale: n(`${L}.handScale`),
+  };
+}
+
+/* ─── the sheet: pose, chain, projection ──────────────────────────────────────────────────────── */
+type SheetExtra = { tx: number; ty: number; rz: number; scale: number };
+export type Anchor = PanelId;
+
+/** The panel that stays put, from the two folds' directions (the validator refuses the one impossible pair). */
+export function anchorOf(folds: { enabled: boolean; direction: 'down' | 'up' }[]): Anchor {
+  const [top, bottom] = folds;
+  if (top!.enabled && top!.direction === 'up') return 'top';
+  if (bottom!.enabled && bottom!.direction === 'down') return 'bottom';
+  return 'middle';
+}
+/** Which folds move a panel relative to the anchor (the hinges between them). */
+export function moversOf(anchor: Anchor, panel: PanelId): number[] {
+  const idx = { top: 0, middle: 1, bottom: 2 };
+  const a = idx[anchor], p = idx[panel];
+  const out: number[] = [];
+  for (let k = Math.min(a, p); k < Math.max(a, p); k++) out.push(k);
+  return out;
+}
+
+/** How many hinges a curved crease is spread over (its bend is drawn as that many narrow strips). */
+export const BEND_SEGMENTS = 6;
+/** The widest bend band, as a fraction of the shorter panel beside the crease (at curvature 1). */
+const MAX_BEND = 0.22;
+
+/**
+ * One strip of the sheet: the flat part of a panel, or one narrow step of a crease's bend. Strips are
+ * cut from the ONE sheet at its hinge lines, so neighbouring strips share their edge exactly.
+ */
+export type Strip = { index: number; y0: number; y1: number; region: PanelId | 'crease0' | 'crease1'; T: Mat; /** Part of a free edge's lift curl. */ lift?: boolean };
+export type Sheet = {
+  anchor: Anchor;
+  /** Sheet pose (sheet px → canvas px, in 3D). */
+  S: Mat;
+  /** The strips, top to bottom, each with its place in the sheet frame (the hinge chain). */
+  strips: Strip[];
+  /** Each panel's flat strip. */
+  T: Record<PanelId, Mat>;
+  /** The bend band of each crease (sheet px), [start, end]; equal when the crease is sharp. */
+  bands: [[number, number], [number, number]];
+  /** The camera's perspective. */
+  P: Mat;
+};
+
+/** Hinges near the sheet's free edges that curl the gripped edge (EDGE_LIFT_SEGMENTS per edge). */
+export const EDGE_LIFT_SEGMENTS = 4;
+type Lift = { top: number; bottom: number; topSize: number; bottomSize: number };
+function buildSheet(cfg: PaperFoldConfig, lay: Layout, dihedrals: [number, number], curvatures: [number, number], perspectiveFactor: number, extra: SheetExtra, anchor: Anchor, lift: Lift = { top: 0, bottom: 0, topSize: 0, bottomSize: 0 }): Sheet {
+  const { n } = reader(cfg);
+  const { width: PW, height: PH, pivotX, pivotY } = lay.paper;
+  const u = lay.unit;
+  const sc = n('paper.scale') * extra.scale;
+  const S = chain(
+    translate(pivotX + (n('paper.translateX') + extra.tx) * u, pivotY + (n('paper.translateY') + extra.ty) * u),
+    rotZ((n('paper.rotationZ') + extra.rz) * RAD),
+    rotY(n('paper.rotationY') * RAD),
+    rotX(n('paper.rotationX') * RAD),
+    skew(n('paper.skewX') * RAD, n('paper.skewY') * RAD),
+    scale3(n('paper.scaleX') * sc, n('paper.scaleY') * sc),
+    translate(-n('paper.originX') * PW, -n('paper.originY') * PH),
+  );
+  // Hinges: a sharp crease is one hinge carrying the whole dihedral; a curved one spreads it evenly
+  // over BEND_SEGMENTS hinges across a band centred on the crease — a bend, not a card rotation.
+  const hinges: { y: number; a: number }[] = [];
+  const bands = ([0, 1] as const).map((k) => {
+    const yc = lay.creases[k];
+    const beside = Math.min(k === 0 ? lay.panels.top.height : lay.panels.middle.height, k === 0 ? lay.panels.middle.height : lay.panels.bottom.height);
+    const L = curvatures[k] * MAX_BEND * beside;
+    if (L < 0.5) { hinges.push({ y: yc, a: dihedrals[k] }); return [yc, yc] as [number, number]; }
+    for (let i = 0; i < BEND_SEGMENTS; i++) hinges.push({ y: yc - L / 2 + ((i + 0.5) * L) / BEND_SEGMENTS, a: dihedrals[k] / BEND_SEGMENTS });
+    return [yc - L / 2, yc + L / 2] as [number, number];
+  }) as Sheet['bands'];
+  // The lift curl: a few hinges across a band at a free edge, sharing its lift angle, so that edge rolls up.
+  const liftHinges: { y: number; a: number }[] = [];
+  if (lift.topSize > 0) for (let i = 0; i < EDGE_LIFT_SEGMENTS; i++) liftHinges.push({ y: ((i + 1) / (EDGE_LIFT_SEGMENTS + 1)) * lift.topSize * lay.panels.top.height, a: lift.top / EDGE_LIFT_SEGMENTS });
+  if (lift.bottomSize > 0) for (let i = 0; i < EDGE_LIFT_SEGMENTS; i++) liftHinges.push({ y: PH - ((EDGE_LIFT_SEGMENTS - i) / (EDGE_LIFT_SEGMENTS + 1)) * lift.bottomSize * lay.panels.bottom.height, a: lift.bottom / EDGE_LIFT_SEGMENTS });
+  hinges.push(...liftHinges);
+  hinges.sort((a, b) => a.y - b.y);
+  const liftTop = lift.topSize > 0 ? lift.topSize * lay.panels.top.height : -1, liftBottom = lift.bottomSize > 0 ? PH - lift.bottomSize * lay.panels.bottom.height : PH + 1;
+  const edges = [0, ...hinges.map((h) => h.y), PH];
+  const regionOf = (mid: number): Strip['region'] =>
+    mid < bands[0][0] ? 'top' : mid < bands[0][1] ? 'crease0' : mid < bands[1][0] ? 'middle' : mid < bands[1][1] ? 'crease1' : 'bottom';
+  const strips: Strip[] = edges.slice(0, -1).map((y0, i) => {
+    const y1 = edges[i + 1]!, mid = (y0 + y1) / 2;
+    return { index: i, y0, y1, region: regionOf(mid), T: I(), ...(mid < liftTop || mid > liftBottom ? { lift: true } : {}) };
+  });
+  // Walk the chain outward from the anchored panel's flat part: below a hinge the next strip turns by
+  // the hinge's angle about the hinge line; above it, by the inverse.
+  const flatOf = (id: PanelId) => strips.reduce((best, st, i) => (st.region === id && !st.lift && (best < 0 || st.y1 - st.y0 > strips[best]!.y1 - strips[best]!.y0) ? i : best), -1);
+  const a = flatOf(anchor);
+  for (let i = a + 1; i < strips.length; i++) strips[i]!.T = mul(strips[i - 1]!.T, hinge(hinges[i - 1]!.y, hinges[i - 1]!.a * RAD));
+  for (let i = a - 1; i >= 0; i--) strips[i]!.T = mul(strips[i + 1]!.T, hinge(hinges[i]!.y, -hinges[i]!.a * RAD));
+  const T = Object.fromEntries(PANELS.map((id) => [id, strips[flatOf(id)]!.T])) as Record<PanelId, Mat>;
+  const [vx, vy] = project(S, [n('camera.vanishX') * PW, n('camera.vanishY') * PH, 0]);
+  const P = perspectiveAt(vx, vy, (n('camera.perspective') * u) / perspectiveFactor);
+  return { anchor, S, strips, T, bands, P };
+}
+/** The strip that carries sheet height `y` (px). */
+export function stripAt(sheet: Sheet, y: number): Strip {
+  return sheet.strips.find((st) => y >= st.y0 && y <= st.y1) ?? (y < 0 ? sheet.strips[0]! : sheet.strips.at(-1)!);
+}
+
+/* ─── lighting ────────────────────────────────────────────────────────────────────────────────── */
+function lightVector(cfg: PaperFoldConfig): Vec3 {
+  const { n } = reader(cfg);
+  const az = n('foldLighting.lightAngle') * RAD, el = n('foldLighting.lightElevation') * RAD;
+  return norm3([Math.cos(el) * Math.cos(az), Math.cos(el) * Math.sin(az), Math.sin(el)]);
+}
+
+/* ─── state ───────────────────────────────────────────────────────────────────────────────────── */
+export type EdgeFx = {
+  edge: 'top' | 'bottom';
+  crease: 0 | 1;
+  line: { opacity: number; width: number; blur: number; color: string };
+  highlight: { opacity: number; width: number; color: string };
+  valley: { opacity: number; length: number };
+  shadow: { opacity: number; length: number; blur: number };
+};
+/** One drawn strip of the sheet. */
+export type StripState = {
+  index: number;
+  region: Strip['region'];
+  /** Sheet heights (px) the strip covers. */
+  y0: number; y1: number;
+  /** CSS matrix3d placing the strip's box (0‥paper width × 0‥height) on the canvas. */
+  matrix: string;
+  corners: [number, number][];
+  facing: 'front' | 'back';
+  depth: number;
+  rank: number;
+  z: number;
+  brightness: number;
+  sheen: number;
+  /** 0 = facing the viewer, 1 = edge-on: how much of the paper's cut edge (thickness) shows. */
+  edgeOn: number;
+  lift?: boolean;
+};
+export type TextFit = { slot: string; panel: PanelId; x: number; y: number; width: number; fontSize: number; scale: number; lines: number; area: { x: number; y: number; width: number; height: number } };
+export type PanelState = {
+  id: PanelId;
+  y0: number; height: number; width: number;
+  /** CSS matrix3d placing the panel's box (0‥width × 0‥height) on the canvas. */
+  matrix: string;
+  /** Projected corners: top-left, top-right, bottom-right, bottom-left. */
+  corners: [number, number][];
+  facing: 'front' | 'back';
+  /** Depth of the panel's centre (px toward the viewer, before perspective). */
+  depth: number;
+  /** Paint order: 0 = furthest back. */
+  rank: number;
+  z: number;
+  brightness: number;
+  sheen: number;
+  edges: EdgeFx[];
+};
+export type HandState = {
+  id: HandId;
+  enabled: boolean;
+  panel: PanelId;
+  /** Where the hand's grip point is drawn (canvas px) and its pose. */
+  x: number; y: number; rotation: number; scale: number; skewX: number; skewY: number; opacity: number;
+  /** Local offset of the drawing from its grip point (hand units). */
+  offsetX: number; offsetY: number;
+  fingerAngle: number;
+  /** The grip point on the paper, exactly (canvas px): the debug anchor. */
+  gripX: number; gripY: number;
+  bodyZ: number; fingerZ: number;
+  /** Hand units → px: the drawing's reference paper width is 600 units. */
+  unitScale: number;
+  /** The pose the art is built with. */
+  pose: { wrist: number; fingerCurl: number; thumbBend: number; thumbRotation: number; thumbScale: number; thumbX: number; thumbY: number };
+};
+export type FrameState = {
+  cfg: PaperFoldConfig;
+  frame: number;
+  size: Layout;
+  timeline: Timeline;
+  phase: { id: PhaseId; label: string; progress: number };
+  folds: FoldState[];
+  anchor: Anchor;
+  panels: PanelState[];
+  /** The sheet as drawn: its strips (flat panel parts and crease bends), each placed by its own matrix. */
+  strips: StripState[];
+  /** Bend band of each crease in sheet px. */
+  bands: [[number, number], [number, number]];
+  /** Where each text element sits on its panel, fitted into the panel's content area. */
+  text: TextFit[];
+  /** The grip anchors: the point on the paper, and where the hand's grip point is drawn (canvas px). */
+  anchors: Record<HandId, { paper: [number, number]; hand: [number, number] }>;
+  hands: HandState[];
+  camera: { transform: string; backgroundTransform: string; zoom: number };
+  /** Projected outline of each panel, for the sheet's cast shadow (px). */
+  shadowQuads: [number, number][][];
+  sheetCentre: [number, number];
+  background: { typeRows: { y: number; x: number }[]; typeRepeat: number };
+  logo: { x: number; y: number; opacity: number; scale: number };
+  cta: { x: number; y: number; opacity: number; scale: number };
+  debug: { creases: { id: string; from: [number, number]; to: [number, number]; position: number; angle: number }[] };
+};
+
+/** Where the hand is pulled (x, y, rot, scale) and the grip it follows (bx, by), which it rides exactly. */
+type HandTarget = { x: number; y: number; rot: number; scale: number; bx: number; by: number };
+
+/** Everything the frame needs from the fold state at motion frame t (no hands). */
+function sheetAt(cfg: PaperFoldConfig, lay: Layout, tl: Timeline, t: number) {
+  const { n, s, b, list } = reader(cfg);
+  const foldsCfg = list<FoldCfg>('folds');
+  const manual = s('motion.progressMode') === 'manual';
+  const folds = manual
+    ? manualFolds(foldsCfg, n('motion.foldProgress'))
+    : foldsCfg.map((f, k) => foldState(f, tl.phases[k === 0 ? 'topFold' : 'bottomFold'], tl.phases[k === 0 ? 'topUnfold' : 'bottomUnfold'], t));
+  const anchor = anchorOf(foldsCfg);
+  // Idle sway and bob; the intro rise.
+  const rnd = seeded(n('canvas.seed'));
+  const ph1 = rnd() * TAU, ph2 = rnd() * TAU;
+  const sec = t / MOTION_FPS;
+  const idle = b('motion.idle.enabled');
+  const swayRz = idle ? n('motion.idle.swayAngle') * Math.sin(TAU * n('motion.idle.frequency') * sec + ph1) : 0;
+  const bob = idle ? n('motion.idle.bobAmplitude') * Math.sin(TAU * n('motion.idle.frequency') * 1.31 * sec + ph2) : 0;
+  const intro = tl.phases.intro;
+  const eIntro = ease(s('timeline.intro.easing'), (t - intro.start) / Math.max(1, intro.end - intro.start), intro.end - intro.start);
+  const rise = s('motion.intro.mode') === 'rise' ? 1 - eIntro : 0;
+  const hold = tl.phases.foldedHold;
+  const pHold = hold.end > hold.start ? clamp((t - hold.start) / (hold.end - hold.start)) : 0;
+  const squeeze = lerp(1, n('motion.holdSqueeze'), Math.sin(Math.PI * ease(s('timeline.foldedHold.easing'), pHold, hold.end - hold.start)));
+  const base: SheetExtra = { tx: 0, ty: bob + n('motion.intro.paperOffsetY') * rise, rz: swayRz + n('motion.intro.paperRotation') * rise, scale: 1 };
+  const withFolds: SheetExtra = {
+    tx: base.tx + folds.reduce((a, f) => a + f.tx, 0),
+    ty: base.ty + folds.reduce((a, f) => a + f.ty, 0),
+    rz: base.rz + folds.reduce((a, f) => a + f.rz, 0),
+    scale: folds.reduce((a, f) => a * f.scale, 1) * squeeze,
+  };
+  const persp = folds.reduce((a, f) => a * f.perspective, 1);
+  const curv = foldsCfg.map((f) => f.curvature) as [number, number];
+  // The free edge each fold swings (down: the sheet's top edge; up: its bottom edge) lifts ahead of it.
+  const lift: Lift = { top: 0, bottom: 0, topSize: 0, bottomSize: 0 };
+  foldsCfg.forEach((f, k) => {
+    if (!f.enabled || f.edgeLift <= 0) return;
+    const sign = f.side === 'inward' ? 1 : -1;
+    if (f.direction === 'down') { lift.top += sign * folds[k]!.lift; lift.topSize = Math.max(lift.topSize, f.edgeLiftSize); } else { lift.bottom += sign * folds[k]!.lift; lift.bottomSize = Math.max(lift.bottomSize, f.edgeLiftSize); }
+  });
+  const sheet = buildSheet(cfg, lay, [folds[0]!.dihedral, folds[1]!.dihedral], curv, persp, withFolds, anchor, lift);
+  // The same sheet with every crease at its start angle and no fold-driven motion: where the hands rest.
+  const restDihedrals = foldsCfg.map((f) => (f.side === 'inward' ? 1 : -1) * f.startAngle) as [number, number];
+  const rest = buildSheet(cfg, lay, restDihedrals, curv, 1, base, anchor, { ...lift, top: 0, bottom: 0 });
+  return { folds, anchor, sheet, rest, foldsCfg, manual };
+}
+
+function panelOf(cfg: PaperFoldConfig, gy: number): PanelId {
+  const c0 = getPath(cfg, 'creases.0.position') as number, c1 = getPath(cfg, 'creases.1.position') as number;
+  return gy < c0 ? 'top' : gy < c1 ? 'middle' : 'bottom';
+}
+
+/** Where a paper point is on the picture, and the paper's local direction and scale there. */
+function gripOn(sheet: Sheet, lay: Layout, _panel: PanelId, gx: number, gy: number) {
+  const q: Vec3 = [gx * lay.paper.width, gy * lay.paper.height, 0];
+  const M = chain(sheet.P, sheet.S, stripAt(sheet, q[1]).T);
+  const g = project(M, q);
+  const e = project(M, [q[0] + 10, q[1], 0]);
+  return { x: g[0], y: g[1], angle: Math.atan2(e[1] - g[1], e[0] - g[0]) / RAD, scale: Math.hypot(e[0] - g[0], e[1] - g[1]) / 10 };
+}
+
+/** The pose a hand is pulled toward at motion frame t (before its settle spring). */
+function handTarget(cfg: PaperFoldConfig, lay: Layout, tl: Timeline, id: HandId, t: number): HandTarget {
+  const { n, s } = reader(cfg);
+  const H = `hands.${id}`, HI = `handInteraction.${id}`;
+  const lead = n(`${HI}.leadFrames`);
+  const gx = n(`${H}.x`), gy = n(`${H}.y`);
+  const panel = panelOf(cfg, gy);
+  const at = sheetAt(cfg, lay, tl, t + lead);
+  const now = gripOn(at.sheet, lay, panel, gx, gy);
+  const rest = gripOn(at.rest, lay, panel, gx, gy);
+  const follow = n(`${HI}.followStrength`);
+  const movers = moversOf(at.anchor, panel);
+  const own = movers.map((k) => at.folds[k]!);
+  const amount = own.reduce((a, f) => Math.max(a, clamp(f.amount)), 0);
+  const tugActivity = own.reduce((a, f) => Math.max(a, f.activity), 0);
+  const anyActivity = at.folds.reduce((a, f) => Math.max(a, f.activity), 0);
+  const bx = rest.x + follow * (now.x - rest.x), by = rest.y + follow * (now.y - rest.y);
+  let x = bx, y = by;
+  // The tug: the hand pulls ahead along the way its grip point is travelling.
+  if (tugActivity > 0) {
+    const ahead = gripOn(sheetAt(cfg, lay, tl, t + lead + 2).sheet, lay, panel, gx, gy);
+    const dx = ahead.x - now.x, dy = ahead.y - now.y, len = Math.hypot(dx, dy);
+    if (len > 1e-3) { x += (dx / len) * n(`${HI}.gripOffset`) * lay.pu * tugActivity; y += (dy / len) * n(`${HI}.gripOffset`) * lay.pu * tugActivity; }
+  }
+  // Bracing: while any fold moves, the hand leans toward the sheet's centre.
+  if (anyActivity > 0) {
+    const c = project(chain(at.sheet.P, at.sheet.S), [lay.paper.width / 2, lay.paper.height / 2, 0]);
+    const dx = c[0] - rest.x, dy = c[1] - rest.y, len = Math.hypot(dx, dy) || 1;
+    x += (dx / len) * n(`${HI}.movementAmplitude`) * lay.pu * anyActivity;
+    y += (dy / len) * n(`${HI}.movementAmplitude`) * lay.pu * anyActivity;
+  }
+  // The approach from off the paper (none in manual mode: the hands already hold it).
+  if (s('motion.intro.mode') === 'hands' && s('motion.progressMode') !== 'manual') {
+    const intro = tl.phases.intro, delay = n(`${HI}.enterDelayFrames`);
+    const dur = Math.max(1, intro.end - intro.start - delay);
+    const e = ease(s('timeline.intro.easing'), (t - intro.start - delay) / dur, dur);
+    x += n(`${HI}.enterFromX`) * lay.width * (1 - e);
+    y += n(`${HI}.enterFromY`) * lay.height * (1 - e);
+  }
+  const rot = n(`${H}.rotation`) + follow * angleDelta(now.angle, rest.angle) + n(`${HI}.rotationAmplitude`) * amount;
+  const scale = n(`${H}.scale`) * (1 + follow * (now.scale / Math.max(1e-3, rest.scale) - 1));
+  return { x, y, rot, scale, bx, by };
+}
+const angleDelta = (a: number, b: number) => { let d = a - b; while (d > 180) d -= 360; while (d < -180) d += 360; return d; };
+
+/**
+ * The hands' settle is a damped spring pulled toward the target, integrated from frame 0 in fixed
+ * one-frame steps — so any frame, sampled on its own and in any order, gets the same pose. The
+ * trajectory is cached per config object and size.
+ */
+const TRAJECTORIES = new WeakMap<object, Map<string, HandTarget[]>>();
+function handPose(cfg: PaperFoldConfig, lay: Layout, tl: Timeline, id: HandId, t: number): HandTarget {
+  // FOLD PROGRESS poses the paper directly: the hands sit exactly on their grip, no settle to play out.
+  if (getPath(cfg, 'motion.progressMode') === 'manual') return handTarget(cfg, lay, tl, id, t);
+  const key = `${id}:${lay.width}x${lay.height}`;
+  let byKey = TRAJECTORIES.get(cfg);
+  if (!byKey) { byKey = new Map(); TRAJECTORIES.set(cfg, byKey); }
+  let traj = byKey.get(key);
+  if (!traj) { traj = []; byKey.set(key, traj); }
+  const HI = `handInteraction.${id}`;
+  const zeta = getPath(cfg, `${HI}.bounce`) as number;
+  // One-frame steps stay stable while ω ≤ 1 (a settle of at least ~4/ζ frames).
+  const omega = Math.min(1, 4 / (zeta * (getPath(cfg, `${HI}.settleDuration`) as number)));
+  const target = Math.max(0, Math.ceil(t));
+  // The spring carries only what the hand adds to its grip (the approach, the bracing, the wrist turn):
+  // the grip point itself is ridden exactly, so the fingers never trail the paper however fast it folds.
+  const offset = (g: HandTarget): HandTarget => ({ ...g, x: g.x - g.bx, y: g.y - g.by });
+  if (!traj.length) traj.push(offset(handTarget(cfg, lay, tl, id, 0)));
+  // Velocities are recomputed from the last two samples, so the cache holds only poses.
+  while (traj.length <= target) {
+    const k = traj.length;
+    const cur = traj[k - 1]!, prev = traj[k - 2] ?? cur;
+    const goal = offset(handTarget(cfg, lay, tl, id, k));
+    const step = (x: number, px: number, g: number) => {
+      let v = x - px;
+      v += -2 * zeta * omega * v - omega * omega * (x - g);
+      return x + v;
+    };
+    traj.push({ x: step(cur.x, prev.x, goal.x), y: step(cur.y, prev.y, goal.y), rot: step(cur.rot, prev.rot, goal.rot), scale: step(cur.scale, prev.scale, goal.scale), bx: 0, by: 0 });
+  }
+  const f = Math.max(0, Math.floor(t)), fr = t <= 0 ? 0 : t - f;
+  const a = traj[f]!, bb = traj[Math.min(f + 1, traj.length - 1)]!;
+  const now = handTarget(cfg, lay, tl, id, Math.max(0, t));
+  return { x: now.bx + lerp(a.x, bb.x, fr), y: now.by + lerp(a.y, bb.y, fr), rot: lerp(a.rot, bb.rot, fr), scale: lerp(a.scale, bb.scale, fr), bx: now.bx, by: now.by };
+}
+
+const TEXT_SLOTS: { slot: string; path: string; panel: PanelId }[] = [
+  { slot: 'topLogo', path: 'content.top.logo', panel: 'top' }, { slot: 'topHeadline', path: 'content.top.headline', panel: 'top' },
+  { slot: 'topSubtitle', path: 'content.top.subtitle', panel: 'top' }, { slot: 'middleHeadline', path: 'content.middle.headline', panel: 'middle' },
+  { slot: 'middleBody', path: 'content.middle.body', panel: 'middle' }, { slot: 'bottomHeadline', path: 'content.bottom.headline', panel: 'bottom' },
+  { slot: 'bottomBody', path: 'content.bottom.body', panel: 'bottom' }, { slot: 'bottomCta', path: 'content.bottom.cta', panel: 'bottom' },
+];
+/**
+ * How many lines `text` wraps to at `width` px: greedy word wrap on an estimated advance (an average
+ * glyph is ≈ 0.52 em at weight 400, a little wider when heavier, plus the tracking). Pure and
+ * deterministic; the renderer's own wrapping may differ by a word, and the content area clips anyway.
+ */
+export function estimateLines(text: string, fontSize: number, width: number, weight: number, tracking: number): number {
+  const em = fontSize * (0.5 + Math.max(0, weight - 300) * 0.00016 + tracking);
+  const maxChars = Math.max(1, Math.floor(width / Math.max(0.1, em)));
+  let lines = 0;
+  for (const para of text.split('\n')) {
+    let cur = 0;
+    lines++;
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      const need = (cur ? cur + 1 : 0) + word.length;
+      if (need > maxChars && cur) { lines++; cur = word.length; } else cur = need;
+    }
+  }
+  return lines;
+}
+/** Every text element placed on its panel and fitted into the panel's content area. */
+export function textFits(cfg: PaperFoldConfig, lay: Layout): TextFit[] {
+  const { n, s, b } = reader(cfg);
+  const PW = lay.paper.width;
+  const out: TextFit[] = [];
+  for (const { slot, path, panel } of TEXT_SLOTS) {
+    const text = s(path);
+    if (!text) continue;
+    const T = `typography.${slot}`, A = `panels.${panel}.contentArea`;
+    const h = lay.panels[panel].height, pad = n(`${A}.padding`) * lay.pu;
+    const area = { x: n(`${A}.x`) * PW + pad, y: n(`${A}.y`) * h + pad, width: Math.max(1, n(`${A}.width`) * PW - 2 * pad), height: Math.max(1, n(`${A}.height`) * h - 2 * pad) };
+    const x = n(`${T}.x`) * PW, y = n(`${T}.y`) * h, size = n(`${T}.fontSize`) * lay.pu;
+    const overflow = b(`panels.${panel}.overflow`);
+    const width = overflow ? n(`${T}.maxWidth`) * PW : Math.max(1, Math.min(n(`${T}.maxWidth`) * PW, area.x + area.width - Math.max(x, area.x)));
+    let scale = 1, lines = estimateLines(text, size, width, n(`${T}.fontWeight`), n(`${T}.letterSpacing`));
+    if (!overflow) {
+      const room = area.y + area.height - Math.max(y, area.y);
+      while (scale > 0.4 && lines * n(`${T}.lineHeight`) * size * scale > room) {
+        scale -= 0.04;
+        lines = estimateLines(text, size * scale, width, n(`${T}.fontWeight`), n(`${T}.letterSpacing`));
+      }
+    }
+    out.push({ slot, panel, x: overflow ? x : Math.max(x, area.x), y: overflow ? y : Math.max(y, area.y), width, fontSize: size * scale, scale: Math.round(scale * 100) / 100, lines, area });
+  }
+  return out;
+}
+
+/** Everything drawn at motion frame `frame` on a `width` × `height` canvas. */
+export function frameState(cfg: PaperFoldConfig, frame: number, width: number, height: number): FrameState {
+  const { n, s, b, list } = reader(cfg);
+  const lay = layout(cfg, width, height);
+  const tl = timeline(cfg);
+  const t = clamp(frame, 0, Math.max(0, tl.length));
+  const { folds, anchor, sheet, foldsCfg } = sheetAt(cfg, lay, tl, t);
+  const L = lightVector(cfg);
+  const PW = lay.paper.width;
+  const creases = list<{ enabled: boolean; width: number; color: string; opacity: number; darkness: number; softness: number; highlight: number; highlightColor: string; position: number }>('creases');
+
+  /* strips: the one sheet, cut at its hinges */
+  const halfway = norm3([L[0], L[1], L[2] + 1]);
+  const rawStrips = sheet.strips.map((st) => {
+    const h = st.y1 - st.y0;
+    const world = mul(sheet.S, st.T);
+    const M = chain(sheet.P, world, translate(0, st.y0));
+    const corners = ([[0, 0], [PW, 0], [PW, h], [0, h]] as [number, number][]).map(([x, y]) => project(M, [x, y, 0]));
+    let area = 0;
+    for (let i = 0; i < 4; i++) { const [x1, y1] = corners[i]!, [x2, y2] = corners[(i + 1) % 4]!; area += x1 * y2 - x2 * y1; }
+    const facing: 'front' | 'back' = area >= 0 ? 'front' : 'back';
+    const centre = apply(world, [PW / 2, st.y0 + h / 2, 0]);
+    let normal = norm3(cross(linear(world, [1, 0, 0]), linear(world, [0, 1, 0])));
+    if (facing === 'back') normal = [-normal[0], -normal[1], -normal[2]];
+    const panel: PanelId = st.region === 'crease0' ? ((st.y0 + st.y1) / 2 < lay.creases[0] ? 'top' : 'middle') : st.region === 'crease1' ? ((st.y0 + st.y1) / 2 < lay.creases[1] ? 'middle' : 'bottom') : st.region;
+    const brightness = n('foldLighting.ambient') + n('foldLighting.diffuse') * Math.max(0, dot3(normal, L)) + n(`panels.${panel}.shade`) + (facing === 'back' ? n('foldLighting.backShade') : 0);
+    const sheen = n('foldLighting.highlightOpacity') * n(`panels.${panel}.highlightOpacity`) * Math.pow(Math.max(0, dot3(normal, halfway)), 24);
+    return { st, M, corners, facing, depth: centre[2], brightness, sheen, edgeOn: 1 - Math.abs(normal[2]) };
+  });
+  /* explicit depth order: back to front by the depth of each strip's centre (ties keep top → bottom) */
+  const order = [...rawStrips].sort((a, c) => a.depth - c.depth || a.st.index - c.st.index);
+  const STRIP_Z0 = 100, STRIP_STEP = 4;
+  const strips: StripState[] = rawStrips.map((r) => {
+    const rank = order.indexOf(r);
+    return {
+      index: r.st.index, region: r.st.region, y0: r.st.y0, y1: r.st.y1, matrix: cssMatrix(r.M), corners: r.corners, facing: r.facing,
+      depth: r.depth, rank, z: STRIP_Z0 + rank * STRIP_STEP, brightness: r.brightness, sheen: r.sheen, edgeOn: r.edgeOn, ...(r.st.lift ? { lift: true } : {}),
+    };
+  });
+  /** A sheet point on the picture, through the strip that carries it. */
+  const onPicture = (x: number, y: number) => project(chain(sheet.P, sheet.S, stripAt(sheet, y).T), [x, y, 0]);
+
+  /* crease effects on each panel's edges (drawn in sheet coordinates, on whichever strips carry them) */
+  const heightOf = (id: PanelId) => lay.panels[id].height;
+  const edgeFx = (id: PanelId, facing: 'front' | 'back'): EdgeFx[] => {
+    const out: EdgeFx[] = [];
+    const adj: [0 | 1, 'top' | 'bottom', PanelId][] = id === 'top' ? [[0, 'bottom', 'middle']] : id === 'middle' ? [[0, 'top', 'top'], [1, 'bottom', 'bottom']] : [[1, 'top', 'middle']];
+    for (const [k, edge, other] of adj) {
+      const c = creases[k]!, f = folds[k]!, fc = foldsCfg[k]!;
+      const closed = Math.abs(f.dihedral) / 180;
+      // Seen from the front, a positive dihedral (the fronts closing) is a valley; seen from the back, a ridge.
+      const concave = (facing === 'front') === (f.dihedral > 0) && Math.abs(f.dihedral) > 0.5;
+      const lineOpacity = c.enabled ? c.opacity * n('paperMaterial.creaseShadow') * clamp(n('paperMaterial.creaseTexture') + (1 - n('paperMaterial.creaseTexture')) * clamp(closed * fc.creaseIntensity)) : 0;
+      const moving = moversOf(anchor, id).includes(k);
+      const edgeLight = !concave && moving ? n('foldLighting.edgeHighlight') * Math.abs(Math.sin(f.dihedral * RAD)) : 0;
+      const shadowLen = Math.min(heightOf(id), heightOf(other) * (1 - Math.cos(f.dihedral * RAD)) / 2 + n('foldLighting.shadowOffset') * lay.pu);
+      out.push({
+        edge, crease: k,
+        line: { opacity: clamp(lineOpacity), width: c.width * lay.pu, blur: c.softness * lay.pu, color: c.color },
+        highlight: {
+          opacity: concave ? 0 : clamp(((c.enabled ? c.highlight * (0.35 + 0.65 * clamp(closed * fc.creaseIntensity)) : 0) + edgeLight) * n('paperMaterial.creaseHighlight')),
+          width: Math.max(c.width * lay.pu * 0.8, n('paper.thickness') * lay.pu * clamp(closed * 1.6)), color: c.highlightColor,
+        },
+        valley: { opacity: concave ? clamp(n('foldLighting.creaseDarkness') * c.darkness * 2 * clamp(closed * fc.creaseIntensity)) : 0, length: 70 * lay.pu * (0.4 + closed) },
+        shadow: {
+          opacity: concave ? n('foldLighting.shadowOpacity') * fc.shadowIntensity * n(`panels.${id}.shadowOpacity`) * clamp(closed * 1.4) ** 1.5 : 0,
+          length: Math.max(0, shadowLen), blur: n('foldLighting.shadowBlur') * lay.pu,
+        },
+      });
+    }
+    return out;
+  };
+
+  /* panels: the three regions of the sheet, summarized (their flat strip gives facing, light and depth) */
+  const panels: PanelState[] = PANELS.map((id) => {
+    const { y0, y1, height: h } = lay.panels[id];
+    const flat = strips.filter((st) => st.region === id && !st.lift).reduce((a, b) => (b.y1 - b.y0 > a.y1 - a.y0 ? b : a));
+    const corners: [number, number][] = [onPicture(0, y0), onPicture(PW, y0), onPicture(PW, y1), onPicture(0, y1)];
+    return {
+      id, y0, height: h, width: PW, matrix: flat.matrix, corners, facing: flat.facing, depth: flat.depth,
+      rank: flat.rank, z: flat.z, brightness: flat.brightness, sheen: flat.sheen, edges: edgeFx(id, flat.facing),
+    };
+  });
+
+  /* text: each element in its panel's content area, shrunk to fit unless the panel allows overflow */
+  const text = textFits(cfg, lay);
+
+  /* hands */
+  const hands: HandState[] = (['top', 'bottom'] as HandId[]).map((id, i) => {
+    const H = `hands.${id}`, HI = `handInteraction.${id}`;
+    const gx = n(`${H}.x`), gy = n(`${H}.y`);
+    const panelId = panelOf(cfg, gy);
+    const panel = panels.find((p) => p.id === panelId)!;
+    const pose = handPose(cfg, lay, tl, id, t);
+    const exact = gripOn(sheet, lay, panelId, gx, gy);
+    const intro = tl.phases.intro, delay = n(`${HI}.enterDelayFrames`);
+    const manualMode = s('motion.progressMode') === 'manual';
+    const approach = s('motion.intro.mode') === 'hands' && !manualMode ? clamp((t - intro.start - delay) / Math.max(1, intro.end - intro.start - delay)) : 1;
+    const closeOn = ease(s('easing.fingerGrip'), clamp((approach - 0.55) / 0.45), 30);
+    // Contact → grip → pull → fold → stabilize; while the paper holds folded the hand eases its grip,
+    // then takes it again before the paper unfolds.
+    const hold = tl.phases.foldedHold, rf = n(`${HI}.releaseFrames`);
+    const release = manualMode || hold.end <= hold.start ? 0 : Math.min(clamp((t - hold.start) / rf), clamp((hold.end - t) / rf));
+    const grip = closeOn * (1 - n(`${HI}.releaseAmount`) * ease('easeInOut', release, rf));
+    // Front-facing: the body is behind the whole sheet and the finger lies on the panel's front.
+    // Turned over: what was behind the panel is now in front of it, so the two swap.
+    const front = panel.facing === 'front';
+    return {
+      id, enabled: b(`${H}.enabled`), panel: panelId,
+      x: pose.x, y: pose.y, rotation: pose.rot, scale: pose.scale * lay.handScale, skewX: n(`${H}.skewX`), skewY: n(`${H}.skewY`), opacity: n(`${H}.opacity`),
+      offsetX: n(`${H}.offsetX`) * 0.6, offsetY: n(`${H}.offsetY`) * 0.6,
+      // Open by gripAngle before the grip closes; once holding, open by whatever pose.grip leaves open.
+      fingerAngle: n(`${HI}.gripAngle`) * (1 - grip * n(`${H}.pose.grip`)),
+      gripX: exact.x, gripY: exact.y,
+      bodyZ: front ? 20 + i : panel.z + 2,
+      fingerZ: front ? panel.z + 2 : panel.z - 2,
+      unitScale: PW / 600,
+      pose: {
+        wrist: n(`${H}.pose.wrist`),
+        fingerCurl: n(`${H}.pose.fingerCurl`), thumbBend: n(`${H}.pose.thumbBend`), thumbRotation: n(`${H}.thumb.rotation`),
+        thumbScale: n(`${H}.thumb.scale`), thumbX: n(`${H}.thumb.x`), thumbY: n(`${H}.thumb.y`),
+      },
+    };
+  });
+  const anchors = Object.fromEntries(hands.map((h) => [h.id, { paper: [h.gripX, h.gripY], hand: [h.x, h.y] }])) as FrameState['anchors'];
+
+  /* camera */
+  const enabledFolds = folds.filter((f, k) => foldsCfg[k]!.enabled);
+  const foldAmount = enabledFolds.length ? enabledFolds.reduce((a, f) => a + clamp(f.amount), 0) / enabledFolds.length : 0;
+  const fin = tl.phases.finalHold;
+  let zoom = lerp(n('camera.startZoom'), n('camera.foldZoom'), ease(s('easing.camera'), foldAmount, 60));
+  if (t >= fin.start && fin.end > fin.start) zoom = lerp(zoom, n('camera.endZoom'), ease(s('timeline.finalHold.easing'), (t - fin.start) / (fin.end - fin.start), fin.end - fin.start));
+  const u = lay.unit, W = width, Hh = height;
+  const camT = (z: number, k: number) => `translate(${W / 2}px, ${Hh / 2}px) rotate(${n('camera.rotation') * k}deg) scale(${z}) translate(${-W / 2 - n('camera.x') * u * k}px, ${-Hh / 2 - n('camera.y') * u * k}px)`;
+  const par = n('camera.parallax');
+
+  /* background type rows */
+  const bt = 'background.backgroundTypography';
+  const size = n(`${bt}.fontSize`) * u * lay.backgroundType.scale;
+  const pitch = size * n(`${bt}.rowGap`);
+  const drift = n(`${bt}.drift`) * u * (t / MOTION_FPS);
+  const typeRows = Array.from({ length: n(`${bt}.rows`) }, (_, i) => ({
+    y: n(`${bt}.y`) * u + lay.backgroundType.y + i * pitch,
+    x: n(`${bt}.x`) * u + lay.backgroundType.x + (b(`${bt}.alternate`) && i % 2 ? -drift : drift),
+  }));
+
+  // Fill: an estimate of the word's width (caps ≈ 0.66 em each, plus tracking) decides how many repeats span the canvas.
+  const wordWidth = Math.max(1, s(`${bt}.text`).length * (0.66 + n(`${bt}.tracking`)) * size + 0.3 * size);
+  const reach = width + Math.abs(n(`${bt}.x`) * u + lay.backgroundType.x) + Math.abs(drift) + size;
+  const typeRepeat = Math.max(n(`${bt}.repeat`), b(`${bt}.fill`) ? Math.min(12, Math.ceil(reach / wordWidth)) : 1);
+
+  /* logo and CTA */
+  const introSpan = tl.phases.intro;
+  const eLogo = ease(s('easing.logoEnter'), (t - introSpan.start) / Math.max(1, introSpan.end - introSpan.start), introSpan.end - introSpan.start);
+  const logoMode = s('logo.animation');
+  const logo = { x: lay.logo.x, y: lay.logo.y - (logoMode === 'drop' ? (1 - eLogo) * 60 * u : 0), opacity: logoMode === 'none' ? 1 : eLogo, scale: lay.logo.scale };
+  const ctaMode = s('cta.animation');
+  const pCta = clamp((t - n('cta.enterDelayFrames')) / n('cta.enterDurationFrames'));
+  const pop = ctaMode === 'pop' || ctaMode === 'pop-pulse';
+  const pulse = ctaMode === 'pulse' || ctaMode === 'pop-pulse';
+  const pulseT = Math.max(0, t - fin.start) / MOTION_FPS;
+  const pulseK = pulse && t >= fin.start ? n('cta.pulseAmount') * (0.5 - 0.5 * Math.cos(TAU * n('cta.pulseFrequency') * pulseT)) : 0;
+  const cta = { x: lay.cta.x, y: lay.cta.y, opacity: pop ? clamp(pCta * 3) : 1, scale: lay.cta.scale * (pop ? Math.max(0, ease(s('easing.ctaEnter'), pCta, n('cta.enterDurationFrames'))) : 1) * (1 + pulseK) };
+
+  /* debug: the creases on the picture */
+  const creaseLine = (k: 0 | 1) => {
+    const y = lay.creases[k];
+    return { id: k === 0 ? 'top' : 'bottom', from: onPicture(0, y), to: onPicture(PW, y), position: creases[k]!.position, angle: folds[k]!.angle };
+  };
+
+  return {
+    cfg, frame: t, size: lay, timeline: tl, phase: phaseAt(tl, t), folds, anchor, panels, strips, bands: sheet.bands, text, anchors, hands,
+    camera: { transform: camT(zoom, 1), backgroundTransform: camT(1 + (zoom - 1) * par, par), zoom },
+    shadowQuads: strips.map((p) => p.corners),
+    sheetCentre: project(chain(sheet.P, sheet.S), [PW / 2, lay.paper.height / 2, 0]),
+    background: { typeRows, typeRepeat },
+    logo, cta,
+    debug: { creases: [creaseLine(0), creaseLine(1)] },
+  };
+}
+
+/** The phase ids in order (re-exported for tests and tools). */
+export { PHASES };