@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/promo/icons.tsx

@@ -0,0 +1,29 @@
+import type { ReactElement } from 'react';
+
+/**
+ * The icons a config may name (`ICONS` in controls.ts), drawn from this fixed set of paths. A config
+ * picks an icon by name; it can never supply a path or any SVG of its own.
+ */
+const PATHS: Record<string, string> = {
+  sparkle: 'M12 2l1.9 6.1L20 10l-6.1 1.9L12 18l-1.9-6.1L4 10l6.1-1.9L12 2zm7 12l.9 2.6 2.6.9-2.6.9L19 21l-.9-2.6-2.6-.9 2.6-.9L19 14z',
+  bolt: 'M13 2L4 14h7l-1 8 9-12h-7l1-8z',
+  star: 'M12 2.5l2.9 6.1 6.6.8-4.9 4.6 1.3 6.6L12 17.3l-5.9 3.3 1.3-6.6-4.9-4.6 6.6-.8L12 2.5z',
+  check: 'M9.5 16.2L5.3 12l-1.4 1.4 5.6 5.6L20.1 8.4 18.7 7 9.5 16.2z',
+  chart: 'M4 20h16v-2H4v2zm1-4h3V9H5v7zm5 0h3V4h-3v12zm5 0h3v-5h-3v5z',
+  heart: 'M12 21s-7.5-4.6-9.6-9.2C.9 8.4 3 4.5 6.7 4.5c2.1 0 3.6 1.2 4.3 2.4.7-1.2 2.2-2.4 4.3-2.4 3.7 0 5.8 3.9 4.3 7.3C19.5 16.4 12 21 12 21z',
+  rocket: 'M14 3c3.5 0 6 1 7 2 1 1 2 3.5 2 7-2 0-3.5.7-5 2.2L15.2 17 7 8.8 9.8 6C11.3 4.5 12 5 14 3zM6 10l8 8-2 2-2.5-.5L8 21l-1-3-3-1 1.5-1.5L5 13l1-3zm10-2.5a1.5 1.5 0 100 3 1.5 1.5 0 000-3z',
+  lock: 'M7 10V8a5 5 0 0110 0v2h1a1 1 0 011 1v9a1 1 0 01-1 1H6a1 1 0 01-1-1v-9a1 1 0 011-1h1zm2 0h6V8a3 3 0 00-6 0v2z',
+  arrow: 'M5 11h10.2l-4.6-4.6L12 5l7 7-7 7-1.4-1.4 4.6-4.6H5v-2z',
+  globe: 'M12 2a10 10 0 100 20 10 10 0 000-20zm6.9 9h-3a15 15 0 00-1.3-5.6A8 8 0 0118.9 11zM12 4c.9 1.2 1.8 3.6 2 7h-4c.2-3.4 1.1-5.8 2-7zM9.4 5.4A15 15 0 008.1 11h-3a8 8 0 014.3-5.6zM5.1 13h3a15 15 0 001.3 5.6A8 8 0 015.1 13zM12 20c-.9-1.2-1.8-3.6-2-7h4c-.2 3.4-1.1 5.8-2 7zm2.6-1.4a15 15 0 001.3-5.6h3a8 8 0 01-4.3 5.6z',
+  chat: 'M4 4h16a2 2 0 012 2v10a2 2 0 01-2 2H9l-5 4v-4a2 2 0 01-2-2V6a2 2 0 012-2z',
+};
+
+export function Icon({ name, size, color }: { name: string; size: number; color: string }): ReactElement | null {
+  const d = PATHS[name];
+  if (!d) return null;
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" aria-hidden="true" style={{ display: 'block', flex: 'none' }}>
+      <path d={d} fill={color} />
+    </svg>
+  );
+}

package/src/motion/promo/index.ts

@@ -0,0 +1,24 @@
+/**
+ * **promo-product-showcase — a configurable-motion template drawn procedurally and rendered by
+ * Remotion.** One canonical config (the control table), a pure engine that turns it into frames,
+ * and a React/DOM renderer that draws them. `docs/MOTION-TEMPLATES.md`.
+ */
+export {
+  CONTROLS, CONTROL_BY_PATH, LISTS, LIST_BY_PATH, GROUPS, EASING_NAMES, ASPECT_RATIOS, FPS_OPTIONS, FONT_FAMILIES, FONT_WEIGHTS, ICONS,
+  TEXT_MODES, CARD_ENTRANCES, PLACEHOLDERS, PHASES, LAYOUT_FOR, OVERRIDE_SCOPES, allControls,
+  type Control, type ControlType, type ListSpec, type Group, type EasingName, type AspectRatio, type PhaseId,
+} from './controls';
+export {
+  CONFIG_SCHEMA_ID, defaultConfig, defaultItem, validateConfig, resolveConfig, applyPatch, diffConfig, configJsonSchema, getPath, controlAt, sceneConfig, isAssetRef,
+  PromoConfigError, type PromoConfig, type ConfigError, type ConfigPatch, type PatchOp,
+} from './config';
+export { PRESET_PATCHES, presetConfig, type PresetName } from './presets';
+export {
+  frameState, timeline, layout, uiLayout, outputDuration, outputFrameToMotion, textAnim, splitText, blendConfigs, seeded, luminance, mixHex, rgba, MOTION_FPS,
+  type FrameState, type Timeline, type PhaseSpan, type SceneSpan, type Layout, type UiLayout, type Anim, type Rect, type TextBlock,
+} from './engine';
+export { ease } from './easing';
+export { PROMO_FONTS_CSS, installPromoFonts } from './fonts';
+export { PromoFrame, FONT_STACK, type PromoFrameProps, type ImageProps } from './PromoFrame';
+export { PromoShowcasePlayer, type PromoShowcasePlayerProps } from './PromoShowcasePlayer';
+export { promoProductShowcase } from './template';

package/src/motion/promo/presets.ts

@@ -0,0 +1,40 @@
+/* eslint-disable comppack/no-raw-colour -- preset colours are content, set through the same config as any edit (DECISIONS §25, §26). */
+import { applyPatch, defaultConfig, type PromoConfig } from './config';
+
+/**
+ * **Presets** — named patches over the reference config. Every preset is the same template with
+ * different values; applying one is the same operation as any agent or person edit.
+ */
+export const PRESET_PATCHES: Record<string, { description: string; patch: Record<string, unknown> }> = {
+  reference: { description: 'The reference look: luminous purple/pink/blue, a white SaaS window, 16:9 at 3840 × 2160, 60 fps.', patch: {} },
+  landscape: { description: '16:9, 3840 × 2160 (layout.landscape).', patch: { 'canvas.aspectRatio': '16:9', 'canvas.width': 3840, 'canvas.height': 2160 } },
+  portrait: { description: '9:16, 2160 × 3840: the portrait layout block — headline on top, a tall window with two card columns, the CTA near the bottom.', patch: { 'canvas.aspectRatio': '9:16', 'canvas.width': 2160, 'canvas.height': 3840 } },
+  square: { description: '1:1, 2160 × 2160 (layout.square).', patch: { 'canvas.aspectRatio': '1:1', 'canvas.width': 2160, 'canvas.height': 2160 } },
+  scenes: {
+    description: 'Four scenes over one product: Meet Acme → Generate websites → Ship faster → Try Acme today, with copy and colour changes per scene.',
+    patch: {
+      'timeline.showcase.durationFrames': 330,
+      scenes: [
+        { id: 'meet', durationFrames: 150, contentOverrides: { 'content.eyebrow': 'Introducing', 'content.title': 'Meet Acme', 'content.subtitle': 'Your AI product studio.' } },
+        { id: 'generate', durationFrames: 150, contentOverrides: { 'content.eyebrow': 'Generate', 'content.title': 'Generate websites', 'content.subtitle': 'Describe it. Acme builds it in seconds.' }, productOverrides: { 'productHeader.activeItem': 'Images' }, backgroundOverrides: { 'background.glow.color': '#9fb4ff' } },
+        { id: 'ship', durationFrames: 150, contentOverrides: { 'content.eyebrow': 'Launch', 'content.title': 'Ship faster', 'content.subtitle': 'From prompt to production in one afternoon.' }, backgroundOverrides: { 'background.glow.color': '#ffb4e6' } },
+        { id: 'try', durationFrames: 150, contentOverrides: { 'content.eyebrow': 'Free to start', 'content.title': 'Try Acme today', 'content.subtitle': 'No credit card. Cancel anytime.' } },
+      ],
+    },
+  },
+  loop: { description: 'A seamless loop: the settled composition with float, drift, lights, particles and card highlights fitted to 8 s.', patch: { 'loop.enabled': true, 'loop.loopDurationFrames': 480 } },
+  minimal: {
+    description: 'Quiet: no particles, floating elements, grain or badge; one soft glow.',
+    patch: { 'particles.enabled': false, floatingElements: [], 'background.noise.enabled': false, 'content.badge.enabled': false, 'background.secondaryGlow.enabled': false, lights: [], 'glow.intensity': 0.3 },
+  },
+};
+export type PresetName = keyof typeof PRESET_PATCHES;
+
+/** A preset as a complete, valid config. */
+export function presetConfig(name: string): PromoConfig {
+  const p = PRESET_PATCHES[name];
+  if (!p) throw new Error(`Unknown promo-product-showcase preset "${name}". Available: ${Object.keys(PRESET_PATCHES).join(', ')}.`);
+  const r = applyPatch(defaultConfig(), { patch: p.patch });
+  if (!r.valid) throw new Error(`Preset "${name}" is invalid: ${r.errors.map((e) => e.message).join(' ')}`);
+  return r.config;
+}

package/src/motion/promo/template.ts

@@ -0,0 +1,36 @@
+import type { ConfigurableMotionTemplate } from '../types';
+import { configJsonSchema, defaultConfig } from './config';
+import { allControls, GROUPS } from './controls';
+import { outputDuration } from './engine';
+import { PRESET_PATCHES } from './presets';
+
+/**
+ * **promo-product-showcase in the motion registry.** A configurable-motion template (DECISIONS §25,
+ * §26) drawn procedurally by React/DOM and rendered to video by Remotion. People and agents edit the
+ * same canonical config. Plain data — safe to JSON-serialise.
+ */
+export const promoProductShowcase: ConfigurableMotionTemplate = {
+  id: 'promo-product-showcase',
+  version: '1.0.0',
+  kind: 'configurableMotion',
+  renderer: 'remotion',
+  title: 'Promo product showcase — a SaaS product promo',
+  description: 'A premium SaaS promo: a luminous gradient atmosphere, a large rounded product window with a procedural app UI (navigation, chat, result cards, input), promotional typography, floating badges, particles and a slow camera. Every word, colour, position, timing and easing is configurable; 16:9, 9:16 and 1:1 each have their own layout.',
+  fps: 60,
+  formats: [
+    { id: 'landscape', aspectRatio: '16:9', width: 3840, height: 2160 },
+    { id: 'portrait', aspectRatio: '9:16', width: 2160, height: 3840 },
+    { id: 'square', aspectRatio: '1:1', width: 2160, height: 2160 },
+  ],
+  durationInFrames: outputDuration(defaultConfig()),
+  groups: [...GROUPS],
+  controls: allControls(),
+  schema: configJsonSchema(),
+  presets: PRESET_PATCHES,
+  remotion: {
+    project: 'remotion-prototype',
+    compositions: ['PromoProductShowcaseLandscape', 'PromoProductShowcasePortrait', 'PromoProductShowcaseSquare'],
+    reference: 'remotion-prototype/content/promo-product-showcase/reference.json',
+  },
+  exampleContent: defaultConfig(),
+};

package/src/motion/replication2/Replication2Player.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { validateConfig, type ConfigError, type Replication2Config } from './config';
+import { createReplication2Driver, type DriverOptions, type Replication2Driver } from './driver';
+import { effectiveSpeed, frameState, MOTION_FPS, timeline } from './engine';
+import { riveValues } from './rive-contract';
+
+export type Replication2PlayerProps = {
+  /** The canonical config (any subset; defaults fill the rest). Validated before anything is drawn. */
+  config: unknown;
+  autoPlay?: boolean;
+  /** Overrides canvas.loop for this player. */
+  loop?: boolean;
+  /** Rendered width in CSS px; the height follows the config's aspect ratio. Defaults to 640. */
+  width?: number;
+  /** Seek to this motion frame and hold (scrubbing). */
+  frame?: number;
+  onFrame?: (frame: number, status: string) => void;
+  onInvalid?: (errors: ConfigError[]) => void;
+  /** Where rive.wasm is served from (defaults to the runtime's CDN). */
+  wasmUrl?: DriverOptions['wasmUrl'];
+  className?: string;
+};
+
+const DESIGN_RATIO: Record<string, number> = { '16:9': 16 / 9, '9:16': 9 / 16, '1:1': 1 };
+
+/**
+ * **replication-2 in a React web app.** Validates the config, then draws each frame with the Rive
+ * file: the engine decides the frame, the driver writes the view model and draws. The canvas is
+ * `aria-hidden` inside a `role="img"` box labelled with the copy (or `text.ariaLabel`). Reduced
+ * motion — the OS setting or `motion.reducedMotion` — shows the resolved final frame, still.
+ */
+export function Replication2Player({ config, autoPlay = true, loop, width = 640, frame, onFrame, onInvalid, wasmUrl, className }: Replication2PlayerProps) {
+  const key = JSON.stringify(config ?? {});
+  const checked = useMemo(() => validateConfig(JSON.parse(key)), [key]);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const driverRef = useRef<Replication2Driver | null>(null);
+  const [ready, setReady] = useState(false);
+  const callbacks = useRef({ onFrame, onInvalid });
+  callbacks.current = { onFrame, onInvalid };
+
+  const cfg = checked.config as Replication2Config | undefined;
+  const aspect = cfg ? String((cfg.canvas as { aspectRatio: string }).aspectRatio) : '16:9';
+  const height = Math.round(width / (DESIGN_RATIO[aspect] ?? 16 / 9));
+
+  useEffect(() => {
+    if (!checked.valid) callbacks.current.onInvalid?.(checked.errors);
+  }, [checked]);
+
+  // One driver per canvas.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    let live = true;
+    createReplication2Driver(canvas, { wasmUrl }).then((d) => {
+      if (!live) return d.dispose();
+      driverRef.current = d;
+      setReady(true);
+    });
+    return () => {
+      live = false;
+      driverRef.current?.dispose();
+      driverRef.current = null;
+      setReady(false);
+    };
+  }, [wasmUrl]);
+
+  // The clock: requestAnimationFrame → motion frame → engine → Rive.
+  useEffect(() => {
+    const driver = driverRef.current;
+    const canvas = canvasRef.current;
+    if (!ready || !driver || !canvas || !cfg) return;
+    const dpr = typeof window !== 'undefined' ? Math.min(2, window.devicePixelRatio || 1) : 1;
+    canvas.width = Math.round(width * dpr);
+    canvas.height = Math.round(height * dpr);
+    const total = timeline(cfg).durationFrames;
+    const speed = effectiveSpeed(cfg);
+    const looping = loop ?? Boolean((cfg.canvas as { loop: boolean }).loop);
+    const reduced = Boolean((cfg.motion as { reducedMotion: boolean }).reducedMotion)
+      || (typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
+    const draw = (f: number) => {
+      driver.draw(riveValues(frameState(cfg, f)));
+      callbacks.current.onFrame?.(f, driver.status());
+    };
+    if (frame !== undefined || reduced || !autoPlay) {
+      draw(frame ?? (reduced ? total - 1 : 0));
+      return;
+    }
+    let raf = 0;
+    const start = performance.now();
+    const tick = (now: number) => {
+      const m = ((now - start) / 1000) * MOTION_FPS * speed;
+      const f = looping ? m % total : Math.min(m, total - 1);
+      draw(f);
+      if (looping || m < total) raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [ready, cfg, width, height, frame, autoPlay, loop]);
+
+  if (!checked.valid) {
+    return (
+      <div role="alert" className={className} style={{ width, padding: 12, font: '13px/1.4 system-ui', border: '1px solid currentColor' }}>
+        <strong>This Replication 2 configuration is not valid.</strong>
+        <ul>{checked.errors.slice(0, 8).map((e) => <li key={e.path + e.message}>{e.message}</li>)}</ul>
+      </div>
+    );
+  }
+  const text = cfg!.text as Record<string, string>;
+  const label = text.ariaLabel || [`${text.what} ${text.line}`.trim(), text.aiAgent, [text.final1, text.final2, text.final3].filter(Boolean).join(' ')].join(' — ');
+  return (
+    <div role="img" aria-label={label} className={className} style={{ width, height, position: 'relative' }} data-rive={ready ? 'ready' : 'loading'}>
+      <canvas ref={canvasRef} aria-hidden="true" style={{ width, height, display: 'block' }} />
+    </div>
+  );
+}

package/src/motion/replication2/config.ts

@@ -0,0 +1,323 @@
+import {
+  CONTROLS, CONTROL_BY_PATH, EASING_NAMES, SCENE_IDS, type AspectRatio, type Control, type EasingValue,
+} from './controls';
+
+/**
+ * **The canonical configuration** — one nested JSON object, built from the control table. People,
+ * the Studio, the site editor and agents all read and write this same object; nothing else exists.
+ *
+ * Pure: no React, no DOM. Nothing here throws on bad input: validation returns errors.
+ */
+export const CONFIG_SCHEMA_ID = 'replication-2/1';
+
+/** The config as plain nested data. Leaves are what the control table says they are. */
+export type Replication2Config = { schema?: typeof CONFIG_SCHEMA_ID } & { [group: string]: unknown };
+export type ConfigError = { path: string; message: string };
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export function getPath(obj: unknown, path: string): unknown {
+  let cur: unknown = obj;
+  for (const k of path.split('.')) {
+    if (!isObj(cur)) return undefined;
+    cur = cur[k];
+  }
+  return cur;
+}
+
+function setPath(obj: Obj, path: string, value: unknown) {
+  const keys = path.split('.');
+  let cur = obj;
+  for (const k of keys.slice(0, -1)) {
+    if (!isObj(cur[k])) cur[k] = {};
+    cur = cur[k] as Obj;
+  }
+  cur[keys.at(-1)!] = value;
+}
+
+const clone = <T>(v: T): T => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+
+/** The reference preset: every control at its default. A fresh copy each call. */
+export function defaultConfig(): Replication2Config {
+  const out: Obj = { schema: CONFIG_SCHEMA_ID };
+  for (const c of CONTROLS) setPath(out, c.path, clone(c.default));
+  return out as Replication2Config;
+}
+
+/* ─── validation ──────────────────────────────────────────────────────────────────────────── */
+const HEX = /^#[0-9a-fA-F]{6}$/;
+// Single-line text. Copy is only ever drawn by Rive or written with textContent / JSON-escaped, never
+// parsed as markup, so characters like < and > are safe (and the reference's placeholders use them).
+// eslint-disable-next-line no-control-regex -- rejecting control characters is the point
+const UNSAFE_TEXT = /[\u0000-\u001f\u007f]/;
+
+function checkEasing(v: unknown, path: string, errors: ConfigError[]) {
+  if (typeof v === 'string') {
+    if (!(EASING_NAMES as readonly string[]).includes(v)) errors.push({ path, message: `${path} must be one of ${EASING_NAMES.join(', ')}, or a cubicBezier / spring object (got "${v}").` });
+    return;
+  }
+  if (!isObj(v)) return void errors.push({ path, message: `${path} must be an easing name or a cubicBezier / spring object.` });
+  const need = (keys: string[], ranges: Record<string, [number, number]>) => {
+    const extra = Object.keys(v).filter((k) => k !== 'type' && !keys.includes(k));
+    if (extra.length) errors.push({ path, message: `${path}: ${extra.join(', ')} ${extra.length === 1 ? 'is' : 'are'} not part of a ${String(v.type)} easing.` });
+    for (const k of keys) {
+      const n = v[k];
+      const [lo, hi] = ranges[k]!;
+      if (typeof n !== 'number' || !Number.isFinite(n)) errors.push({ path: `${path}.${k}`, message: `${path}.${k} must be a finite number.` });
+      else if (n < lo || n > hi) errors.push({ path: `${path}.${k}`, message: `${path}.${k} must be between ${lo} and ${hi} (got ${n}).` });
+    }
+  };
+  if (v.type === 'cubicBezier') need(['x1', 'y1', 'x2', 'y2'], { x1: [0, 1], y1: [-2, 3], x2: [0, 1], y2: [-2, 3] });
+  else if (v.type === 'spring') need(['mass', 'damping', 'stiffness', 'velocity'], { mass: [0.1, 20], damping: [0.1, 200], stiffness: [1, 1000], velocity: [-50, 50] });
+  else errors.push({ path, message: `${path}.type must be "cubicBezier" or "spring".` });
+}
+
+function checkLeaf(c: Control, v: unknown, errors: ConfigError[]) {
+  const p = c.path;
+  switch (c.type) {
+    case 'number':
+    case 'integer': {
+      if (typeof v !== 'number' || !Number.isFinite(v)) return void errors.push({ path: p, message: `${p} must be a finite number (got ${JSON.stringify(v)}).` });
+      if (c.type === 'integer' && !Number.isInteger(v)) return void errors.push({ path: p, message: `${p} must be a whole number (got ${v}).` });
+      if (v < c.min! || v > c.max!) errors.push({ path: p, message: `${p} must be between ${c.min} and ${c.max}${c.unit && !['fraction', 'factor'].includes(c.unit) ? ` ${c.unit}` : ''} (got ${v}).` });
+      return;
+    }
+    case 'boolean':
+      if (typeof v !== 'boolean') errors.push({ path: p, message: `${p} must be true or false.` });
+      return;
+    case 'color':
+      if (typeof v !== 'string' || !HEX.test(v)) errors.push({ path: p, message: `${p} must be a hex colour in the form #rrggbb (got ${JSON.stringify(v)}).` });
+      return;
+    case 'enum':
+      if (!c.options!.includes(v as string | number)) errors.push({ path: p, message: `${p} must be one of ${c.options!.map((o) => JSON.stringify(o)).join(', ')} (got ${JSON.stringify(v)}).` });
+      return;
+    case 'text': {
+      if (typeof v !== 'string') return void errors.push({ path: p, message: `${p} must be a string.` });
+      if (UNSAFE_TEXT.test(v)) return void errors.push({ path: p, message: `${p} must be a single line of plain text (no control characters or line breaks).` });
+      if (v.trim().length < (c.minLength ?? 0)) errors.push({ path: p, message: `${p} must not be empty.` });
+      if (v.length > c.maxLength!) errors.push({ path: p, message: `${p} accepts at most ${c.maxLength} characters (got ${v.length}).` });
+      if (p === 'characters.scramble.glyphs' && /[^\x21-\x7e]/.test(v)) errors.push({ path: p, message: `${p} must be printable ASCII with no spaces.` });
+      return;
+    }
+    case 'easing':
+      checkEasing(v, p, errors);
+  }
+}
+
+const RATIOS: Record<AspectRatio, number> = { '16:9': 16 / 9, '9:16': 9 / 16, '1:1': 1 };
+
+/** Cross-field rules: things no single control can check. */
+function checkRelations(cfg: Obj, errors: ConfigError[]) {
+  const n = (p: string) => getPath(cfg, p) as number;
+  const ratio = RATIOS[getPath(cfg, 'canvas.aspectRatio') as AspectRatio];
+  if (ratio && Number.isFinite(n('canvas.width')) && Number.isFinite(n('canvas.height'))) {
+    const actual = n('canvas.width') / n('canvas.height');
+    if (Math.abs(actual / ratio - 1) > 0.01) errors.push({ path: 'canvas.width', message: `canvas.width × canvas.height (${n('canvas.width')} × ${n('canvas.height')}) does not match canvas.aspectRatio ${String(getPath(cfg, 'canvas.aspectRatio'))}. Set all three together (the portrait, landscape and square presets do).` });
+  }
+  if (getPath(cfg, 'canvas.timingMode') === 'totalFrames') {
+    const motion = SCENE_IDS.reduce((sum, id) => {
+      const on = getPath(cfg, `scenes.${id}.enabled`);
+      return sum + (on === false ? 0 : n(`scenes.${id}.durationFrames`));
+    }, 0);
+    const speed = (motion * n('canvas.fps')) / 60 / n('canvas.totalFrames');
+    if (speed < 0.25 || speed > 4) {
+      const lo = Math.ceil((motion * n('canvas.fps')) / 60 / 4), hi = Math.floor((motion * n('canvas.fps')) / 60 / 0.25);
+      errors.push({ path: 'canvas.totalFrames', message: `canvas.totalFrames ${n('canvas.totalFrames')} would play at ${speed.toFixed(2)}× speed; with these scenes at ${n('canvas.fps')} fps it must be between ${lo} and ${hi} frames (0.25×–4×).` });
+    }
+  }
+  const inside = (scene: string, parts: [string, number][]) => {
+    const dur = n(`scenes.${scene}.durationFrames`);
+    for (const [label, end] of parts) {
+      if (Number.isFinite(end) && Number.isFinite(dur) && end > dur) errors.push({ path: `scenes.${scene}.durationFrames`, message: `scenes.${scene}: ${label} ends at frame ${end}, after the scene's ${dur} frames. Lengthen the scene or shorten the part.` });
+    }
+  };
+  inside('cursor', [['the intro (introFrames)', n('scenes.cursor.introFrames')]]);
+  inside('line', [
+    ['the brackets (bracketsAtFrame + stagger + duration)', n('scenes.line.bracketsAtFrame') + n('brackets.enter.staggerFrames') + n('brackets.enter.durationFrames')],
+    ['the background glow (backgroundGlowAtFrame + backgroundGlowFrames)', n('scenes.line.backgroundGlowAtFrame') + n('scenes.line.backgroundGlowFrames')],
+  ]);
+  inside('collapse', [['the hold and collapse (holdFrames + collapseFrames)', n('scenes.collapse.holdFrames') + n('scenes.collapse.collapseFrames')]]);
+  inside('aiAgent', [['the track-in (trackInFrames)', n('scenes.aiAgent.trackInFrames')], ['the reveal (revealFrames)', n('scenes.aiAgent.revealFrames')]]);
+  inside('developers', [
+    ['the intro (introFrames)', n('scenes.developers.introFrames')],
+    ['the third word (word3AtFrame + wordDelayFrames + wordFadeFrames)', n('scenes.developers.word3AtFrame') + n('scenes.developers.wordDelayFrames') + n('scenes.developers.wordFadeFrames')],
+  ]);
+  const w1 = n('scenes.developers.typingAtFrame'), w2 = n('scenes.developers.word2AtFrame'), w3 = n('scenes.developers.word3AtFrame');
+  if (w2 <= w1) errors.push({ path: 'scenes.developers.word2AtFrame', message: `scenes.developers.word2AtFrame (${w2}) must come after typingAtFrame (${w1}).` });
+  if (w3 <= w2) errors.push({ path: 'scenes.developers.word3AtFrame', message: `scenes.developers.word3AtFrame (${w3}) must come after word2AtFrame (${w2}).` });
+  if (getPath(cfg, 'text.final2') === '' && getPath(cfg, 'text.final3') !== '') errors.push({ path: 'text.final3', message: 'text.final3 needs text.final2: the words are added in order.' });
+}
+
+/** Keys in `value` that no control or group declares, as dotted paths. */
+function unknownKeys(value: Obj, prefix = ''): string[] {
+  const out: string[] = [];
+  for (const [k, v] of Object.entries(value)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (!prefix && k === 'schema') continue;
+    const control = CONTROL_BY_PATH.get(path);
+    if (control) continue; // a leaf (easing objects are checked by the leaf check)
+    const isGroup = CONTROLS.some((c) => c.path.startsWith(`${path}.`));
+    if (!isGroup) out.push(path);
+    else if (isObj(v)) out.push(...unknownKeys(v, path));
+    else out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Check a config. Partial configs are allowed (missing values take their defaults); anything present
+ * must be a known control with a valid value. Never throws.
+ */
+export function validateConfig(input: unknown): { valid: boolean; errors: ConfigError[]; config?: Replication2Config } {
+  const errors: ConfigError[] = [];
+  if (!isObj(input)) return { valid: false, errors: [{ path: '', message: 'The configuration must be a JSON object.' }] };
+  if (input.schema !== undefined && input.schema !== CONFIG_SCHEMA_ID) errors.push({ path: 'schema', message: `schema must be "${CONFIG_SCHEMA_ID}" (got ${JSON.stringify(input.schema)}).` });
+  for (const path of unknownKeys(input)) {
+    errors.push({ path, message: `${path} is not a Replication 2 control. Only the values in the schema can be set — no code, CSS, SVG, HTML or shader of any kind.` });
+  }
+  const merged = defaultConfig() as Obj;
+  for (const c of CONTROLS) {
+    const v = getPath(input, c.path);
+    if (v === undefined) continue;
+    const before = errors.length;
+    checkLeaf(c, v, errors);
+    if (errors.length === before) setPath(merged, c.path, clone(v));
+  }
+  if (!errors.length) checkRelations(merged, errors);
+  return errors.length ? { valid: false, errors } : { valid: true, errors, config: merged as Replication2Config };
+}
+
+/** A valid, complete config, or an error listing every problem. */
+export class Replication2ConfigError extends Error {
+  constructor(readonly errors: ConfigError[]) {
+    super(`Invalid Replication 2 configuration:\n${errors.map((e) => `  ${e.path || '(root)'}: ${e.message}`).join('\n')}`);
+  }
+}
+export function resolveConfig(input: unknown): Replication2Config {
+  const r = validateConfig(input);
+  if (!r.valid) throw new Replication2ConfigError(r.errors);
+  return r.config!;
+}
+
+/* ─── patches ─────────────────────────────────────────────────────────────────────────────── */
+/**
+ * One change to the config. `replace` sets a control, `merge` sets several under a group
+ * (`{ op: 'merge', path: 'cursor.dark', value: { width: 0.2 } }`), `remove` resets a control or a
+ * whole group to its default (every control always has a value).
+ */
+export type PatchOp =
+  | { op: 'replace'; path: string; value: unknown }
+  | { op: 'merge'; path: string; value: Obj }
+  | { op: 'remove'; path: string };
+/** Either a list of operations or the flat form `{ patch: { 'cursor.dark.width': 0.2 } }` (all replaces). */
+export type ConfigPatch = PatchOp[] | { patch: Record<string, unknown> };
+
+const flatten = (value: Obj, prefix: string): [string, unknown][] =>
+  Object.entries(value).flatMap(([k, v]) => {
+    const path = prefix ? `${prefix}.${k}` : k;
+    return isObj(v) && !CONTROL_BY_PATH.has(path) ? flatten(v, path) : [[path, v] as [string, unknown]];
+  });
+
+/**
+ * Apply a patch to a config and validate the result. The input is never modified. Nothing is
+ * applied unless every operation is well formed and the result is valid.
+ */
+export function applyPatch(config: unknown, patch: unknown): { valid: true; config: Replication2Config; changed: string[] } | { valid: false; errors: ConfigError[] } {
+  const start = validateConfig(config);
+  if (!start.valid) return { valid: false, errors: start.errors.map((e) => ({ ...e, message: `(before the patch) ${e.message}` })) };
+  let ops: PatchOp[];
+  if (Array.isArray(patch)) ops = patch as PatchOp[];
+  else if (isObj(patch) && isObj(patch.patch) && Object.keys(patch).length === 1) ops = Object.entries(patch.patch).map(([path, value]) => ({ op: 'replace', path, value }));
+  else return { valid: false, errors: [{ path: '', message: 'A patch is a list of { op, path, value } operations, or { "patch": { "<path>": value } }.' }] };
+
+  const next = clone(start.config!) as Obj;
+  const errors: ConfigError[] = [];
+  const changed: string[] = [];
+  const isGroupPath = (path: string) => CONTROLS.some((c) => c.path.startsWith(`${path}.`));
+  ops.forEach((o, i) => {
+    const where = `patch[${i}]`;
+    if (!isObj(o) || typeof o.path !== 'string') return void errors.push({ path: where, message: `${where} must be { op, path, value } with a dotted path.` });
+    const extra = Object.keys(o).filter((k) => !['op', 'path', 'value'].includes(k));
+    if (extra.length) return void errors.push({ path: where, message: `${where}: ${extra.join(', ')} ${extra.length === 1 ? 'is' : 'are'} not part of a patch operation.` });
+    if (o.op === 'replace') {
+      if (!CONTROL_BY_PATH.has(o.path)) return void errors.push({ path: o.path, message: `${o.path} is not a Replication 2 control${isGroupPath(o.path) ? ' (it is a group: use "merge")' : ''}.` });
+      setPath(next, o.path, clone(o.value));
+      changed.push(o.path);
+    } else if (o.op === 'merge') {
+      if (!isGroupPath(o.path) || !isObj(o.value)) return void errors.push({ path: o.path, message: `merge needs a group path (such as "cursor.dark") and an object value.` });
+      for (const [path, value] of flatten(o.value, o.path)) {
+        if (!CONTROL_BY_PATH.has(path)) { errors.push({ path, message: `${path} is not a Replication 2 control.` }); continue; }
+        setPath(next, path, clone(value));
+        changed.push(path);
+      }
+    } else if (o.op === 'remove') {
+      const hits = CONTROLS.filter((c) => c.path === o.path || c.path.startsWith(`${o.path}.`));
+      if (!hits.length) return void errors.push({ path: o.path, message: `${o.path} is not a Replication 2 control or group.` });
+      for (const c of hits) { setPath(next, c.path, clone(c.default)); changed.push(c.path); }
+    } else {
+      errors.push({ path: where, message: `${where}.op must be "replace", "merge" or "remove".` });
+    }
+  });
+  if (errors.length) return { valid: false, errors };
+  const end = validateConfig(next);
+  if (!end.valid) return { valid: false, errors: end.errors };
+  return { valid: true, config: end.config!, changed };
+}
+
+/** The difference between two configs as a flat patch (only what changed) — handy for sharing edits. */
+export function diffConfig(from: unknown, to: unknown): { patch: Record<string, unknown> } {
+  const patch: Record<string, unknown> = {};
+  for (const c of CONTROLS) {
+    const a = getPath(from, c.path) ?? c.default, b = getPath(to, c.path) ?? c.default;
+    if (JSON.stringify(a) !== JSON.stringify(b)) patch[c.path] = clone(b);
+  }
+  return { patch };
+}
+
+/* ─── JSON Schema ─────────────────────────────────────────────────────────────────────────── */
+const EASING_SCHEMA = {
+  oneOf: [
+    { type: 'string', enum: [...EASING_NAMES] },
+    { type: 'object', additionalProperties: false, required: ['type', 'x1', 'y1', 'x2', 'y2'], properties: { type: { const: 'cubicBezier' }, x1: { type: 'number', minimum: 0, maximum: 1 }, y1: { type: 'number', minimum: -2, maximum: 3 }, x2: { type: 'number', minimum: 0, maximum: 1 }, y2: { type: 'number', minimum: -2, maximum: 3 } } },
+    { type: 'object', additionalProperties: false, required: ['type', 'mass', 'damping', 'stiffness', 'velocity'], properties: { type: { const: 'spring' }, mass: { type: 'number', minimum: 0.1, maximum: 20 }, damping: { type: 'number', minimum: 0.1, maximum: 200 }, stiffness: { type: 'number', minimum: 1, maximum: 1000 }, velocity: { type: 'number', minimum: -50, maximum: 50 } } },
+  ],
+};
+
+function leafSchema(c: Control): Obj {
+  const meta = { description: c.description, default: c.default, 'x-group': c.group, 'x-userEditable': c.userEditable, 'x-agentEditable': c.agentEditable, ...(c.unit ? { 'x-unit': c.unit } : {}) };
+  switch (c.type) {
+    case 'number': return { type: 'number', minimum: c.min, maximum: c.max, ...meta };
+    case 'integer': return { type: 'integer', minimum: c.min, maximum: c.max, ...meta };
+    case 'boolean': return { type: 'boolean', ...meta };
+    case 'color': return { type: 'string', pattern: '^#[0-9a-fA-F]{6}$', format: 'hex-color', ...meta };
+    case 'enum': return { enum: [...c.options!], ...meta };
+    case 'text': return { type: 'string', minLength: c.minLength ?? 0, maxLength: c.maxLength, pattern: '^[^\\u0000-\\u001f\\u007f]*$', ...meta };
+    case 'easing': return { ...EASING_SCHEMA, ...meta };
+  }
+}
+
+/** JSON Schema 2020-12 of the whole config. Every property is optional (defaults fill the gaps). */
+export function configJsonSchema(): Obj {
+  const root: Obj = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://comppack.vercel.app/schemas/replication-2.json',
+    title: 'Replication 2 configuration',
+    description: 'The one canonical configuration of the replication-2 configurable-motion template. People and agents edit the same object; only these values exist.',
+    type: 'object', additionalProperties: false,
+    properties: { schema: { const: CONFIG_SCHEMA_ID } },
+  };
+  for (const c of CONTROLS) {
+    let node = root;
+    const keys = c.path.split('.');
+    for (const k of keys.slice(0, -1)) {
+      const props = node.properties as Obj;
+      props[k] ??= { type: 'object', additionalProperties: false, properties: {} };
+      node = props[k] as Obj;
+    }
+    (node.properties as Obj)[keys.at(-1)!] = leafSchema(c);
+  }
+  return root;
+}
+
+export type { EasingValue };