@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/replication2/engine.ts

@@ -0,0 +1,539 @@
+import { getPath, type Replication2Config } from './config';
+import { SCENE_IDS, type AspectRatio, type DistortionMode, type EasingValue, type SceneId } from './controls';
+import { ease } from './easing';
+import { lineWidthEm } from './measure';
+
+/**
+ * **The Replication 2 engine — when, not what.** A pure function from (config, frame) to the value of
+ * every layer: the Rive file draws them, this decides them. Deterministic: no clock, no Math.random,
+ * no DOM. The same config, seed and frame always give the same state, so Remotion can render frames
+ * in any order and in parallel, and the live player and the video agree frame for frame.
+ *
+ * Frames here are 60 fps motion frames. `outputFrameToMotion` maps an output frame (at canvas.fps,
+ * after the overall speed and loops) onto them.
+ */
+export const MOTION_FPS = 60;
+
+export type Rgba = { hex: string; alpha: number };
+export type Glow = { visible: boolean; x: number; y: number; rx: number; ry: number; color: string; falloff: number; opacity: number };
+export type FrameState = {
+  frame: number;
+  scene: SceneId | 'complete';
+  sceneIndex: number;
+  status: string;
+  design: { width: number; height: number };
+  theme: 'dark' | 'light';
+  background: {
+    dark: string; light: string; lightOpacity: number;
+    gradient: { opacity: number; from: string; to: string; x1: number; y1: number; x2: number; y2: number };
+    top: Glow; bottom: Glow;
+    vignette: { opacity: number; color: string; radius: number };
+    streaks: { color: string; width: number; items: { x: number; opacity: number }[] };
+  };
+  /** The text group: position (design units), scale, rotation (deg), opacity. Everything below is in its local space. */
+  stage: { x: number; y: number; scale: number; rotation: number; opacity: number };
+  /** The typed sentence (dark scenes). `settled` + `head` (the placeholder, if any) are drawn as one centred line. */
+  line: {
+    visible: boolean; settled: string; head: string; headColor: Rgba; color: string;
+    fontSize: number; weight: number; letterSpacing: number; opacity: number;
+    enter: GlyphTransform; distortion: Distortion;
+  };
+  /** The display line (AI Agent?). */
+  display: {
+    visible: boolean; text: string; fontSize: number; weight: number; letterSpacing: number; opacity: number;
+    gradientTop: string; gradientBottom: string; hideLeftTo: number; hideRightFrom: number; softness: number;
+    distortion: Distortion;
+  };
+  /** The light-scene words. `settled` + `head` (placeholder) + `entering` (an added word, resolving). */
+  final: {
+    visible: boolean; settled: string; head: string; headColor: Rgba; entering: string; enteringColor: Rgba; color: string;
+    fontSize: number; weight: number; letterSpacing: number; opacity: number; enter: GlyphTransform;
+  };
+  cursor: {
+    visible: boolean; solid: boolean; attach: 'line' | 'final'; width: number; height: number; stroke: number; radius: number;
+    color: string; opacity: number; gap: number; scale: number; glow: { opacity: number; color: string; radius: number };
+  };
+  headGlow: { opacity: number; color: string; rx: number; ry: number; falloff: number; offsetX: number; offsetY: number; blend: 'normal' | 'screen' | 'additive' };
+  brackets: {
+    visible: boolean; color: string; opacity: number; thickness: number; height: number; serif: number; padding: number;
+    leftOffset: number; rightOffset: number; leftTrim: number; rightTrim: number; leftOpacity: number; rightOpacity: number;
+    glow: { opacity: number; color: string; radius: number };
+  };
+  brace: {
+    visible: boolean; color: string; opacity: number; size: number; weight: number; padding: number; offsetY: number;
+    closingVisible: number; closingSlack: number; glow: { opacity: number; color: string; radius: number };
+  };
+};
+export type GlyphTransform = { index: number; x: number; y: number; scale: number; rotation: number; opacity: number; strength: number };
+export type Distortion = { mode: DistortionMode; strength: number; from: number; to: number; falloffFrom: number; falloffTo: number; x: number; y: number; rotation: number; scaleX: number; scaleY: number; opacity: number };
+
+/* ─── helpers ─────────────────────────────────────────────────────────────────────────────── */
+const DESIGN: Record<AspectRatio, { width: number; height: number }> = {
+  '16:9': { width: 1920, height: 1080 }, '9:16': { width: 1080, height: 1920 }, '1:1': { width: 1080, height: 1080 },
+};
+const clamp = (v: number, lo = 0, hi = 1) => (v < lo ? lo : v > hi ? hi : v);
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+const prog = (t: number, start: number, dur: number) => (dur <= 0 ? (t >= start ? 1 : 0) : clamp((t - start) / dur));
+function mixHex(a: string, b: string, t: number) {
+  const pa = parseInt(a.slice(1), 16), pb = parseInt(b.slice(1), 16);
+  const ch = (s: number) => Math.round(lerp((pa >> s) & 255, (pb >> s) & 255, t));
+  return `#${((ch(16) << 16) | (ch(8) << 8) | ch(0)).toString(16).padStart(6, '0')}`;
+}
+
+/** mulberry32 over a hash of the inputs: a deterministic random number in [0, 1). */
+export function seeded(...keys: number[]): number {
+  let h = 0x9e3779b9;
+  for (const k of keys) h = Math.imul(h ^ (k | 0), 0x85ebca6b) ^ (h >>> 13);
+  let t = h + 0x6d2b79f5;
+  t = Math.imul(t ^ (t >>> 15), t | 1);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+type Cfg = { n: (p: string) => number; b: (p: string) => boolean; s: (p: string) => string; e: (p: string) => EasingValue };
+const reader = (config: Replication2Config): Cfg => ({
+  n: (p) => getPath(config, p) as number,
+  b: (p) => getPath(config, p) as boolean,
+  s: (p) => getPath(config, p) as string,
+  e: (p) => getPath(config, p) as EasingValue,
+});
+
+const transform = (text: string, mode: string) => (mode === 'uppercase' ? text.toUpperCase() : mode === 'lowercase' ? text.toLowerCase() : text);
+
+/* ─── timeline ────────────────────────────────────────────────────────────────────────────── */
+export type SceneSpan = { id: SceneId; index: number; start: number; duration: number; enabled: boolean };
+
+/** Each scene's start and length in motion frames; disabled scenes take no time. */
+export function timeline(config: Replication2Config): { scenes: SceneSpan[]; durationFrames: number } {
+  const c = reader(config);
+  let at = 0;
+  const scenes = SCENE_IDS.map((id, index) => {
+    const flag = getPath(config, `scenes.${id}.enabled`);
+    const enabled = flag === undefined ? true : Boolean(flag);
+    const duration = enabled ? c.n(`scenes.${id}.durationFrames`) : 0;
+    const span = { id, index, start: at, duration, enabled };
+    at += duration;
+    return span;
+  });
+  return { scenes, durationFrames: at };
+}
+
+/**
+ * The overall speed actually played. In `speed` mode it is canvas.playbackSpeed; in `totalFrames`
+ * mode it follows from canvas.totalFrames: the timeline's length at canvas.fps divided by the frames
+ * asked for. Speed and total frames are one setting seen two ways.
+ */
+export function effectiveSpeed(config: Replication2Config): number {
+  const c = reader(config);
+  if (c.s('canvas.timingMode') !== 'totalFrames') return c.n('canvas.playbackSpeed');
+  return speedForFrames(config, c.n('canvas.totalFrames'));
+}
+
+/** The speed that makes one play-through last `frames` output frames at canvas.fps. */
+export function speedForFrames(config: Replication2Config, frames: number): number {
+  return (timeline(config).durationFrames * reader(config).n('canvas.fps')) / MOTION_FPS / Math.max(1, frames);
+}
+
+/** The output frames one play-through lasts at `speed`, at canvas.fps. */
+export function framesForSpeed(config: Replication2Config, speed: number): number {
+  return Math.ceil((timeline(config).durationFrames * reader(config).n('canvas.fps')) / MOTION_FPS / speed);
+}
+
+/** Output frames of a render at canvas.fps (speed or total frames, and loops, included). */
+export function outputDuration(config: Replication2Config): number {
+  const c = reader(config);
+  const perLoop = c.s('canvas.timingMode') === 'totalFrames' ? c.n('canvas.totalFrames') : framesForSpeed(config, c.n('canvas.playbackSpeed'));
+  return perLoop * (c.b('canvas.loop') ? c.n('canvas.loopCount') : 1);
+}
+
+/** The motion frame an output frame shows. */
+export function outputFrameToMotion(config: Replication2Config, outputFrame: number): number {
+  const c = reader(config);
+  const total = timeline(config).durationFrames;
+  const m = (outputFrame * MOTION_FPS * effectiveSpeed(config)) / c.n('canvas.fps');
+  if (c.b('canvas.loop')) {
+    const loops = c.n('canvas.loopCount');
+    return m >= total * loops ? total - 1e-6 : m % total;
+  }
+  return Math.min(m, total - 1e-6);
+}
+
+/* ─── typing ──────────────────────────────────────────────────────────────────────────────── */
+/** When each character starts (placeholder first), in frames from the typing start. Fits `available`. */
+function typingTimes(count: number, startCps: number, endCps: number, available: number): number[] {
+  const times: number[] = [];
+  let t = 0;
+  for (let i = 0; i < count; i++) {
+    times.push(t);
+    const cps = count > 1 ? lerp(startCps, endCps, i / (count - 1)) : startCps;
+    t += MOTION_FPS / cps;
+  }
+  const last = times.at(-1) ?? 0;
+  if (available > 0 && last > available) return times.map((x) => (x * available) / last);
+  return times;
+}
+
+type Typed = { settled: string; head: string; newest: number; sinceNewest: number; done: boolean; doneAt: number };
+/** The text typed by frame `t` (frames from the typing start): what is resolved and the placeholder at the head. */
+function typed(c: Cfg, sceneKey: number, full: string, from: number, times: number[], t: number, reduced: boolean): Typed {
+  const chars = [...full];
+  const lead = c.n('characters.scramble.leadFrames');
+  const doneAt = (times.at(-1) ?? 0) + (c.b('characters.scramble.enabled') ? lead : 0);
+  if (reduced || t >= doneAt) return { settled: full, head: '', newest: chars.length - 1, sinceNewest: Infinity, done: true, doneAt };
+  let n = 0;
+  while (n < times.length && times[n]! <= t) n++;
+  const shown = from + n;
+  const newest = shown - 1;
+  const since = n > 0 ? t - times[n - 1]! : Infinity;
+  if (n > 0 && c.b('characters.scramble.enabled') && since < lead && chars[newest] !== ' ') {
+    const glyphs = [...c.s('characters.scramble.glyphs')];
+    const step = Math.floor(since / c.n('characters.scramble.changeEveryFrames'));
+    const g = glyphs[Math.floor(seeded(c.n('canvas.seed'), sceneKey, newest, step) * glyphs.length)] ?? '#';
+    return { settled: chars.slice(0, newest).join(''), head: g, newest, sinceNewest: since, done: false, doneAt };
+  }
+  return { settled: chars.slice(0, shown).join(''), head: '', newest, sinceNewest: since, done: false, doneAt };
+}
+
+function glyphEnter(c: Cfg, index: number, since: number): GlyphTransform {
+  const dur = c.n('characters.enter.durationFrames');
+  const k = dur > 0 && Number.isFinite(since) ? 1 - ease(c.e('characters.enter.easing'), since / dur, dur) : 0;
+  return {
+    index, strength: k,
+    x: c.n('characters.enter.offsetX'), y: c.n('characters.enter.offsetY'),
+    scale: c.n('characters.enter.scale'), rotation: c.n('characters.enter.rotation'), opacity: c.n('characters.enter.opacity'),
+  };
+}
+
+const NO_DISTORTION: Distortion = { mode: 'none', strength: 0, from: 0, to: 0, falloffFrom: 0, falloffTo: 0, x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1, opacity: 1 };
+/** A band of glyphs travelling along the line, moved by the chosen mode. `scramble` is placeholders only. */
+function distortion(c: Cfg, t: number, active: boolean, reduced: boolean): Distortion {
+  const mode = c.s('distortion.mode') as DistortionMode;
+  if (reduced || mode === 'none' || mode === 'scramble' || (c.b('distortion.whileTypingOnly') && !active)) return NO_DISTORTION;
+  const width = 1 / c.n('distortion.frequency');
+  const centre = (((c.n('distortion.phase') + (c.n('distortion.speed') * t) / MOTION_FPS) % 1) + 1) % 1;
+  const from = centre - width / 2, to = centre + width / 2;
+  const d = { mode, strength: c.n('distortion.amount'), from, to, falloffFrom: centre, falloffTo: centre, x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1, opacity: c.n('distortion.opacity') };
+  const dy = c.n('distortion.displacement'), rot = c.n('distortion.rotation'), sx = c.n('distortion.scaleX'), sy = c.n('distortion.scaleY');
+  switch (mode) {
+    case 'wave': return { ...d, y: dy };
+    case 'stretch': return { ...d, scaleX: sx, scaleY: sy };
+    case 'rotate': return { ...d, rotation: rot };
+    case 'warp': return { ...d, y: dy, rotation: rot, scaleX: sx };
+    case 'verticalMorph': return { ...d, scaleY: sy };
+    case 'horizontalMorph': return { ...d, scaleX: sx };
+  }
+  return NO_DISTORTION;
+}
+
+/* ─── the frame ───────────────────────────────────────────────────────────────────────────── */
+/** Every layer's value at motion frame `frame`. `config` must be resolved (see `resolveConfig`). */
+export function frameState(config: Replication2Config, frame: number): FrameState {
+  const c = reader(config);
+  const reduced = c.b('motion.reducedMotion');
+  const design = DESIGN[c.s('canvas.aspectRatio') as AspectRatio];
+  const { scenes, durationFrames } = timeline(config);
+  const f = clamp(frame, 0, Math.max(0, durationFrames - 1e-6));
+  const span = scenes.find((s) => s.enabled && f >= s.start && f < s.start + s.duration) ?? scenes.filter((s) => s.enabled).at(-1)!;
+  const t = f - span.start; // frames into the scene
+  const S = (id: SceneId) => scenes[SCENE_IDS.indexOf(id)]!;
+  const tt = (p: string) => transform(c.s(p), c.s('typography.textTransform'));
+  const safe = c.n('canvas.safeArea');
+  const safeW = design.width * (1 - 2 * safe), safeH = design.height * (1 - 2 * safe);
+  const fitW = safeW * c.n('motion.zoom.fitWidth');
+  const sizeScale = c.n('typography.sizeScale');
+  const fit = (widthDu: number) => (c.b('motion.zoom.enabled') && widthDu > fitW ? Math.max(c.n('motion.zoom.minScale'), fitW / widthDu) : 1);
+  const light = span.id === 'developers';
+
+  /* sentence text and typing (what + line) */
+  const what = tt('text.what');
+  const rest = tt('text.line');
+  const lineOn = S('line').enabled && rest.trim() !== '';
+  const sentence = lineOn ? `${what} ${rest}` : what;
+  const lineSize = c.n('scenes.what.fontSize') * sizeScale;
+  const lineWeight = c.n('scenes.what.fontWeight');
+  const lineLs = c.n('scenes.what.letterSpacing');
+  const lead = c.b('characters.scramble.enabled') ? c.n('characters.scramble.leadFrames') : 0;
+  const whatTimes = typingTimes([...what].length, c.n('scenes.what.cps'), c.n('scenes.what.cps'), S('what').duration - lead - 1);
+  const restChars = [...sentence].length - [...what].length;
+  const restTimes = typingTimes(restChars, c.n('scenes.line.startCps'), c.n('scenes.line.endCps'), S('line').duration - lead - 1);
+  /** Typing state of the sentence at absolute motion frame `af`. */
+  const sentenceAt = (af: number): Typed => {
+    if (af < S('what').start) return { settled: '', head: '', newest: -1, sinceNewest: Infinity, done: false, doneAt: 0 };
+    if (!lineOn || af < S('line').start) {
+      const r = typed(c, 1, what, 0, whatTimes, af - S('what').start, reduced);
+      return lineOn || af < S('what').start + S('what').duration ? r : { ...r, done: true };
+    }
+    return typed(c, 2, sentence, [...what].length, restTimes, af - S('line').start, reduced);
+  };
+  const sentenceWidth = (s: Typed) => lineWidthEm(s.settled + s.head, lineWeight, lineLs) * lineSize;
+  /** Zoom trails the text by smoothingFrames: the mean of the fit over the frames just before. */
+  const smoothedFit = (af: number) => {
+    const n = reduced ? 0 : c.n('motion.zoom.smoothingFrames');
+    let sum = 0;
+    for (let k = 0; k <= n; k++) sum += fit(sentenceWidth(sentenceAt(Math.max(S('what').start, af - k))));
+    return sum / (n + 1);
+  };
+  const drift = (p: number, to: number) => (reduced ? 1 : lerp(1, to, ease(c.e('motion.driftEasing'), p)));
+  const whatDrift = (af: number) => {
+    const s = S('what');
+    const typedFor = typed(c, 1, what, 0, whatTimes, 0, false).doneAt;
+    return drift(prog(af - s.start, typedFor, s.duration - typedFor), c.n('scenes.what.driftScale'));
+  };
+
+  /* defaults: nothing visible */
+  // eslint-disable-next-line comppack/no-raw-colour -- an invisible glow's placeholder colour, never drawn
+  const glowOff: Glow = { visible: false, x: 0, y: 0, rx: 0, ry: 0, color: '#000000', falloff: 0.5, opacity: 0 };
+  const st: FrameState = {
+    frame: f, scene: span.id, sceneIndex: span.index, status: span.id,
+    design, theme: light ? 'light' : 'dark',
+    background: {
+      dark: c.s('background.dark.color'), light: c.s('background.light.color'), lightOpacity: light ? 1 : 0,
+      gradient: { opacity: 0, from: c.s('background.gradient.from'), to: c.s('background.gradient.to'), x1: 0, y1: 0, x2: 0, y2: 0 },
+      top: glowOff, bottom: glowOff,
+      vignette: { opacity: 0, color: c.s('background.vignette.color'), radius: Math.hypot(design.width, design.height) / 2 },
+      streaks: { color: c.s('background.streaks.color'), width: c.n('background.streaks.width'), items: [] },
+    },
+    stage: { x: 0, y: 0, scale: 1, rotation: c.n('motion.rotation'), opacity: 1 },
+    line: {
+      visible: false, settled: '', head: '', headColor: { hex: c.s('typography.color.dark'), alpha: c.n('characters.scramble.opacity') },
+      color: c.s('typography.color.dark'), fontSize: lineSize, weight: lineWeight, letterSpacing: lineLs * lineSize,
+      opacity: c.n('typography.opacity'), enter: glyphEnter(c, -1, Infinity), distortion: NO_DISTORTION,
+    },
+    display: {
+      visible: false, text: tt('text.aiAgent'), fontSize: c.n('scenes.aiAgent.fontSize') * sizeScale, weight: c.n('scenes.aiAgent.fontWeight'),
+      letterSpacing: 0, opacity: 0, gradientTop: c.s('scenes.aiAgent.gradientTop'), gradientBottom: c.s('scenes.aiAgent.gradientBottom'),
+      hideLeftTo: -1, hideRightFrom: 2, softness: 0, distortion: NO_DISTORTION,
+    },
+    final: {
+      visible: false, settled: '', head: '', headColor: { hex: c.s('typography.color.light'), alpha: c.n('characters.scramble.opacity') },
+      entering: '', enteringColor: { hex: c.s('typography.color.light'), alpha: 0 }, color: c.s('typography.color.light'),
+      fontSize: c.n('scenes.developers.fontSize') * sizeScale, weight: c.n('scenes.developers.fontWeight'),
+      letterSpacing: c.n('scenes.developers.letterSpacing') * c.n('scenes.developers.fontSize') * sizeScale, opacity: c.n('typography.opacity'),
+      enter: glyphEnter(c, -1, Infinity),
+    },
+    cursor: {
+      visible: false, solid: c.s('cursor.dark.style') === 'solid', attach: 'line', width: 0, height: 0, stroke: 0, radius: 0,
+      color: c.s('cursor.dark.color'), opacity: c.n('cursor.opacity'), gap: 0, scale: 1,
+      glow: { opacity: 0, color: c.s('cursor.glow.color'), radius: 0 },
+    },
+    headGlow: {
+      opacity: 0, color: c.s('glow.color'), rx: 0, ry: 0, falloff: c.n('glow.falloff'), offsetX: 0, offsetY: 0,
+      blend: c.s('glow.blendMode') as 'normal' | 'screen' | 'additive',
+    },
+    brackets: {
+      visible: false, color: c.s('brackets.color'), opacity: c.n('brackets.opacity'), thickness: 0, height: 0, serif: 0, padding: 0,
+      leftOffset: 0, rightOffset: 0, leftTrim: 1, rightTrim: 1, leftOpacity: 1, rightOpacity: 1, glow: { opacity: 0, color: c.s('brackets.glow.color'), radius: 0 },
+    },
+    brace: {
+      visible: false, color: c.s('brace.color'), opacity: c.n('brace.opacity'), size: c.n('brace.size'), weight: c.n('brace.weight'),
+      padding: 0, offsetY: 0, closingVisible: 0, closingSlack: 0, glow: { opacity: 0, color: c.s('brace.glow.color'), radius: 0 },
+    },
+  };
+
+  /* background: gradient, glows, vignette, streaks (dark scenes) */
+  if (!light) {
+    if (c.b('background.gradient.enabled')) {
+      const a = (c.n('background.gradient.angle') * Math.PI) / 180;
+      const hx = (Math.sin(a) * design.width) / 2, hy = (-Math.cos(a) * design.height) / 2;
+      st.background.gradient = { ...st.background.gradient, opacity: c.n('background.gradient.opacity'), x1: design.width / 2 - hx, y1: design.height / 2 - hy, x2: design.width / 2 + hx, y2: design.height / 2 + hy };
+    }
+    const lineS = S('line');
+    const rise = lineS.enabled
+      ? ease('easeOutCubic', prog(f, lineS.start + c.n('scenes.line.backgroundGlowAtFrame'), c.n('scenes.line.backgroundGlowFrames')))
+      : f >= S('collapse').start ? 1 : 0;
+    const bgGlow = (k: 'top' | 'bottom'): Glow => (c.b(`background.${k}Glow.enabled`)
+      ? {
+        visible: true, x: c.n(`background.${k}Glow.x`) * design.width, y: c.n(`background.${k}Glow.y`) * design.height,
+        rx: c.n(`background.${k}Glow.radiusX`) * design.width, ry: c.n(`background.${k}Glow.radiusY`) * design.height,
+        color: c.s(`background.${k}Glow.color`), falloff: 0.5, opacity: c.n(`background.${k}Glow.intensity`) * (reduced ? 1 : rise),
+      }
+      : glowOff);
+    st.background.top = bgGlow('top');
+    st.background.bottom = bgGlow('bottom');
+    st.background.vignette.opacity = c.n('background.vignette.intensity');
+    const from = S(c.s('background.streaks.fromScene') as SceneId);
+    if (c.b('background.streaks.enabled') && f >= from.start) {
+      const count = c.n('background.streaks.count');
+      const band = c.n('background.streaks.band') * design.width;
+      for (let i = 0; i < count; i++) {
+        const r = seeded(c.n('canvas.seed'), 77, i);
+        const x = i % 2 === 0 ? r * band : design.width - r * band;
+        st.background.streaks.items.push({ x, opacity: c.n('background.streaks.opacity') * (0.5 + 0.5 * seeded(c.n('canvas.seed'), 78, i)) });
+      }
+    }
+  }
+
+  /* anchor: where the group's centre sits, given its width */
+  const place = (widthDu: number, heightDu: number) => {
+    const anchor = c.s('motion.anchor');
+    let x = design.width * safe + safeW * c.n('motion.position.x');
+    let y = design.height * safe + safeH * c.n('motion.position.y');
+    if (anchor === 'centerLeft') x += widthDu / 2;
+    if (anchor === 'centerRight') x -= widthDu / 2;
+    if (anchor === 'topCenter') y += heightDu / 2;
+    if (anchor === 'bottomCenter') y -= heightDu / 2;
+    return { x, y };
+  };
+  const cursorDark = (em: number) => ({
+    visible: c.b('cursor.enabled'), solid: c.s('cursor.dark.style') === 'solid', attach: 'line' as const,
+    width: c.n('cursor.dark.width') * em, height: c.n('cursor.dark.height') * em, stroke: c.n('cursor.dark.strokeWidth') * em,
+    radius: c.n('cursor.dark.cornerRadius') * em, color: c.s('cursor.dark.color'), opacity: c.n('cursor.opacity'), gap: c.n('cursor.gap') * em, scale: 1,
+    glow: { opacity: c.b('cursor.glow.enabled') ? c.n('cursor.glow.intensity') : 0, color: c.s('cursor.glow.color'), radius: c.n('cursor.glow.radius') * em },
+  });
+  const blink = (waiting: boolean) => (c.b('cursor.blink.enabled') && waiting && !reduced ? (Math.floor(f / (c.n('cursor.blink.periodFrames') / 2)) % 2 === 0 ? 1 : 0) : 1);
+  const headGlow = (em: number, strength: number) => ({
+    ...st.headGlow, opacity: c.b('glow.enabled') && !reduced ? c.n('glow.intensity') * strength : 0,
+    rx: c.n('glow.radiusX') * em, ry: c.n('glow.radiusY') * em, offsetX: c.n('glow.offsetX') * em, offsetY: c.n('glow.offsetY') * em,
+  });
+
+  /* ─── scenes ─── */
+  if (span.id === 'cursor') {
+    const p = reduced ? 1 : ease(c.e('scenes.cursor.easing'), t / c.n('scenes.cursor.introFrames'), c.n('scenes.cursor.introFrames'));
+    st.stage = { ...st.stage, ...place(0, lineSize), scale: c.n('motion.scale') };
+    st.line = { ...st.line, visible: true };
+    st.cursor = { ...cursorDark(lineSize), scale: lerp(c.n('scenes.cursor.fromScale'), 1, p), gap: 0 };
+    st.cursor.opacity *= blink(true);
+  }
+
+  if (span.id === 'what' || span.id === 'line') {
+    const s = sentenceAt(f);
+    const width = sentenceWidth(s);
+    let zoom = smoothedFit(f);
+    if (span.id === 'line' && c.s('motion.zoom.mode') === 'anticipate' && !reduced) {
+      // Ease towards the finished line's zoom; never less zoomed out than the text so far needs.
+      const target = fit(lineWidthEm(sentence, lineWeight, lineLs) * lineSize);
+      const zf = c.n('scenes.line.zoomFrames');
+      zoom = Math.min(zoom, lerp(fit(lineWidthEm(what, lineWeight, lineLs) * lineSize), target, ease(c.e('scenes.line.zoomEasing'), t / zf, zf)));
+    }
+    const scale = zoom * whatDrift(Math.min(f, S('what').start + S('what').duration)) * c.n('motion.scale');
+    st.stage = { ...st.stage, ...place(width * scale, lineSize * scale), scale };
+    st.line = {
+      ...st.line, visible: true, settled: s.settled, head: s.head,
+      enter: glyphEnter(c, s.newest, s.sinceNewest), distortion: distortion(c, t, !s.done, reduced),
+    };
+    const typingActive = !s.done;
+    const sinceDone = f - (span.id === 'what' ? S('what').start : S('line').start) - s.doneAt;
+    const activity = typingActive ? 1 : clamp(1 - sinceDone / Math.max(1, c.n('glow.fadeOutFrames')));
+    st.headGlow = headGlow(lineSize, activity * c.n(`scenes.${span.id}.glowIntensity`));
+    const complete = s.done && (span.id === 'line' || !lineOn);
+    st.cursor = { ...cursorDark(lineSize), visible: c.b('cursor.enabled') && !(complete && c.b('cursor.hideOnComplete')) && !reduced };
+    st.cursor.opacity *= blink(s.done);
+    if (span.id === 'line' && c.b('brackets.enabled')) Object.assign(st.brackets, bracketState(c, t - c.n('scenes.line.bracketsAtFrame'), lineSize, scale, design.width, reduced));
+  }
+
+  if (span.id === 'collapse') {
+    const final = sentenceAt(S('collapse').start - 1e-6);
+    const width = sentenceWidth({ ...final, head: '' });
+    const base = fit(width) * whatDrift(S('what').start + S('what').duration) * c.n('motion.scale');
+    const hold = c.n('scenes.collapse.holdFrames'), dur = c.n('scenes.collapse.collapseFrames');
+    const pc = reduced ? 0 : ease(c.e('scenes.collapse.easing'), prog(t, hold, dur), dur);
+    const scale = base * drift(prog(t, 0, hold), c.n('scenes.collapse.holdDriftScale')) * lerp(1, c.n('scenes.collapse.toScale'), pc);
+    st.stage = { ...st.stage, ...place(width * scale, lineSize * scale), scale, opacity: c.b('scenes.collapse.fade') ? 1 - pc : 1 };
+    st.line = { ...st.line, visible: true, settled: final.settled, head: '' };
+    if (c.b('brackets.enabled') && S('line').enabled) Object.assign(st.brackets, bracketState(c, Infinity, lineSize, scale, design.width, true));
+  }
+
+  if (span.id === 'aiAgent') {
+    const size = st.display.fontSize, weight = st.display.weight;
+    const toLs = c.n('scenes.aiAgent.letterSpacing'), fromLs = c.n('scenes.aiAgent.fromLetterSpacing');
+    const trackIn = c.n('scenes.aiAgent.trackInFrames');
+    const p = reduced ? 1 : ease(c.e('scenes.aiAgent.easing'), t / trackIn, trackIn);
+    const ls = lerp(fromLs, toLs, p);
+    const settledWidth = lineWidthEm(st.display.text, weight, toLs) * size;
+    const pd = prog(t, trackIn, span.duration - trackIn);
+    const scale = fit(settledWidth) * lerp(c.n('scenes.aiAgent.fromScale'), 1, p) * drift(pd, c.n('scenes.aiAgent.driftScale')) * c.n('motion.scale');
+    const width = lineWidthEm(st.display.text, weight, ls) * size;
+    st.stage = { ...st.stage, ...place(width * scale, size * scale), scale };
+    const rf = c.n('scenes.aiAgent.revealFrames');
+    const r = reduced || rf === 0 ? 1 : ease(c.e('scenes.aiAgent.revealEasing'), t / rf, rf);
+    const soft = c.n('scenes.aiAgent.revealSoftness');
+    const mode = c.s('scenes.aiAgent.revealMode');
+    // Hidden spans, in fractions of the line: glyphs left of hideLeftTo and right of hideRightFrom.
+    const [hideLeftTo, hideRightFrom] = mode === 'centerOut' ? [0.5 - r * (0.5 + soft), 0.5 + r * (0.5 + soft)]
+      : mode === 'leftToRight' ? [-1 - soft, r * (1 + soft)]
+        : mode === 'rightToLeft' ? [1 - r * (1 + soft), 2 + soft]
+          : [-1 - soft, 2 + soft];
+    st.display = {
+      ...st.display, visible: true, letterSpacing: ls * size, opacity: c.n('typography.opacity') * lerp(1, c.n('scenes.aiAgent.dimTo'), reduced ? 0 : pd),
+      hideLeftTo, hideRightFrom, softness: soft, distortion: distortion(c, t, t < trackIn, reduced),
+    };
+  }
+
+  if (span.id === 'developers') {
+    const size = st.final.fontSize, weight = st.final.weight, ls = c.n('scenes.developers.letterSpacing');
+    const w1 = tt('text.final1'), w2 = tt('text.final2'), w3 = tt('text.final3');
+    const at2 = c.n('scenes.developers.word2AtFrame'), at3 = c.n('scenes.developers.word3AtFrame');
+    const typingAt = c.n('scenes.developers.typingAtFrame');
+    const times = typingTimes([...w1].length, c.n('scenes.developers.cps'), c.n('scenes.developers.cps'), (w2 ? at2 : span.duration) - typingAt - lead - 1);
+    const s = typed(c, 3, w1, 0, times, t - typingAt, reduced);
+    const typingStarted = t >= typingAt || reduced;
+    const words = [w1, ...(w2 && (t >= at2 || reduced) ? [w2] : []), ...(w3 && (t >= at3 || reduced) ? [w3] : [])];
+    const addingAt = words.length === 3 ? at3 : words.length === 2 ? at2 : -1;
+    const fadeDur = c.n('scenes.developers.wordFadeFrames');
+    const pw = reduced || addingAt < 0 ? 1 : prog(t, addingAt + c.n('scenes.developers.wordDelayFrames'), fadeDur);
+    const settledWords = pw < 1 ? words.slice(0, -1) : words;
+    const settled = typingStarted ? (words.length > 1 ? settledWords.join(' ') : s.settled) : '';
+    const entering = pw < 1 ? ` ${words.at(-1)}` : '';
+    const all = settled + (words.length > 1 ? entering : s.head);
+    const width = lineWidthEm(all, weight, ls) * size;
+    const introP = reduced ? 1 : ease(c.e('scenes.developers.introEasing'), t / c.n('scenes.developers.introFrames'), c.n('scenes.developers.introFrames'));
+    const introEnd = c.n('scenes.developers.introFrames');
+    const braceExtra = c.b('brace.enabled') ? 2 * (c.n('brace.padding') + 0.6 * c.n('brace.size')) * size : 0;
+    const scale = fit(width + braceExtra) * lerp(c.n('scenes.developers.introFromScale'), 1, introP)
+      * drift(prog(t, introEnd, span.duration - introEnd), c.n('scenes.developers.driftScale')) * c.n('motion.scale');
+    st.stage = { ...st.stage, ...place((width + braceExtra) * scale, size * c.n('brace.size') * scale), scale };
+    st.final = {
+      ...st.final, visible: true, settled, head: words.length > 1 ? '' : s.head,
+      entering, enteringColor: { hex: mixHex(c.s('scenes.developers.wordFromColor'), c.s('typography.color.light'), pw), alpha: pw },
+      enter: glyphEnter(c, s.newest, s.sinceNewest),
+    };
+    st.cursor = {
+      ...cursorDark(size), attach: 'final', solid: c.s('cursor.light.style') === 'solid',
+      visible: c.b('cursor.enabled') && !typingStarted, width: c.n('cursor.light.width') * size, height: c.n('cursor.light.height') * size,
+      color: c.s('cursor.light.color'), glow: { opacity: 0, color: c.s('cursor.glow.color'), radius: 0 },
+    };
+    st.cursor.opacity *= blink(true);
+    if (c.b('brace.enabled')) {
+      const gapDur = c.n('brace.gapFrames');
+      const pg = reduced || addingAt < 0 ? 1 : ease(c.e('brace.gapEasing'), prog(t, addingAt, gapDur), gapDur);
+      const added = addingAt < 0 ? 0 : lineWidthEm(` ${words.at(-1)}`, weight, ls) * size + ls * size;
+      st.brace = {
+        ...st.brace, visible: true, padding: c.n('brace.padding') * size, offsetY: c.n('brace.offsetY') * size,
+        closingVisible: reduced || t >= typingAt + c.n('brace.closingDelayFrames') ? 1 : 0,
+        closingSlack: -added * (1 - pg),
+        glow: { opacity: c.b('brace.glow.enabled') ? c.n('brace.glow.intensity') : 0, color: c.s('brace.glow.color'), radius: c.n('brace.glow.radius') * size },
+      };
+    }
+  }
+
+  // The last frame reports completion (the state machine's Complete state keeps every group shown;
+  // the opacities above decide what is visible).
+  if (frame >= durationFrames - 1) {
+    st.sceneIndex = SCENE_IDS.length;
+    st.status = 'complete';
+  }
+  if (reduced) {
+    st.line.head = '';
+    st.final.head = '';
+  }
+  return st;
+}
+
+/** The brackets `t` frames after they start arriving (Infinity = settled). */
+function bracketState(c: Cfg, t: number, em: number, stageScale: number, designWidth: number, settled: boolean): Partial<FrameState['brackets']> {
+  const dur = c.n('brackets.enter.durationFrames'), stagger = c.n('brackets.enter.staggerFrames');
+  const e = c.e('brackets.enter.easing');
+  const pl = settled ? 1 : ease(e, prog(t, 0, dur), dur);
+  const pr = settled ? 1 : ease(e, prog(t, stagger, dur), dur);
+  if (!settled && t < 0) return { visible: false };
+  const mode = c.s('brackets.enter.mode');
+  const travel = (c.n('brackets.enter.distance') * designWidth) / Math.max(stageScale, 1e-3);
+  return {
+    visible: true, thickness: c.n('brackets.thickness') * em, height: c.n('brackets.height') * em, serif: c.n('brackets.serifLength') * em,
+    padding: c.n('brackets.padding') * em,
+    leftOffset: mode === 'slide' ? -travel * (1 - pl) : 0, rightOffset: mode === 'slide' ? travel * (1 - pr) : 0,
+    leftTrim: mode === 'draw' ? pl : 1, rightTrim: mode === 'draw' ? pr : 1,
+    leftOpacity: mode === 'fade' ? pl : pl > 0 || mode !== 'slide' ? 1 : 0, rightOpacity: mode === 'fade' ? pr : pr > 0 || mode !== 'slide' ? 1 : 0,
+    glow: { opacity: c.b('brackets.glow.enabled') ? c.n('brackets.glow.intensity') : 0, color: c.s('brackets.glow.color'), radius: c.n('brackets.glow.radius') * em },
+  };
+}

package/src/motion/replication2/html.ts

@@ -0,0 +1,87 @@
+import { CONFIG_SCHEMA_ID, validateConfig, type ConfigError } from './config';
+import { replication2 } from './template';
+
+/**
+ * **HTML serialization** — the portable form of a replication-2 animation, following the Rive host
+ * pattern of `rive-prototype/`: a page that carries the config as JSON and draws it with the Rive
+ * runtime (`runtime.js` + `replication-2.riv` + `rive.wasm` beside it). No frames, images or video:
+ * configuration plus a reference to the reusable runtime asset.
+ *
+ * The config is embedded in a `<script type="application/json">` with `<`, `>` and `&` escaped as
+ * \u escapes, so no value can close the tag or start markup — whatever the text says.
+ */
+export const HTML_ASSETS = { runtime: 'runtime.js', riv: 'replication-2.riv', wasm: 'rive.wasm' } as const;
+
+const escapeJson = (value: unknown) =>
+  JSON.stringify(value, null, 2).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+const escapeAttr = (s: string) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** The accessible description of a config: `text.ariaLabel`, or the copy in order. */
+export function describeCopy(config: Record<string, unknown>): string {
+  const t = config.text as Record<string, string>;
+  return t.ariaLabel || [`${t.what} ${t.line}`.trim(), t.aiAgent, [t.final1, t.final2, t.final3].filter(Boolean).join(' ')].join(' — ');
+}
+
+/* The host page's own chrome (black letterbox, white error text), not a component colour. */
+/* eslint-disable comppack/no-raw-colour */
+const HOST_STYLE = (w: number, h: number) => `  <style>
+    html, body { margin: 0; height: 100%; background: #000; }
+    figure { margin: 0; height: 100%; display: grid; place-items: center; }
+    canvas { max-width: 100%; max-height: 100%; aspect-ratio: ${w} / ${h}; }
+    [data-error] { color: #fff; font: 14px/1.5 system-ui; padding: 16px; white-space: pre-wrap; }
+    .visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  </style>
+`;
+/* eslint-enable comppack/no-raw-colour */
+
+/** A complete host page for `config`, or the validation errors. */
+export function serializeReplication2Html(config: unknown, options: { title?: string; assetBase?: string; wasmFromCdn?: boolean } = {}): { valid: true; html: string } | { valid: false; errors: ConfigError[] } {
+  const checked = validateConfig(config);
+  if (!checked.valid) return { valid: false, errors: checked.errors };
+  const cfg = checked.config!;
+  const canvas = cfg.canvas as { width: number; height: number; aspectRatio: string };
+  const base = options.assetBase ?? './';
+  const label = describeCopy(cfg);
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeAttr(options.title ?? replication2.title)}</title>
+${HOST_STYLE(canvas.width, canvas.height)}</head>
+<body>
+  <!--
+    replication-2: a thin host for ${HTML_ASSETS.riv}. It validates the config, and the package engine
+    decides each frame; the Rive file draws it. Config, first found wins: #config=<url-encoded JSON> ·
+    ?config=<url-encoded JSON> · the JSON below. In an iframe, post { type: 'replication-2:update', config }.
+  -->
+  <figure role="img" aria-label="${escapeAttr(label)}" data-template="${replication2.id}" data-version="${replication2.version}" data-schema="${CONFIG_SCHEMA_ID}">
+    <canvas width="${canvas.width}" height="${canvas.height}" aria-hidden="true"></canvas>
+    <p class="visually-hidden">${escapeAttr(label)}</p>
+    <pre data-error role="alert" hidden></pre>
+  </figure>
+  <script type="application/json" id="replication-2-config">
+${escapeJson(cfg)}
+  </script>
+  <script type="module">
+    const { mountReplication2 } = await import(new URL('${escapeAttr(base)}${HTML_ASSETS.runtime}', location.href).href);
+    const read = () => {
+      const q = (s) => new URLSearchParams(s).get('config');
+      const raw = q(location.hash.slice(1)) ?? q(location.search) ?? document.getElementById('replication-2-config').textContent;
+      try { return JSON.parse(raw); } catch { return { __unparseable: raw }; }
+    };
+    const errorBox = document.querySelector('[data-error]');
+    const show = (errors) => { errorBox.hidden = false; errorBox.textContent = 'replication-2 could not show this configuration:\\n\\n' + errors.map((e) => '• ' + (e.path || '(config)') + ' — ' + e.message).join('\\n'); };
+    const handle = await mountReplication2(document.querySelector('canvas'), read(), {
+      riv: new URL('${escapeAttr(base)}${HTML_ASSETS.riv}', location.href).href,
+${options.wasmFromCdn ? '      // rive.wasm comes from the Rive runtime\'s CDN' : `      wasmUrl: new URL('${escapeAttr(base)}${HTML_ASSETS.wasm}', import.meta.url).href,`}
+      onInvalid: show,
+    });
+    window.replication2 = handle;
+    addEventListener('message', ({ data }) => { if (data?.type === 'replication-2:update') { const r = handle?.update(data.config); if (r && !r.valid) show(r.errors); } });
+  </script>
+</body>
+</html>
+`;
+  return { valid: true, html };
+}

package/src/motion/replication2/index.ts

@@ -0,0 +1,14 @@
+/**
+ * **replication-2 — a configurable-motion template rendered by Rive.** One canonical config (the
+ * control table), a pure engine that turns it into frames, and the Rive file that draws them.
+ * `docs/replication-2.md`.
+ */
+export { CONTROLS, CONTROL_BY_PATH, GROUPS, EASING_NAMES, ASPECT_RATIOS, FPS_OPTIONS, FONT_FAMILIES, DISTORTION_MODES, SCENE_IDS, type Control, type ControlType, type EasingValue, type Group, type SceneId } from './controls';
+export { CONFIG_SCHEMA_ID, defaultConfig, validateConfig, resolveConfig, applyPatch, diffConfig, configJsonSchema, getPath, Replication2ConfigError, type Replication2Config, type ConfigError, type ConfigPatch, type PatchOp } from './config';
+export { PRESET_PATCHES, presetConfig, type PresetName } from './presets';
+export { frameState, timeline, outputDuration, outputFrameToMotion, effectiveSpeed, speedForFrames, framesForSpeed, seeded, MOTION_FPS, type FrameState, type SceneSpan } from './engine';
+export { ease, cubicBezier, springAt } from './easing';
+export { lineWidthEm } from './measure';
+export { riveValues, argb, RIVE_PROPS, RIVE_ARTBOARD, RIVE_STATE_MACHINE, RIVE_VIEW_MODEL, type RiveValues, type RiveProp } from './rive-contract';
+export { createReplication2Driver, type Replication2Driver, type DriverOptions } from './driver';
+export { serializeReplication2Html, describeCopy, HTML_ASSETS } from './html';