@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/paperfold/PaperFoldPlayer.tsx

@@ -0,0 +1,80 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { getPath, validateConfig, type ConfigError, type PaperFoldConfig } from './config';
+import { MOTION_FPS, timeline } from './engine';
+import { installPaperFoldFonts } from './fonts';
+import { PaperFoldFrame, type PaperFoldFrameProps } from './PaperFoldFrame';
+
+export type PaperFoldPlayerProps = {
+  /** The canonical config (any subset; defaults fill the rest). Validated before anything is drawn. */
+  config: unknown;
+  autoPlay?: boolean;
+  /** Replay from the start when the timeline ends (default true). */
+  loop?: boolean;
+  /** Rendered width in CSS px; the height follows the config's aspect ratio. Defaults to 360. */
+  width?: number;
+  /** Seek to this authored motion frame and hold (scrubbing). */
+  frame?: number;
+  /** Development overlay: creases, panels, pivots, angles, anchors, frame. */
+  debug?: boolean;
+  onFrame?: (frame: number) => void;
+  onInvalid?: (errors: ConfigError[]) => void;
+  resolveAsset?: PaperFoldFrameProps['resolveAsset'];
+  className?: string;
+};
+
+const RATIO: Record<string, number> = { '9:16': 9 / 16, '16:9': 16 / 9, '1:1': 1 };
+
+/**
+ * **paper-fold-promo in a React web app.** Validates the config, then draws each frame with the
+ * package's procedural renderer at the player's own size (vector, never a scaled bitmap). A rAF clock
+ * turns time into authored motion frames (× motion.speed); the engine does the rest. The drawing is
+ * `aria-hidden` inside a `role="img"` box labelled with the copy. Reduced motion shows the final frame.
+ */
+export function PaperFoldPlayer({ config, autoPlay = true, loop = true, width = 360, frame, debug, onFrame, onInvalid, resolveAsset, className }: PaperFoldPlayerProps) {
+  const key = JSON.stringify(config ?? {});
+  const checked = useMemo(() => validateConfig(JSON.parse(key)), [key]);
+  const cfg = checked.config as PaperFoldConfig | undefined;
+  const [now, setNow] = useState(0);
+  const cb = useRef({ onFrame, onInvalid });
+  cb.current = { onFrame, onInvalid };
+  const aspect = cfg ? String(getPath(cfg, 'canvas.aspectRatio')) : '9:16';
+  const height = Math.round(width / (RATIO[aspect] ?? 9 / 16));
+
+  useEffect(() => installPaperFoldFonts(), []);
+  useEffect(() => { if (!checked.valid) cb.current.onInvalid?.(checked.errors); }, [checked]);
+  useEffect(() => {
+    if (!cfg) return;
+    const total = timeline(cfg).end;
+    const speed = getPath(cfg, 'motion.speed') as number;
+    const reduced = typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    if (frame !== undefined || !autoPlay || reduced) { setNow(frame ?? (reduced ? total - 1 : 0)); return; }
+    let raf = 0;
+    const start = performance.now();
+    const tick = (t: number) => {
+      const m = ((t - start) / 1000) * MOTION_FPS * speed;
+      const f = loop ? m % total : Math.min(m, total - 1);
+      setNow(f);
+      cb.current.onFrame?.(f);
+      if (loop || m < total) raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [cfg, frame, autoPlay, loop]);
+
+  if (!checked.valid) {
+    return (
+      <div role="alert" className={className} style={{ width, padding: 12, font: '13px/1.4 system-ui', border: '1px solid currentColor' }}>
+        <strong>This paper-fold configuration is not valid.</strong>
+        <ul>{checked.errors.slice(0, 8).map((e) => <li key={e.path + e.message}>{e.message}</li>)}</ul>
+      </div>
+    );
+  }
+  const label = [getPath(cfg, 'content.logo'), getPath(cfg, 'content.top.headline'), getPath(cfg, 'content.middle.headline'), getPath(cfg, 'content.bottom.body'), getPath(cfg, 'content.cta.text')].filter(Boolean).join(' — ');
+  return (
+    <div role="img" aria-label={label} className={className} style={{ width, height, position: 'relative', overflow: 'hidden' }}>
+      <div aria-hidden="true">
+        <PaperFoldFrame config={cfg!} frame={now} width={width} height={height} debug={debug} resolveAsset={resolveAsset} />
+      </div>
+    </div>
+  );
+}

package/src/motion/paperfold/art.ts

@@ -0,0 +1,455 @@
+/* eslint-disable comppack/no-raw-colour -- vector artwork: colours come from the config (hands.style, paperMaterial, logo); the literals are the reference defaults written into the exported SVG files. */
+/**
+ * **The vector artwork of paper-fold-promo**, as data: SVG path geometry for each separately movable
+ * part. The renderer draws these paths inline (each part its own element, coloured from the config), and
+ * `tools/export-paper-fold-assets.ts` writes the same geometry out as standalone SVG files — so the files
+ * and the video cannot drift apart. Nothing here is traced from the reference raster.
+ *
+ * **Hands** are built from an anatomical skeleton and drawn as an editorial vector illustration:
+ * - a forearm that widens from the wrist to the muscle belly, sharing its wrist edge with the palm;
+ * - the back of the hand (palm) with the four knuckles (metacarpal heads) in an arc;
+ * - four fingers, each ONE continuous silhouette — its base inside the palm, the knuckle, three
+ *   phalanges tapering to a rounded tip — with a knuckle bulge on the convex side of each bend and a
+ *   slight pinch on the concave side, instead of drawn joint lines;
+ * - the thumb, an opposing digit rooted in the thenar region at the side of the palm;
+ * - layered shading: midtones on turned-away surfaces, shadows under and between fingers, under the
+ *   thumb and at the wrist, highlights on knuckles and lit edges, subtle nails.
+ * Every part is named (forearm, palm, thumb, indexFinger, middleFinger, ringFinger, littleFinger,
+ * fingerShadows, palmShadow, highlights, nails) and placed `behind` the paper or in `front` of it.
+ *
+ * Hand coordinates are "hand units": the reference sheet is 600 units wide and the hand's grip anchor
+ * is (0, 0) — the point that sits on the paper's grip anchor. The renderer scales hand units with the
+ * sheet, so the hands keep their size relative to the paper in every layout.
+ */
+export type P = [number, number];
+export type HandPartName = 'forearm' | 'sleeve' | 'palm' | 'thumb' | 'indexFinger' | 'middleFinger' | 'ringFinger' | 'littleFinger' | 'fingerShadows' | 'palmShadow' | 'highlights' | 'nails';
+export type HandFill = 'base' | 'midtone' | 'shadow' | 'highlight' | 'nail' | 'sleeve';
+export type HandShape = { d: string; fill: HandFill; opacity?: number; /** Part of the silhouette (gets hands.style.outlineWidth). */ outline?: boolean };
+/** `grips`: a digit holding the paper from behind it — once that panel turns over, it shows only where it lies on the panel. */
+export type HandPart = { name: HandPartName; layer: 'behind' | 'front'; shapes: HandShape[]; grips?: boolean };
+export type HandArt = {
+  /** In drawing order within each layer. */
+  parts: HandPart[];
+  /** Skeleton joints per digit (root in the palm, knuckle, two finger joints, tip), for tests and the debug overlay. */
+  joints: Record<string, P[]>;
+  /** The palm's outline points and the wrist edge it shares with the forearm. */
+  palmOutline: P[];
+  wristEdge: [P, P];
+  /** The forearm's wrist end (equal to wristEdge: the wrist flows into the forearm). */
+  forearmStart: [P, P];
+  /** The hand's grip anchor (always (0, 0)). */
+  gripAnchor: P;
+  wrist: { at: P; toward: P; width: number };
+};
+export type HandPose = {
+  armLength: number;
+  /** Degrees the gripping digit is opened away from the paper (the grip animation). */
+  open: number;
+  /** Degrees the hand turns against the forearm about the wrist. */
+  wrist: number;
+  fingerCurl: number;
+  thumbBend: number;
+  thumbRotation: number;
+  thumbScale: number;
+  thumbX: number;
+  thumbY: number;
+  nails: boolean;
+  nailScale: number;
+};
+export const DEFAULT_POSE: HandPose = { armLength: 1500, open: 0, wrist: 0, fingerCurl: 1, thumbBend: 0, thumbRotation: 0, thumbScale: 1, thumbX: 0, thumbY: 0, nails: true, nailScale: 1 };
+
+const f = (v: number) => Math.round(v * 10) / 10;
+const pt = ([x, y]: P) => `${f(x)} ${f(y)}`;
+const unit = (x: number, y: number): P => { const l = Math.hypot(x, y) || 1; return [x / l, y / l]; };
+const add = (a: P, b: P): P => [a[0] + b[0], a[1] + b[1]];
+const sub = (a: P, b: P): P => [a[0] - b[0], a[1] - b[1]];
+const mulv = (a: P, k: number): P => [a[0] * k, a[1] * k];
+const dir = (deg: number): P => [Math.cos((deg * Math.PI) / 180), Math.sin((deg * Math.PI) / 180)];
+const lerpP = (a: P, b: P, t: number): P => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+const rot = (p: P, about: P, deg: number): P => {
+  const c = Math.cos((deg * Math.PI) / 180), s = Math.sin((deg * Math.PI) / 180), d = sub(p, about);
+  return [about[0] + d[0] * c - d[1] * s, about[1] + d[0] * s + d[1] * c];
+};
+
+/** Cubic segments through `pts` (open Catmull–Rom), continuing a path already at pts[0]. */
+function through(pts: P[]): string {
+  let d = '';
+  for (let i = 0; i < pts.length - 1; i++) {
+    const p0 = pts[Math.max(0, i - 1)]!, p1 = pts[i]!, p2 = pts[i + 1]!, p3 = pts[Math.min(pts.length - 1, i + 2)]!;
+    d += ` C ${pt(add(p1, mulv(sub(p2, p0), 1 / 6)))} ${pt(sub(p2, mulv(sub(p3, p1), 1 / 6)))} ${pt(p2)}`;
+  }
+  return d;
+}
+/** A smooth closed outline through `points`. */
+function smoothClosed(points: P[]): string {
+  const k = points.length;
+  let d = `M ${pt(points[0]!)}`;
+  for (let i = 0; i < k; i++) {
+    const p0 = points[(i - 1 + k) % k]!, p1 = points[i]!, p2 = points[(i + 1) % k]!, p3 = points[(i + 2) % k]!;
+    d += ` C ${pt(add(p1, mulv(sub(p2, p0), 1 / 6)))} ${pt(sub(p2, mulv(sub(p3, p1), 1 / 6)))} ${pt(p2)}`;
+  }
+  return `${d} Z`;
+}
+
+/**
+ * The forearm: from the wrist's two sides (`a`, `b`) it widens quickly to the muscle belly (× `flare`, a
+ * quarter of the way along), then runs on almost straight to `length` along `toward` — narrowest at the
+ * wrist, fullest below the elbow. It starts exactly on the palm's wrist edge.
+ */
+function forearm(a: P, b: P, toward: P, length: number, flare: number): string {
+  const [tx, ty] = toward;
+  const mid = lerpP(a, b, 0.5);
+  const half = Math.hypot(a[0] - b[0], a[1] - b[1]) / 2;
+  const nx = -ty, ny = tx;
+  const sa = Math.sign((a[0] - mid[0]) * nx + (a[1] - mid[1]) * ny) || 1;
+  const at = (along: number, side: number, w: number): P => [mid[0] + tx * along + nx * side * w, mid[1] + ty * along + ny * side * w];
+  const belly = Math.min(length * 0.25, half * 3.2);
+  return `M ${pt(a)} C ${pt(at(belly * 0.45, sa, half * 1.02))} ${pt(at(belly * 0.7, sa, half * flare))} ${pt(at(belly, sa, half * flare))}`
+    + ` L ${pt(at(length, sa, half * flare * 1.04))} L ${pt(at(length, -sa, half * flare * 1.04))} L ${pt(at(belly, -sa, half * flare))}`
+    + ` C ${pt(at(belly * 0.7, -sa, half * flare))} ${pt(at(belly * 0.45, -sa, half * 1.02))} ${pt(b)} Z`;
+}
+
+/* ─── digits ──────────────────────────────────────────────────────────────────────────────────── */
+/** A digit's skeleton: its root (inside the palm), knuckle, and three segments by screen angle and length. */
+type DigitSpec = { root: P; knuckle: P; angles: [number, number, number]; lengths: [number, number, number]; /** Half-widths at root, knuckle, the two joints, the tip. */ widths: [number, number, number, number, number] };
+function joints(d: DigitSpec): P[] {
+  const out: P[] = [d.root, d.knuckle];
+  d.angles.forEach((a, i) => out.push(add(out[i + 1]!, mulv(dir(a), d.lengths[i]!))));
+  return out;
+}
+/**
+ * One continuous silhouette along joints J0..J4 with half-widths w0..w4: offsets along the bisecting
+ * normal at each joint, a knuckle bulge on the convex side of a bend and a slight pinch on the concave
+ * side, a rounded tip. `from`/`to` cut a sub-range (for a shading overlay on part of the digit); `side`
+ * keeps one side only, inset to `inset` of the width (a shading strip).
+ */
+function digitOutline(j: P[], w: number[], opts: { from?: number; to?: number; side?: 1 | -1; inset?: number; tip?: boolean } = {}): string {
+  const n = j.length;
+  const from = opts.from ?? 0, to = opts.to ?? n - 1;
+  const normals: P[] = [], scaleL: number[] = [], scaleR: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const a = i > 0 ? unit(...sub(j[i]!, j[i - 1]!)) : unit(...sub(j[1]!, j[0]!));
+    const b = i < n - 1 ? unit(...sub(j[i + 1]!, j[i]!)) : a;
+    const t = unit(a[0] + b[0], a[1] + b[1]);
+    normals.push([-t[1], t[0]]);
+    // Bend at this joint: its sign says which side is convex (the knuckle).
+    const cross = a[0] * b[1] - a[1] * b[0];
+    const bend = Math.min(1, Math.abs(Math.asin(Math.max(-1, Math.min(1, cross)))) / 1.2);
+    const miter = Math.min(1.35, 1 / Math.max(0.6, Math.cos(Math.acos(Math.max(-1, Math.min(1, a[0] * b[0] + a[1] * b[1]))) / 2)));
+    const convexLeft = cross < 0;
+    scaleL.push((convexLeft ? 1 + 0.12 * bend : 1 - 0.1 * bend) * (convexLeft ? miter : 1));
+    scaleR.push((convexLeft ? 1 - 0.1 * bend : 1 + 0.12 * bend) * (convexLeft ? 1 : miter));
+  }
+  const L: P[] = [], R: P[] = [];
+  for (let i = from; i <= to; i++) {
+    L.push(add(j[i]!, mulv(normals[i]!, w[i]! * scaleL[i]!)));
+    R.push(sub(j[i]!, mulv(normals[i]!, w[i]! * scaleR[i]!)));
+  }
+  if (opts.side) {
+    // A strip along one side: the edge and a line inset toward the axis.
+    const edge = opts.side === 1 ? L : R;
+    // The inner line meets the edge at both ends, so the strip tapers to a point instead of ending square.
+    const inner: P[] = [];
+    for (let i = from; i <= to; i++) {
+      const k = i === from || i === to ? 0.97 : (opts.inset ?? 0.4);
+      inner.push(add(j[i]!, mulv(normals[i]!, opts.side * w[i]! * k * (opts.side === 1 ? scaleL[i]! : scaleR[i]!))));
+    }
+    return `M ${pt(edge[0]!)}${through(edge)} L ${pt(inner.at(-1)!)}${through([...inner].reverse())} Z`;
+  }
+  const tipOn = opts.tip ?? to === n - 1;
+  const r = w[to]!;
+  let d = `M ${pt(R[0]!)}${through(R)}`;
+  if (tipOn) {
+    const u = unit(...sub(j[to]!, j[to - 1]!));
+    const cap = add(j[to]!, mulv(u, r));
+    // A rounded fingertip: two quarter curves around the tip.
+    d += ` C ${pt(add(R.at(-1)!, mulv(u, r * 0.55)))} ${pt(sub(cap, mulv(normals[to]!, -r * 0.55 * -1)))} ${pt(cap)}`;
+    d += ` C ${pt(add(cap, mulv(normals[to]!, r * 0.55)))} ${pt(add(L.at(-1)!, mulv(u, r * 0.55)))} ${pt(L.at(-1)!)}`;
+  } else d += ` L ${pt(L.at(-1)!)}`;
+  d += through([...L].reverse());
+  return `${d} Z`;
+}
+/** A fingernail on the last segment, facing the viewer: rounded, slightly narrower than the fingertip. */
+function nail(j: P[], w: number[], scale: number): string {
+  const a = j[3]!, b = j[4]!, r = w[4]! * scale;
+  const u = unit(...sub(b, a)), nrm: P = [-u[1], u[0]];
+  const base = lerpP(a, b, 0.42), end = add(b, mulv(u, r * 0.55));
+  const hw = r * 0.62;
+  return `M ${pt(add(base, mulv(nrm, hw * 0.9)))} C ${pt(add(lerpP(base, end, 0.5), mulv(nrm, hw * 1.05)))} ${pt(add(end, mulv(nrm, hw * 0.9)))} ${pt(add(end, mulv(u, hw * 0.25)))}`
+    + ` C ${pt(sub(end, mulv(nrm, hw * 0.9)))} ${pt(sub(lerpP(base, end, 0.5), mulv(nrm, hw * 1.05)))} ${pt(sub(base, mulv(nrm, hw * 0.9)))}`
+    + ` Q ${pt(sub(base, mulv(u, hw * 0.35)))} ${pt(add(base, mulv(nrm, hw * 0.9)))} Z`;
+}
+/** A rotated ellipse (knuckle heads). */
+function ellipse(c: P, rx: number, ry: number, deg: number): string {
+  const a = add(c, rot([rx, 0], [0, 0], deg)), b = sub(c, rot([rx, 0], [0, 0], deg));
+  return `M ${pt(a)} A ${f(rx)} ${f(ry)} ${f(deg)} 1 0 ${pt(b)} A ${f(rx)} ${f(ry)} ${f(deg)} 1 0 ${pt(a)} Z`;
+}
+/** Which side of a digit faces away from the light (the shadow side): +1 = its left offset, −1 = its right. */
+function shadowSide(j: P[], light: P): 1 | -1 {
+  const u = unit(...sub(j[3]!, j[1]!));
+  const left: P = [-u[1], u[0]];
+  return left[0] * light[0] + left[1] * light[1] < 0 ? 1 : -1;
+}
+
+type HandSpec = {
+  wrist: [P, P]; toward: P; flare: number;
+  palm: P[];
+  knuckles: P[];
+  /** Index, middle, ring, little. */
+  fingers: Record<'indexFinger' | 'middleFinger' | 'ringFinger' | 'littleFinger', DigitSpec & { layer: 'behind' | 'front'; curled?: boolean; hidden?: boolean }>;
+  thumb: DigitSpec & { layer: 'behind' | 'front' };
+  light: P;
+  palmShadow: P[][];
+  palmHighlight: P[][];
+  /** The digit whose tip is the grip anchor, and where that tip sits relative to the anchor. */
+  anchor: { digit: 'indexFinger' | 'thumb'; offset: P };
+  /** Which way opening the grip turns the gripping digits (+1 clockwise on screen). */
+  openSign: 1 | -1;
+  gripping: ('indexFinger' | 'middleFinger' | 'thumb')[];
+};
+
+function pose(d: DigitSpec, curl: number, extraBend: number, openDeg: number, rotDeg = 0, scale = 1, shift: P = [0, 0]): DigitSpec {
+  const [a1, a2, a3] = d.angles;
+  const sign = Math.sign(a3 - a1) || 1;
+  const angles: [number, number, number] = [
+    a1 + openDeg + rotDeg,
+    a1 + (a2 - a1) * curl + sign * extraBend * 18 + openDeg + rotDeg,
+    a1 + (a3 - a1) * curl + sign * extraBend * 34 + openDeg + rotDeg,
+  ];
+  const knuckle = rot(add(d.knuckle, shift), add(d.root, shift), rotDeg);
+  return { root: add(d.root, shift), knuckle, angles, lengths: d.lengths.map((l) => l * scale) as DigitSpec['lengths'], widths: d.widths.map((w) => w * scale) as DigitSpec['widths'] };
+}
+
+/** The hand turned against the forearm about the wrist's centre: palm, knuckles, digits and shading. */
+function bendWrist(spec: HandSpec, deg: number): HandSpec {
+  if (!deg) return spec;
+  const c = lerpP(spec.wrist[0], spec.wrist[1], 0.5);
+  const r = (q: P) => rot(q, c, deg);
+  const digit = <D extends DigitSpec>(d: D): D => ({ ...d, root: r(d.root), knuckle: r(d.knuckle), angles: d.angles.map((a) => a + deg) as DigitSpec['angles'] });
+  return {
+    ...spec,
+    wrist: [r(spec.wrist[0]), r(spec.wrist[1])],
+    palm: spec.palm.map(r), knuckles: spec.knuckles.map(r),
+    palmShadow: spec.palmShadow.map((q) => q.map(r)), palmHighlight: spec.palmHighlight.map((q) => q.map(r)),
+    fingers: Object.fromEntries(Object.entries(spec.fingers).map(([k, d]) => [k, digit(d)])) as HandSpec['fingers'],
+    thumb: digit(spec.thumb),
+  };
+}
+
+function build(rawSpec: HandSpec, p: HandPose): HandArt {
+  const spec = bendWrist(rawSpec, p.wrist);
+  const fingers = Object.fromEntries(Object.entries(spec.fingers).map(([name, d]) => {
+    const gripping = spec.gripping.includes(name as 'indexFinger');
+    return [name, { ...d, posed: pose(d, p.fingerCurl, 0, gripping ? spec.openSign * p.open : 0) }];
+  })) as Record<keyof HandSpec['fingers'], HandSpec['fingers'][keyof HandSpec['fingers']] & { posed: DigitSpec }>;
+  const thumbPosed = pose(spec.thumb, 1, p.thumbBend, spec.gripping.includes('thumb') ? spec.openSign * p.open : 0, p.thumbRotation, p.thumbScale, [p.thumbX, p.thumbY]);
+  // Place the grip anchor at (0, 0): shift everything so the anchoring tip — posed, with the grip
+  // closed — sits at its offset. Opening the grip then lifts the tip off the anchor, as it should.
+  const closed = spec.anchor.digit === 'thumb'
+    ? pose(spec.thumb, 1, p.thumbBend, 0, p.thumbRotation, p.thumbScale, [p.thumbX, p.thumbY])
+    : pose(spec.fingers[spec.anchor.digit], p.fingerCurl, 0, 0);
+  const shift = sub(spec.anchor.offset, joints(closed)[4]!);
+  const m = (q: P): P => add(q, shift);
+  const J = (d: DigitSpec) => joints(d).map(m);
+
+  const parts: HandPart[] = [];
+  const shapes = (name: HandPartName, layer: 'behind' | 'front', s: HandShape[], grips = false) => { if (s.length) parts.push({ name, layer, shapes: s, ...(grips ? { grips } : {}) }); };
+  const wrist: [P, P] = [m(spec.wrist[0]), m(spec.wrist[1])];
+  shapes('forearm', 'behind', [{ d: forearm(wrist[0], wrist[1], spec.toward, p.armLength, spec.flare), fill: 'base', outline: true }]);
+
+  const jointMap: Record<string, P[]> = {};
+  const fingerShadowsBehind: HandShape[] = [], fingerShadowsFront: HandShape[] = [];
+  const highlightsBehind: HandShape[] = [], highlightsFront: HandShape[] = [];
+  const nails: HandShape[] = [];
+  const digit = (name: HandPartName, d: DigitSpec, layer: 'behind' | 'front', kind: 'lit' | 'curled' | 'hidden', grips = false) => {
+    const j = J(d), w = d.widths;
+    jointMap[name] = j;
+    const out: HandShape[] = [{ d: digitOutline(j, w), fill: kind === 'hidden' ? 'shadow' : 'base', outline: kind !== 'hidden' }];
+    // Turned under past the middle joint: in half-shadow.
+    if (kind === 'curled') out.push({ d: digitOutline(j, w, { from: 2 }), fill: 'midtone' });
+    shapes(name, layer, out, grips);
+    const side = shadowSide(j, spec.light);
+    const own = { shadows: [] as HandShape[], lights: [] as HandShape[] };
+    const shadows = grips ? own.shadows : layer === 'front' ? fingerShadowsFront : fingerShadowsBehind;
+    const lights = grips ? own.lights : layer === 'front' ? highlightsFront : highlightsBehind;
+    const flush = () => { if (grips) { shapes('fingerShadows', layer, own.shadows, true); shapes('highlights', layer, own.lights, true); } };
+    if (kind === 'hidden') {
+      lights.push({ d: digitOutline(j, w, { from: 1, side: (-side) as 1 | -1, inset: 0.72 }), fill: 'midtone', opacity: 0.9 });
+      flush();
+      return;
+    }
+    shadows.push({ d: digitOutline(j, w, { from: 1, side, inset: 0.3 }), fill: 'midtone', opacity: 0.9 });
+    lights.push({ d: digitOutline(j, w, { from: 1, to: 3, side: (-side) as 1 | -1, inset: 0.66 }), fill: 'highlight', opacity: 0.5 });
+    if (layer === 'front' && p.nails) nails.push({ d: nail(j, w, p.nailScale), fill: 'nail' });
+    flush();
+  };
+
+  // Behind the paper, back to front: the thumb and folded fingers sit under the palm.
+  const behindFingers = (['littleFinger', 'ringFinger', 'middleFinger', 'indexFinger'] as const).filter((k) => fingers[k].layer === 'behind');
+  // Digits behind the sheet that are not folded into the palm are holding it from behind.
+  if (spec.thumb.layer === 'behind') digit('thumb', thumbPosed, 'behind', 'lit', true);
+  for (const k of behindFingers) digit(k, fingers[k].posed, 'behind', fingers[k].hidden ? 'hidden' : fingers[k].curled ? 'curled' : 'lit', !fingers[k].curled);
+  const palm = spec.palm.map(m);
+  shapes('palm', 'behind', [{ d: smoothClosed(palm), fill: 'base', outline: true }]);
+  shapes('palmShadow', 'behind', spec.palmShadow.map((q) => ({ d: smoothClosed(q.map(m)), fill: 'midtone' as HandFill, opacity: 0.85 })));
+  // Knuckles: the metacarpal heads catch the light on the back of the hand.
+  for (const k of spec.knuckles) highlightsBehind.push({ d: ellipse(add(m(k), mulv(spec.light, 5)), 12, 8, Math.atan2(spec.light[1], spec.light[0]) * 57.3 + 90), fill: 'highlight', opacity: 0.6 });
+  for (const q of spec.palmHighlight) highlightsBehind.push({ d: smoothClosed(q.map(m)), fill: 'highlight', opacity: 0.8 });
+  shapes('fingerShadows', 'behind', fingerShadowsBehind);
+  shapes('highlights', 'behind', highlightsBehind);
+
+  // In front of the paper: the gripping digits, their shading and nails.
+  if (spec.thumb.layer === 'front') digit('thumb', thumbPosed, 'front', 'lit');
+  for (const k of (['littleFinger', 'ringFinger', 'middleFinger', 'indexFinger'] as const).filter((q) => fingers[q].layer === 'front')) digit(k, fingers[k].posed, 'front', 'lit');
+  shapes('fingerShadows', 'front', fingerShadowsFront);
+  shapes('highlights', 'front', highlightsFront);
+  shapes('nails', 'front', nails);
+
+  return {
+    parts, joints: jointMap, palmOutline: palm, wristEdge: wrist, forearmStart: wrist, gripAnchor: [0, 0],
+    wrist: { at: lerpP(wrist[0], wrist[1], 0.5), toward: spec.toward, width: Math.hypot(...sub(wrist[0], wrist[1])) },
+  };
+}
+
+/**
+ * The top hand — a left hand seen from its back, reaching in from the upper left (the reference pose).
+ * Palm about as long as the middle finger; middle finger longest, index ≈ ring, little finger to the
+ * ring finger's last joint. Index and middle fingers curl over the sheet's top edge onto its front,
+ * nails toward the viewer; ring and little fingers fold into the palm; the thumb pinches from behind
+ * the sheet, rooted at the side of the palm.
+ */
+const TOP: HandSpec = {
+  // Proportions after the reference sheet: a wrist about three quarters of the palm's width, a palm
+  // about as long as the middle finger, slender fingers (each about a quarter of the palm's width).
+  wrist: [[-236, -194], [-232, -122]], toward: unit(-0.93, 0.36), flare: 1.26,
+  palm: [[-236, -194], [-186, -214], [-116, -222], [-66, -214], [-42, -194], [-32, -160], [-34, -126], [-46, -100], [-86, -92], [-150, -98], [-200, -110], [-232, -122]],
+  knuckles: [[-54, -200], [-40, -172], [-34, -142], [-40, -112]],
+  fingers: {
+    littleFinger: { root: [-78, -198], knuckle: [-54, -200], angles: [26, 104, 176], lengths: [36, 24, 10], widths: [11.5, 12, 11, 10, 9], layer: 'behind', curled: true },
+    ringFinger: { root: [-64, -172], knuckle: [-40, -172], angles: [20, 98, 172], lengths: [46, 30, 14], widths: [13, 13.5, 12.5, 11.5, 10], layer: 'behind', curled: true },
+    middleFinger: { root: [-58, -142], knuckle: [-34, -142], angles: [16, 52, 80], lengths: [80, 56, 42], widths: [14, 14.5, 13.5, 12.5, 11], layer: 'front' },
+    indexFinger: { root: [-64, -112], knuckle: [-40, -112], angles: [22, 58, 86], lengths: [72, 50, 38], widths: [14, 14, 13, 12, 10.5], layer: 'front' },
+  },
+  thumb: { root: [-150, -108], knuckle: [-124, -100], angles: [36, 50, 62], lengths: [64, 50, 38], widths: [21, 20, 17.5, 15.5, 13.5], layer: 'behind' },
+  light: unit(-0.35, -1),
+  palmShadow: [
+    [[-232, -122], [-200, -110], [-150, -98], [-86, -92], [-46, -100], [-66, -110], [-130, -112], [-196, -124]],
+  ],
+  palmHighlight: [[[-222, -190], [-156, -212], [-80, -208], [-94, -198], [-156, -204], [-208, -184]]],
+  anchor: { digit: 'indexFinger', offset: [0, 16] },
+  openSign: -1,
+  gripping: ['indexFinger', 'middleFinger'],
+};
+
+/**
+ * The bottom hand — a right hand seen from its thumb side, rising from the lower left: the thumb up over
+ * the sheet's front (nail toward the viewer), rooted in the full thenar pad at the side of the palm;
+ * the four fingers behind the sheet, dark where their roots show below its edge.
+ */
+const BOTTOM: HandSpec = {
+  wrist: [[-146, 334], [-22, 350]], toward: unit(-0.6, 0.8), flare: 1.12,
+  palm: [[-146, 334], [-150, 252], [-142, 198], [-104, 174], [-50, 162], [0, 158], [30, 176], [40, 230], [42, 296], [-22, 350]],
+  knuckles: [],
+  fingers: {
+    littleFinger: { root: [-122, 222], knuckle: [-120, 196], angles: [-100, -96, -94], lengths: [60, 38, 28], widths: [14, 14, 13, 12, 10.5], layer: 'behind', hidden: true },
+    ringFinger: { root: [-88, 206], knuckle: [-86, 180], angles: [-96, -94, -92], lengths: [74, 48, 34], widths: [15.5, 15.5, 14.5, 13, 11.5], layer: 'behind', hidden: true },
+    middleFinger: { root: [-52, 196], knuckle: [-50, 170], angles: [-94, -92, -90], lengths: [82, 54, 38], widths: [16, 16, 15, 13.5, 12], layer: 'behind', hidden: true },
+    indexFinger: { root: [-16, 192], knuckle: [-14, 166], angles: [-92, -90, -88], lengths: [74, 48, 34], widths: [15.5, 15.5, 14.5, 13, 11.5], layer: 'behind', hidden: true },
+  },
+  thumb: { root: [8, 300], knuckle: [34, 268], angles: [-66, -88, -96], lengths: [76, 58, 42], widths: [28, 30, 24.5, 21, 17], layer: 'front' },
+  light: unit(-0.6, -1),
+  palmShadow: [
+    [[-146, 334], [-150, 252], [-142, 198], [-116, 196], [-122, 270], [-118, 334]],
+    // Under the thumb, where it leaves the thenar pad.
+    [[24, 236], [34, 290], [18, 306], [12, 262]],
+  ],
+  palmHighlight: [[[20, 190], [34, 230], [36, 290], [24, 300], [26, 236]]],
+  anchor: { digit: 'thumb', offset: [0, -14] },
+  openSign: 1,
+  gripping: ['thumb'],
+};
+
+export const HAND_SPECS = { top: TOP, bottom: BOTTOM };
+export function topHand(p: Partial<HandPose> = {}): HandArt { return build(TOP, { ...DEFAULT_POSE, ...p }); }
+export function bottomHand(p: Partial<HandPose> = {}): HandArt { return build(BOTTOM, { ...DEFAULT_POSE, ...p }); }
+
+/** A sleeve over the forearm: a band from the cuff (at `position` along the arm) to the arm's far end. */
+export function sleevePath(art: HandArt, position: number, armLength: number): string {
+  const { at, toward, width } = art.wrist;
+  const [tx, ty] = toward, nx = -ty, ny = tx;
+  const d = position * armLength;
+  const h = (width / 2) * 1.5;
+  const c: P = [at[0] + tx * d, at[1] + ty * d];
+  const e: P = [at[0] + tx * (armLength + 40), at[1] + ty * (armLength + 40)];
+  const q = (o: P, s: number): P => [o[0] + nx * h * s, o[1] + ny * h * s];
+  return `M ${pt(q(c, 1))} L ${pt(q(e, 1.05))} L ${pt(q(e, -1.05))} L ${pt(q(c, -1))} Z`;
+}
+
+/* ─── standalone SVG assets (tools/export-paper-fold-assets.ts) ──────────────────────────────── */
+export const REFERENCE_HAND_COLOURS: Record<HandFill, string> = { base: '#873a1c', midtone: '#7a3217', shadow: '#5e260b', highlight: '#9d4b26', nail: '#e57953', sleeve: '#1f2a44' };
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const shapeSvg = (s: HandShape, colours: Record<HandFill, string>) => `<path d="${s.d}" fill="${colours[s.fill]}"${s.opacity !== undefined && s.opacity < 1 ? ` fill-opacity="${s.opacity}"` : ''}/>`;
+const partSvg = (p: HandPart, colours: Record<HandFill, string>) => `<g id="${p.name}" data-layer="${p.layer}">${p.shapes.map((s) => shapeSvg(s, colours)).join('')}</g>`;
+const svgDoc = (viewBox: string, body: string, title: string) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}"><title>${esc(title)}</title>${body}</svg>\n`;
+const HAND_VIEW = { top: '-760 -300 900 520', bottom: '-420 -140 560 780' };
+
+/** top-hand.svg / bottom-hand.svg: the whole hand, one group per anatomical part, behind-the-paper parts first. */
+export function handSvg(which: 'top' | 'bottom', colours = REFERENCE_HAND_COLOURS): string {
+  const art = which === 'top' ? topHand({ armLength: 600 }) : bottomHand({ armLength: 520 });
+  const ordered = [...art.parts.filter((p) => p.layer === 'behind'), ...art.parts.filter((p) => p.layer === 'front')];
+  return svgDoc(HAND_VIEW[which], ordered.map((p) => partSvg(p, colours)).join(''), `paper-fold-promo — ${which} hand (grip anchor at 0,0)`);
+}
+/** hand-top.svg / hand-bottom.svg: only the parts behind the paper. */
+export function handBodySvg(which: 'top' | 'bottom', colours = REFERENCE_HAND_COLOURS): string {
+  const art = which === 'top' ? topHand({ armLength: 600 }) : bottomHand({ armLength: 520 });
+  return svgDoc(HAND_VIEW[which], art.parts.filter((p) => p.layer === 'behind').map((p) => partSvg(p, colours)).join(''), `paper-fold-promo — ${which} hand, behind the paper`);
+}
+/** hand-top-finger.svg / hand-bottom-finger.svg: only the gripping digits in front of the paper. */
+export function handFingerSvg(which: 'top' | 'bottom', colours = REFERENCE_HAND_COLOURS): string {
+  const art = which === 'top' ? topHand({ armLength: 600 }) : bottomHand({ armLength: 520 });
+  return svgDoc(HAND_VIEW[which], art.parts.filter((p) => p.layer === 'front').map((p) => partSvg(p, colours)).join(''), `paper-fold-promo — ${which} hand, gripping ${which === 'top' ? 'fingers' : 'thumb'} in front of the paper`);
+}
+
+/** The flat, open sheet in the reference proportions: 600 × 857 units, creases at 0.333 and 0.655. */
+export const REFERENCE_SHEET = { width: 600, height: 857, creases: [0.333, 0.655] as const, colour: '#7b3fb9', secondary: '#7036ac', crease: '#2c0f52', highlight: '#c9a0ff' };
+const creaseLines = (W: number, ys: number[]) => ys.map((y) => `<rect x="0" y="${f(y - 1.5)}" width="${W}" height="3" fill="${REFERENCE_SHEET.crease}" fill-opacity="0.45"/>`).join('');
+/** paper-sheet.svg: ONE sheet — its three regions and two creases in the same coordinate system. */
+export function paperSheetSvg(): string {
+  const { width: W, height: H, creases: [a, b], colour, secondary } = REFERENCE_SHEET;
+  return svgDoc(`0 0 ${W} ${H}`, [
+    `<defs><linearGradient id="g" x1="0" y1="0" x2="0.18" y2="1"><stop offset="0" stop-color="${colour}"/><stop offset="1" stop-color="${secondary}"/></linearGradient></defs>`,
+    `<g id="sheet"><rect width="${W}" height="${H}" rx="2" fill="url(#g)"/>`,
+    `<g id="regions"><rect id="top" x="0" y="0" width="${W}" height="${f(a * H)}" fill="none"/><rect id="middle" x="0" y="${f(a * H)}" width="${W}" height="${f((b - a) * H)}" fill="none"/><rect id="bottom" x="0" y="${f(b * H)}" width="${W}" height="${f((1 - b) * H)}" fill="none"/></g>`,
+    `<g id="creases">${creaseLines(W, [a * H, b * H])}</g></g>`,
+  ].join(''), 'paper-fold-promo — the open sheet (regions and creases)');
+}
+/** paper-top.svg / paper-middle.svg / paper-bottom.svg: one region, cut from the same sheet coordinates. */
+export function paperSvg(part: 'base' | 'top' | 'middle' | 'bottom'): string {
+  if (part === 'base') return paperSheetSvg();
+  const { width: W, height: H, creases: [a, b], colour } = REFERENCE_SHEET;
+  const spans = { top: [0, a * H], middle: [a * H, b * H], bottom: [b * H, H] } as const;
+  const [y0, y1] = spans[part];
+  return svgDoc(`0 ${f(y0)} ${W} ${f(y1 - y0)}`, `<rect x="0" y="${f(y0)}" width="${W}" height="${f(y1 - y0)}" fill="${colour}"/>`, `paper-fold-promo — ${part} region of the sheet`);
+}
+export function creaseSvg(): string {
+  const { width: W, crease, highlight } = REFERENCE_SHEET;
+  return svgDoc(`0 -6 ${W} 12`, `<rect x="0" y="-1.5" width="${W}" height="3" fill="${crease}" fill-opacity="0.55"/><rect x="0" y="1.5" width="${W}" height="1.6" fill="${highlight}" fill-opacity="0.35"/>`, 'paper-fold-promo — crease (line and ridge highlight)');
+}
+/** The logo mark (a rounded gradient tile with a letter) beside a wordmark; text stays text. */
+export function logoSvg(word = 'brand', letter = 'B', colours = { from: '#5e4de6', to: '#7a5cff', letter: '#ffffff', word: '#ffffff' }): string {
+  return svgDoc('0 0 330 64', [
+    `<defs><linearGradient id="m" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="${colours.from}"/><stop offset="1" stop-color="${colours.to}"/></linearGradient></defs>`,
+    '<rect x="2" y="3" width="58" height="58" rx="15" fill="url(#m)"/>',
+    `<text x="31" y="47" text-anchor="middle" font-family="Inter, sans-serif" font-weight="800" font-size="42" fill="${colours.letter}">${esc(letter)}</text>`,
+    `<text x="72" y="47" font-family="Inter, sans-serif" font-weight="600" font-size="52" letter-spacing="-1" fill="${colours.word}">${esc(word)}</text>`,
+  ].join(''), 'paper-fold-promo — logo');
+}
+/** The background word in rows; text stays text. */
+export function backgroundTypeSvg(word = 'PROMO', rows = 9, colour = '#a05ce7', background = '#b46cff'): string {
+  const size = 262, pitch = size * 0.8;
+  return svgDoc(`0 0 1080 1920`, [
+    `<rect width="1080" height="1920" fill="${background}"/>`,
+    ...Array.from({ length: rows }, (_, i) => `<text x="-16" y="${f(-42 + i * pitch + size * 0.86)}" font-family="Inter, sans-serif" font-weight="700" font-size="${size}" letter-spacing="-7.9" fill="${colour}">${esc(word)}</text>`),
+  ].join(''), 'paper-fold-promo — background typography');
+}

package/src/motion/paperfold/config.ts

@@ -0,0 +1,98 @@
+import { createConfigApi, getPath, isAssetRef, type ConfigError, type ConfigPatch, type Obj, type PatchOp } from '../configurable/config';
+import { CONTROLS, LISTS, type AspectRatio } from './controls';
+
+/**
+ * **The canonical configuration** of paper-fold-promo — one nested JSON object built from the control
+ * table (`controls.ts`) by the shared configurable-motion machinery. People (the Remotion Studio, the
+ * site editor) and agents (patches) read and write this same object; nothing else exists.
+ */
+export const CONFIG_SCHEMA_ID = 'paper-fold-promo/1';
+export type PaperFoldConfig = { schema?: typeof CONFIG_SCHEMA_ID } & { [group: string]: unknown };
+export type { ConfigError, ConfigPatch, PatchOp };
+export { getPath, isAssetRef };
+const NAME = 'paper-fold-promo';
+
+const RATIOS: Record<AspectRatio, number> = { '9:16': 9 / 16, '16:9': 16 / 9, '1:1': 1 };
+
+type Fold = { id: string; enabled: boolean; direction: 'down' | 'up'; delayFrames: number; durationFrames: number; unfoldDelayFrames: number; unfoldDurationFrames: number };
+
+/** Cross-field rules: the canvas shape, crease order, one panel that stays put, stops in order, a sane timeline. */
+function relations(cfg: PaperFoldConfig, errors: ConfigError[]) {
+  const n = (p: string) => getPath(cfg, p) as number;
+  const ratio = RATIOS[getPath(cfg, 'canvas.aspectRatio') as AspectRatio];
+  if (ratio) {
+    const actual = n('canvas.width') / n('canvas.height');
+    if (Math.abs(actual / ratio - 1) > 0.01) errors.push({ path: 'canvas.width', message: `canvas.width × canvas.height (${n('canvas.width')} × ${n('canvas.height')}) does not match canvas.aspectRatio ${String(getPath(cfg, 'canvas.aspectRatio'))}. Set all three together (the portrait, landscape and square presets do).` });
+  }
+  const c0 = n('creases.0.position'), c1 = n('creases.1.position');
+  if (c1 - c0 < 0.1) errors.push({ path: 'creases.1.position', message: `creases.bottom.position (${c1}) must be at least 0.1 below creases.top.position (${c0}): every panel needs height.` });
+  const [top, bottom] = getPath(cfg, 'folds') as Fold[];
+  if (top!.enabled && bottom!.enabled && top!.direction === 'up' && bottom!.direction === 'down') {
+    errors.push({ path: 'folds.1.direction', message: 'folds.top.direction "up" swings the middle panel from the top crease while folds.bottom.direction "down" swings it from the bottom crease: one panel has to stay put. Use top down + bottom up (the middle stays), top up + bottom up (the top stays) or top down + bottom down (the bottom stays).' });
+  }
+  const stops = getPath(cfg, 'background.gradient.stops') as { offset: number }[];
+  for (let i = 1; i < stops.length; i++) {
+    if (stops[i]!.offset < stops[i - 1]!.offset) errors.push({ path: `background.gradient.stops.${i}.offset`, message: `background.gradient.stops must be in order of offset: stop ${i} (${stops[i]!.offset}) comes before stop ${i - 1} (${stops[i - 1]!.offset}).` });
+  }
+  // Phases run in order. A negative delay overlaps the phase before, but a phase may not start before
+  // frame 0 or before the phase ahead of it starts, and an unfold may not start before its fold ends.
+  const spans = phaseSpans(cfg);
+  let prev = 0;
+  for (const s of spans) {
+    if (s.start < 0) errors.push({ path: s.delayPath, message: `${s.label} would start at frame ${s.start}, before the video starts. Raise ${s.delayPath}.` });
+    else if (s.start < prev) errors.push({ path: s.delayPath, message: `${s.label} would start at frame ${s.start}, before the phase ahead of it (frame ${prev}). Phases run in order; raise ${s.delayPath} or the phase's startFrame.` });
+    prev = Math.max(prev, s.start);
+  }
+  const at = (id: string) => spans.find((s) => s.id === id)!;
+  for (const [fold, unfold, key] of [['topFold', 'topUnfold', 'top'], ['bottomFold', 'bottomUnfold', 'bottom']] as const) {
+    if (at(unfold).start < at(fold).end) errors.push({ path: `folds.${key === 'top' ? 0 : 1}.unfoldDelayFrames`, message: `The ${key} fold would start unfolding (frame ${at(unfold).start}) before it has finished folding (frame ${at(fold).end}).` });
+  }
+}
+
+/**
+ * The seven phases in order with their start and end (60 fps motion frames, before motion.speed).
+ * Pure; also used by the engine, so the validator and the renderer agree on every phase boundary.
+ */
+export function phaseSpans(cfg: PaperFoldConfig) {
+  const n = (p: string) => getPath(cfg, p) as number;
+  const folds = getPath(cfg, 'folds') as Fold[];
+  const fold = (k: 0 | 1) => folds[k]!;
+  const spec = [
+    { id: 'intro', label: 'INTRO', start: 'timeline.intro.startFrame', delay: 'timeline.intro.delayFrames', duration: () => n('timeline.intro.durationFrames') },
+    { id: 'topFold', label: 'TOP_FOLD', start: 'timeline.topFold.startFrame', delay: 'folds.0.delayFrames', duration: () => (fold(0).enabled ? fold(0).durationFrames : 0), enabled: fold(0).enabled },
+    { id: 'bottomFold', label: 'BOTTOM_FOLD', start: 'timeline.bottomFold.startFrame', delay: 'folds.1.delayFrames', duration: () => (fold(1).enabled ? fold(1).durationFrames : 0), enabled: fold(1).enabled },
+    { id: 'foldedHold', label: 'FOLDED_HOLD', start: 'timeline.foldedHold.startFrame', delay: 'timeline.foldedHold.delayFrames', duration: () => n('timeline.foldedHold.durationFrames') },
+    { id: 'bottomUnfold', label: 'BOTTOM_UNFOLD', start: 'timeline.bottomUnfold.startFrame', delay: 'folds.1.unfoldDelayFrames', duration: () => (fold(1).enabled ? fold(1).unfoldDurationFrames : 0), enabled: fold(1).enabled },
+    { id: 'topUnfold', label: 'TOP_UNFOLD', start: 'timeline.topUnfold.startFrame', delay: 'folds.0.unfoldDelayFrames', duration: () => (fold(0).enabled ? fold(0).unfoldDurationFrames : 0), enabled: fold(0).enabled },
+    { id: 'finalHold', label: 'FINAL_HOLD', start: 'timeline.finalHold.startFrame', delay: 'timeline.finalHold.delayFrames', duration: () => n('timeline.finalHold.durationFrames') },
+  ];
+  let end = 0;
+  return spec.map((s) => {
+    const explicit = n(s.start);
+    // A disabled fold's phases take no time and no delay.
+    const delay = s.enabled === false ? 0 : n(s.delay);
+    const start = (explicit >= 0 ? explicit : end) + delay;
+    const e = start + s.duration();
+    end = Math.max(end, e);
+    return { id: s.id, label: s.label, start, end: e, delayPath: s.delay, startPath: s.start };
+  });
+}
+
+const api = createConfigApi<PaperFoldConfig>({ name: NAME, schemaId: CONFIG_SCHEMA_ID, title: 'Paper fold promo configuration', controls: CONTROLS, lists: LISTS, relations });
+
+export const { defaultItem, canonicalPath, controlAt, validateConfig, applyPatch, diffConfig, configJsonSchema } = api;
+/** The neutral default config (no reference copy): every control and list at its default. A fresh copy each call. */
+export const defaultConfig = api.defaultConfig;
+
+/** A valid, complete config, or an error listing every problem. */
+export class PaperFoldConfigError extends Error {
+  constructor(readonly errors: ConfigError[]) {
+    super(`Invalid ${NAME} configuration:\n${errors.map((e) => `  ${e.path || '(root)'}: ${e.message}`).join('\n')}`);
+  }
+}
+export function resolveConfig(input: unknown): PaperFoldConfig {
+  const r = validateConfig(input);
+  if (!r.valid) throw new PaperFoldConfigError(r.errors);
+  return r.config!;
+}
+export type { Obj };