@appinternalleads/ui 0.4.0 → 0.4.1

package/src/components/onboarding/shared/describe.ts

@@ -13,7 +13,7 @@ import { presetsOf, resolveConfig, type OnboardingComponent } from './contract';
  */
 
 /** Keys whose values select behaviour or carry data rather than words. The agent-editable test uses the same rule. */
-export const CHOICE_KEYS = /^(type|icon|ship|id|key|status|tone|sentiment|kind|variant|format|currency|paymentMethod|value|mode|unit|date|when|time|href|url|ext|code|symbol|period|layout|state|strength|priority|previewKind|defaultPlan|defaultSelected|suggestions|range|start|end|today|hue|color|colour|primary|accent|font|avatar|initials|column|sortKey|field)$/i;
+export const CHOICE_KEYS = /^(type|icon|ship|id|key|status|tone|sentiment|kind|variant|format|currency|paymentMethod|value|mode|unit|date|when|time|href|url|ext|code|symbol|period|layout|state|strength|priority|previewKind|defaultPlan|defaultSelected|suggestions|range|start|end|today|hue|color|colour|primary|accent|font|avatar|initials|column|sortKey|field|textColor|accentColor|emblemIcon|autoplay|backgroundColor|buttonColor|iconColor|completionColor|trailColor|sendIcon|iconScale|cornerRadius|width|showTapCue|loop)$/i;
 
 export type SettingKind = 'text' | 'number' | 'yes/no' | 'list' | 'object';
 export type SettingDescription = {

package/src/components/onboarding/shared/mock.ts

@@ -34,6 +34,8 @@ export const ONBOARDING_TIMING = {
   toast: 6000,
   /** Receipt Printer: the host's print. Shorter than the paper's feed, so a failure lands mid-feed. */
   print: 900,
+  /** Send Completion: the host's send. Shorter than the launch, so the check never waits in the demo. */
+  send: 900,
 } as const;
 
 export type OnboardingOutcome = { ok: true } | { ok: false; message?: string };

package/src/components/onboarding/views.ts

@@ -46,6 +46,8 @@ import { CriteriaSpider } from './criteria-spider/CriteriaSpiderView';
 import { ActivityHeatmap } from './activity-heatmap/ActivityHeatmapView';
 import { TagCloud } from './tag-cloud/TagCloudView';
 import { ReceiptPrinter } from './receipt-printer/ReceiptPrinterView';
+import { AnimatedStatus } from './animated-status/AnimatedStatusView';
+import { SendCompletion } from './send-completion/SendCompletionView';
 import type { ComponentType } from 'react';
 import { AB_TESTS_IN_FLIGHT, AB_TESTS_SCENES, abTestsSeed } from './ab-tests';
 import { ACHIEVEMENT_IN_FLIGHT, ACHIEVEMENT_SCENES, achievementSeed } from './achievement';
@@ -84,6 +86,8 @@ import { QUEUE_IN_FLIGHT, QUEUE_SCENES, queueSeed } from './queue-status';
 import { QUICK_ACTIONS_IN_FLIGHT, QUICK_ACTIONS_SCENES, quickActionsSeed } from './quick-actions';
 import { RATE_LIMIT_IN_FLIGHT, RATE_LIMIT_SCENES, rateLimitSeed } from './rate-limit';
 import { RECEIPT_PRINTER_IN_FLIGHT, RECEIPT_PRINTER_SCENES, receiptPrinterSeed } from './receipt-printer';
+import { ANIMATED_STATUS_IN_FLIGHT, ANIMATED_STATUS_SCENES, animatedStatusSeed } from './animated-status';
+import { SEND_COMPLETION_IN_FLIGHT, SEND_COMPLETION_SCENES, sendCompletionSeed } from './send-completion';
 import { SCORE_IN_FLIGHT, SCORE_SCENES, scoreSeed } from './score-summary';
 import { SEAT_IN_FLIGHT, SEAT_SCENES, seatSeed } from './seat-allocation';
 import { SETUP_TASKS_IN_FLIGHT, SETUP_TASKS_SCENES, setupTasksSeed } from './setup-tasks';
@@ -154,6 +158,8 @@ export const ONBOARDING_VIEWS: Record<OnboardingComponent, ComponentType<Record<
   'activity-heatmap': ActivityHeatmap,
   'tag-cloud': TagCloud,
   'receipt-printer': ReceiptPrinter,
+  'animated-status': AnimatedStatus,
+  'send-completion': SendCompletion,
 } as unknown as Record<OnboardingComponent, ComponentType<Record<string, unknown> & GuardProps>>;
 
 /**
@@ -200,6 +206,8 @@ export const ONBOARDING_SCENES: Record<OnboardingComponent, OnboardingScenes> =
   'quick-actions': { scenes: QUICK_ACTIONS_SCENES, seed: quickActionsSeed as OnboardingScenes['seed'], inFlight: QUICK_ACTIONS_IN_FLIGHT },
   'rate-limit': { scenes: RATE_LIMIT_SCENES, seed: rateLimitSeed as OnboardingScenes['seed'], inFlight: RATE_LIMIT_IN_FLIGHT },
   'receipt-printer': { scenes: RECEIPT_PRINTER_SCENES, seed: receiptPrinterSeed as OnboardingScenes['seed'], inFlight: RECEIPT_PRINTER_IN_FLIGHT },
+  'animated-status': { scenes: ANIMATED_STATUS_SCENES, seed: animatedStatusSeed as OnboardingScenes['seed'], inFlight: ANIMATED_STATUS_IN_FLIGHT },
+  'send-completion': { scenes: SEND_COMPLETION_SCENES, seed: sendCompletionSeed as OnboardingScenes['seed'], inFlight: SEND_COMPLETION_IN_FLIGHT },
   'score-summary': { scenes: SCORE_SCENES, seed: scoreSeed as OnboardingScenes['seed'], inFlight: SCORE_IN_FLIGHT },
   'seat-allocation': { scenes: SEAT_SCENES, seed: seatSeed as OnboardingScenes['seed'], inFlight: SEAT_IN_FLIGHT },
   'setup-tasks': { scenes: SETUP_TASKS_SCENES, seed: setupTasksSeed as OnboardingScenes['seed'], inFlight: SETUP_TASKS_IN_FLIGHT },

package/src/motion/MotionPlayer.tsx

@@ -0,0 +1,62 @@
+import { useEffect, useRef, useState } from 'react';
+import { formatFor } from './sample';
+import { mountMotion, MotionContentValidationError, type MotionController } from './player';
+import type { MotionTemplate } from './types';
+import type { MotionContentError } from './validate';
+
+export type MotionPlayerProps = {
+  template: MotionTemplate;
+  /** The content contract: text slots, optional `theme`, optional scenes. Validated before mounting. */
+  content: unknown;
+  autoPlay?: boolean;
+  loop?: boolean;
+  /** Rendered width in px; the canvas keeps its aspect ratio (the content's `aspectRatio` format). Defaults to the canvas width. */
+  width?: number;
+  onReady?: (controller: MotionController) => void;
+  onFrame?: (frame: number) => void;
+  onInvalid?: (errors: MotionContentError[]) => void;
+  className?: string;
+};
+
+/**
+ * **A motion template in a React web app.** Web only (it plays DOM, not React Native views). The
+ * animation is the template's; this component only passes content through and scales the canvas.
+ */
+export function MotionPlayer({ template, content, autoPlay = true, loop = true, width, onReady, onFrame, onInvalid, className }: MotionPlayerProps) {
+  const mountRef = useRef<HTMLDivElement>(null);
+  const [errors, setErrors] = useState<MotionContentError[] | null>(null);
+  const callbacks = useRef({ onReady, onFrame, onInvalid });
+  callbacks.current = { onReady, onFrame, onInvalid };
+  const key = JSON.stringify(content);
+
+  useEffect(() => {
+    const root = mountRef.current;
+    if (!root) return;
+    let controller: MotionController | undefined;
+    try {
+      controller = mountMotion(root, template, JSON.parse(key), { autoPlay, loop, onFrame: (f) => callbacks.current.onFrame?.(f) });
+      setErrors(null);
+      callbacks.current.onReady?.(controller);
+    } catch (e) {
+      if (!(e instanceof MotionContentValidationError)) throw e;
+      setErrors(e.errors);
+      callbacks.current.onInvalid?.(e.errors);
+    }
+    return () => controller?.destroy();
+  }, [template, key, autoPlay, loop]);
+
+  const { width: w, height: h } = formatFor(template.motion, content);
+  const shown = width ?? w;
+  const scale = shown / w;
+  return (
+    <div className={className} style={{ position: 'relative', width: shown, height: (h * shown) / w, overflow: 'hidden' }}>
+      <div ref={mountRef} style={{ width: w, height: h, transform: `scale(${scale})`, transformOrigin: '0 0' }} />
+      {errors && (
+        <div role="alert" style={{ position: 'absolute', inset: 0, padding: 16, background: 'Canvas', color: 'CanvasText', font: '13px/1.5 system-ui, sans-serif', overflow: 'auto' }}>
+          <strong>Content does not fit this template:</strong>
+          <ul>{errors.map((e) => <li key={e.path + e.message}>{e.message}</li>)}</ul>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/motion/agent.ts

@@ -0,0 +1,288 @@
+import { applyPatch, validateConfig, type Replication2Config } from './replication2/config';
+import { outputDuration } from './replication2/engine';
+import * as PromoConfig from './promo/config';
+import { outputDuration as promoOutputDuration } from './promo/engine';
+import { LISTS as PROMO_LISTS } from './promo/controls';
+import * as PaperFoldConfig from './paperfold/config';
+import { outputDuration as paperFoldOutputDuration } from './paperfold/engine';
+import { LISTS as PAPER_FOLD_LISTS } from './paperfold/controls';
+import { durationFor } from './sample';
+import { CONFIGURABLE_MOTION_TEMPLATES, MOTION_TEMPLATES } from './templates';
+import type { ConfigurableMotionTemplate, MotionTemplate } from './types';
+import { validateMotionContent, type MotionContentError } from './validate';
+
+/**
+ * **Motion templates for agents** — pure, no React, no DOM. An agent lists templates, reads one
+ * contract, sends `{ schema: 'motion/1', template, content }`, and checks it here (the MCP server and
+ * the site's API run the same code). The motion itself is never part of what an agent sees or sends.
+ */
+export const MOTION_REQUEST_SCHEMA = 'motion/1';
+
+export const NOT_CONFIGURABLE = [
+  'animation timing', 'scene order', 'scene duration', 'frame rate', 'easing', 'motion paths', 'positions',
+  'scale', 'rotation', 'transitions', 'font family', 'font size', 'font weight', 'layout', 'canvas size',
+  'word / character limits', 'markup, CSS or script of any kind',
+];
+
+/**
+ * **What a template can be turned into, and in what format.** Said explicitly because "an animation"
+ * could mean a video file or a live element, and the two are used differently.
+ */
+export function motionOutputFormats(t: MotionTemplate) {
+  const { fps } = t.motion;
+  const canvases = (t.motion.formats ?? [{ id: 'default', aspectRatio: '', width: t.motion.width, height: t.motion.height }])
+    .map((f) => `${f.width}×${f.height}${f.aspectRatio ? ` (${f.aspectRatio})` : ''}`).join(' or ');
+  const composition = t.id.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+  return [
+    {
+      output: 'live',
+      format: 'HTML + CSS (DOM)',
+      detail: `${canvases} canvas, ${fps} fps, scalable; played in the page by the package runtime (MotionPlayer / mountMotion). Not a video file.`,
+    },
+    {
+      output: 'video',
+      format: 'MP4 (H.264)',
+      detail: `${canvases}, ${fps} fps, rendered with Remotion from the same template source (remotion-prototype/, composition ${composition}${t.motion.formats ? '<Format>' : ''}). --scale=3 renders true 4K (2160×3840 / 3840×2160 for a 720-line canvas).`,
+    },
+    { output: 'request', format: 'JSON (motion/1)', detail: 'What a person or agent sends: { schema, template, content }.' },
+    { output: 'schema', format: 'JSON Schema 2020-12', detail: 'The content contract, with the maxWords, onlyWith and hex-color extensions.' },
+  ];
+}
+
+export type MotionRequest = { schema: typeof MOTION_REQUEST_SCHEMA; template: string; content: Record<string, unknown>; patch?: unknown };
+
+const seconds = (t: MotionTemplate, frames: number) => Math.round((frames / t.motion.fps) * 100) / 100;
+
+export function getMotionTemplate(id: string): MotionTemplate | undefined {
+  return (MOTION_TEMPLATES as Record<string, MotionTemplate>)[id];
+}
+
+/** Short cards, for choosing a template. */
+export function listMotionTemplates() {
+  return Object.values(MOTION_TEMPLATES).map((t: MotionTemplate) => ({
+    template: t.id,
+    version: t.version,
+    title: t.title,
+    description: t.description,
+    canvas: { width: t.motion.width, height: t.motion.height },
+    ...(t.motion.formats ? { aspectRatios: t.motion.formats.map((f) => f.aspectRatio) } : {}),
+    ...(t.motion.sequence ? { kind: 'sequence' as const } : {}),
+    seconds: seconds(t, t.motion.durationInFrames),
+    slots: t.slots.length,
+    formats: motionOutputFormats(t).map((f) => f.format),
+  })).concat(Object.values(CONFIGURABLE_MOTION_TEMPLATES).map((t: ConfigurableMotionTemplate) => ({
+    template: t.id,
+    version: t.version,
+    title: t.title,
+    description: t.description,
+    canvas: { width: t.formats[0]!.width, height: t.formats[0]!.height },
+    aspectRatios: t.formats.map((f) => f.aspectRatio),
+    kind: 'configurableMotion' as const,
+    renderer: t.renderer,
+    seconds: Math.round((t.durationInFrames / t.fps) * 100) / 100,
+    slots: 0,
+    controls: t.controls.length,
+    formats: configurableOutputFormats(t).map((f) => f.format),
+  })) as never[]);
+}
+
+export function getConfigurableMotionTemplate(id: string): ConfigurableMotionTemplate | undefined {
+  return (CONFIGURABLE_MOTION_TEMPLATES as Record<string, ConfigurableMotionTemplate>)[id];
+}
+
+type ConfigCheck = { valid: boolean; errors: { path: string; message: string }[]; config?: Record<string, unknown> };
+/** Each configurable template's own validator, patcher and clock — the functions behind its data. */
+const CONFIG_API: Record<string, { validate: (c: unknown) => ConfigCheck; patch: (c: unknown, p: unknown) => ConfigCheck; frames: (c: Record<string, unknown>) => number }> = {
+  'replication-2': { validate: validateConfig, patch: applyPatch as (c: unknown, p: unknown) => ConfigCheck, frames: (c) => outputDuration(c as Replication2Config) },
+  'promo-product-showcase': { validate: PromoConfig.validateConfig, patch: PromoConfig.applyPatch as (c: unknown, p: unknown) => ConfigCheck, frames: (c) => promoOutputDuration(c as PromoConfig.PromoConfig) },
+  'paper-fold-promo': { validate: PaperFoldConfig.validateConfig, patch: PaperFoldConfig.applyPatch as (c: unknown, p: unknown) => ConfigCheck, frames: (c) => paperFoldOutputDuration(c as PaperFoldConfig.PaperFoldConfig) },
+};
+/** The React web player of each procedural template. */
+const LIVE_PLAYER: Record<string, string> = { 'promo-product-showcase': 'PromoShowcasePlayer', 'paper-fold-promo': 'PaperFoldPlayer' };
+
+/** What a configurable-motion template can be turned into. */
+export function configurableOutputFormats(t: ConfigurableMotionTemplate) {
+  const canvases = t.formats.map((f) => `${f.width}×${f.height} (${f.aspectRatio})`).join(', ');
+  if (t.renderer === 'remotion') {
+    return [
+      { output: 'live', format: 'HTML + CSS (DOM)', detail: `Any size, ${t.fps} fps; drawn procedurally from the config by the package's renderer (${LIVE_PLAYER[t.id] ?? 'its player'} on the web). Not a video file.` },
+      { output: 'video', format: 'MP4 (H.264, yuv420p, bt709) / H.265 / ProRes / VP9', detail: `${canvases}, ${t.fps} fps, rendered with Remotion from the same renderer and engine (remotion-prototype/, compositions ${t.remotion!.compositions.join(' / ')}). The codec, pixel format and colour space come from the config's export group.` },
+      { output: 'request', format: 'JSON (motion/1)', detail: 'What a person or agent sends: { schema, template, content } where content is the config (any subset), optionally with patch.' },
+      { output: 'schema', format: 'JSON Schema 2020-12', detail: 'Every control and list, with type, range or options, default, unit, and x-userEditable / x-agentEditable.' },
+    ];
+  }
+  return [
+    { output: 'live', format: 'Rive (canvas)', detail: `${canvases}, ${t.fps} fps; drawn by the package's Rive driver from the config (Replication2Player on the web). Not a video file.` },
+    { output: 'video', format: 'MP4 (H.264) / ProRes', detail: `${canvases}, ${t.fps} fps, rendered with Remotion from the same Rive file and engine (remotion-prototype/, compositions ${t.id}-landscape-4k / -portrait-4k / -square-4k).` },
+    { output: 'request', format: 'JSON (motion/1)', detail: 'What a person or agent sends: { schema, template, content } where content is the config (any subset), optionally with patch.' },
+    { output: 'schema', format: 'JSON Schema 2020-12', detail: 'Every control, with type, range or options, default, unit, and x-userEditable / x-agentEditable.' },
+    { output: 'html', format: 'HTML host (manifest + config + .riv)', detail: 'replication-2-prototype/dist/replication-2/: index.html reads config.json and draws with the Rive runtime.' },
+  ];
+}
+
+/* Example patches an agent reads: their colours are config content, not UI colours. */
+const EXAMPLE_PATCHES: Record<string, Record<string, unknown>> = {
+  'replication-2': { 'text.what': 'Why', 'glow.intensity': 0.9, 'scenes.what.durationFrames': 42 },
+  // eslint-disable-next-line comppack/no-raw-colour -- a config value in an example request
+  'promo-product-showcase': { 'content.title': 'Launch faster.', 'background.gradient.stops.1.color': '#6a7cff', 'productEntrance.durationFrames': 60, 'content.cta.enabled': false },
+  // eslint-disable-next-line comppack/no-raw-colour -- a config value in an example request
+  'paper-fold-promo': { 'content.top.headline': 'Summer events are here', 'paperMaterial.baseColor': '#ff7a18', 'folds.top.peakAngle': 170, 'folds.0.durationFrames': 72, 'hands.top.x': 0.56, 'background.backgroundTypography.enabled': false, 'content.cta.text': 'Join the beta' },
+};
+
+/** The contract of a configurable-motion template, grouped for choosing what to change. */
+function describeConfigurable(t: ConfigurableMotionTemplate) {
+  const promo = t.id === 'promo-product-showcase';
+  const paper = t.id === 'paper-fold-promo';
+  return {
+    template: t.id,
+    version: t.version,
+    kind: t.kind,
+    renderer: t.renderer,
+    title: t.title,
+    description: t.description,
+    request: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: '<object: any subset of the config below>', patch: '<optional: { "patch": { "<control path>": value } } or [{ op: replace|merge|remove, path, value }]>' },
+    output: {
+      width: t.formats[0]!.width, height: t.formats[0]!.height, fps: t.fps, durationInFrames: t.durationInFrames,
+      seconds: Math.round((t.durationInFrames / t.fps) * 100) / 100, formats: configurableOutputFormats(t),
+    },
+    rules: [
+      'People and agents edit the same config: change values, never code.',
+      'Every value is one of the controls below: a typed property with a range or an approved option. Unknown keys are refused.',
+      'Timing is in 60 fps motion frames; canvas.fps is the output sampling rate.',
+      'No JavaScript, CSS, HTML, SVG, shader or animation code of any kind can be set.',
+      ...(promo ? [
+        'Lists (controls whose path has "[]") are arrays: address an item by index ("productContent.cards.1.title"), add one at index = length, delete one with { op: "remove", path: "productContent.cards.2" }, or replace the whole array.',
+        'Assets are references only: "static:<file>", "https://…" or a PNG/JPEG/WebP data: URL. "" draws a procedural placeholder.',
+        'Each aspect ratio reads its own layout block (layout.landscape / portrait / square); productWindow.x/y/width/height place the window inside that slot.',
+      ] : []),
+      ...(paper ? [
+        'folds and creases are fixed two-item lists (top, then bottom): address an item by index ("folds.0.peakAngle") or by its id ("folds.top.peakAngle").',
+        'A fold turns about its crease (creases.<id>.position): direction says which side swings (down = the part above, up = the part below), side says toward the viewer (inward) or behind (outward). Angles are the crease\'s dihedral: 0 flat, 180 folded flat.',
+        'Timing is the phase order INTRO → TOP_FOLD → BOTTOM_FOLD → FOLDED_HOLD → BOTTOM_UNFOLD → TOP_UNFOLD → FINAL_HOLD; a fold phase takes its delay, length and easing from its fold (folds.<id>.durationFrames, unfoldDurationFrames, …).',
+        'Hands are attached to a point of the paper (hands.<id>.x / y, 0‥1 across and down the sheet) and follow it through the folds; handInteraction sets how.',
+        'Each aspect ratio reads its own layout block (layout.portrait / landscape / square). Text on the paper is sized in paper units (1/1000 of the sheet width), so it keeps its place on the sheet in every layout.',
+        'Copy may contain line breaks (\\n); it is always rendered as text.',
+      ] : []),
+    ],
+    controls: Object.fromEntries(t.groups.map((g) => [g, Object.fromEntries(t.controls.filter((c) => c.group === g).map((c) => [c.path, {
+      type: c.type, default: c.default, ...(c.min !== undefined ? { min: c.min, max: c.max } : {}), ...(c.options ? { options: c.options } : {}),
+      ...(c.maxLength !== undefined ? { maxLength: c.maxLength } : {}), ...(c.unit ? { unit: c.unit } : {}), ...(c.allow ? { allow: c.allow } : {}),
+      description: c.description, userEditable: c.userEditable, agentEditable: c.agentEditable,
+    }]))])),
+    ...(promo ? { lists: Object.fromEntries(PROMO_LISTS.map((l) => [l.path, { minItems: l.minItems, maxItems: l.maxItems, description: l.description, default: l.default }])) } : {}),
+    ...(paper ? { lists: Object.fromEntries(PAPER_FOLD_LISTS.map((l) => [l.path, { minItems: l.minItems, maxItems: l.maxItems, description: l.description, default: l.default, ...(l.keys ? { keys: l.keys } : {}) }])) } : {}),
+    presets: Object.fromEntries(Object.entries(t.presets).map(([k, v]) => [k, v.description])),
+    notConfigurable: promo
+      ? ['markup, CSS, SVG, shaders or script of any kind', 'typefaces outside the registered five', 'icons outside the registered set', 'the phase order (intro → productEntrance → productSettle → contentReveal → showcase → outro; delays may overlap them)']
+      : paper
+        ? ['markup, CSS, SVG, shaders or script of any kind', 'the number of panels (three) and creases (two)', 'typefaces outside the registered five', 'the hand drawings (their pose, size, colours and motion are configurable)', 'the phase order (delays may overlap phases, never reorder them)', 'the debug overlay (a development flag of the renderer, never part of the config)']
+        : ['markup, CSS, SVG, shaders or script of any kind', 'fonts that are not embedded in the Rive file', 'scene order (each scene builds on the one before; scenes can be switched off)'],
+    example: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: {}, patch: { patch: EXAMPLE_PATCHES[t.id] ?? {} } },
+    schema: t.schema,
+  };
+}
+
+/** The content contract of one template: every slot and limit, the theme tokens, optional scenes. */
+export function describeMotionTemplate(id: string) {
+  const configurable = getConfigurableMotionTemplate(id);
+  if (configurable) return describeConfigurable(configurable) as unknown as ReturnType<typeof describeDom>;
+  return describeDom(id);
+}
+
+function describeDom(id: string) {
+  const t = getMotionTemplate(id);
+  if (!t) return undefined;
+  const withoutOptional = Object.fromEntries(Object.entries(t.exampleContent).filter(([k]) => !t.optionalScenes.includes(k)));
+  return {
+    template: t.id,
+    version: t.version,
+    title: t.title,
+    description: t.description,
+    request: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: '<object: the slots below, plus optional theme>' },
+    output: {
+      width: t.motion.width,
+      height: t.motion.height,
+      fps: t.motion.fps,
+      durationInFrames: t.motion.durationInFrames,
+      seconds: seconds(t, t.motion.durationInFrames),
+      secondsWithoutOptionalScenes: seconds(t, durationFor(t.motion, withoutOptional)),
+      formats: motionOutputFormats(t),
+    },
+    slots: Object.fromEntries(t.slots.map((s) => [s.path, {
+      type: 'string', maxWords: s.maxWords, maxChars: s.maxChars, description: s.description,
+      ...(s.optional ? { optional: true } : {}), ...(s.onlyWith ? { onlyWith: s.onlyWith } : {}),
+      autoFit: 'text wider than the slot is scaled down, never wrapped',
+    }])),
+    theme: Object.fromEntries(t.theme.map((c) => [`theme.${c.token}`, { type: 'hex colour', default: c.default, description: c.description }])),
+    optionalScenes: t.optionalScenes.map((id) => ({ scene: id, effect: `leave "${id}" out of content (or set it to null) to ${t.motion.sequence ? 'hide it' : 'end the video before it'}` })),
+    ...(t.motion.formats ? { aspectRatio: { field: 'aspectRatio', values: t.motion.formats.map((f) => ({ value: f.aspectRatio, width: f.width, height: f.height })), default: t.motion.formats[0]!.aspectRatio, effect: 'the same animation, laid out for that canvas' } } : {}),
+    ...(t.motion.sequence ? { sequence: describeSequence(t) } : {}),
+    notConfigurable: NOT_CONFIGURABLE,
+    example: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: t.exampleContent },
+    schema: t.schema,
+  };
+}
+
+/** A sequence template, for an agent: the list, its limits, each item's choices, and its rhythm. */
+function describeSequence(t: MotionTemplate) {
+  const seq = t.motion.sequence!;
+  return {
+    list: seq.path,
+    minItems: seq.minItems,
+    maxItems: seq.maxItems,
+    item: `each item is one scene: its text slots (${t.slots.filter((s) => s.path.startsWith(`${seq.path}[]`)).map((s) => s.path.split('.').pop()).join(', ')}) plus the choices below`,
+    choices: Object.fromEntries((t.choices ?? []).map((c) => [c.field, { default: c.default, description: c.description, values: Object.fromEntries(c.values.map((v) => [v.value, v.description])) }])),
+    timing: `fixed by the template: item i lasts rhythm[i] frames at ${t.motion.fps} fps (the last value repeats), or longer when its transition needs it. More items make a longer video; nothing makes one item slower or faster.`,
+    rhythm: seq.rhythm,
+  };
+}
+
+/** Check a request before rendering it. Never throws. */
+export function validateMotionRequest(request: unknown): { valid: true; request: MotionRequest; seconds: number } | { valid: false; errors: MotionContentError[] } {
+  const bad = (path: string, message: string) => ({ valid: false as const, errors: [{ scene: '(request)', path, message }] });
+  if (typeof request !== 'object' || request === null || Array.isArray(request)) return bad('', 'The request must be an object: { schema: "motion/1", template, content }.');
+  const { schema, template, content, patch, ...extra } = request as Record<string, unknown>;
+  const configurable = typeof template === 'string' ? getConfigurableMotionTemplate(template) : undefined;
+  if (patch !== undefined && !configurable) extra.patch = patch;
+  if (Object.keys(extra).length) return bad(Object.keys(extra)[0]!, `Only schema, template and content may be sent${configurable ? ' (and patch)' : ''}; got ${Object.keys(extra).join(', ')}.`);
+  if (schema !== undefined && schema !== MOTION_REQUEST_SCHEMA) return bad('schema', `schema must be "${MOTION_REQUEST_SCHEMA}".`);
+  if (configurable) return validateConfigurableRequest(configurable, content, patch);
+  const t = typeof template === 'string' ? getMotionTemplate(template) : undefined;
+  if (!t) return bad('template', `Unknown template "${String(template)}". Available: ${[...Object.keys(MOTION_TEMPLATES), ...Object.keys(CONFIGURABLE_MOTION_TEMPLATES)].join(', ')}.`);
+  const checked = validateMotionContent(t.schema, content);
+  if (!checked.valid) return { valid: false, errors: checked.errors };
+  return { valid: true, request: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: content as Record<string, unknown> }, seconds: seconds(t, durationFor(t.motion, content)) };
+}
+
+/** A configurable-motion request: the content (a config, any subset) with the patch applied, validated. */
+function validateConfigurableRequest(t: ConfigurableMotionTemplate, content: unknown, patch: unknown): { valid: true; request: MotionRequest; seconds: number } | { valid: false; errors: MotionContentError[] } {
+  const api = CONFIG_API[t.id]!;
+  const base = content === undefined ? {} : content;
+  const checked = patch === undefined ? api.validate(base) : api.patch(base, patch);
+  if (!checked.valid) return { valid: false as const, errors: checked.errors.map((e) => ({ scene: e.path.split('.')[0] || '(root)', path: e.path, message: e.message })) };
+  const config = checked.config as Record<string, unknown>;
+  return {
+    valid: true as const,
+    request: { schema: MOTION_REQUEST_SCHEMA, template: t.id, content: config } as MotionRequest,
+    seconds: Math.round((api.frames(config) / Number((config.canvas as { fps: number }).fps)) * 100) / 100,
+  };
+}
+
+/** A link that plays the request on the template's own page of the CompPack site (`/animations/<id>`). */
+export function motionPreviewUrl(request: MotionRequest, origin = 'https://comppack.vercel.app') {
+  const json = JSON.stringify({ template: request.template, content: request.content });
+  const b64 = btoa(String.fromCharCode(...new TextEncoder().encode(json)));
+  return `${origin.replace(/\/+$/, '')}/animations/${encodeURIComponent(request.template)}?request=${b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`;
+}
+
+/** Inverse of `motionPreviewUrl`'s parameter. Returns undefined if it is not valid base64url JSON. */
+export function decodeMotionPreview(param: string): { template: string; content: unknown } | undefined {
+  try {
+    const b64 = param.replace(/-/g, '+').replace(/_/g, '/');
+    const json = new TextDecoder().decode(Uint8Array.from(atob(b64), (ch) => ch.charCodeAt(0)));
+    const v = JSON.parse(json);
+    return v && typeof v === 'object' ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/motion/cat/Cat.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+import { useEffect, useRef, useState, type ReactNode, type Ref, type SVGProps } from 'react';
+import { CAT_CREDIT, CAT_VIEWBOX, TAIL_BONES } from './art.generated';
+import { buildAnimationDocument, catPose, type CatAnimationDocument } from './animation';
+import { resolveCatConfig, type CatConfigInput } from './config';
+import { posedJoints, pathD } from './rig';
+import { catScene, matrixAttr, tailMatrix, type SceneNode } from './scene';
+
+export type CatProps = Omit<SVGProps<SVGSVGElement>, 'children' | 'viewBox' | 'ref'> & {
+  /** The root <svg> element (for pointer maths: getScreenCTM). */
+  svgRef?: Ref<SVGSVGElement>;
+  /** The manipulation model (any subset; the rest are defaults). */
+  config?: CatConfigInput;
+  /** The clock, in ms. The caller owns time — Remotion passes frame / fps × 1000 — so a frame is a pure function of it. */
+  timeMs?: number;
+  /** An animation model to play instead of the one the config builds (e.g. an exported JSON). */
+  animation?: CatAnimationDocument;
+  /** Shorthands over `config.tail` / `config.color` / `config.background`. */
+  tailWiggle?: boolean;
+  tailWiggleAmount?: number;
+  tailWiggleDuration?: number;
+  tailWiggleSpeed?: number;
+  color?: string;
+  background?: string | null;
+  /** Prepended to every element id, so several cats can share a page. */
+  idPrefix?: string;
+  /** Draw the tail's bones and joints over the art. */
+  debug?: boolean;
+  /** Drawn inside the SVG after the cat, in artboard coordinates (the editor's handles). */
+  children?: ReactNode;
+};
+
+function renderNode(node: SceneNode, prefix: string): ReactNode {
+  if (node.kind === 'path') return <path key={node.id} id={prefix + node.id} data-part={node.id} fill={node.fill} d={pathD(node.commands)} />;
+  return (
+    <g key={node.id} id={prefix + node.id} data-part={node.id} fill={node.fill} transform={node.transform ? matrixAttr(node.transform) : undefined}>
+      {node.children.map((c) => renderNode(c, prefix))}
+    </g>
+  );
+}
+
+/**
+ * **The cat, as a live SVG.** Every part is a real element with a semantic id (`cat-tail`,
+ * `cat-head`, `cat-eye-left`, …); the tail's outline is re-skinned from its bones each render. Pure:
+ * the same props and `timeMs` always draw the same frame, which is what Remotion needs.
+ *
+ *   <Cat tailWiggle tailWiggleAmount={12} tailWiggleDuration={1500} timeMs={frame / fps * 1000} />
+ */
+export function Cat({
+  config: input, timeMs = 0, animation, tailWiggle, tailWiggleAmount, tailWiggleDuration, tailWiggleSpeed, color, background,
+  idPrefix = '', debug = false, children, svgRef, ...svg
+}: CatProps) {
+  /* No hooks on purpose: <Cat> is a pure function of its props, so it renders the same under any React
+     copy (Remotion's bundle imports it from outside its own node_modules) and in a server render. */
+  const base = resolveCatConfig(input);
+  const config = {
+    ...base,
+    color: color ?? base.color,
+    background: background === undefined ? base.background : background,
+    tail: {
+      ...base.tail,
+      wiggle: tailWiggle ?? base.tail.wiggle,
+      amount: tailWiggleAmount ?? base.tail.amount,
+      duration: tailWiggleDuration ?? base.tail.duration,
+      speed: tailWiggleSpeed ?? base.tail.speed,
+    },
+  };
+  const doc = animation ?? buildAnimationDocument(config);
+  const pose = catPose(config, timeMs, doc);
+  const scene = catScene(config, pose);
+  const { x, y, width, height } = CAT_VIEWBOX;
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox={`${x} ${y} ${width} ${height}`} role="img" aria-label="Cat" ref={svgRef} {...svg}>
+      <title>{`Cat. ${CAT_CREDIT}`}</title>
+      {config.background ? <rect x={x} y={y} width={width} height={height} fill={config.background} /> : null}
+      {renderNode(scene, idPrefix)}
+      {debug && pose.tail.visible ? <TailBones pose={pose} /> : null}
+      {children}
+    </svg>
+  );
+}
+
+/** The bone chain drawn over the tail: joints as dots, bones as lines. */
+function TailBones({ pose }: { pose: ReturnType<typeof catPose> }) {
+  const m = tailMatrix(pose.tail);
+  const joints = posedJoints(pose.tail.bones);
+  return (
+    <g data-part="cat-tail-rig" transform={matrixAttr(m)} pointerEvents="none">
+      <polyline points={joints.map((j) => j.join(',')).join(' ')} fill="none" stroke="currentColor" strokeWidth={10} strokeDasharray="28 18" opacity={0.7} />
+      {joints.map(([jx, jy], i) => <circle key={i} cx={jx} cy={jy} r={i < TAIL_BONES.length ? 26 : 16} fill="currentColor" opacity={0.85} />)}
+    </g>
+  );
+}
+
+export type CatPlayerProps = Omit<CatProps, 'timeMs'> & { playing?: boolean };
+
+/**
+ * **A realtime player for the web** — `<Cat>` driven by requestAnimationFrame. For pages only; a
+ * Remotion composition passes its frame to `<Cat timeMs>` instead.
+ */
+export function CatPlayer({ playing = true, ...props }: CatPlayerProps) {
+  const [t, setT] = useState(0);
+  const start = useRef<number | null>(null);
+  useEffect(() => {
+    if (!playing) { start.current = null; return; }
+    let raf = 0;
+    const tick = (now: number) => {
+      if (start.current === null) start.current = now - t;
+      setT(now - start.current);
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+    /* Resumes from the current time only when `playing` toggles. */
+  }, [playing]);
+  return <Cat {...props} timeMs={t} />;
+}