@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/paperfold/controls.ts

@@ -0,0 +1,557 @@
+/* eslint-disable comppack/no-raw-colour -- the defaults are content: the reference look's colours, which people and agents replace (DECISIONS §25–§27). */
+import { controlKit, expandControls, inGroup, type Control as BaseControl, type ListSpec as BaseListSpec } from '../configurable/controls';
+import { EASING_NAMES, FONT_FAMILIES } from '../promo/controls';
+
+/**
+ * **paper-fold-promo — the control table.** Every editable value of the template, once: its path, type,
+ * range or options, default, description, and who may edit it. The defaults, validator, JSON Schema,
+ * patch API, Remotion Studio schema, site editor and the docs table are all generated from here, so a
+ * person and an agent always edit the same contract.
+ *
+ * The defaults are a neutral starting point in the reference look. The reference copy (the tixdoor
+ * launch) lives only in the `reference` preset (`presets.ts` → `content/paper-fold-promo/reference.json`).
+ *
+ * Units:
+ * - `frames` — motion frames at the canonical 60 fps, whatever `canvas.fps` the output samples at.
+ * - `du` — design units: 1/1080 of the canvas's short side (2 px at 4K). Canvas-level things: logo, CTA,
+ *   background type, camera, shadows on the background.
+ * - `pu` — paper units: 1/1000 of the open sheet's width. Everything printed on or attached to the paper
+ *   (text, creases, hands), so it scales with the sheet in every layout.
+ * - `normalized` — 0‥1 across the box the description names (the canvas, the sheet, one panel).
+ * - `deg` — degrees. A fold angle is the dihedral turn at its crease: 0 = flat, 180 = folded flat.
+ */
+export { EASING_NAMES, FONT_FAMILIES };
+export type EasingName = (typeof EASING_NAMES)[number];
+export const ASPECT_RATIOS = ['9:16', '16:9', '1:1'] as const;
+export type AspectRatio = (typeof ASPECT_RATIOS)[number];
+export const LAYOUT_FOR: Record<AspectRatio, 'portrait' | 'landscape' | 'square'> = { '9:16': 'portrait', '16:9': 'landscape', '1:1': 'square' };
+export const FPS_OPTIONS = [24, 25, 30, 50, 60] as const;
+export const FONT_WEIGHTS = [300, 400, 500, 600, 700, 800, 900] as const;
+export const PANELS = ['top', 'middle', 'bottom'] as const;
+export type PanelId = (typeof PANELS)[number];
+export const FOLD_KEYS = ['top', 'bottom'] as const;
+export type FoldKey = (typeof FOLD_KEYS)[number];
+export const HANDS = ['top', 'bottom'] as const;
+export type HandId = (typeof HANDS)[number];
+/** Which side of the crease swings: `down` — the part above the crease; `up` — the part below it. */
+export const FOLD_DIRECTIONS = ['down', 'up'] as const;
+/** `inward` — the fronts close together (a valley, the flap comes toward the viewer); `outward` — the backs do (a mountain, the flap goes behind). */
+export const FOLD_SIDES = ['inward', 'outward'] as const;
+export const PHASES = ['intro', 'topFold', 'bottomFold', 'foldedHold', 'bottomUnfold', 'topUnfold', 'finalHold'] as const;
+export type PhaseId = (typeof PHASES)[number];
+export const PHASE_LABEL: Record<PhaseId, string> = {
+  intro: 'INTRO', topFold: 'TOP_FOLD', bottomFold: 'BOTTOM_FOLD', foldedHold: 'FOLDED_HOLD', bottomUnfold: 'BOTTOM_UNFOLD', topUnfold: 'TOP_UNFOLD', finalHold: 'FINAL_HOLD',
+};
+/** The text slots printed on the paper, and the two canvas-level text elements. */
+export const PAPER_TEXT = ['topLogo', 'topHeadline', 'topSubtitle', 'middleHeadline', 'middleBody', 'bottomHeadline', 'bottomBody', 'bottomCta', 'back'] as const;
+export type PaperTextId = (typeof PAPER_TEXT)[number];
+
+/** The groups people see (the Studio sections and the site editor tabs), in order. */
+export const GROUPS = [
+  'Canvas', 'Content', 'Typography', 'Logo', 'Paper', 'Paper Material', 'Panels', 'Folds', 'Creases', 'Fold Lighting',
+  'Hands', 'Hand Styling', 'Hand Motion', 'Background', 'Background Typography', 'Noise', 'CTA', 'Camera', 'Timeline',
+  'Motion', 'Easing', 'Responsive Layout', 'Export',
+] as const;
+export type Group = (typeof GROUPS)[number];
+export type Control = BaseControl<Group>;
+export type ListSpec = BaseListSpec<Group>;
+
+/** Which group a path belongs to: the longest matching prefix wins. */
+const GROUP_PREFIX: [string, Group][] = ([
+  ['canvas', 'Canvas'], ['layout', 'Responsive Layout'], ['content', 'Content'], ['typography', 'Typography'], ['logo', 'Logo'],
+  ['paper', 'Paper'], ['paperMaterial', 'Paper Material'], ['panels', 'Panels'], ['folds', 'Folds'], ['creases', 'Creases'],
+  ['foldLighting', 'Fold Lighting'], ['hands', 'Hands'], ['handInteraction', 'Hand Motion'],
+  ['background', 'Background'], ['background.backgroundTypography', 'Background Typography'], ['hands.style', 'Hand Styling'], ['hands.nails', 'Hand Styling'], ['background.noise', 'Noise'],
+  ['cta', 'CTA'], ['camera', 'Camera'], ['timeline', 'Timeline'], ['motion', 'Motion'], ['easing', 'Easing'], ['export', 'Export'],
+] as [string, Group][]).sort((a, b) => b[0].length - a[0].length);
+const groupOf = (path: string): Group => GROUP_PREFIX.find(([p]) => path === p || path.startsWith(`${p}.`))?.[1] ?? 'Canvas';
+
+const K = controlKit<Group>(groupOf, EASING_NAMES);
+const { num, int, frames, bool, color, choice, text, easing, asset, opacity, du, pu, norm, deg, factor } = K;
+const weight = (path: string, def: number, description: string) => choice(path, def, FONT_WEIGHTS, description, { unit: 'weight' });
+
+/* ─── per-aspect layout blocks ────────────────────────────────────────────────────────────────── */
+type LayoutDefaults = {
+  paperX: number; paperY: number; paperHeight: number; logoX: number; logoY: number; logoScale: number;
+  ctaX: number; ctaY: number; ctaScale: number; typeScale: number; typeX: number; typeY: number; handScale: number;
+};
+const LAYOUTS: Record<'portrait' | 'landscape' | 'square', LayoutDefaults> = {
+  portrait: { paperX: 0.47, paperY: 0.55, paperHeight: 0.43, logoX: 0.5, logoY: 0.095, logoScale: 1.25, ctaX: 0.79, ctaY: 0.93, ctaScale: 1.3, typeScale: 1, typeX: 0, typeY: 0, handScale: 1 },
+  landscape: { paperX: 0.37, paperY: 0.57, paperHeight: 0.66, logoX: 0.74, logoY: 0.3, logoScale: 1.35, ctaX: 0.74, ctaY: 0.7, ctaScale: 1.35, typeScale: 0.92, typeX: 0, typeY: -30, handScale: 1 },
+  square: { paperX: 0.46, paperY: 0.55, paperHeight: 0.6, logoX: 0.5, logoY: 0.075, logoScale: 1, ctaX: 0.8, ctaY: 0.925, ctaScale: 1, typeScale: 0.78, typeX: 0, typeY: -10, handScale: 1 },
+};
+const layoutControls = (name: keyof typeof LAYOUTS, d: LayoutDefaults): Control[] => {
+  const p = `layout.${name}`;
+  const shape = name === 'portrait' ? '9:16' : name === 'landscape' ? '16:9' : '1:1';
+  return [
+    norm(`${p}.paper.x`, d.paperX, 0, 1, `(${shape}) Where the sheet's pivot (paper.originX/Y) sits across the canvas.`),
+    norm(`${p}.paper.y`, d.paperY, 0, 1, `(${shape}) Where the sheet's pivot sits down the canvas.`),
+    norm(`${p}.paper.height`, d.paperHeight, 0.15, 1.2, `(${shape}) Height of the open (flat) sheet as a fraction of the canvas height; its width follows paper.aspect.`),
+    norm(`${p}.logo.x`, d.logoX, 0, 1, `(${shape}) Centre of the logo across the canvas.`),
+    norm(`${p}.logo.y`, d.logoY, 0, 1, `(${shape}) Centre of the logo down the canvas.`),
+    factor(`${p}.logo.scale`, d.logoScale, 0.2, 4, `(${shape}) Multiplies the logo's size on this canvas shape.`),
+    norm(`${p}.cta.x`, d.ctaX, 0, 1, `(${shape}) Centre of the call-to-action button across the canvas.`),
+    norm(`${p}.cta.y`, d.ctaY, 0, 1, `(${shape}) Centre of the call-to-action button down the canvas.`),
+    factor(`${p}.cta.scale`, d.ctaScale, 0.2, 4, `(${shape}) Multiplies the CTA's size on this canvas shape.`),
+    factor(`${p}.backgroundType.scale`, d.typeScale, 0.2, 4, `(${shape}) Multiplies the background typography's size on this canvas shape.`),
+    du(`${p}.backgroundType.x`, d.typeX, -2000, 2000, `(${shape}) Extra horizontal offset of the background typography.`),
+    du(`${p}.backgroundType.y`, d.typeY, -2000, 2000, `(${shape}) Extra vertical offset of the background typography.`),
+    factor(`${p}.handScale`, d.handScale, 0.2, 4, `(${shape}) Multiplies both hands' size on this canvas shape (they already scale with the sheet).`),
+  ];
+};
+
+/* ─── typography blocks ───────────────────────────────────────────────────────────────────────── */
+type TypeDefaults = { family?: string; weight: number; style?: 'normal' | 'italic'; size: number; lineHeight?: number; tracking?: number; color?: string; x?: number; y?: number; maxWidth?: number; align?: string; rotation?: number; skew?: number };
+/** A text element printed on the paper: position and size are relative to its panel (pu, normalized). */
+const paperType = (id: PaperTextId, what: string, d: TypeDefaults): Control[] => {
+  const p = `typography.${id}`;
+  return [
+    choice(`${p}.fontFamily`, d.family ?? 'Inter', FONT_FAMILIES, `Typeface of the ${what}.`),
+    weight(`${p}.fontWeight`, d.weight, `Weight of the ${what}.`),
+    choice(`${p}.fontStyle`, d.style ?? 'normal', ['normal', 'italic'], `Upright or italic ${what}.`),
+    num(`${p}.fontSize`, d.size, 8, 400, `Type size of the ${what}, in paper units (1/1000 of the sheet's width).`, { step: 1, unit: 'pu' }),
+    factor(`${p}.lineHeight`, d.lineHeight ?? 1.05, 0.6, 2.5, `Line height of the ${what}, as a multiple of its size.`),
+    num(`${p}.letterSpacing`, d.tracking ?? 0, -0.2, 0.5, `Letter spacing of the ${what}, in em.`, { step: 0.005, unit: 'em' }),
+    color(`${p}.color`, d.color ?? '#ffffff', `Colour of the ${what}.`),
+    opacity(`${p}.opacity`, 1, `Opacity of the ${what}.`),
+    norm(`${p}.x`, d.x ?? 0.12, -0.5, 1.5, `Left edge of the ${what}'s box across its panel (0 = the panel's left edge, 1 = its right edge).`),
+    norm(`${p}.y`, d.y ?? 0.2, -0.5, 1.5, `Top of the ${what}'s box down its panel.`),
+    norm(`${p}.maxWidth`, d.maxWidth ?? 0.76, 0.05, 1.5, `Width the ${what} wraps within, as a fraction of the panel's width.`),
+    choice(`${p}.alignment`, d.align ?? 'left', ['left', 'center', 'right'], `Alignment of the ${what} inside its box.`),
+    deg(`${p}.rotation`, d.rotation ?? 0, -45, 45, `Rotation of the ${what} on the paper.`),
+    factor(`${p}.scale`, 1, 0.1, 4, `Scale of the ${what}.`),
+    deg(`${p}.skew`, d.skew ?? 0, -30, 30, `Horizontal slant of the ${what} (negative leans it forward).`),
+    color(`${p}.shadow`, '#1b0a33', `Colour of the ${what}'s shadow.`),
+    num(`${p}.shadowBlur`, 0, 0, 80, `Blur of the ${what}'s shadow.`, { step: 1, unit: 'pu' }),
+    opacity(`${p}.shadowOpacity`, 0, `Strength of the ${what}'s shadow (0 = none).`),
+  ];
+};
+/** A canvas-level text element (logo wordmark, CTA label): placed by its own group and the layout. */
+const uiType = (id: 'logo' | 'cta', what: string, d: TypeDefaults): Control[] => {
+  const p = `typography.${id}`;
+  return [
+    choice(`${p}.fontFamily`, d.family ?? 'Inter', FONT_FAMILIES, `Typeface of the ${what}.`),
+    weight(`${p}.fontWeight`, d.weight, `Weight of the ${what}.`),
+    choice(`${p}.fontStyle`, d.style ?? 'normal', ['normal', 'italic'], `Upright or italic ${what}.`),
+    du(`${p}.fontSize`, d.size, 6, 300, `Type size of the ${what}.`),
+    num(`${p}.letterSpacing`, d.tracking ?? 0, -0.2, 0.5, `Letter spacing of the ${what}, in em.`, { step: 0.005, unit: 'em' }),
+    color(`${p}.color`, d.color ?? '#ffffff', `Colour of the ${what}.`),
+    opacity(`${p}.opacity`, 1, `Opacity of the ${what}.`),
+    color(`${p}.shadow`, '#1b0a33', `Colour of the ${what}'s shadow.`),
+    du(`${p}.shadowBlur`, 0, 0, 80, `Blur of the ${what}'s shadow.`),
+    opacity(`${p}.shadowOpacity`, 0, `Strength of the ${what}'s shadow (0 = none).`),
+  ];
+};
+
+/* ─── panels, hands, timeline ─────────────────────────────────────────────────────────────────── */
+const panelControls = (id: PanelId, shade: number, area: { x: number; y: number; width: number; height: number }): Control[] => {
+  const p = `panels.${id}`;
+  return [
+    choice(`${p}.colorMode`, 'material', ['material', 'own'], `material: the ${id} panel shows the paper (paperMaterial). own: it is printed in panels.${id}.backgroundColor. The panel's shape never changes — it is part of the one sheet.`),
+    color(`${p}.backgroundColor`, '#763bb3', `The ${id} panel's own colour (colorMode own).`),
+    bool(`${p}.gradient`, true, `Show the paper gradient on the ${id} panel (off: its flat colour).`),
+    factor(`${p}.textureOpacity`, 1, 0, 3, `Multiplies the paper texture and grain on the ${id} panel.`),
+    num(`${p}.shade`, shade, -1, 1, `Brightness offset of the ${id} panel over the lighting (negative darkens it). The lighting alone already shades a panel by its angle.`, { step: 0.01 }),
+    opacity(`${p}.highlightOpacity`, 1, `How much of the fold lighting's sheen the ${id} panel shows.`),
+    opacity(`${p}.shadowOpacity`, 1, `How much shadow the ${id} panel receives from a panel folded over it.`),
+    norm(`${p}.contentArea.x`, area.x, 0, 1, `Left edge of the ${id} panel's content safe area (0‥1 across the panel). Text is kept inside it.`),
+    norm(`${p}.contentArea.y`, area.y, 0, 1, `Top of the ${id} panel's content safe area (0‥1 down the panel).`),
+    norm(`${p}.contentArea.width`, area.width, 0.1, 1, `Width of the ${id} panel's content safe area.`),
+    norm(`${p}.contentArea.height`, area.height, 0.1, 1, `Height of the ${id} panel's content safe area.`),
+    pu(`${p}.contentArea.padding`, 0, 0, 200, `Inset inside the ${id} panel's content safe area.`),
+    bool(`${p}.overflow`, false, `Let text on the ${id} panel run outside its content safe area (off: text is shrunk to fit and clipped to it).`),
+    pu(`${p}.contentOffsetX`, 0, -500, 500, `Moves everything printed on the ${id} panel across it (the panel itself never moves off the sheet).`),
+    pu(`${p}.contentOffsetY`, 0, -500, 500, `Moves everything printed on the ${id} panel down it.`),
+    deg(`${p}.contentRotation`, 0, -45, 45, `Rotates everything printed on the ${id} panel.`),
+    factor(`${p}.contentScale`, 1, 0.1, 3, `Scales everything printed on the ${id} panel.`),
+  ];
+};
+type HandDefaults = { x: number; y: number; rotation: number; scale: number; offsetX: number; offsetY: number; armLength: number };
+const handControls = (id: HandId, d: HandDefaults): Control[] => {
+  const p = `hands.${id}`;
+  return [
+    bool(`${p}.enabled`, true, `Show the ${id} hand.`),
+    norm(`${p}.x`, d.x, 0, 1, `Where the ${id} hand grips the sheet, across it (0 = the left edge, 1 = the right edge). The hand is attached to that point of the paper and follows it through every fold.`),
+    norm(`${p}.y`, d.y, 0, 1, `Where the ${id} hand grips the sheet, down it (0 = the top edge, 1 = the bottom edge). The panel under this point is the one it holds.`),
+    pu(`${p}.offsetX`, d.offsetX, -600, 600, `Nudges the ${id} hand's drawing across, relative to its grip point.`),
+    pu(`${p}.offsetY`, d.offsetY, -600, 600, `Nudges the ${id} hand's drawing down, relative to its grip point.`),
+    deg(`${p}.rotation`, d.rotation, -180, 180, `Rotation of the ${id} hand at rest.`),
+    factor(`${p}.scale`, d.scale, 0.2, 4, `Size of the ${id} hand (it also scales with the sheet and with depth).`),
+    deg(`${p}.skewX`, 0, -30, 30, `Horizontal skew of the ${id} hand.`),
+    deg(`${p}.skewY`, 0, -30, 30, `Vertical skew of the ${id} hand.`),
+    opacity(`${p}.opacity`, 1, `Opacity of the ${id} hand.`),
+    num(`${p}.armLength`, d.armLength, 100, 4000, `How far the ${id} arm reaches back from the wrist (paper units). Long enough to leave the canvas on every shape.`, { step: 10, unit: 'pu' }),
+    factor(`${p}.pose.grip`, 1, 0, 1, `How firmly the ${id} hand's gripping fingers close on the paper once it holds it (1 = pressed to the sheet, 0 = open).`),
+    factor(`${p}.pose.fingerCurl`, 1, 0.3, 1.4, `How far the ${id} hand's fingers curl at their joints (1 = the reference pose).`),
+    num(`${p}.pose.thumbBend`, 0, -1, 1, `Bends the ${id} thumb at its two joints (-1 straighter, 1 more bent).`, { step: 0.01 }),
+    deg(`${p}.pose.wrist`, 0, -35, 35, `Bends the ${id} wrist: turns the hand against the forearm about the wrist (the grip stays on the paper; the forearm swings).`),
+    deg(`${p}.thumb.rotation`, 0, -25, 25, `Turns the ${id} thumb about its root at the side of the palm.`),
+    factor(`${p}.thumb.scale`, 1, 0.8, 1.25, `Size of the ${id} thumb relative to the hand.`),
+    num(`${p}.thumb.x`, 0, -30, 30, `Moves the ${id} thumb's root along the side of the palm (hand units).`, { step: 1 }),
+    num(`${p}.thumb.y`, 0, -30, 30, `Moves the ${id} thumb's root across the side of the palm (hand units).`, { step: 1 }),
+  ];
+};
+type InteractionDefaults = { follow: number; grip: number; move: number; rotate: number; settle: number; lead: number; fromX: number; fromY: number; delay: number; bounce: number; release: number };
+const interactionControls = (id: HandId, d: InteractionDefaults): Control[] => {
+  const p = `handInteraction.${id}`;
+  return [
+    factor(`${p}.followStrength`, d.follow, 0, 1.5, `How closely the ${id} hand follows its grip point as the paper folds (1 = stays on it, 0 = stays put).`),
+    pu(`${p}.gripOffset`, d.grip, 0, 200, `The tug: how far the ${id} hand pulls ahead of its grip point while the paper under it is moving.`),
+    pu(`${p}.movementAmplitude`, d.move, 0, 200, `How far the ${id} hand shifts toward the sheet's centre while any fold is moving (it braces the sheet).`),
+    deg(`${p}.rotationAmplitude`, d.rotate, -60, 60, `How much the ${id} hand's wrist turns at the peak of the fold that moves it.`),
+    frames(`${p}.settleDuration`, d.settle, 240, `How long the ${id} hand takes to settle after a move (a damped spring; shorter is tighter).`, 8),
+    num(`${p}.bounce`, d.bounce, 0.2, 1.2, `Damping of the ${id} hand's settle: below 1 it overshoots and settles, 1 and above it glides in.`, { step: 0.01, unit: 'factor' }),
+    frames(`${p}.leadFrames`, d.lead, 30, `The ${id} hand moves this many frames ahead of the paper — it pulls, the paper follows.`),
+    num(`${p}.enterFromX`, d.fromX, -1.5, 1.5, `Where the ${id} hand starts its approach, as an offset across the canvas from its grip (the intro).`, { step: 0.01, unit: 'normalized' }),
+    num(`${p}.enterFromY`, d.fromY, -1.5, 1.5, `Where the ${id} hand starts its approach, as an offset down the canvas from its grip.`, { step: 0.01, unit: 'normalized' }),
+    frames(`${p}.enterDelayFrames`, d.delay, 600, `Delay of the ${id} hand's approach after the intro starts.`),
+    deg(`${p}.gripAngle`, 22, -90, 90, `How far the ${id} hand's gripping finger is open before it closes on the paper.`),
+    factor(`${p}.releaseAmount`, d.release, 0, 1, `During FOLDED_HOLD the ${id} hand eases its grip by this much (0 = holds on, 1 = lets go), and grips again before the paper unfolds.`),
+    frames(`${p}.releaseFrames`, 14, 120, `How long the ${id} hand takes to ease and re-take its grip.`, 1),
+  ];
+};
+
+export const CONTROLS: readonly Control[] = [
+  /* ─── canvas ─────────────────────────────────────────────────────────────────────────────── */
+  choice('canvas.aspectRatio', '9:16', ASPECT_RATIOS, 'Canvas shape. Each shape reads its own layout block (layout.portrait / landscape / square): the composition is laid out again, never stretched. 9:16 is the reference.'),
+  int('canvas.width', 2160, 256, 7680, 'Output width in pixels. Must match the aspect ratio (±1%).', { unit: 'px' }),
+  int('canvas.height', 3840, 256, 7680, 'Output height in pixels. Must match the aspect ratio (±1%).', { unit: 'px' }),
+  choice('canvas.fps', 60, FPS_OPTIONS, 'Output frame rate. Timing is authored in 60 fps motion frames; a lower rate samples the same motion, it does not slow it down.'),
+  choice('canvas.durationMode', 'auto', ['auto', 'fixed'], 'auto: the video lasts as long as the timeline. fixed: it lasts canvas.durationFrames — the end is held, or the timeline is cut.'),
+  int('canvas.durationFrames', 480, 30, 36000, 'Output length in output frames (durationMode fixed).', { unit: 'frames' }),
+  int('canvas.seed', 20260930, 0, 2147483647, 'The seed of every random choice not seeded on its own (the idle sway\'s phase). Same config + same seed = identical frames.'),
+  num('canvas.safeArea', 0.03, 0, 0.2, 'Inset on every side, as a fraction of the short side, that the logo and CTA keep clear of.', { unit: 'fraction' }),
+
+  /* ─── layout (per aspect ratio) ─────────────────────────────────────────────────────────── */
+  ...layoutControls('portrait', LAYOUTS.portrait),
+  ...layoutControls('landscape', LAYOUTS.landscape),
+  ...layoutControls('square', LAYOUTS.square),
+
+  /* ─── content: every word, plain text ─────────────────────────────────────────────────────── */
+  text('content.logo', 'brand', 32, 'The logo wordmark. Empty shows the mark alone.'),
+  text('content.top.headline', 'Your headline here', 140, 'The headline printed on the top panel. Wraps within its box; line breaks are kept. Empty hides it.', { multiline: true }),
+  text('content.top.logo', '', 32, 'A small wordmark printed at the top of the top panel. Empty hides it.'),
+  text('content.top.subtitle', '', 220, 'A subtitle on the top panel. Empty hides it.', { multiline: true }),
+  text('content.middle.headline', 'A second message on the middle panel', 140, 'The headline printed on the middle panel. Empty hides it.', { multiline: true }),
+  text('content.middle.body', '', 220, 'A subtitle on the middle panel. Empty hides it.', { multiline: true }),
+  text('content.bottom.headline', '', 140, 'A headline on the bottom panel. Empty hides it.', { multiline: true }),
+  text('content.bottom.body', 'Body copy printed on the bottom panel.', 260, 'The body copy on the bottom panel. Empty hides it.', { multiline: true }),
+  text('content.bottom.cta', '', 40, 'A call to action printed on the bottom panel (it folds with the paper). Empty hides it; content.cta.text is the button beside the paper.'),
+  text('content.back.text', '', 60, 'Printed on the back of one panel (content.back.panel) — the side the viewer sees once the paper is folded. Empty leaves the back plain.', { multiline: true }),
+  choice('content.back.panel', 'top', PANELS, 'Which panel\'s back carries content.back.text.'),
+  text('content.cta.text', 'Call to action', 40, 'The call-to-action label. Empty hides the button.'),
+
+  /* ─── typography ─────────────────────────────────────────────────────────────────────────── */
+  ...paperType('topHeadline', 'top headline', { weight: 900, style: 'italic', size: 104, lineHeight: 0.86, tracking: -0.01, x: 0.2, y: 0.17, maxWidth: 0.74, skew: -4 }),
+  ...paperType('topLogo', 'wordmark on the top panel', { weight: 700, size: 40, lineHeight: 1, tracking: -0.01, x: 0.2, y: 0.07, maxWidth: 0.6 }),
+  ...paperType('topSubtitle', 'top subtitle', { weight: 500, size: 44, lineHeight: 1.15, x: 0.2, y: 0.72, maxWidth: 0.7 }),
+  ...paperType('middleHeadline', 'middle headline', { weight: 500, size: 80, lineHeight: 0.98, tracking: -0.025, x: 0.17, y: 0.2, maxWidth: 0.72 }),
+  ...paperType('middleBody', 'middle subtitle', { weight: 400, size: 42, lineHeight: 1.2, x: 0.17, y: 0.7, maxWidth: 0.72 }),
+  ...paperType('bottomHeadline', 'bottom headline', { weight: 800, size: 70, lineHeight: 0.95, x: 0.2, y: 0.12, maxWidth: 0.72 }),
+  ...paperType('bottomBody', 'bottom body copy', { weight: 500, style: 'italic', size: 50, lineHeight: 1.08, tracking: 0.005, x: 0.21, y: 0.24, maxWidth: 0.74 }),
+  ...paperType('bottomCta', 'CTA printed on the bottom panel', { weight: 700, size: 40, lineHeight: 1, x: 0.21, y: 0.68, maxWidth: 0.6, color: '#1b0a33' }),
+  ...paperType('back', 'text on the back', { weight: 800, size: 90, lineHeight: 1, tracking: -0.02, x: 0.1, y: 0.36, maxWidth: 0.8, align: 'center' }),
+  ...uiType('logo', 'logo wordmark', { weight: 600, size: 56, tracking: -0.02 }),
+  ...uiType('cta', 'CTA label', { weight: 500, size: 27, tracking: 0, color: '#0a0a0a' }),
+
+  /* ─── logo ───────────────────────────────────────────────────────────────────────────────── */
+  bool('logo.enabled', true, 'Show the logo.'),
+  bool('logo.showMark', true, 'Draw the logo mark (a rounded tile with a letter) before the wordmark.'),
+  text('logo.markText', 'B', 2, 'The letter(s) on the logo mark.'),
+  color('logo.markColor', '#5e4de6', 'Logo mark colour (top-left of its gradient).'),
+  color('logo.markColorEnd', '#7a5cff', 'Logo mark colour (bottom-right of its gradient).'),
+  color('logo.markTextColor', '#ffffff', 'Colour of the letter on the logo mark.'),
+  factor('logo.markSize', 1.05, 0.3, 3, 'Size of the mark, as a multiple of the wordmark\'s type size.'),
+  factor('logo.markRadius', 0.26, 0, 0.5, 'Corner radius of the mark, as a fraction of its size.'),
+  factor('logo.gap', 0.18, 0, 2, 'Gap between the mark and the wordmark, as a multiple of the type size.'),
+  deg('logo.rotation', 0, -45, 45, 'Rotation of the logo.'),
+  asset('logo.image', 'A logo image (asset reference) shown instead of the mark and wordmark. Empty: the procedural mark and the wordmark.'),
+  du('logo.imageHeight', 90, 10, 600, 'Height of the logo image.'),
+  choice('logo.animation', 'drop', ['none', 'drop', 'fade'], 'How the logo arrives during the intro: drop (slides down into place), fade, or none (there from the start).'),
+
+  /* ─── paper: the sheet and its pose ───────────────────────────────────────────────────────── */
+  factor('paper.aspect', 0.7, 0.3, 1.6, 'Width of the open sheet divided by its height.'),
+  pu('paper.thickness', 3, 0, 20, 'Paper thickness: the width of the rolled edge a fold makes, and the lip a folded flap shows.'),
+  pu('paper.cornerRadius', 3, 0, 60, 'Corner rounding of the sheet.'),
+  norm('paper.originX', 0.5, 0, 1, 'The sheet\'s pivot across it: where layout.<shape>.paper.x places it, and what it rotates, skews and scales about.'),
+  norm('paper.originY', 0.5, 0, 1, 'The sheet\'s pivot down it.'),
+  deg('paper.rotationX', 8, -60, 60, 'Tilts the whole sheet toward (negative) or away from (positive) the viewer about a horizontal axis, in perspective.'),
+  deg('paper.rotationY', -9, -60, 60, 'Turns the whole sheet about a vertical axis, in perspective.'),
+  deg('paper.rotationZ', 3, -45, 45, 'Rotates the whole sheet in the picture plane.'),
+  deg('paper.skewX', -2, -30, 30, 'Skews the whole sheet horizontally.'),
+  deg('paper.skewY', 0, -30, 30, 'Skews the whole sheet vertically.'),
+  du('paper.translateX', 0, -1500, 1500, 'Moves the whole sheet across.'),
+  du('paper.translateY', 0, -1500, 1500, 'Moves the whole sheet down.'),
+  factor('paper.scaleX', 1, 0.2, 3, 'Scales the whole sheet across.'),
+  factor('paper.scaleY', 1, 0.2, 3, 'Scales the whole sheet down.'),
+  factor('paper.scale', 1, 0.2, 3, 'Scales the whole sheet (with scaleX and scaleY).'),
+  color('paper.edgeColor', '#4a1f7a', 'Colour of the paper\'s cut edge (its thickness), seen as a panel turns edge-on.'),
+  bool('paper.shadow.enabled', true, 'Cast the sheet\'s shadow onto the background.'),
+  color('paper.shadow.color', '#3c1473', 'Colour of the sheet\'s shadow on the background.'),
+  opacity('paper.shadow.opacity', 0.32, 'Strength of the sheet\'s shadow on the background.'),
+  du('paper.shadow.blur', 36, 0, 300, 'Blur of the sheet\'s shadow on the background.'),
+  du('paper.shadow.offsetX', 16, -400, 400, 'Horizontal offset of the sheet\'s shadow.'),
+  du('paper.shadow.offsetY', 28, -400, 400, 'Vertical offset of the sheet\'s shadow.'),
+
+  /* ─── paper material ─────────────────────────────────────────────────────────────────────── */
+  color('paperMaterial.baseColor', '#7b3fb9', 'The paper\'s colour (its front). With the gradient on, it runs from this colour to secondaryColor.'),
+  color('paperMaterial.secondaryColor', '#7036ac', 'The far end of the paper gradient.'),
+  color('paperMaterial.backColor', '#8750c2', 'The paper\'s colour on its back, seen when a panel turns over.'),
+  bool('paperMaterial.gradientEnabled', true, 'Print a gradient from baseColor to secondaryColor across the whole sheet (continuous over the creases).'),
+  deg('paperMaterial.gradientAngle', 170, 0, 360, 'Direction of the paper gradient (CSS angle: 180 = top to bottom).'),
+  opacity('paperMaterial.textureOpacity', 0.07, 'Strength of the paper fibre texture (procedural, seeded).'),
+  bool('paperMaterial.grainEnabled', true, 'Fine procedural grain on the paper.'),
+  opacity('paperMaterial.grainOpacity', 0.05, 'Strength of the fine paper grain.'),
+  factor('paperMaterial.grainScale', 1, 0.3, 4, 'Size of the grain (1 = fine).'),
+  int('paperMaterial.grainSeed', 7, 0, 99999, 'Seed of the paper texture and grain.'),
+  opacity('paperMaterial.edgeHighlight', 0.22, 'A light line along the sheet\'s outer edges.'),
+  opacity('paperMaterial.edgeShadow', 0.18, 'A dark line along the sheet\'s outer edges.'),
+  opacity('paperMaterial.creaseTexture', 0.12, 'How visible a crease is while the paper lies flat (it deepens as the paper folds).'),
+  factor('paperMaterial.creaseHighlight', 1, 0, 2, 'Multiplies every crease\'s ridge highlight.'),
+  factor('paperMaterial.creaseShadow', 1, 0, 2, 'Multiplies every crease\'s valley shading.'),
+
+  /* ─── panels ─────────────────────────────────────────────────────────────────────────────── */
+  ...panelControls('top', 0, { x: 0.06, y: 0.05, width: 0.88, height: 0.9 }),
+  ...panelControls('middle', 0, { x: 0.06, y: 0.05, width: 0.88, height: 0.9 }),
+  ...panelControls('bottom', 0, { x: 0.06, y: 0.05, width: 0.88, height: 0.9 }),
+
+  /* ─── fold lighting ──────────────────────────────────────────────────────────────────────── */
+  deg('foldLighting.lightAngle', -95, -180, 180, 'Where the light comes from in the picture plane (-90 = from above, 0 = from the right, 90 = from below).'),
+  deg('foldLighting.lightElevation', 25, 0, 90, 'How far the light is raised toward the viewer (90 = straight from the viewer: every panel facing you is equally lit).'),
+  num('foldLighting.ambient', 0.62, 0, 1.5, 'Light every panel gets whatever its angle.', { unit: 'factor' }),
+  num('foldLighting.diffuse', 0.6, 0, 1.5, 'Light a panel gets from facing the light.', { unit: 'factor' }),
+  opacity('foldLighting.shadowOpacity', 0.5, 'Strength of the shadow a folding panel casts on the panel it closes over (the contact region darkens).'),
+  pu('foldLighting.shadowBlur', 40, 0, 300, 'Softness of that shadow\'s far edge.'),
+  pu('foldLighting.shadowOffset', 18, 0, 300, 'How far the shadow reaches past the folding panel\'s edge.'),
+  opacity('foldLighting.creaseDarkness', 0.45, 'Darkening in the valley of a crease as it closes.'),
+  opacity('foldLighting.edgeHighlight', 0.55, 'Highlight on a folded edge where it turns toward the light.'),
+  opacity('foldLighting.highlightOpacity', 0.16, 'The sheen a panel shows when it faces the light.'),
+  num('foldLighting.backShade', -0.05, -1, 1, 'Brightness offset of the paper\'s back.', { step: 0.01 }),
+
+  /* ─── hands ──────────────────────────────────────────────────────────────────────────────── */
+  ...handControls('top', { x: 0.5, y: 0, rotation: -4, scale: 1.15, offsetX: 0, offsetY: 0, armLength: 2600 }),
+  ...handControls('bottom', { x: 0.55, y: 0.955, rotation: 0, scale: 1.1, offsetX: 0, offsetY: 0, armLength: 2000 }),
+
+  /* ─── hand styling ───────────────────────────────────────────────────────────────────────── */
+  color('hands.style.baseColor', '#873a1c', 'Skin colour (both hands).'),
+  color('hands.style.midtoneColor', '#7a3217', 'Skin turning away from the light (the sides of fingers, the far side of the palm).'),
+  color('hands.style.shadowColor', '#5e260b', 'Skin in shadow: under and between fingers, under the thumb, the wrist crease, fingers behind the paper.'),
+  color('hands.style.highlightColor', '#9d4b26', 'Lit skin (the knuckles, the top of the hand and thumb).'),
+  color('hands.style.nailColor', '#e57953', 'Fingernail colour.'),
+  opacity('hands.style.highlightOpacity', 0.9, 'Strength of the highlight shapes.'),
+  opacity('hands.style.shadowOpacity', 1, 'Strength of the shadow shapes.'),
+  opacity('hands.style.dropShadowOpacity', 0.28, 'Strength of the contact shadow the gripping fingers cast on the paper.'),
+  pu('hands.style.dropShadowBlur', 10, 0, 100, 'Blur of that contact shadow.'),
+  pu('hands.style.dropShadowOffset', 7, 0, 100, 'Offset of that contact shadow.'),
+  bool('hands.style.sleeve.enabled', false, 'Draw a sleeve on each forearm.'),
+  color('hands.style.sleeve.color', '#1f2a44', 'Sleeve colour.'),
+  factor('hands.style.sleeve.position', 0.35, 0, 1, 'Where the cuff sits along the arm, from the wrist (0) to the arm\'s far end (1).'),
+  pu('hands.style.outlineWidth', 0, 0, 20, 'An outline around the hand\'s silhouette (0 = none, as in the reference).'),
+  color('hands.style.outlineColor', '#3a1606', 'Outline colour.'),
+  bool('hands.nails.enabled', true, 'Draw fingernails where they face the viewer.'),
+  opacity('hands.nails.opacity', 0.95, 'Nail opacity (lower for a subtler accent).'),
+  factor('hands.nails.scale', 1, 0.6, 1.3, 'Nail size relative to its fingertip.'),
+
+  /* ─── hand motion ────────────────────────────────────────────────────────────────────────── */
+  ...interactionControls('top', { follow: 1, grip: 0, move: 6, rotate: 14, settle: 24, lead: 0, fromX: -0.35, fromY: -0.22, delay: 0, bounce: 0.62, release: 0.4 }),
+  ...interactionControls('bottom', { follow: 1, grip: 0, move: 12, rotate: -8, settle: 28, lead: 0, fromX: -0.28, fromY: 0.26, delay: 8, bounce: 0.7, release: 0.2 }),
+
+  /* ─── background ─────────────────────────────────────────────────────────────────────────── */
+  color('background.baseColor', '#b46cff', 'Background colour (under the gradient).'),
+  bool('background.gradient.enabled', true, 'Paint the background with the gradient stops.'),
+  choice('background.gradient.type', 'linear', ['linear', 'radial'], 'Linear or radial gradient.'),
+  deg('background.gradient.angle', 180, 0, 360, 'Direction of a linear gradient (CSS angle: 180 = top to bottom).'),
+  bool('background.glow.enabled', true, 'A soft glow behind the paper.'),
+  norm('background.glow.x', 0.46, -0.5, 1.5, 'Glow centre across the canvas.'),
+  norm('background.glow.y', 0.52, -0.5, 1.5, 'Glow centre down the canvas.'),
+  num('background.glow.radius', 0.6, 0.02, 3, 'Glow radius, as a fraction of the short side.', { unit: 'short' }),
+  color('background.glow.color', '#d6a6ff', 'Glow colour.'),
+  opacity('background.glow.opacity', 0.28, 'Glow strength.'),
+  du('background.glow.blur', 90, 0, 600, 'Glow blur.'),
+
+  /* ─── background typography ──────────────────────────────────────────────────────────────── */
+  bool('background.backgroundTypography.enabled', true, 'Show the large background word.'),
+  text('background.backgroundTypography.text', 'PROMO', 24, 'The background word, repeated in rows.'),
+  choice('background.backgroundTypography.fontFamily', 'Inter', FONT_FAMILIES, 'Typeface of the background word.'),
+  du('background.backgroundTypography.fontSize', 262, 20, 1600, 'Type size of the background word.'),
+  weight('background.backgroundTypography.weight', 700, 'Weight of the background word.'),
+  opacity('background.backgroundTypography.opacity', 1, 'Opacity of the background word.'),
+  color('background.backgroundTypography.color', '#a05ce7', 'Colour of the background word.'),
+  num('background.backgroundTypography.tracking', -0.03, -0.3, 1, 'Letter spacing of the background word, in em.', { step: 0.005, unit: 'em' }),
+  du('background.backgroundTypography.x', -16, -2000, 2000, 'Horizontal offset of the rows.'),
+  du('background.backgroundTypography.y', -42, -2000, 2000, 'Vertical offset of the first row.'),
+  deg('background.backgroundTypography.rotation', 0, -90, 90, 'Rotation of the whole block of rows.'),
+  int('background.backgroundTypography.rows', 9, 1, 24, 'How many rows of the word.'),
+  factor('background.backgroundTypography.rowGap', 0.8, 0.4, 3, 'Row pitch, as a multiple of the type size.'),
+  int('background.backgroundTypography.repeat', 1, 1, 8, 'How many times the word repeats along each row (at least).'),
+  bool('background.backgroundTypography.fill', true, 'Repeat the word further where one row would not span the canvas (a wide canvas), so every shape is covered edge to edge.'),
+  num('background.backgroundTypography.drift', 0, -400, 400, 'Rows slide sideways at this speed.', { step: 1, unit: 'du/s' }),
+  bool('background.backgroundTypography.alternate', true, 'Alternate rows slide the opposite way.'),
+
+  /* ─── noise ──────────────────────────────────────────────────────────────────────────────── */
+  bool('background.noise.enabled', true, 'Procedural grain over the background.'),
+  opacity('background.noise.opacity', 0.05, 'Grain strength.'),
+  factor('background.noise.scale', 1, 0.2, 5, 'Grain size (1 = fine film grain).'),
+  int('background.noise.seed', 11, 0, 99999, 'Grain seed. Same seed = same grain.'),
+
+  /* ─── CTA ────────────────────────────────────────────────────────────────────────────────── */
+  bool('cta.enabled', true, 'Show the call-to-action button.'),
+  color('cta.backgroundColor', '#ffffff', 'Button colour.'),
+  color('cta.borderColor', '#ffffff', 'Button border colour.'),
+  du('cta.borderWidth', 0, 0, 20, 'Button border width.'),
+  du('cta.radius', 9, 0, 200, 'Button corner radius.'),
+  du('cta.paddingX', 30, 0, 200, 'Space left and right of the label.'),
+  du('cta.paddingY', 13, 0, 120, 'Space above and below the label.'),
+  deg('cta.rotation', -4, -45, 45, 'Button rotation.'),
+  color('cta.shadowColor', '#3c1473', 'Button shadow colour.'),
+  opacity('cta.shadowOpacity', 0.2, 'Button shadow strength.'),
+  du('cta.shadowBlur', 18, 0, 120, 'Button shadow blur.'),
+  choice('cta.animation', 'pop-pulse', ['none', 'pop', 'pulse', 'pop-pulse'], 'pop: springs in during the intro. pulse: breathes during the final hold. pop-pulse: both. none: there from the start, still.'),
+  frames('cta.enterDelayFrames', 24, 3600, 'When the button pops in, after the video starts.'),
+  frames('cta.enterDurationFrames', 30, 600, 'How long the pop takes.', 1),
+  factor('cta.pulseAmount', 0.04, 0, 0.3, 'How much the button grows at the top of each pulse.'),
+  num('cta.pulseFrequency', 1.1, 0.1, 4, 'Pulses per second.', { unit: 'hz' }),
+
+  /* ─── camera ─────────────────────────────────────────────────────────────────────────────── */
+  factor('camera.startZoom', 1, 0.5, 3, 'Zoom while the paper is open, before it folds.'),
+  factor('camera.foldZoom', 1.12, 0.5, 3, 'Zoom the camera pushes to as the paper folds (reached when every fold is at its peak).'),
+  factor('camera.endZoom', 1, 0.5, 3, 'Zoom the camera settles at in the final hold.'),
+  du('camera.x', 0, -1500, 1500, 'Camera pan across (positive moves the view right: the picture moves left).'),
+  du('camera.y', 0, -1500, 1500, 'Camera pan down.'),
+  deg('camera.rotation', 0, -30, 30, 'Camera roll.'),
+  du('camera.perspective', 2400, 1400, 12000, 'Distance from the viewer to the paper: smaller is a stronger perspective (a fold looks deeper).'),
+  norm('camera.vanishX', 0.5, -0.5, 1.5, 'The vanishing point across the sheet (0.5 = its centre).'),
+  norm('camera.vanishY', 0.45, -0.5, 1.5, 'The vanishing point down the sheet.'),
+  factor('camera.parallax', 0.35, 0, 1, 'How much the background follows the camera (0 = it stays still, 1 = it moves with the paper).'),
+
+  /* ─── timeline ───────────────────────────────────────────────────────────────────────────── */
+  int('timeline.intro.startFrame', 0, 0, 3600, 'Frame the intro starts on (the hands approach and grip).', { unit: 'frames' }),
+  int('timeline.intro.delayFrames', 0, 0, 600, 'Extra frames before the intro starts.', { unit: 'frames' }),
+  frames('timeline.intro.durationFrames', 60, 600, 'Length of the intro: the hands\' approach and grip.', 1),
+  easing('timeline.intro.easing', 'easeOutCubic', 'How the hands (and, with motion.intro.mode rise, the paper) arrive.'),
+  int('timeline.topFold.startFrame', -1, -1, 3600, 'Frame TOP_FOLD starts on; -1 = right after the intro. Its delay, length and easing are the top fold\'s (folds.top.delayFrames / durationFrames / easing).', { unit: 'frames' }),
+  int('timeline.bottomFold.startFrame', -1, -1, 3600, 'Frame BOTTOM_FOLD starts on; -1 = right after TOP_FOLD. Delay, length and easing: folds.bottom.', { unit: 'frames' }),
+  int('timeline.foldedHold.startFrame', -1, -1, 3600, 'Frame FOLDED_HOLD starts on; -1 = right after BOTTOM_FOLD.', { unit: 'frames' }),
+  int('timeline.foldedHold.delayFrames', 0, -240, 600, 'Gap before the hold (negative overlaps the fold).', { unit: 'frames' }),
+  frames('timeline.foldedHold.durationFrames', 44, 3600, 'How long the paper stays folded.'),
+  easing('timeline.foldedHold.easing', 'easeInOut', 'Shapes the squeeze the paper gives while it is held folded (motion.holdSqueeze).'),
+  int('timeline.bottomUnfold.startFrame', -1, -1, 3600, 'Frame BOTTOM_UNFOLD starts on; -1 = right after the hold. Delay, length and easing: folds.bottom.unfold*.', { unit: 'frames' }),
+  int('timeline.topUnfold.startFrame', -1, -1, 3600, 'Frame TOP_UNFOLD starts on; -1 = right after BOTTOM_UNFOLD. Delay, length and easing: folds.top.unfold*.', { unit: 'frames' }),
+  int('timeline.finalHold.startFrame', -1, -1, 3600, 'Frame FINAL_HOLD starts on; -1 = right after TOP_UNFOLD.', { unit: 'frames' }),
+  int('timeline.finalHold.delayFrames', 0, -240, 600, 'Gap before the final hold (negative overlaps the unfold).', { unit: 'frames' }),
+  frames('timeline.finalHold.durationFrames', 60, 3600, 'How long the open paper holds at the end.'),
+  easing('timeline.finalHold.easing', 'easeInOutCubic', 'How the camera settles to camera.endZoom in the final hold.'),
+
+  /* ─── motion ─────────────────────────────────────────────────────────────────────────────── */
+  factor('motion.speed', 1, 0.25, 4, 'Plays the whole timeline faster (above 1) or slower (below 1). The video\'s length follows.'),
+  choice('motion.progressMode', 'timeline', ['timeline', 'manual'], 'timeline: the folds play as the timeline says. manual: motion.foldProgress poses the paper directly (the hands hold on; the rest of the motion still plays).'),
+  factor('motion.foldProgress', 0, 0, 1, 'FOLD PROGRESS (manual mode): 0 = the paper completely flat, 0.5 = the first fold done, 1 = completely folded. It sets the crease angles themselves — the geometry, not a picture of it.'),
+  choice('motion.intro.mode', 'hands', ['hands', 'rise', 'none'], 'hands: the paper is there, the hands reach in and grip it. rise: paper and hands rise into frame together. none: everything in place from the first frame.'),
+  du('motion.intro.paperOffsetY', 900, 0, 4000, 'rise: how far below its place the paper starts.'),
+  deg('motion.intro.paperRotation', -8, -90, 90, 'rise: the paper\'s rotation as it starts.'),
+  bool('motion.idle.enabled', true, 'A slow sway and bob that keeps the held paper alive.'),
+  deg('motion.idle.swayAngle', 0.7, 0, 10, 'How far the paper sways.'),
+  du('motion.idle.bobAmplitude', 5, 0, 80, 'How far the paper bobs up and down.'),
+  num('motion.idle.frequency', 0.3, 0.02, 3, 'Sway and bob cycles per second.', { unit: 'hz' }),
+  factor('motion.holdSqueeze', 0.985, 0.8, 1.2, 'The folded paper\'s scale at the middle of FOLDED_HOLD (below 1 squeezes it; the hands press it).'),
+
+  /* ─── easing ─────────────────────────────────────────────────────────────────────────────── */
+  easing('easing.camera', 'easeInOutCubic', 'How the camera moves toward camera.foldZoom as the paper folds.'),
+  easing('easing.ctaEnter', 'easeOutBack', 'How the CTA pops in.'),
+  easing('easing.fingerGrip', 'easeInOutCubic', 'How the gripping fingers close on the paper at the end of each hand\'s approach.'),
+  easing('easing.logoEnter', 'easeOutCubic', 'How the logo arrives.'),
+
+  /* ─── export ─────────────────────────────────────────────────────────────────────────────── */
+  choice('export.codec', 'h264', ['h264', 'h265', 'prores', 'vp9'], 'Video codec of the rendered file.'),
+  choice('export.pixelFormat', 'yuv420p', ['yuv420p', 'yuv444p', 'yuv422p10le'], 'Pixel format. yuv420p plays everywhere.'),
+  choice('export.colorSpace', 'bt709', ['bt709', 'default'], 'Colour space tag. bt709 is correct for HD/4K SDR.'),
+  int('export.crf', 12, 0, 51, 'H.264/H.265 quality (lower is better; 12 is visually lossless).'),
+  choice('export.x264Preset', 'slow', ['ultrafast', 'veryfast', 'fast', 'medium', 'slow', 'slower', 'veryslow'], 'Encoder effort.'),
+  choice('export.imageFormat', 'png', ['png', 'jpeg'], 'Frame capture format (png keeps gradients clean).'),
+];
+
+/* ─── lists ───────────────────────────────────────────────────────────────────────────────────── */
+const F = (c: BaseControl<string>) => inGroup<Group>('Folds', c);
+const FOLD_ITEM: Control[] = [
+  F({ ...choice('id', 'top', FOLD_KEYS, 'Which crease this fold turns about: top = creases.top, bottom = creases.bottom. Fixed.'), userEditable: false, agentEditable: false }),
+  F(bool('enabled', true, 'Fold at this crease. Off: the crease stays at its start angle and its phases take no time.')),
+  F(choice('direction', 'down', FOLD_DIRECTIONS, 'Which side of the crease swings: down — the part above it (the top panel, for the top fold); up — the part below it. The two folds must agree on one panel that stays put: top up + bottom down is refused.')),
+  F(choice('side', 'inward', FOLD_SIDES, 'inward: the panel folds toward the viewer, over the front (a valley). outward: it folds away, behind (a mountain). Decides whether the folded panel lies in front of or behind its neighbour.')),
+  F(deg('startAngle', 0, -90, 180, 'The crease\'s angle while the paper is open, before this fold (0 = flat; negative bends it the other way).')),
+  F(deg('peakAngle', 150, -90, 180, 'The crease\'s angle at the peak of the fold (180 = folded flat).')),
+  F(deg('endAngle', 0, -90, 180, 'The crease\'s angle after it unfolds (the same as startAngle returns the paper to its open geometry).')),
+  F(factor('startScale', 1, 0.5, 1.5, 'The sheet\'s scale before this fold.')),
+  F(factor('peakScale', 1, 0.5, 1.5, 'The sheet\'s scale at the fold\'s peak (the folds multiply).')),
+  F(factor('endScale', 1, 0.5, 1.5, 'The sheet\'s scale after this fold unfolds.')),
+  F(deg('edgeLift', 40, 0, 70, 'How far the gripped free edge lifts and curls ahead of the fold (the hand lifts the paper before it folds over). Peaks early in the fold, flat again when folded.')),
+  F(factor('edgeLiftSize', 0.32, 0.05, 0.6, 'How much of the panel, from its free edge, curls with that lift.')),
+  F(factor('curvature', 0.35, 0, 1, 'How round the fold is: 0 = a sharp hinge, 1 = a wide bend. The turn is spread over a band of the sheet around the crease, so the paper bends rather than rotating like a card.')),
+  F(factor('perspective', 1.15, 0.5, 2.5, 'Perspective strength at the peak of this fold (above 1 deepens it; it relaxes as the paper unfolds).')),
+  F(du('translationX', 0, -800, 800, 'How far the sheet shifts across at the peak of this fold (the hands move it).')),
+  F(du('translationY', 0, -800, 800, 'How far the sheet shifts down at the peak of this fold.')),
+  F(deg('rotationZ', 0, -30, 30, 'How far the sheet turns in the picture plane at the peak of this fold.')),
+  F({ ...int('delayFrames', 6, -240, 600, 'Gap before the fold starts (negative overlaps the phase before).', { unit: 'frames' }) }),
+  F(frames('durationFrames', 54, 3600, 'How long the fold takes.', 1)),
+  F(easing('easing', 'easeInOutCubic', 'How the fold moves.')),
+  F({ ...int('unfoldDelayFrames', 0, -240, 600, 'Gap before the unfold starts (negative overlaps the phase before).', { unit: 'frames' }) }),
+  F(frames('unfoldDurationFrames', 50, 3600, 'How long the unfold takes.', 1)),
+  F(easing('unfoldEasing', 'easeInOutCubic', 'How the unfold moves.')),
+  F(factor('shadowIntensity', 1, 0, 2, 'Multiplies the fold lighting\'s shadow for this fold.')),
+  F(factor('creaseIntensity', 1, 0, 2, 'How much this crease darkens as it folds (it softens again as it opens).')),
+];
+const C = (c: BaseControl<string>) => inGroup<Group>('Creases', c);
+const CREASE_ITEM: Control[] = [
+  C({ ...choice('id', 'top', FOLD_KEYS, 'Which crease: top (between the top and middle panels) or bottom (between the middle and bottom panels). Fixed.'), userEditable: false, agentEditable: false }),
+  C(bool('enabled', true, 'Draw the crease line (the paper still folds here when this is off).')),
+  C(norm('position', 0.333, 0.1, 0.9, 'Where the crease runs, down the sheet (0 = the top edge, 1 = the bottom edge). The panels are the strips between the creases.')),
+  C(pu('width', 3, 0.5, 30, 'Width of the crease line.')),
+  C(color('color', '#2c0f52', 'Crease colour.')),
+  C(opacity('opacity', 0.55, 'Crease line strength at full fold.')),
+  C(opacity('darkness', 0.45, 'How dark the crease\'s valley gets as it closes (× foldLighting.creaseDarkness).')),
+  C(pu('softness', 1.5, 0, 30, 'Softness (blur) of the crease line.')),
+  C(opacity('highlight', 0.35, 'The light ridge beside the crease on its convex side.')),
+  C(color('highlightColor', '#c9a0ff', 'Colour of that ridge.')),
+];
+const G = (c: BaseControl<string>) => inGroup<Group>('Background', c);
+const STOP_ITEM: Control[] = [
+  G(num('offset', 0, 0, 1, 'Where the stop sits along the gradient (0‥1). Stops must be in order.', { step: 0.01, unit: 'fraction' })),
+  G(color('color', '#b46cff', 'Stop colour.')),
+];
+
+const fold = (id: FoldKey, over: Record<string, unknown>) => ({
+  id, enabled: true, direction: id === 'top' ? 'down' : 'up', side: 'inward', startAngle: 0, peakAngle: 150, endAngle: 0,
+  startScale: 1, peakScale: 1, endScale: 1, edgeLift: 40, edgeLiftSize: 0.32, curvature: 0.35, perspective: 1.15, translationX: 0, translationY: 0, rotationZ: 0,
+  delayFrames: 6, durationFrames: 54, easing: 'easeInOutCubic', unfoldDelayFrames: 0, unfoldDurationFrames: 50, unfoldEasing: 'easeInOutCubic',
+  shadowIntensity: 1, creaseIntensity: 1, ...over,
+});
+const crease = (id: FoldKey, position: number) => ({ id, enabled: true, position, width: 3, color: '#2c0f52', opacity: 0.55, darkness: 0.45, softness: 1.5, highlight: 0.35, highlightColor: '#c9a0ff' });
+
+export const LISTS: readonly ListSpec[] = [
+  {
+    path: 'folds', group: 'Folds', minItems: 2, maxItems: 2, item: FOLD_ITEM, keyField: 'id', keys: FOLD_KEYS,
+    description: 'The two folds, one per crease, in order: top (folds.0, also folds.top), then bottom (folds.1, also folds.bottom).',
+    default: [
+      // The reference: the bottom hand holds the bottom panel still (both folds swing the part above
+      // their crease). The top hand pulls the top panel forward over the front; then the folded pair
+      // tucks behind the bottom panel, leaving a small card with the body copy facing the viewer.
+      fold('top', { side: 'inward', startAngle: 0, peakAngle: 172, endAngle: 0, peakScale: 1.02, translationY: 40, rotationZ: -1.5, delayFrames: 26, durationFrames: 84, unfoldDurationFrames: 62, curvature: 0.4 }),
+      fold('bottom', { direction: 'down', side: 'outward', startAngle: 0, peakAngle: 168, endAngle: 0, peakScale: 1.02, translationY: -70, rotationZ: 1, delayFrames: 4, durationFrames: 78, unfoldDurationFrames: 60, edgeLift: 18, curvature: 0.4 }),
+    ],
+  },
+  {
+    path: 'creases', group: 'Creases', minItems: 2, maxItems: 2, item: CREASE_ITEM, keyField: 'id', keys: FOLD_KEYS,
+    description: 'The two creases, top (creases.0, also creases.top) then bottom. Their positions split the sheet into the three panels.',
+    default: [crease('top', 0.333), crease('bottom', 0.655)],
+  },
+  {
+    path: 'background.gradient.stops', group: 'Background', minItems: 2, maxItems: 6, item: STOP_ITEM,
+    description: 'Background gradient stops, in order of offset.',
+    default: [{ offset: 0, color: '#b46cff' }, { offset: 1, color: '#aa62f7' }],
+  },
+];
+
+export const CONTROL_BY_PATH = new Map(CONTROLS.map((c) => [c.path, c]));
+export const LIST_BY_PATH = new Map(LISTS.map((l) => [l.path, l]));
+
+/** Every editable leaf, lists expanded as `<list>[].<field>` — the count people and agents see. */
+export const allControls = () => expandControls(CONTROLS, LISTS);