@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/replication2/controls.ts

@@ -0,0 +1,336 @@
+/* eslint-disable comppack/no-raw-colour -- the defaults are content: colours measured from the reference GIF, which people and agents replace (DECISIONS §25). */
+/**
+ * **Replication 2 — the control table.** Every editable value of the animation, once: its path,
+ * type, range or options, default, description, and who may edit it. The JSON Schema, the validator,
+ * the defaults, the Remotion Studio schema, the site's editor and `REPLICATION_2_CONFIG_SCHEMA.md` are
+ * all generated from this list, so a person and an agent always see the same contract.
+ *
+ * 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 (so 1920 × 1080 on a 16:9 canvas).
+ * - `em` — multiples of the current font size; the element scales with the text it belongs to.
+ * - `normalized` — 0‥1 across the canvas (x across its width, y down its height).
+ *
+ * Defaults are the `reference` preset: measured from replication2.gif (see
+ * replication-2-prototype/REPLICATION_2_ANALYSIS.md). Where the reference cannot establish a value
+ * (an effect it never shows), the default switches the effect off rather than inventing one.
+ */
+export const EASING_NAMES = [
+  'linear', 'hold',
+  'easeInQuad', 'easeOutQuad', 'easeInOutQuad',
+  'easeInCubic', 'easeOutCubic', 'easeInOutCubic',
+  'easeInQuart', 'easeOutQuart', 'easeInOutQuart',
+  'easeInExpo', 'easeOutExpo', 'easeInOutExpo',
+  'easeOutBack',
+] as const;
+export type EasingName = (typeof EASING_NAMES)[number];
+export type CubicBezierEasing = { type: 'cubicBezier'; x1: number; y1: number; x2: number; y2: number };
+export type SpringEasing = { type: 'spring'; mass: number; damping: number; stiffness: number; velocity: number };
+/** A named curve, or a custom one. Never a function. */
+export type EasingValue = EasingName | CubicBezierEasing | SpringEasing;
+
+export const ASPECT_RATIOS = ['16:9', '9:16', '1:1'] as const;
+export type AspectRatio = (typeof ASPECT_RATIOS)[number];
+export const FPS_OPTIONS = [24, 25, 30, 48, 50, 60] as const;
+/** Fonts embedded in the Rive file. A family not listed here cannot be drawn, so it cannot be chosen. */
+export const FONT_FAMILIES = ['Inter'] as const;
+export const ANCHORS = ['center', 'topCenter', 'bottomCenter', 'centerLeft', 'centerRight'] as const;
+export const DISTORTION_MODES = ['none', 'wave', 'stretch', 'rotate', 'scramble', 'warp', 'verticalMorph', 'horizontalMorph'] as const;
+export type DistortionMode = (typeof DISTORTION_MODES)[number];
+export const REVEAL_MODES = ['type', 'centerOut', 'leftToRight', 'rightToLeft'] as const;
+export const SCENE_IDS = ['cursor', 'what', 'line', 'collapse', 'aiAgent', 'developers'] as const;
+export type SceneId = (typeof SCENE_IDS)[number];
+
+export const GROUPS = [
+  'canvas', 'background', 'typography', 'text', 'characters', 'cursor', 'brackets', 'brace',
+  'distortion', 'glow', 'motion', 'scenes', 'export',
+] as const;
+export type Group = (typeof GROUPS)[number];
+
+export type ControlType = 'number' | 'integer' | 'boolean' | 'color' | 'enum' | 'text' | 'easing';
+
+export type Control = {
+  /** Dotted path into the config, e.g. `scenes.what.durationFrames`. */
+  path: string;
+  group: Group;
+  type: ControlType;
+  default: string | number | boolean | EasingValue;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** `enum`: the allowed values. */
+  options?: readonly (string | number)[];
+  /** `text`: limits. Text is a single line of printable characters. */
+  maxLength?: number;
+  minLength?: number;
+  unit?: 'frames' | 'du' | 'em' | 'normalized' | 'deg' | 'px' | 'cps' | 'factor' | 'weight' | 'fraction';
+  description: string;
+  userEditable: boolean;
+  agentEditable: boolean;
+};
+
+type Opts = Partial<Pick<Control, 'step' | 'unit' | 'userEditable' | 'agentEditable' | 'minLength'>>;
+const base = (o: Opts = {}) => ({ userEditable: o.userEditable ?? true, agentEditable: o.agentEditable ?? true, ...(o.unit ? { unit: o.unit } : {}), ...(o.step !== undefined ? { step: o.step } : {}) });
+const group = (path: string) => path.split('.')[0] as Group;
+const num = (path: string, def: number, min: number, max: number, description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'number', default: def, min, max, description, ...base(o) });
+const int = (path: string, def: number, min: number, max: number, description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'integer', default: def, min, max, description, ...base({ step: 1, ...o }) });
+const frames = (path: string, def: number, max: number, description: string, min = 0): Control => int(path, def, min, max, description, { unit: 'frames' });
+const bool = (path: string, def: boolean, description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'boolean', default: def, description, ...base(o) });
+const color = (path: string, def: string, description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'color', default: def, description, ...base(o) });
+const choice = (path: string, def: string | number, options: readonly (string | number)[], description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'enum', default: def, options, description, ...base(o) });
+const text = (path: string, def: string, maxLength: number, description: string, o: Opts = {}): Control => ({ path, group: group(path), type: 'text', default: def, maxLength, minLength: o.minLength ?? 0, description, ...base(o) });
+const easing = (path: string, def: EasingValue, description: string): Control => ({ path, group: group(path), type: 'easing', default: def, description, ...base() });
+const opacity = (path: string, def: number, description: string) => num(path, def, 0, 1, description, { step: 0.01, unit: 'fraction' });
+
+export const CONTROLS: readonly Control[] = [
+  /* ─── canvas ─────────────────────────────────────────────────────────────────────────────── */
+  choice('canvas.aspectRatio', '16:9', ASPECT_RATIOS, 'Canvas shape. Layouts recompose for each shape (normalized positions, safe area, fit width); nothing is stretched or rotated.'),
+  int('canvas.width', 3840, 256, 7680, 'Output width in pixels. Must match the aspect ratio (±1%).', { unit: 'px' }),
+  int('canvas.height', 2160, 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.'),
+  int('canvas.seed', 20260929, 0, 2147483647, 'Seed for every random choice (placeholder glyphs, streak positions). The same config and seed always render the same frames.'),
+  num('canvas.safeArea', 0.05, 0, 0.3, 'Inset on every side, as a fraction of the canvas, that text and frames keep clear of.', { step: 0.01, unit: 'fraction' }),
+  choice('canvas.timingMode', 'speed', ['speed', 'totalFrames'], 'Which value sets the overall length. speed: playbackSpeed is set and the total frames follow from it. totalFrames: totalFrames is set and the speed follows from it. Either way every scene, hold and transition scales together.'),
+  num('canvas.playbackSpeed', 0.6, 0.25, 4, 'Overall speed (timingMode speed): every scene, hold and transition together. 1 is the reference GIF\'s own speed (5.43 s); the default 0.6 plays it slower (9.07 s); 2 plays it in half the time.', { step: 0.05, unit: 'factor' }),
+  int('canvas.totalFrames', 544, 24, 36000, 'Overall length in output frames at canvas.fps, for one play-through (timingMode totalFrames). More frames = slower, fewer = faster; the speed this implies must stay within 0.25–4.', { unit: 'frames' }),
+  bool('canvas.loop', false, 'Play again from the start after the last frame (live players; a video repeats the timeline loopCount times).'),
+  int('canvas.loopCount', 1, 1, 100, 'How many times the timeline plays in a rendered video when loop is on.'),
+
+  /* ─── background ─────────────────────────────────────────────────────────────────────────── */
+  color('background.dark.color', '#020415', 'Base colour of the dark scenes (cursor → AI Agent?).'),
+  color('background.light.color', '#ffffff', 'Base colour of the light scene (the brace mark).'),
+  bool('background.gradient.enabled', false, 'Lay a linear gradient over the dark base. Off in the reference.'),
+  num('background.gradient.angle', 180, 0, 360, 'Gradient direction in degrees (0 = upwards, 90 = to the right).', { unit: 'deg' }),
+  color('background.gradient.from', '#020415', 'Gradient start colour.'),
+  color('background.gradient.to', '#0a1040', 'Gradient end colour.'),
+  opacity('background.gradient.opacity', 1, 'Gradient opacity over the base.'),
+  bool('background.topGlow.enabled', true, 'The dim radial glow at the top of the dark scenes.'),
+  color('background.topGlow.color', '#080c3b', 'Top glow core colour (fades to transparent).'),
+  num('background.topGlow.x', 0.5, -0.5, 1.5, 'Top glow centre, across the canvas.', { step: 0.01, unit: 'normalized' }),
+  num('background.topGlow.y', 0, -0.5, 1.5, 'Top glow centre, down the canvas.', { step: 0.01, unit: 'normalized' }),
+  num('background.topGlow.radiusX', 0.55, 0, 2, 'Top glow horizontal radius, as a fraction of the canvas width.', { step: 0.01, unit: 'normalized' }),
+  num('background.topGlow.radiusY', 0.5, 0, 2, 'Top glow vertical radius, as a fraction of the canvas height.', { step: 0.01, unit: 'normalized' }),
+  opacity('background.topGlow.intensity', 1, 'Top glow strength.'),
+  bool('background.bottomGlow.enabled', true, 'The blue radial glow that rises from the bottom edge during the sentence.'),
+  color('background.bottomGlow.color', '#09135b', 'Bottom glow core colour (fades to transparent).'),
+  num('background.bottomGlow.x', 0.5, -0.5, 1.5, 'Bottom glow centre, across the canvas.', { step: 0.01, unit: 'normalized' }),
+  num('background.bottomGlow.y', 1, -0.5, 1.5, 'Bottom glow centre, down the canvas.', { step: 0.01, unit: 'normalized' }),
+  num('background.bottomGlow.radiusX', 0.55, 0, 2, 'Bottom glow horizontal radius, as a fraction of the canvas width.', { step: 0.01, unit: 'normalized' }),
+  num('background.bottomGlow.radiusY', 0.6, 0, 2, 'Bottom glow vertical radius, as a fraction of the canvas height.', { step: 0.01, unit: 'normalized' }),
+  opacity('background.bottomGlow.intensity', 1, 'Bottom glow strength.'),
+  opacity('background.vignette.intensity', 0, 'Darkening towards the corners of the dark scenes. Off in the reference.'),
+  color('background.vignette.color', '#000000', 'Vignette colour.'),
+  bool('background.streaks.enabled', true, 'Faint vertical streaks in the left and right bands of the dark scenes (from the collapse on).'),
+  int('background.streaks.count', 8, 0, 12, 'Number of streaks (split between the two bands).'),
+  color('background.streaks.color', '#000000', 'Streak colour.'),
+  opacity('background.streaks.opacity', 0.18, 'Streak opacity.'),
+  num('background.streaks.width', 14, 1, 120, 'Streak width.', { unit: 'du' }),
+  num('background.streaks.band', 0.2, 0, 0.5, 'Width of each edge band the streaks are scattered in, as a fraction of the canvas width.', { step: 0.01, unit: 'normalized' }),
+  choice('background.streaks.fromScene', 'collapse', SCENE_IDS, 'The first scene the streaks show in (they stay until the light scene).'),
+
+  /* ─── typography ─────────────────────────────────────────────────────────────────────────── */
+  choice('typography.fontFamily', 'Inter', FONT_FAMILIES, 'Typeface. Inter (OFL) is the closest registered match to the reference; the reference font itself cannot be established from a 414-pixel GIF.'),
+  num('typography.sizeScale', 1, 0.2, 4, 'Multiplies every scene\'s font size.', { step: 0.05, unit: 'factor' }),
+  choice('typography.textTransform', 'none', ['none', 'uppercase', 'lowercase'], 'Case applied to all copy.'),
+  num('typography.lineHeight', 1.2, 0.8, 2, 'Line box height in em (vertical centring of the single line).', { step: 0.05, unit: 'em' }),
+  color('typography.color.dark', '#fefefe', 'Text colour in the dark scenes.'),
+  color('typography.color.light', '#000000', 'Text colour in the light scene.'),
+  opacity('typography.opacity', 1, 'Opacity of all text.'),
+
+  /* ─── text (the copy) ────────────────────────────────────────────────────────────────────── */
+  text('text.what', 'What', 40, 'The first word, typed on its own after the cursor.', { minLength: 1 }),
+  text('text.line', 'does it take to build an', 80, 'Typed after the first word, on the same line. Empty ends the sentence at the first word.'),
+  text('text.aiAgent', 'AI Agent?', 40, 'The display line that tracks in after the collapse.', { minLength: 1 }),
+  text('text.final1', 'Developers', 30, 'First word inside the braces, typed.', { minLength: 1 }),
+  text('text.final2', 'Delays', 30, 'Second word, added inside the braces. Empty skips it.'),
+  text('text.final3', 'Documentation', 30, 'Third word, added inside the braces. Empty skips it.'),
+  text('text.ariaLabel', '', 200, 'Accessible description. Empty means it is built from the copy.'),
+
+  /* ─── characters (typing, placeholders, per-glyph entry) ─────────────────────────────────── */
+  bool('characters.scramble.enabled', true, 'Show a placeholder glyph at the typing head before each character resolves.'),
+  text('characters.scramble.glyphs', '#<@%*!>', 32, 'Placeholder glyphs, picked with the seed. Printable ASCII, no spaces.', { minLength: 1 }),
+  frames('characters.scramble.leadFrames', 3, 24, 'How long a placeholder shows before its character resolves.'),
+  frames('characters.scramble.changeEveryFrames', 2, 24, 'A placeholder shown longer than this changes glyph this often.', 1),
+  opacity('characters.scramble.opacity', 0.8, 'Placeholder opacity (the reference\'s placeholder is blurred; see known differences).'),
+  num('characters.enter.offsetY', 0, -2, 2, 'Where a newly typed glyph starts, vertically, in em (0 = in place).', { step: 0.01, unit: 'em' }),
+  num('characters.enter.offsetX', 0, -2, 2, 'Where a newly typed glyph starts, horizontally, in em.', { step: 0.01, unit: 'em' }),
+  num('characters.enter.scale', 1, 0, 4, 'Scale of a newly typed glyph as it appears.', { step: 0.01, unit: 'factor' }),
+  num('characters.enter.rotation', 0, -180, 180, 'Rotation of a newly typed glyph as it appears.', { unit: 'deg' }),
+  opacity('characters.enter.opacity', 1, 'Opacity of a newly typed glyph as it appears.'),
+  frames('characters.enter.durationFrames', 0, 60, 'How long a newly typed glyph takes to settle from the values above. 0 = it appears settled (the reference).'),
+  easing('characters.enter.easing', 'easeOutCubic', 'How a newly typed glyph settles.'),
+
+  /* ─── cursor ─────────────────────────────────────────────────────────────────────────────── */
+  bool('cursor.enabled', true, 'Show the typing cursor.'),
+  choice('cursor.dark.style', 'hollow', ['hollow', 'solid'], 'Cursor style in the dark scenes (outlined, as in the reference, or filled).'),
+  num('cursor.dark.width', 0.105, 0.005, 1, 'Dark cursor width.', { step: 0.005, unit: 'em' }),
+  num('cursor.dark.height', 1.1, 0.1, 4, 'Dark cursor height.', { step: 0.01, unit: 'em' }),
+  num('cursor.dark.strokeWidth', 0.016, 0.001, 0.2, 'Outline width of the hollow cursor.', { step: 0.001, unit: 'em' }),
+  num('cursor.dark.cornerRadius', 0.03, 0, 0.5, 'Corner radius of the dark cursor.', { step: 0.005, unit: 'em' }),
+  color('cursor.dark.color', '#99a2cb', 'Dark cursor colour.'),
+  choice('cursor.light.style', 'solid', ['hollow', 'solid'], 'Cursor style in the light scene.'),
+  num('cursor.light.width', 0.062, 0.005, 1, 'Light cursor width.', { step: 0.005, unit: 'em' }),
+  num('cursor.light.height', 1.23, 0.1, 4, 'Light cursor height.', { step: 0.01, unit: 'em' }),
+  color('cursor.light.color', '#000000', 'Light cursor colour.'),
+  num('cursor.gap', 0.1, 0, 2, 'Space between the end of the text and the cursor.', { step: 0.01, unit: 'em' }),
+  opacity('cursor.opacity', 1, 'Cursor opacity.'),
+  bool('cursor.glow.enabled', false, 'A soft glow around the cursor. Off in the reference (its glow is the text head glow).'),
+  color('cursor.glow.color', '#3f57a8', 'Cursor glow colour.'),
+  num('cursor.glow.radius', 0.6, 0, 4, 'Cursor glow radius.', { step: 0.05, unit: 'em' }),
+  opacity('cursor.glow.intensity', 0.5, 'Cursor glow strength.'),
+  bool('cursor.blink.enabled', false, 'Blink the cursor while it waits. The reference never blinks.'),
+  frames('cursor.blink.periodFrames', 60, 240, 'One blink cycle (on then off).', 2),
+  bool('cursor.hideOnComplete', true, 'Hide the cursor once the sentence is fully typed.'),
+
+  /* ─── brackets [ ] ───────────────────────────────────────────────────────────────────────── */
+  bool('brackets.enabled', true, 'Frame the sentence with square brackets.'),
+  color('brackets.color', '#8b8db9', 'Bracket colour.'),
+  opacity('brackets.opacity', 1, 'Bracket opacity.'),
+  num('brackets.thickness', 0.28, 0.01, 1, 'Stroke thickness.', { step: 0.01, unit: 'em' }),
+  num('brackets.height', 5, 0.5, 20, 'Bracket height.', { step: 0.05, unit: 'em' }),
+  num('brackets.serifLength', 0.45, 0, 3, 'Length of the short horizontal ends.', { step: 0.01, unit: 'em' }),
+  num('brackets.padding', 1.7, 0, 10, 'Gap between the text and each bracket.', { step: 0.01, unit: 'em' }),
+  choice('brackets.enter.mode', 'slide', ['slide', 'draw', 'fade'], 'How the brackets arrive: slide in from the edges (reference), draw their stroke, or fade.'),
+  num('brackets.enter.distance', 0.12, 0, 2, 'How far the brackets slide from, as a fraction of the canvas width.', { step: 0.01, unit: 'normalized' }),
+  frames('brackets.enter.durationFrames', 14, 240, 'How long each bracket takes to arrive.', 1),
+  frames('brackets.enter.staggerFrames', 6, 120, 'The right bracket starts this long after the left.'),
+  easing('brackets.enter.easing', 'easeOutQuad', 'How the brackets arrive.'),
+  bool('brackets.glow.enabled', false, 'A soft glow behind each bracket. Off in the reference.'),
+  color('brackets.glow.color', '#3f57a8', 'Bracket glow colour.'),
+  opacity('brackets.glow.intensity', 0.5, 'Bracket glow strength.'),
+  num('brackets.glow.radius', 1.2, 0, 6, 'Bracket glow radius.', { step: 0.05, unit: 'em' }),
+
+  /* ─── brace { } ──────────────────────────────────────────────────────────────────────────── */
+  bool('brace.enabled', true, 'Wrap the final words in curly braces.'),
+  color('brace.color', '#0b5bf8', 'Brace colour.'),
+  opacity('brace.opacity', 1, 'Brace opacity.'),
+  num('brace.size', 1.9, 0.5, 5, 'Brace glyph size, relative to the text.', { step: 0.05, unit: 'factor' }),
+  num('brace.weight', 450, 100, 900, 'Brace glyph weight (estimated from the reference\'s stroke thickness).', { step: 10, unit: 'weight' }),
+  num('brace.padding', 0.1, 0, 4, 'Gap between the text and each brace.', { step: 0.01, unit: 'em' }),
+  num('brace.offsetY', 0, -1, 1, 'Vertical offset of the braces from the text centre.', { step: 0.01, unit: 'em' }),
+  frames('brace.closingDelayFrames', 4, 120, 'The closing brace appears this long after typing starts, then rides after the typing head.'),
+  frames('brace.gapFrames', 8, 60, 'When a word is added, how long the closing brace takes to open the gap.', 1),
+  easing('brace.gapEasing', 'easeOutCubic', 'How the closing brace opens the gap.'),
+  bool('brace.glow.enabled', false, 'A soft glow behind each brace. Off in the reference.'),
+  color('brace.glow.color', '#0b5bf8', 'Brace glow colour.'),
+  opacity('brace.glow.intensity', 0.3, 'Brace glow strength.'),
+  num('brace.glow.radius', 1, 0, 6, 'Brace glow radius.', { step: 0.05, unit: 'em' }),
+
+  /* ─── distortion (a registry of per-glyph modes; never code) ─────────────────────────────── */
+  choice('distortion.mode', 'scramble', DISTORTION_MODES, 'Per-glyph distortion. "scramble" is the reference: placeholder glyphs at the typing head (see characters.scramble). The others move a band of glyphs along the line.'),
+  opacity('distortion.amount', 1, 'Strength of the distortion.'),
+  num('distortion.frequency', 1, 0.1, 10, 'Bands per line: higher is a tighter band.', { step: 0.1, unit: 'factor' }),
+  num('distortion.speed', 1, -5, 5, 'Lines per second the band travels (negative runs right to left).', { step: 0.1, unit: 'factor' }),
+  num('distortion.phase', 0, 0, 1, 'Starting position of the band along the line.', { step: 0.01, unit: 'fraction' }),
+  num('distortion.displacement', 0.25, -2, 2, 'Vertical displacement at full strength (wave, warp).', { step: 0.01, unit: 'em' }),
+  num('distortion.rotation', 12, -90, 90, 'Rotation at full strength (rotate, warp).', { unit: 'deg' }),
+  num('distortion.scaleX', 1.4, 0.1, 4, 'Horizontal scale at full strength (stretch, horizontalMorph).', { step: 0.05, unit: 'factor' }),
+  num('distortion.scaleY', 1.4, 0.1, 4, 'Vertical scale at full strength (stretch, verticalMorph).', { step: 0.05, unit: 'factor' }),
+  opacity('distortion.opacity', 1, 'Glyph opacity at full strength.'),
+  bool('distortion.whileTypingOnly', true, 'Apply only while a line is being typed or tracked in.'),
+
+  /* ─── glow (the light on the typing head) ────────────────────────────────────────────────── */
+  bool('glow.enabled', true, 'The blue radial light that sits on the typing head.'),
+  color('glow.color', '#5a80c9', 'Head glow core colour (fades to transparent).'),
+  opacity('glow.intensity', 1, 'Head glow strength at rest.'),
+  num('glow.radiusX', 1.6, 0, 6, 'Head glow horizontal radius.', { step: 0.01, unit: 'em' }),
+  num('glow.radiusY', 0.95, 0, 6, 'Head glow vertical radius.', { step: 0.01, unit: 'em' }),
+  num('glow.falloff', 0.5, 0.05, 0.95, 'Where the glow is half strength, from centre (0) to edge (1).', { step: 0.01, unit: 'fraction' }),
+  num('glow.offsetX', -0.8, -4, 4, 'Glow centre relative to the typing head.', { step: 0.01, unit: 'em' }),
+  num('glow.offsetY', 0, -4, 4, 'Glow centre relative to the line centre.', { step: 0.01, unit: 'em' }),
+  frames('glow.fadeOutFrames', 40, 240, 'How long the glow takes to fade once typing pauses.'),
+  choice('glow.blendMode', 'screen', ['normal', 'screen', 'additive'], 'How the glow mixes with what is under it.'),
+
+  /* ─── motion (layout and camera) ─────────────────────────────────────────────────────────── */
+  bool('motion.reducedMotion', false, 'Reduced motion: no typing, zoom, distortion or placeholders — each scene shows resolved, and a live player can jump straight to the final mark.'),
+  choice('motion.anchor', 'center', ANCHORS, 'Which point of the text group sits on motion.position.'),
+  num('motion.position.x', 0.5, 0, 1, 'Where the text group sits, across the safe area.', { step: 0.01, unit: 'normalized' }),
+  num('motion.position.y', 0.5, 0, 1, 'Where the text group sits, down the safe area.', { step: 0.01, unit: 'normalized' }),
+  num('motion.rotation', 0, -180, 180, 'Rotation of the whole text group.', { unit: 'deg' }),
+  num('motion.scale', 1, 0.1, 4, 'Scale of the whole text group.', { step: 0.01, unit: 'factor' }),
+  bool('motion.zoom.enabled', true, 'Zoom out as a line grows so it keeps within the fit width.'),
+  num('motion.zoom.fitWidth', 0.8, 0.1, 1, 'The widest a line may get, as a fraction of the safe area\'s width.', { step: 0.01, unit: 'fraction' }),
+  choice('motion.zoom.mode', 'anticipate', ['fit', 'anticipate'], 'fit: zoom out only as far as the text so far needs. anticipate: ease towards the finished line\'s zoom while typing (the reference), never less zoomed than fit.'),
+  frames('motion.zoom.smoothingFrames', 6, 60, 'How far the zoom trails the text (0 = exact).'),
+  num('motion.zoom.minScale', 0.05, 0.01, 1, 'Never zoom out further than this.', { step: 0.01, unit: 'factor' }),
+  easing('motion.driftEasing', 'linear', 'How the slow drifts in every hold move.'),
+
+  /* ─── scenes (timing and per-scene look) ─────────────────────────────────────────────────── */
+  frames('scenes.cursor.durationFrames', 20, 600, 'Cursor scene length.', 1),
+  num('scenes.cursor.fromScale', 2.45, 0, 20, 'Cursor scale at the start; it settles to 1.', { step: 0.05, unit: 'factor' }),
+  frames('scenes.cursor.introFrames', 18, 600, 'How long the cursor takes to settle.', 1),
+  easing('scenes.cursor.easing', 'easeOutQuart', 'How the cursor settles.'),
+
+  frames('scenes.what.durationFrames', 32, 600, 'First-word scene length (typing plus hold).', 1),
+  num('scenes.what.fontSize', 323, 8, 1200, 'Font size of the first word (the line zooms out from this).', { unit: 'du' }),
+  num('scenes.what.fontWeight', 400, 100, 900, 'Font weight of the sentence.', { step: 10, unit: 'weight' }),
+  num('scenes.what.letterSpacing', 0.045, -0.2, 1, 'Letter spacing of the sentence.', { step: 0.005, unit: 'em' }),
+  num('scenes.what.cps', 17, 1, 240, 'Typing speed, characters per second.', { unit: 'cps' }),
+  num('scenes.what.driftScale', 0.9, 0.1, 2, 'Scale reached by the end of the hold (a slow zoom out).', { step: 0.01, unit: 'factor' }),
+  opacity('scenes.what.glowIntensity', 1, 'Head glow strength in this scene, multiplied by glow.intensity.'),
+
+  bool('scenes.line.enabled', true, 'Type the rest of the sentence. Off ends the sentence at the first word.'),
+  frames('scenes.line.durationFrames', 34, 600, 'Sentence scene length.', 1),
+  num('scenes.line.startCps', 66, 1, 240, 'Typing speed at the start of the line, characters per second.', { unit: 'cps' }),
+  num('scenes.line.endCps', 40, 1, 240, 'Typing speed by the end of the line (the reference slows as it finishes).', { unit: 'cps' }),
+  frames('scenes.line.zoomFrames', 34, 600, 'anticipate zoom: how long the zoom takes to reach the finished line\'s scale.', 1),
+  easing('scenes.line.zoomEasing', 'easeOutCubic', 'anticipate zoom: how it gets there.'),
+  frames('scenes.line.bracketsAtFrame', 14, 600, 'When the brackets start to arrive, from the scene start.'),
+  frames('scenes.line.backgroundGlowAtFrame', 8, 600, 'When the background glows start to rise, from the scene start.'),
+  frames('scenes.line.backgroundGlowFrames', 24, 600, 'How long the background glows take to rise.', 1),
+  opacity('scenes.line.glowIntensity', 0.5, 'Head glow strength in this scene, multiplied by glow.intensity.'),
+
+  bool('scenes.collapse.enabled', true, 'Collapse the framed sentence to a point. Off cuts straight to the next scene.'),
+  frames('scenes.collapse.durationFrames', 56, 600, 'Collapse scene length (hold plus collapse).', 1),
+  frames('scenes.collapse.holdFrames', 28, 600, 'How long the framed sentence holds before collapsing.'),
+  num('scenes.collapse.holdDriftScale', 0.875, 0.1, 2, 'Scale reached by the end of the hold.', { step: 0.005, unit: 'factor' }),
+  frames('scenes.collapse.collapseFrames', 26, 600, 'How long the collapse takes.', 1),
+  easing('scenes.collapse.easing', 'easeInCubic', 'How the sentence collapses.'),
+  num('scenes.collapse.toScale', 0, 0, 1, 'Scale the sentence collapses to.', { step: 0.01, unit: 'factor' }),
+  bool('scenes.collapse.fade', true, 'Fade out while collapsing.'),
+
+  bool('scenes.aiAgent.enabled', true, 'Show the display line.'),
+  frames('scenes.aiAgent.durationFrames', 84, 600, 'Display-line scene length (track-in plus drift).', 1),
+  num('scenes.aiAgent.fontSize', 167, 8, 1200, 'Font size of the display line once settled.', { unit: 'du' }),
+  num('scenes.aiAgent.fontWeight', 400, 100, 900, 'Font weight of the display line.', { step: 10, unit: 'weight' }),
+  num('scenes.aiAgent.letterSpacing', 0.03, -0.2, 1, 'Letter spacing once settled.', { step: 0.005, unit: 'em' }),
+  num('scenes.aiAgent.fromLetterSpacing', 0.25, -0.2, 2, 'Letter spacing it tracks in from.', { step: 0.005, unit: 'em' }),
+  num('scenes.aiAgent.fromScale', 1.64, 0.1, 10, 'Scale it tracks in from.', { step: 0.01, unit: 'factor' }),
+  frames('scenes.aiAgent.trackInFrames', 18, 600, 'How long the track-in takes.', 1),
+  easing('scenes.aiAgent.easing', 'easeOutCubic', 'How the track-in settles.'),
+  choice('scenes.aiAgent.revealMode', 'centerOut', REVEAL_MODES, 'Order the glyphs appear in during the track-in.'),
+  frames('scenes.aiAgent.revealFrames', 14, 600, 'How long the reveal takes.'),
+  easing('scenes.aiAgent.revealEasing', 'linear', 'How the reveal spreads.'),
+  num('scenes.aiAgent.revealSoftness', 0.2, 0, 1, 'Soft edge of the reveal: partially transparent glyphs at its edges.', { step: 0.01, unit: 'fraction' }),
+  num('scenes.aiAgent.driftScale', 0.6, 0.1, 2, 'Scale reached by the end of the scene.', { step: 0.01, unit: 'factor' }),
+  opacity('scenes.aiAgent.dimTo', 0.75, 'Opacity reached by the end of the scene.'),
+  color('scenes.aiAgent.gradientTop', '#e1e3e8', 'Top colour of the display line\'s vertical gradient.'),
+  color('scenes.aiAgent.gradientBottom', '#7179ab', 'Bottom colour of the display line\'s vertical gradient.'),
+
+  bool('scenes.developers.enabled', true, 'Show the light scene with the brace mark.'),
+  frames('scenes.developers.durationFrames', 100, 900, 'Light scene length.', 1),
+  num('scenes.developers.fontSize', 57, 8, 1200, 'Font size of the final words.', { unit: 'du' }),
+  num('scenes.developers.fontWeight', 400, 100, 900, 'Font weight of the final words.', { step: 10, unit: 'weight' }),
+  num('scenes.developers.letterSpacing', 0.045, -0.2, 1, 'Letter spacing of the final words.', { step: 0.005, unit: 'em' }),
+  num('scenes.developers.introFromScale', 8.1, 0.1, 20, 'Scale the brace mark settles from after the cut.', { step: 0.05, unit: 'factor' }),
+  frames('scenes.developers.introFrames', 24, 600, 'How long the brace mark takes to settle.', 1),
+  easing('scenes.developers.introEasing', 'easeOutCubic', 'How the brace mark settles.'),
+  frames('scenes.developers.typingAtFrame', 4, 600, 'When the first word starts typing, from the scene start.'),
+  num('scenes.developers.cps', 34, 1, 240, 'Typing speed of the first word, characters per second.', { unit: 'cps' }),
+  frames('scenes.developers.word2AtFrame', 38, 900, 'When the second word is added, from the scene start.'),
+  frames('scenes.developers.word3AtFrame', 62, 900, 'When the third word is added, from the scene start.'),
+  frames('scenes.developers.wordDelayFrames', 3, 60, 'An added word starts resolving this long after the brace starts opening its gap.'),
+  frames('scenes.developers.wordFadeFrames', 10, 120, 'How long an added word takes to resolve.', 1),
+  color('scenes.developers.wordFromColor', '#7c8fb3', 'Colour an added word resolves from.'),
+  num('scenes.developers.driftScale', 0.92, 0.1, 2, 'Scale reached by the end of the scene.', { step: 0.01, unit: 'factor' }),
+
+  /* ─── export (Remotion render settings) ──────────────────────────────────────────────────── */
+  choice('export.codec', 'h264', ['h264', 'h265', 'prores', 'vp9'], 'Video codec.'),
+  choice('export.pixelFormat', 'yuv420p', ['yuv420p', 'yuv422p10le', 'yuv444p', 'yuv444p10le'], 'Pixel format.'),
+  choice('export.colorSpace', 'bt709', ['default', 'bt709', 'bt2020-ncl'], 'Colour space.'),
+  int('export.crf', 12, 0, 51, 'Constant rate factor (lower is higher quality).'),
+  choice('export.x264Preset', 'slow', ['ultrafast', 'veryfast', 'fast', 'medium', 'slow', 'slower', 'veryslow'], 'x264 speed/size trade-off.'),
+  choice('export.imageFormat', 'png', ['png', 'jpeg'], 'Intermediate frame format (PNG keeps flat colour clean).'),
+];
+
+export const CONTROL_BY_PATH: ReadonlyMap<string, Control> = new Map(CONTROLS.map((c) => [c.path, c]));

package/src/motion/replication2/driver.ts

@@ -0,0 +1,92 @@
+import { RuntimeLoader } from '@rive-app/canvas';
+import { REPLICATION_2_RIV } from './riv';
+import { RIVE_ARTBOARD, RIVE_PROPS, RIVE_STATE_MACHINE, RIVE_VIEW_MODEL, type RiveValues } from './rive-contract';
+
+/**
+ * **The Rive driver** — draws one frame of the replication-2 Rive file onto a canvas, synchronously,
+ * from a set of view-model values. It owns no clock: the live player calls it from
+ * requestAnimationFrame, the Remotion adapter once per rendered frame. Built on the runtime's
+ * low-level API (Canvas2D renderer) because only that lets a frame be drawn on demand and in any
+ * order — which is what makes a Remotion render deterministic.
+ */
+export type Replication2Driver = {
+  /** Write the values that changed, settle the file, and draw. */
+  draw(values: RiveValues): void;
+  /** What the state machine last wrote to `status`. */
+  status(): string;
+  dispose(): void;
+};
+
+export type DriverOptions = {
+  /** Where rive.wasm is served from. Defaults to the runtime's CDN. */
+  wasmUrl?: string;
+  /** The .riv bytes. Defaults to the file shipped in the package. */
+  riv?: Uint8Array;
+};
+
+let decoded: Uint8Array | undefined;
+function packagedRiv(): Uint8Array {
+  if (!decoded) {
+    const bin = atob(REPLICATION_2_RIV);
+    decoded = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) decoded[i] = bin.charCodeAt(i);
+  }
+  return decoded;
+}
+
+// The low-level runtime's types, derived (the package exports the classes, not their declarations).
+type RiveCanvas = Awaited<ReturnType<typeof RuntimeLoader.awaitInstance>>;
+type File = Awaited<ReturnType<RiveCanvas['load']>>;
+type Artboard = ReturnType<File['artboardByName']>;
+type StateMachineInstance = InstanceType<RiveCanvas['StateMachineInstance']>;
+type ViewModelInstance = ReturnType<ReturnType<File['viewModelByName']>['defaultInstance']>;
+type WrappedRenderer = ReturnType<RiveCanvas['makeRenderer']>;
+
+const TYPES = new Map(RIVE_PROPS.map((p) => [p.name, p.type]));
+
+export async function createReplication2Driver(canvas: HTMLCanvasElement, options: DriverOptions = {}): Promise<Replication2Driver> {
+  if (options.wasmUrl) RuntimeLoader.setWasmUrl(options.wasmUrl);
+  const rive: RiveCanvas = await RuntimeLoader.awaitInstance();
+  const file: File = await rive.load(options.riv ?? packagedRiv());
+  const artboard: Artboard = file.artboardByName(RIVE_ARTBOARD);
+  const machine: StateMachineInstance = new rive.StateMachineInstance(artboard.stateMachineByName(RIVE_STATE_MACHINE), artboard);
+  const vm: ViewModelInstance = file.viewModelByName(RIVE_VIEW_MODEL).defaultInstance();
+  machine.bindViewModelInstance(vm);
+  artboard.bindViewModelInstance(vm);
+  const renderer: WrappedRenderer = rive.makeRenderer(canvas);
+  const last = new Map<string, number | string>();
+
+  const write = (name: string, value: number | string) => {
+    if (last.get(name) === value) return;
+    last.set(name, value);
+    const type = TYPES.get(name);
+    if (type === 'Number') vm.number(name)!.value = value as number;
+    else if (type === 'String') vm.string(name)!.value = value as string;
+    else if (type === 'Color') vm.color(name)!.value = value as number;
+  };
+
+  return {
+    draw(values) {
+      for (const [k, v] of Object.entries(values)) write(k, v);
+      // Twice: the first pass lays the text out and writes its width back to the view model
+      // (lineWidth / finalWidth); the second moves what is attached to it (cursor, brackets, braces).
+      machine.advanceAndApply(0);
+      machine.advanceAndApply(0);
+      const w = Number(values.artW ?? artboard.width), h = Number(values.artH ?? artboard.height);
+      renderer.clear();
+      renderer.save();
+      renderer.align(rive.Fit.contain, rive.Alignment.center, { minX: 0, minY: 0, maxX: canvas.width, maxY: canvas.height }, { minX: 0, minY: 0, maxX: w, maxY: h });
+      artboard.draw(renderer);
+      renderer.restore();
+      renderer.flush();
+      rive.resolveAnimationFrame();
+    },
+    status: () => vm.string('status')?.value ?? '',
+    dispose() {
+      machine.delete();
+      artboard.delete();
+      renderer.delete();
+      file.unref?.();
+    },
+  };
+}

package/src/motion/replication2/easing.ts

@@ -0,0 +1,88 @@
+import type { EasingValue } from './controls';
+
+/**
+ * **The easing registry.** Every curve the config can name, plus the two parametric forms
+ * (cubicBezier, spring). A curve is data looked up here — never a function carried in the config.
+ */
+const pow = (k: number) => ({
+  in: (t: number) => t ** k,
+  out: (t: number) => 1 - (1 - t) ** k,
+  inOut: (t: number) => (t < 0.5 ? 2 ** (k - 1) * t ** k : 1 - (-2 * t + 2) ** k / 2),
+});
+const quad = pow(2), cubic = pow(3), quart = pow(4);
+
+const NAMED: Record<string, (t: number) => number> = {
+  linear: (t) => t,
+  hold: (t) => (t >= 1 ? 1 : 0),
+  easeInQuad: quad.in, easeOutQuad: quad.out, easeInOutQuad: quad.inOut,
+  easeInCubic: cubic.in, easeOutCubic: cubic.out, easeInOutCubic: cubic.inOut,
+  easeInQuart: quart.in, easeOutQuart: quart.out, easeInOutQuart: quart.inOut,
+  easeInExpo: (t) => (t <= 0 ? 0 : 2 ** (10 * t - 10)),
+  easeOutExpo: (t) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t)),
+  easeInOutExpo: (t) => (t <= 0 ? 0 : t >= 1 ? 1 : t < 0.5 ? 2 ** (20 * t - 10) / 2 : (2 - 2 ** (-20 * t + 10)) / 2),
+  easeOutBack: (t) => 1 + 2.70158 * (t - 1) ** 3 + 1.70158 * (t - 1) ** 2,
+};
+
+/** CSS-style cubic-bezier(x1, y1, x2, y2), solved for x by Newton's method with a bisection fallback. */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number) {
+  const cx = 3 * x1, bx = 3 * (x2 - x1) - cx, ax = 1 - cx - bx;
+  const cy = 3 * y1, by = 3 * (y2 - y1) - cy, ay = 1 - cy - by;
+  const x = (t: number) => ((ax * t + bx) * t + cx) * t;
+  const y = (t: number) => ((ay * t + by) * t + cy) * t;
+  const dx = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
+  return (p: number) => {
+    let t = p;
+    for (let i = 0; i < 8; i++) {
+      const err = x(t) - p;
+      if (Math.abs(err) < 1e-6) return y(t);
+      const d = dx(t);
+      if (Math.abs(d) < 1e-6) break;
+      t -= err / d;
+    }
+    let lo = 0, hi = 1;
+    t = p;
+    for (let i = 0; i < 40; i++) {
+      if (x(t) < p) lo = t; else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return y(t);
+  };
+}
+
+/**
+ * A damped spring from 0 to 1, evaluated at `seconds` (closed form, so any frame can be sampled
+ * on its own). Mass/damping/stiffness/velocity as in Remotion's `spring()`.
+ */
+export function springAt(seconds: number, { mass, damping, stiffness, velocity }: { mass: number; damping: number; stiffness: number; velocity: number }) {
+  const w0 = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  const v0 = -velocity;
+  const x0 = -1; // displacement from the target
+  const t = seconds;
+  let x: number;
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    x = Math.exp(-zeta * w0 * t) * (x0 * Math.cos(wd * t) + ((v0 + zeta * w0 * x0) / wd) * Math.sin(wd * t));
+  } else if (zeta === 1) {
+    x = Math.exp(-w0 * t) * (x0 + (v0 + w0 * x0) * t);
+  } else {
+    const r1 = -w0 * (zeta - Math.sqrt(zeta * zeta - 1)), r2 = -w0 * (zeta + Math.sqrt(zeta * zeta - 1));
+    const c2 = (v0 - r1 * x0) / (r2 - r1), c1 = x0 - c2;
+    x = c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
+  }
+  return 1 + x;
+}
+
+const clamp01 = (t: number) => (t < 0 ? 0 : t > 1 ? 1 : t);
+
+/**
+ * Progress `p` (0‥1, clamped) through a part lasting `durationFrames` (60 fps motion frames), shaped by
+ * `e`. A spring runs on real time across the part and is pinned to 1 at its end.
+ */
+export function ease(e: EasingValue, p: number, durationFrames = 60): number {
+  const t = clamp01(p);
+  if (typeof e === 'string') return (NAMED[e] ?? NAMED.linear!)(t);
+  if (e.type === 'cubicBezier') return cubicBezier(e.x1, e.y1, e.x2, e.y2)(t);
+  if (t >= 1) return 1;
+  return springAt((t * durationFrames) / 60, e);
+}