@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/paperfold/fonts.ts

@@ -0,0 +1,21 @@
+import { FONT_FAMILIES } from './controls';
+
+/**
+ * The registered typefaces (all OFL, from Google Fonts), upright and italic where the family has an
+ * italic. Remotion loads them with `@remotion/google-fonts`; the web player adds this stylesheet once.
+ */
+const ITALIC = new Set(['Inter', 'Manrope', 'DM Sans', 'Plus Jakarta Sans']);
+const RANGE: Record<string, string> = { Inter: '300..900', Manrope: '300..800', 'DM Sans': '300..900', 'Plus Jakarta Sans': '300..800', 'Space Grotesk': '300..700' };
+export const PAPER_FOLD_FONTS_CSS = `https://fonts.googleapis.com/css2?${FONT_FAMILIES.map((f) => {
+  const r = RANGE[f] ?? '300..800';
+  return `family=${f.replace(/ /g, '+')}:${ITALIC.has(f) ? `ital,wght@0,${r};1,${r}` : `wght@${r}`}`;
+}).join('&')}&display=swap`;
+
+export function installPaperFoldFonts(doc: Document | undefined = typeof document === 'undefined' ? undefined : document) {
+  if (!doc || doc.querySelector('link[data-paper-fold-fonts]')) return;
+  const link = doc.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = PAPER_FOLD_FONTS_CSS;
+  link.setAttribute('data-paper-fold-fonts', '');
+  doc.head.appendChild(link);
+}

package/src/motion/paperfold/index.ts

@@ -0,0 +1,30 @@
+/**
+ * **paper-fold-promo — a configurable-motion template drawn procedurally and rendered by Remotion.**
+ * One canonical config (the control table), a pure engine that folds three hinged panels in
+ * perspective and poses two vector hands, and a React/DOM renderer that draws it. `docs/MOTION-TEMPLATES.md`.
+ */
+export {
+  CONTROLS, CONTROL_BY_PATH, LISTS, LIST_BY_PATH, GROUPS, EASING_NAMES, ASPECT_RATIOS, FPS_OPTIONS, FONT_FAMILIES, FONT_WEIGHTS,
+  PANELS, FOLD_KEYS, HANDS, FOLD_DIRECTIONS, FOLD_SIDES, PHASES, PHASE_LABEL, PAPER_TEXT, LAYOUT_FOR, allControls,
+  type Control, type ListSpec, type Group, type EasingName, type AspectRatio, type PhaseId, type PanelId, type FoldKey, type HandId, type PaperTextId,
+} from './controls';
+export {
+  CONFIG_SCHEMA_ID, defaultConfig, defaultItem, validateConfig, resolveConfig, applyPatch, diffConfig, configJsonSchema, getPath, controlAt, canonicalPath,
+  phaseSpans, isAssetRef, PaperFoldConfigError, type PaperFoldConfig, type ConfigError, type ConfigPatch, type PatchOp,
+} from './config';
+export { PRESET_PATCHES, presetConfig, type PresetName } from './presets';
+export {
+  frameState, timeline, layout, foldState, anchorOf, moversOf, outputDuration, outputFrameToMotion, motionToOutputFrame, phaseAt, stageFrames,
+  cssMatrix, project, mul, apply, seeded, mixHex, rgba, stripAt, manualFolds, EDGE_LIFT_SEGMENTS, textFits, estimateLines, BEND_SEGMENTS, MOTION_FPS,
+  type FrameState, type StripState, type Strip, type Sheet, type TextFit, type Timeline, type PhaseSpan, type Layout, type FoldState, type PanelState, type HandState, type EdgeFx, type Anchor, type Mat,
+} from './engine';
+export {
+  topHand, bottomHand, sleevePath, handSvg, handBodySvg, handFingerSvg, paperSheetSvg, paperSvg, creaseSvg, logoSvg, backgroundTypeSvg, HAND_SPECS, DEFAULT_POSE,
+  REFERENCE_HAND_COLOURS, REFERENCE_SHEET, type P, type HandArt, type HandPart, type HandShape, type HandPose, type HandPartName, type HandFill,
+} from './art';
+export { PAPER_FOLD_FONTS_CSS, installPaperFoldFonts } from './fonts';
+export { PaperFoldFrame, FONT_STACK, handArt, handTransform, type PaperFoldFrameProps, type ImageProps } from './PaperFoldFrame';
+export { PaperFoldPlayer, type PaperFoldPlayerProps } from './PaperFoldPlayer';
+export { PaperFold, type PaperFoldProps, type HandPoseProps } from './PaperFold';
+export { hitTest, handlesFor, dragPatch, canvasToSheet, handToScene, squareToQuad, quadToSquare, type Selection, type Handles } from './manipulate';
+export { paperFoldPromo } from './template';

package/src/motion/paperfold/manipulate.ts

@@ -0,0 +1,188 @@
+import { getPath, type PaperFoldConfig } from './config';
+import type { FrameState, HandState } from './engine';
+import type { HandArt, P } from './art';
+
+/**
+ * **Direct manipulation of paper-fold-promo** — pure geometry for an editor laid over the player:
+ * what is under the pointer (a gripping finger, a hand, a fold axis, a panel), its bounding box,
+ * transform origin and rotation handle, and the config patch a drag produces. Every edit is a patch of
+ * the same controls an agent sets, validated by the same `applyPatch`; the editor never moves
+ * pixels on its own.
+ */
+export type Selection =
+  | { kind: 'panel'; id: 'top' | 'middle' | 'bottom' }
+  | { kind: 'axis'; id: 0 | 1 }
+  | { kind: 'hand'; id: 'top' | 'bottom' }
+  | { kind: 'finger'; id: 'top' | 'bottom'; digit: string };
+
+type Quad = [number, number][];
+const dist = (a: P, b: P) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);
+
+/** The 3×3 homography taking the unit square (0,0)(1,0)(1,1)(0,1) onto `q` (a projected quad). */
+export function squareToQuad(q: Quad): number[] {
+  const [[x0, y0], [x1, y1], [x2, y2], [x3, y3]] = q as [P, P, P, P];
+  const dx1 = x1 - x2, dx2 = x3 - x2, dy1 = y1 - y2, dy2 = y3 - y2;
+  const sx = x0 - x1 + x2 - x3, sy = y0 - y1 + y2 - y3;
+  const den = dx1 * dy2 - dx2 * dy1;
+  const g = den ? (sx * dy2 - dx2 * sy) / den : 0, h = den ? (dx1 * sy - sx * dy1) / den : 0;
+  return [x1 - x0 + g * x1, x3 - x0 + h * x3, x0, y1 - y0 + g * y1, y3 - y0 + h * y3, y0, g, h, 1];
+}
+/** Where canvas point `p` lies in quad `q`, as (u, v) in the unit square (outside it when outside the quad). */
+export function quadToSquare(q: Quad, p: P): P {
+  const [a, b, c, d, e, f, g, h] = squareToQuad(q) as [number, number, number, number, number, number, number, number];
+  // Inverse of [[a,b,c],[d,e,f],[g,h,1]] applied to (x, y, 1).
+  const A = e - f * h, B = c * h - b, C = b * f - c * e, D = f * g - d, E = a - c * g, F = c * d - a * f, G = d * h - e * g, H = b * g - a * h, K = a * e - b * d;
+  const [x, y] = p;
+  const w = G * x + H * y + K;
+  return [(A * x + B * y + C) / w, (D * x + E * y + F) / w];
+}
+const insideQuad = (q: Quad, p: P) => { const [u, v] = quadToSquare(q, p); return u >= 0 && u <= 1 && v >= 0 && v <= 1; };
+
+/** The camera's 2D transform (it is applied to the whole scene), as a function canvas-of-scene → canvas. */
+function cameraMap(st: FrameState): { fwd: (p: P) => P; inv: (p: P) => P } {
+  const cfg = st.cfg, n = (k: string) => getPath(cfg, k) as number;
+  const W = st.size.width, H = st.size.height, u = st.size.unit, z = st.camera.zoom, r = (n('camera.rotation') * Math.PI) / 180;
+  const cx = W / 2, cy = H / 2, px = n('camera.x') * u, py = n('camera.y') * u, c = Math.cos(r), s = Math.sin(r);
+  return {
+    fwd: ([x, y]) => { const X = x - cx - px, Y = y - cy - py; return [cx + z * (c * X - s * Y), cy + z * (s * X + c * Y)]; },
+    inv: ([x, y]) => { const X = (x - cx) / z, Y = (y - cy) / z; return [cx + px + c * X + s * Y, cy + py - s * X + c * Y]; },
+  };
+}
+
+/** A point in hand units through the hand's transform (as `handTransform`), onto the scene. */
+export function handToScene(h: HandState, [x, y]: P): P {
+  const k = h.unitScale * h.scale;
+  let X = (x + h.offsetX) * k, Y = (y + h.offsetY) * k;
+  const ty = Math.tan((h.skewY * Math.PI) / 180), tx = Math.tan((h.skewX * Math.PI) / 180);
+  // As SVG applies them: skewY first, then skewX.
+  Y += ty * X;
+  X += tx * Y;
+  const r = (h.rotation * Math.PI) / 180, c = Math.cos(r), s = Math.sin(r);
+  return [h.x + c * X - s * Y, h.y + s * X + c * Y];
+}
+
+/** A canvas point on the sheet, as normalized sheet coordinates (0‥1 across and down), or undefined off it. */
+export function canvasToSheet(st: FrameState, p: P): P | undefined {
+  const q = cameraMap(st).inv(p);
+  // The front-most strip under the point wins.
+  const hit = [...st.strips].sort((a, b) => b.z - a.z).find((s) => insideQuad(s.corners, q));
+  if (!hit) return undefined;
+  const [u, v] = quadToSquare(hit.corners, q);
+  return [u, (hit.y0 + v * (hit.y1 - hit.y0)) / st.size.paper.height];
+}
+
+export type Handles = {
+  /** Axis-aligned bounds on the canvas. */
+  box: { x: number; y: number; width: number; height: number };
+  /** The outline drawn for the selection (a quad, a line, or the hand's silhouette points). */
+  outline: P[];
+  origin: P;
+  /** Where the rotation handle sits (none for a fold axis, which drags along the sheet). */
+  rotate?: P;
+  label: string;
+};
+
+/** Bounding box, transform origin and rotation handle of a selection, in canvas px. */
+export function handlesFor(st: FrameState, sel: Selection, art: Record<'top' | 'bottom', HandArt>): Handles {
+  const cam = cameraMap(st).fwd;
+  const bounds = (pts: P[]) => {
+    const xs = pts.map((p) => p[0]), ys = pts.map((p) => p[1]);
+    return { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+  };
+  if (sel.kind === 'panel') {
+    const p = st.panels.find((x) => x.id === sel.id)!;
+    const outline = p.corners.map(cam) as P[];
+    // A panel turns about its crease: the top panel about its bottom edge, the bottom panel about its top edge.
+    const axis = sel.id === 'top' ? st.debug.creases[0]! : st.debug.creases[1]!;
+    const origin = cam([(axis.from[0] + axis.to[0]) / 2, (axis.from[1] + axis.to[1]) / 2]);
+    // The handle sits on the edge opposite the panel's axis: the edge that travels as it folds.
+    const far = sel.id === 'bottom' ? [outline[3]!, outline[2]!] : [outline[0]!, outline[1]!];
+    const rotate: P = [(far[0]![0] + far[1]![0]) / 2, (far[0]![1] + far[1]![1]) / 2];
+    return { box: bounds(outline), outline, origin, rotate, label: `${sel.id.toUpperCase()} PANEL — drag the handle to fold` };
+  }
+  if (sel.kind === 'axis') {
+    const c = st.debug.creases[sel.id]!;
+    const outline = [cam(c.from), cam(c.to)];
+    return { box: bounds(outline), outline, origin: cam([(c.from[0] + c.to[0]) / 2, (c.from[1] + c.to[1]) / 2]), label: `FOLD AXIS ${c.id.toUpperCase()} · ${c.position.toFixed(3)} · ${c.angle.toFixed(0)}° — drag up or down` };
+  }
+  const h = st.hands.find((x) => x.id === sel.id)!;
+  const a = art[sel.id];
+  if (sel.kind === 'finger') {
+    const j = (a.joints[sel.digit] ?? []).map((q) => cam(handToScene(h, q)));
+    const knuckle = j[1] ?? j[0]!;
+    return { box: bounds(j), outline: j, origin: knuckle, rotate: j.at(-1), label: `${sel.id} ${sel.digit} — drag its tip to curl` };
+  }
+  const pts = [...a.palmOutline, ...Object.values(a.joints).flat()].map((q) => cam(handToScene(h, q)));
+  const origin = cam([h.x, h.y]);
+  const box = bounds(pts);
+  return { box, outline: [[box.x, box.y], [box.x + box.width, box.y], [box.x + box.width, box.y + box.height], [box.x, box.y + box.height]], origin, rotate: [box.x + box.width / 2, box.y - 24], label: `${sel.id.toUpperCase()} HAND — drag to move its grip, the handle to rotate` };
+}
+
+/** What is under canvas point `p`: gripping fingers first, then hands, fold axes, panels. */
+export function hitTest(st: FrameState, p: P, art: Record<'top' | 'bottom', HandArt>, tolerance = 10): Selection | undefined {
+  const cam = cameraMap(st).fwd;
+  for (const h of st.hands) {
+    if (!h.enabled) continue;
+    for (const digit of ['thumb', 'indexFinger', 'middleFinger']) {
+      const j = art[h.id].joints[digit];
+      if (j && j.slice(2).some((q) => dist(cam(handToScene(h, q)), p) < tolerance * 1.4)) return { kind: 'finger', id: h.id, digit };
+    }
+  }
+  for (const h of st.hands) {
+    if (!h.enabled) continue;
+    const palm = art[h.id].palmOutline.map((q) => cam(handToScene(h, q)));
+    const xs = palm.map((q) => q[0]), ys = palm.map((q) => q[1]);
+    if (p[0] >= Math.min(...xs) && p[0] <= Math.max(...xs) && p[1] >= Math.min(...ys) && p[1] <= Math.max(...ys)) return { kind: 'hand', id: h.id };
+  }
+  for (const k of [0, 1] as const) {
+    const c = st.debug.creases[k]!;
+    const a = cam(c.from), b = cam(c.to);
+    const t = clamp(((p[0] - a[0]) * (b[0] - a[0]) + (p[1] - a[1]) * (b[1] - a[1])) / (dist(a, b) ** 2 || 1), 0, 1);
+    if (dist(p, [a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1])]) < tolerance) return { kind: 'axis', id: k };
+  }
+  const panel = [...st.panels].sort((a, b) => b.z - a.z).find((x) => insideQuad(x.corners.map(cam) as Quad, p));
+  return panel ? { kind: 'panel', id: panel.id } : undefined;
+}
+
+/**
+ * The patch a drag produces: from where it started (`from`) to where the pointer is (`to`), both canvas
+ * px, against the state at drag start. Values are clamped to their controls' ranges.
+ */
+export function dragPatch(cfg: PaperFoldConfig, st: FrameState, sel: Selection, from: P, to: P, handle: 'body' | 'rotate'): Record<string, unknown> {
+  const n = (k: string) => getPath(cfg, k) as number;
+  const dy = to[1] - from[1];
+  const scale = st.size.paper.height;
+  if (sel.kind === 'panel') {
+    // Folding by hand: the far edge's handle travels toward the crease → more fold (manual FOLD PROGRESS).
+    const base = getPath(cfg, 'motion.progressMode') === 'manual' ? n('motion.foldProgress') : 0;
+    const dir = sel.id === 'top' ? 1 : -1;
+    const range = sel.id === 'middle' ? 1 : 0.5;
+    const delta = (dir * dy) / (scale * 0.6) * range;
+    const lo = sel.id === 'bottom' ? 0.5 : 0, hi = sel.id === 'top' ? 0.5 : 1;
+    return { 'motion.progressMode': 'manual', 'motion.foldProgress': Math.round(clamp(clamp(base, lo, hi) + delta, lo, hi) * 1000) / 1000 };
+  }
+  if (sel.kind === 'axis') {
+    const at = canvasToSheet(st, to);
+    const pos = at ? at[1] : n(`creases.${sel.id}.position`) + dy / scale;
+    const other = n(`creases.${sel.id === 0 ? 1 : 0}.position`);
+    // Keep every panel at least 0.1 of the sheet tall (the validator's rule).
+    // (A thousandth of margin, so rounding never lands a hair inside the 0.1 limit.)
+    const v = sel.id === 0 ? clamp(pos, 0.1, other - 0.101) : clamp(pos, other + 0.101, 0.9);
+    return { [`creases.${sel.id}.position`]: sel.id === 0 ? Math.floor(v * 1000) / 1000 : Math.ceil(v * 1000) / 1000 };
+  }
+  const H = `hands.${sel.id}`;
+  if (sel.kind === 'finger') {
+    const path = sel.digit === 'thumb' ? `${H}.pose.thumbBend` : `${H}.pose.fingerCurl`;
+    const [lo, hi] = sel.digit === 'thumb' ? [-1, 1] : [0.3, 1.4];
+    return { [path]: Math.round(clamp(n(path) + dy / 150, lo, hi) * 100) / 100 };
+  }
+  if (handle === 'rotate') {
+    const h = st.hands.find((x) => x.id === sel.id)!;
+    const a0 = Math.atan2(from[1] - h.y, from[0] - h.x), a1 = Math.atan2(to[1] - h.y, to[0] - h.x);
+    return { [`${H}.rotation`]: Math.round(clamp(n(`${H}.rotation`) + ((a1 - a0) * 180) / Math.PI, -180, 180) * 10) / 10 };
+  }
+  const at = canvasToSheet(st, to);
+  if (!at) return {};
+  return { [`${H}.x`]: Math.round(clamp(at[0], 0, 1) * 1000) / 1000, [`${H}.y`]: Math.round(clamp(at[1], 0, 1) * 1000) / 1000 };
+}

package/src/motion/paperfold/presets.ts

@@ -0,0 +1,117 @@
+/* eslint-disable comppack/no-raw-colour -- preset colours are content, set through the same config as any edit (DECISIONS §25–§27). */
+import { applyPatch, defaultConfig, type PaperFoldConfig } from './config';
+
+/**
+ * **Presets** — named patches over the neutral default config. Applying one is the same operation as
+ * any agent or person edit. The reference copy (the tixdoor launch) exists only here, in the
+ * `reference` patch, never in the implementation.
+ */
+const REFERENCE: Record<string, unknown> = {
+  'content.logo': 'tixdoor',
+  'logo.markText': 'T',
+  'content.top.headline': 'We are launching soon',
+  'content.middle.headline': 'Ready for a Better Way to Attend Events?',
+  'content.bottom.body': 'We\'re building the smarter way to discover, create, and attend events.',
+  'content.cta.text': 'Join Our Waitlist',
+  'background.backgroundTypography.text': 'LAUNCH',
+};
+const canvas = (aspectRatio: string, width: number, height: number) => ({ 'canvas.aspectRatio': aspectRatio, 'canvas.width': width, 'canvas.height': height });
+
+/** A second campaign on the same template: different words, palette, background word, hands, speed and CTA. */
+const DEMO: Record<string, unknown> = {
+  'content.logo': 'Northstar',
+  'logo.markText': 'N',
+  'logo.markColor': '#ffcc4d',
+  'logo.markColorEnd': '#ff9f1c',
+  'logo.markTextColor': '#10324a',
+  'content.top.headline': 'Your next idea starts here',
+  'content.middle.headline': 'Design. Build. Launch.',
+  'content.bottom.body': 'Everything you need to move from concept to product.',
+  'content.back.text': 'Northstar',
+  'content.back.panel': 'top',
+  'content.cta.text': 'Get Started',
+  'typography.topHeadline.color': '#10324a',
+  'typography.topHeadline.fontStyle': 'normal',
+  'typography.topHeadline.fontWeight': 800,
+  'typography.topHeadline.skew': 0,
+  'typography.topHeadline.fontFamily': 'Space Grotesk',
+  'typography.topHeadline.fontSize': 96,
+  'typography.middleHeadline.color': '#10324a',
+  'typography.middleHeadline.fontFamily': 'Space Grotesk',
+  'typography.middleHeadline.fontWeight': 700,
+  'typography.middleHeadline.fontSize': 92,
+  'typography.middleHeadline.maxWidth': 0.62,
+  'typography.bottomBody.color': '#2b4a60',
+  'typography.bottomBody.fontStyle': 'normal',
+  'typography.back.color': '#10324a',
+  'typography.back.fontFamily': 'Space Grotesk',
+  'typography.logo.fontFamily': 'Space Grotesk',
+  'typography.logo.fontWeight': 700,
+  'typography.cta.color': '#10324a',
+  'typography.cta.fontWeight': 700,
+  'foldLighting.ambient': 0.62,
+  'foldLighting.diffuse': 0.46,
+  'paperMaterial.baseColor': '#f3ede2',
+  'paperMaterial.backColor': '#e4d8c4',
+    'paperMaterial.secondaryColor': '#ece3d3',
+  'paperMaterial.textureOpacity': 0.12,
+  'paperMaterial.edgeShadow': 0.12,
+  'creases.0.color': '#9c8d74',
+  'creases.1.color': '#9c8d74',
+  'creases.0.highlightColor': '#ffffff',
+  'creases.1.highlightColor': '#ffffff',
+  'paper.shadow.color': '#04121c',
+  'paper.shadow.opacity': 0.45,
+  'background.baseColor': '#10324a',
+  'background.gradient.stops': [{ offset: 0, color: '#123a55' }, { offset: 1, color: '#0a2233' }],
+  'background.backgroundTypography.text': 'CREATE',
+  'background.backgroundTypography.color': '#174765',
+  'background.backgroundTypography.weight': 800,
+  'background.backgroundTypography.fontFamily': 'Space Grotesk',
+  'background.backgroundTypography.drift': 24,
+  'background.backgroundTypography.repeat': 2,
+  'background.glow.color': '#3fb6c9',
+  'background.glow.opacity': 0.22,
+  'hands.style.baseColor': '#d9976f',
+  'hands.style.midtoneColor': '#b9744c',
+  'hands.style.shadowColor': '#8a4f31',
+  'hands.style.highlightColor': '#eab08a',
+  'hands.style.nailColor': '#f5cdb7',
+  'hands.style.sleeve.enabled': true,
+  'hands.style.sleeve.color': '#2f6f8f',
+  'hands.top.x': 0.62,
+  'hands.bottom.x': 0.34,
+  'folds.0.peakAngle': 170,
+  'folds.0.durationFrames': 40,
+  'folds.0.unfoldDurationFrames': 36,
+  'folds.0.easing': 'easeInOutQuart',
+  'folds.1.peakAngle': 164,
+  'folds.1.durationFrames': 38,
+  'folds.1.unfoldDurationFrames': 34,
+  'folds.1.easing': 'easeInOutQuart',
+  'timeline.foldedHold.durationFrames': 48,
+  'cta.backgroundColor': '#ffcc4d',
+  'cta.borderColor': '#ffcc4d',
+  'cta.rotation': 3,
+  'cta.radius': 40,
+  'cta.shadowColor': '#04121c',
+  'cta.shadowOpacity': 0.35,
+};
+
+export const PRESET_PATCHES: Record<string, { description: string; patch: Record<string, unknown> }> = {
+  reference: { description: 'The reference: a purple tixdoor launch sheet, Z-folded by two brown hands in front of a LAUNCH wall, 9:16 at 2160 × 3840, 60 fps.', patch: REFERENCE },
+  portrait: { description: '9:16, 2160 × 3840 (layout.portrait) — the reference shape.', patch: { ...REFERENCE, ...canvas('9:16', 2160, 3840) } },
+  landscape: { description: '16:9, 3840 × 2160 (layout.landscape): the sheet on the left, the logo and CTA on the right.', patch: { ...REFERENCE, ...canvas('16:9', 3840, 2160) } },
+  square: { description: '1:1, 2160 × 2160 (layout.square).', patch: { ...REFERENCE, ...canvas('1:1', 2160, 2160) } },
+  demo: { description: 'Northstar: a cream sheet on deep teal, CREATE drifting behind, lighter hands in sleeves, deeper and quicker folds, a yellow Get Started button.', patch: DEMO },
+};
+export type PresetName = keyof typeof PRESET_PATCHES;
+
+/** A preset as a complete, valid config. */
+export function presetConfig(name: string): PaperFoldConfig {
+  const p = PRESET_PATCHES[name];
+  if (!p) throw new Error(`Unknown paper-fold-promo preset "${name}". Available: ${Object.keys(PRESET_PATCHES).join(', ')}.`);
+  const r = applyPatch(defaultConfig(), { patch: p.patch });
+  if (!r.valid) throw new Error(`Preset "${name}" is invalid: ${r.errors.map((e) => e.message).join(' ')}`);
+  return r.config;
+}

package/src/motion/paperfold/template.ts

@@ -0,0 +1,38 @@
+import type { ConfigurableMotionTemplate } from '../types';
+import { configJsonSchema } from './config';
+import { allControls, GROUPS } from './controls';
+import { outputDuration } from './engine';
+import { PRESET_PATCHES, presetConfig } from './presets';
+
+/**
+ * **paper-fold-promo in the motion registry.** A configurable-motion template (DECISIONS §25–§27) drawn
+ * procedurally by React/DOM — three perspective panels hinged at real creases, vector hands, live
+ * text — and rendered to video by Remotion. People and agents edit the same canonical config. Plain
+ * data — safe to JSON-serialise.
+ */
+const reference = presetConfig('reference');
+export const paperFoldPromo: ConfigurableMotionTemplate = {
+  id: 'paper-fold-promo',
+  version: '1.0.0',
+  kind: 'configurableMotion',
+  renderer: 'remotion',
+  title: 'Paper fold promo — a printed sheet folded and opened by two hands',
+  description: 'A vertical promotional sheet in three panels, held by two illustrated hands in front of a wall of large type. The top panel folds over along its crease in true perspective, then the bottom one; the paper holds folded, then unfolds back to the open sheet. Every word, colour, crease, fold angle, timing, easing, hand pose and light is configurable; 9:16, 16:9 and 1:1 each have their own layout.',
+  fps: 60,
+  formats: [
+    { id: 'portrait', aspectRatio: '9:16', width: 2160, height: 3840 },
+    { id: 'landscape', aspectRatio: '16:9', width: 3840, height: 2160 },
+    { id: 'square', aspectRatio: '1:1', width: 2160, height: 2160 },
+  ],
+  durationInFrames: outputDuration(reference),
+  groups: [...GROUPS],
+  controls: allControls(),
+  schema: configJsonSchema(),
+  presets: PRESET_PATCHES,
+  remotion: {
+    project: 'remotion-prototype',
+    compositions: ['PaperFoldPromoPortrait', 'PaperFoldPromoLandscape', 'PaperFoldPromoSquare'],
+    reference: 'remotion-prototype/content/paper-fold-promo/reference.json',
+  },
+  exampleContent: reference,
+};

package/src/motion/player.ts

@@ -0,0 +1,207 @@
+/**
+ * **The HTML runtime** — plays a motion template in any web page.
+ *
+ *   content JSON → validate against the template's schema → template markup → bind [data-content]
+ *   → apply theme → fit text → animate [data-target] from the motion contract
+ *
+ * It knows nothing about any particular template. Content is written with `textContent` only, so text
+ * from an agent can never become markup; theme values are checked hex colours.
+ */
+import { fitScale } from './fit';
+import { createSampler, durationFor, formatFor, itemScene, sceneAt, themeVariables } from './sample';
+import type { MotionTemplate } from './types';
+import { validateMotionContent, type MotionContentError } from './validate';
+
+export class MotionContentValidationError extends Error {
+  constructor(readonly errors: MotionContentError[]) {
+    super(`Invalid content:\n${errors.map((e) => `  - ${e.message}`).join('\n')}`);
+    this.name = 'MotionContentValidationError';
+  }
+}
+
+export type MotionController = {
+  seek(frame: number): void;
+  play(): void;
+  pause(): void;
+  readonly frame: number;
+  readonly playing: boolean;
+  readonly fps: number;
+  readonly durationInFrames: number;
+  /** The canvas this content plays on (its format's size). */
+  readonly width: number;
+  readonly height: number;
+  /** Resolves once fonts are loaded and text has been fitted. Seek/play are safe before it. */
+  readonly ready: Promise<void>;
+  destroy(): void;
+};
+
+const read = (content: unknown, path: string) =>
+  path.split('.').reduce<unknown>((v, k) => (v && typeof v === 'object' ? (v as Record<string, unknown>)[k] : undefined), content);
+
+/**
+ * Add the template's font and style sheets to the document once. Resolves when the font faces are
+ * usable: text is measured for auto-fit, and a measurement taken in a fallback font would be wrong.
+ */
+export function installMotionStyles(template: MotionTemplate, doc: Document = document): Promise<void> {
+  const loads: Promise<unknown>[] = [];
+  for (const f of template.fonts) {
+    const key = `font:${f.family}`;
+    let link = doc.head.querySelector<HTMLLinkElement>(`[data-motion-styles="${key}"]`);
+    if (!link) {
+      link = Object.assign(doc.createElement('link'), { rel: 'stylesheet', href: f.css });
+      link.dataset.motionStyles = key;
+      link.dataset.loaded = 'false';
+      link.addEventListener('load', () => (link!.dataset.loaded = 'true'), { once: true });
+      doc.head.append(link);
+    }
+    if (link.dataset.loaded === 'false') {
+      const l = link;
+      loads.push(new Promise((r) => { l.addEventListener('load', r, { once: true }); l.addEventListener('error', r, { once: true }); }));
+    }
+  }
+  const key = `${template.id}@${template.version}`;
+  if (!doc.head.querySelector(`[data-motion-styles="${key}"]`)) {
+    const style = Object.assign(doc.createElement('style'), { textContent: template.styles });
+    style.dataset.motionStyles = key;
+    doc.head.append(style);
+  }
+  if (!doc.fonts) return Promise.resolve();
+  return Promise.all(loads)
+    .then(() => Promise.all(template.fonts.flatMap((f) => f.weights.map((w) => doc.fonts.load(`${w} ${f.stretch ? `${f.stretch} ` : ''}16px "${f.family}"`)))))
+    .then(() => doc.fonts.ready)
+    .then(() => undefined, () => undefined);
+}
+
+export type MountOptions = { loop?: boolean; autoPlay?: boolean; onFrame?: (frame: number) => void; onEnd?: () => void };
+
+/**
+ * A sequence template's markup holds ONE item scene, `[data-scene="<list>.$"]`. It is cloned once per
+ * item, in order: `$` in `data-scene` and `data-content` becomes the index, and each item choice is
+ * written as `data-<field>` (a validated enum value; unset choices get the schema default). Parts
+ * marked `data-when="<field>=<value>"` stay only in items with that choice.
+ */
+function expandSequence(canvas: HTMLElement, template: MotionTemplate, content: unknown) {
+  const seq = template.motion.sequence!;
+  const proto = canvas.querySelector<HTMLElement>(`[data-scene="${seq.path}.$"]`);
+  if (!proto) return;
+  const items = (read(content, seq.path) as Record<string, unknown>[] | undefined) ?? [];
+  const defaults = Object.fromEntries((template.choices ?? []).map((c) => [c.field, c.default]));
+  const clones = items.map((item, i) => {
+    const el = proto.cloneNode(true) as HTMLElement;
+    el.dataset.scene = `${seq.path}.${i}`;
+    for (const field of Object.keys(seq.options)) {
+      const v = field === seq.motionField ? itemScene(template.motion, item) : item[field] ?? defaults[field];
+      if (v !== undefined) el.setAttribute(`data-${field}`, String(v));
+    }
+    /* `data-when="field=value"` keeps a part only for items that chose that value (e.g. a layout). */
+    for (const part of Array.from(el.querySelectorAll<HTMLElement>('[data-when]'))) {
+      const [field, value] = part.dataset.when!.split('=') as [string, string];
+      if (el.getAttribute(`data-${field}`) !== value) part.remove();
+    }
+    for (const node of [el, ...Array.from(el.querySelectorAll<HTMLElement>('[data-content],[data-if]'))]) {
+      if (node.dataset.content) node.dataset.content = node.dataset.content.replace(`${seq.path}.$.`, `${seq.path}.${i}.`);
+      if (node.dataset.if) node.dataset.if = node.dataset.if.replace(`${seq.path}.$.`, `${seq.path}.${i}.`);
+    }
+    return el;
+  });
+  proto.replaceWith(...clones);
+}
+
+/** Mount a template into `root` with validated content. Throws `MotionContentValidationError`. */
+export function mountMotion(root: HTMLElement, template: MotionTemplate, content: unknown, options: MountOptions = {}): MotionController {
+  const result = validateMotionContent(template.schema, content);
+  if (!result.valid) throw new MotionContentValidationError(result.errors);
+  const stylesReady = installMotionStyles(template, root.ownerDocument);
+
+  root.innerHTML = template.template;
+  const canvas = root.firstElementChild as HTMLElement;
+  const { motion } = template;
+  const format = formatFor(motion, content);
+  if (motion.formats) canvas.dataset.format = format.id;
+  for (const [k, v] of Object.entries(themeVariables((content as { theme?: Record<string, string> }).theme))) canvas.style.setProperty(k, v);
+  if (motion.sequence) expandSequence(canvas, template, content);
+  /* An optional part whose content is absent is removed (`data-if` names the content path). */
+  for (const el of Array.from(root.querySelectorAll<HTMLElement>('[data-if]'))) {
+    const v = read(content, el.dataset.if!);
+    if (v === undefined || v === null || v === '' || v === false) el.remove();
+  }
+  for (const el of Array.from(root.querySelectorAll<HTMLElement>('[data-content]'))) el.textContent = String(read(content, el.dataset.content!) ?? '');
+
+  const sample = createSampler(motion);
+  const durationInFrames = durationFor(motion, content);
+  const scenes = Array.from(root.querySelectorAll<HTMLElement>('[data-scene]'));
+  const targets = new Map(scenes.map((s) => [s.dataset.scene!, Array.from(s.querySelectorAll<HTMLElement>('[data-target]'))]));
+  /* Fit widths may differ per format: `data-fit-<format id>` overrides `data-fit`. */
+  const fitKey = `fit${format.id.charAt(0).toUpperCase()}${format.id.slice(1)}`;
+
+  let current = 0;
+  let destroyed = false;
+  const seek = (frame: number) => {
+    const f = Math.max(0, Math.min(durationInFrames - 1, Math.floor(frame)));
+    current = f;
+    const at = sceneAt(motion, f, content);
+    for (const s of scenes) s.style.display = s.dataset.scene === at?.id ? '' : 'none';
+    for (const el of (at && targets.get(at.id)) ?? []) {
+      el.removeAttribute('style');
+      Object.assign(el.style, sample(el.dataset.target!, at!.frame, at!.scene));
+    }
+    options.onFrame?.(f);
+  };
+
+  /* Fit needs real layout: show every scene for the measurement, then put the frame back. */
+  const fit = () => {
+    if (destroyed) return;
+    for (const s of scenes) s.style.display = '';
+    const spans = Array.from(root.querySelectorAll<HTMLElement>('[data-fit]'));
+    for (const el of spans) el.style.removeProperty('--fit');
+    const scales = spans.map((el) => fitScale(el.offsetWidth, Number(el.dataset[fitKey] ?? el.dataset.fit)));
+    spans.forEach((el, i) => scales[i]! < 1 && el.style.setProperty('--fit', String(scales[i])));
+    seek(current);
+  };
+
+  let raf = 0;
+  let startedAt = 0;
+  const tick = (now: number) => {
+    const frame = Math.floor(((now - startedAt) / 1000) * motion.fps);
+    if (frame >= durationInFrames && !options.loop) {
+      seek(durationInFrames - 1);
+      raf = 0;
+      options.onEnd?.();
+      return;
+    }
+    seek(frame % durationInFrames);
+    raf = requestAnimationFrame(tick);
+  };
+  const play = () => {
+    if (raf || destroyed) return;
+    if (current >= durationInFrames - 1) current = 0;
+    startedAt = performance.now() - (current / motion.fps) * 1000;
+    raf = requestAnimationFrame(tick);
+  };
+  const pause = () => {
+    cancelAnimationFrame(raf);
+    raf = 0;
+  };
+
+  seek(0);
+  const ready = stylesReady.then(() => fit());
+  if (options.autoPlay) void ready.then(play);
+
+  return {
+    seek,
+    play,
+    pause,
+    get frame() { return current; },
+    get playing() { return raf !== 0; },
+    fps: motion.fps,
+    durationInFrames,
+    width: format.width,
+    height: format.height,
+    ready,
+    destroy() {
+      destroyed = true;
+      pause();
+      root.innerHTML = '';
+    },
+  };
+}