@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/cat/scene.ts

@@ -0,0 +1,181 @@
+import { BODY_D, CAT_CREDIT, CAT_VIEWBOX, DETAIL_D, HEAD_D, HEAD_PIVOT, MUZZLE_D, type DetailId, type PathCommand } from './art.generated';
+import { buildAnimationDocument, catPose, documentDuration, type CatAnimationDocument, type CatPose } from './animation';
+import type { CatConfig, PartId } from './config';
+import { IDENTITY, applyMat, mul, pathD, posedTailCommands, rotateAbout, type Mat } from './rig';
+
+/**
+ * **The scene graph** — the rig as a tree of groups and paths, built from a config and a pose. Both
+ * renderers walk this one tree: `catSvg` writes it as SVG text (static or SMIL-animated), and the React
+ * `<Cat>` renders it as elements. The hierarchy:
+ *
+ *   cat                       whole-cat transform, fur colour
+ *   └─ cat-body               body offset; carries the tail and head
+ *      ├─ cat-tail            the tail's own transform  → cat-tail-shape (the skinned outline)
+ *      ├─ cat-body-shape      body and legs (one contour in the source)
+ *      ├─ cat-legs            the white leg lines
+ *      └─ cat-head            head rotation about the neck
+ *         ├─ cat-muzzle       the white under the nose and mouth cut-outs
+ *         ├─ cat-head-shape   head and ears
+ *         ├─ cat-ears         the white ear lines
+ *         └─ cat-eyes         eyes and brow
+ */
+export type SceneNode =
+  | { kind: 'g'; id: string; transform?: Mat; fill?: string; children: SceneNode[] }
+  | { kind: 'path'; id: string; commands: PathCommand[]; fill?: string };
+
+const cache = new Map<string, PathCommand[]>();
+/** Parse the generated path data (absolute M / L / C / Z only). */
+export function parseD(d: string): PathCommand[] {
+  const hit = cache.get(d);
+  if (hit) return hit;
+  const out: PathCommand[] = [];
+  /* An exec loop, not matchAll: older mobile browsers (Safari before 13) lack matchAll. */
+  const re = /([MLCZ])([^MLCZ]*)/g;
+  for (let m = re.exec(d); m; m = re.exec(d)) {
+    const n = m[2]!.trim() ? m[2]!.trim().split(/[\s,]+/).map(Number) : [];
+    out.push([m[1], ...n] as PathCommand);
+  }
+  cache.set(d, out);
+  return out;
+}
+
+export const VIEW_CENTRE: [number, number] = [CAT_VIEWBOX.x + CAT_VIEWBOX.width / 2, CAT_VIEWBOX.y + CAT_VIEWBOX.height / 2];
+const translate = (x: number, y: number): Mat => [1, 0, 0, 1, x, y];
+const scaleAbout = (s: number, cx: number, cy: number): Mat => [s, 0, 0, s, cx - s * cx, cy - s * cy];
+const isIdentity = (m: Mat) => m.every((v, i) => Math.abs(v - IDENTITY[i]!) < 1e-9);
+
+/** The tail group's transform: move, then turn and scale about the origin. */
+export const tailMatrix = (t: CatPose['tail']): Mat =>
+  mul(translate(t.x, t.y), mul(rotateAbout(t.rotate, t.origin.x, t.origin.y), scaleAbout(t.scale, t.origin.x, t.origin.y)));
+export const catMatrix = (t: CatPose['transform']): Mat =>
+  mul(translate(t.x, t.y), mul(rotateAbout(t.rotate, ...VIEW_CENTRE), scaleAbout(t.scale, ...VIEW_CENTRE)));
+export const bodyMatrix = (b: CatPose['body']): Mat => translate(b.x, b.y);
+export const headMatrix = (h: CatPose['head']): Mat => rotateAbout(h.rotate, HEAD_PIVOT[0], HEAD_PIVOT[1]);
+
+export function catScene(config: CatConfig, pose: CatPose): SceneNode {
+  const part = (id: PartId) => config.parts[id] ?? {};
+  const shown = (id: PartId) => part(id).visible !== false;
+  const withMat = (m: Mat) => (isIdentity(m) ? undefined : m);
+  const path = (id: string, d: string | PathCommand[], fill?: string): SceneNode => ({
+    kind: 'path', id, commands: typeof d === 'string' ? parseD(d) : d, fill: part(id as PartId).fill ?? fill,
+  });
+  const details = (id: PartId, ids: DetailId[]): SceneNode[] =>
+    shown(id) ? [{ kind: 'g', id, fill: part(id).fill ?? config.detailColor, children: ids.filter((d) => shown(d as PartId)).map((d) => path(d, DETAIL_D[d])) }] : [];
+
+  const children: SceneNode[] = [];
+  if (pose.tail.visible && shown('cat-tail')) {
+    children.push({ kind: 'g', id: 'cat-tail', transform: withMat(tailMatrix(pose.tail)), fill: part('cat-tail').fill, children: [path('cat-tail-shape', posedTailCommands(pose.tail.bones))] });
+  }
+  if (shown('cat-body-shape')) children.push(path('cat-body-shape', BODY_D));
+  children.push(...details('cat-legs', ['cat-leg-front-line', 'cat-leg-rear-line']));
+  if (shown('cat-head')) {
+    children.push({
+      kind: 'g', id: 'cat-head', transform: withMat(headMatrix(pose.head)), fill: part('cat-head').fill,
+      children: [
+        ...(shown('cat-muzzle') ? [path('cat-muzzle', MUZZLE_D, config.detailColor)] : []),
+        ...(shown('cat-head-shape') ? [path('cat-head-shape', HEAD_D)] : []),
+        ...details('cat-ears', ['cat-ear-left-inner', 'cat-ear-right-inner', 'cat-ear-right-edge']),
+        ...details('cat-eyes', ['cat-eye-left', 'cat-eye-right', 'cat-brow-right']),
+      ],
+    });
+  }
+  return {
+    kind: 'g', id: 'cat', transform: withMat(catMatrix(pose.transform)), fill: config.color,
+    children: [{ kind: 'g', id: 'cat-body', transform: withMat(bodyMatrix(pose.body)), children }],
+  };
+}
+
+/* ---------- SVG text ---------- */
+const num = (v: number) => String(Math.round(v * 1000) / 1000);
+export const matrixAttr = (m: Mat) => `matrix(${m.map(num).join(' ')})`;
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const transformCommands = (m: Mat, cmds: PathCommand[]): PathCommand[] =>
+  cmds.map((c): PathCommand => {
+    if (c[0] === 'Z') return c;
+    const pts: number[] = [];
+    for (let i = 1; i < c.length; i += 2) pts.push(...applyMat(m, c[i] as number, c[i + 1] as number));
+    return [c[0], ...pts] as PathCommand;
+  });
+
+function nodeSvg(node: SceneNode, prefix: string, animatedD?: Map<string, string>): string {
+  const fill = node.fill ? ` fill="${esc(node.fill)}"` : '';
+  if (node.kind === 'path') {
+    const extra = animatedD?.get(node.id) ?? '';
+    return extra ? `<path id="${prefix}${node.id}"${fill}>${extra}</path>` : `<path id="${prefix}${node.id}"${fill} d="${pathD(node.commands)}"/>`;
+  }
+  const t = node.transform ? ` transform="${matrixAttr(node.transform)}"` : '';
+  return `<g id="${prefix}${node.id}"${fill}${t}>${node.children.map((c) => nodeSvg(c, prefix, animatedD)).join('')}</g>`;
+}
+
+/** Every path of a scene with its transform baked in (the groups' matrices applied to its points). */
+function flatPaths(node: SceneNode, parent: Mat = IDENTITY, out = new Map<string, PathCommand[]>()) {
+  if (node.kind === 'path') out.set(node.id, transformCommands(parent, node.commands));
+  else {
+    const m = node.transform ? mul(parent, node.transform) : parent;
+    node.children.forEach((c) => flatPaths(c, m, out));
+  }
+  return out;
+}
+/** A scene with every group transform removed (for the animated export, whose paths carry baked geometry). */
+function stripTransforms(node: SceneNode): SceneNode {
+  return node.kind === 'path' ? node : { ...node, transform: undefined, children: node.children.map(stripTransforms) };
+}
+
+export type CatSvgOptions = {
+  /** The pose at this time (ms) — for a static export. */
+  timeMs?: number;
+  /** Animation model to sample; defaults to the one the config builds. */
+  animation?: CatAnimationDocument;
+  /** Write a self-playing SVG (SMIL `<animate>` on each moving path) instead of one frame. */
+  animated?: boolean;
+  /** Samples per second baked into an animated SVG. */
+  fps?: number;
+  /** Prepended to every id, so several cats can share a page. */
+  idPrefix?: string;
+  width?: number;
+  height?: number;
+  /** Embed the config and animation JSON in <metadata>, so the file can be read back. Default true. */
+  metadata?: boolean;
+};
+
+/**
+ * **A standalone SVG file** of the cat: pure vector, no raster, no script. Static: the pose at
+ * `timeMs`, with the rig's groups and transforms kept (open it in any editor and the tail is still a
+ * group). Animated: every path that moves carries an `<animate attributeName="d">` sampled from the
+ * animation model at `fps`, so it plays by itself in a browser — no JavaScript.
+ */
+export function catSvg(config: CatConfig, opts: CatSvgOptions = {}): string {
+  const doc = opts.animation ?? buildAnimationDocument(config);
+  const prefix = opts.idPrefix ?? '';
+  const { x, y, width, height } = CAT_VIEWBOX;
+  const w = opts.width ?? Math.round(width / 4), h = opts.height ?? Math.round(height / 4);
+  const duration = documentDuration(doc);
+  const anims = Object.values(doc.animations);
+  let body: string;
+  if (opts.animated && duration > 0) {
+    const loop = anims.every((a) => a.loop);
+    const frames = Math.max(2, Math.round((duration / 1000) * (opts.fps ?? 60)));
+    const samples = Array.from({ length: frames + 1 }, (_, k) => flatPaths(catScene(config, catPose(config, (k * duration) / frames, doc))));
+    const animatedD = new Map<string, string>();
+    for (const id of samples[0]!.keys()) {
+      const values = samples.map((s) => pathD(s.get(id)!));
+      animatedD.set(id, values.every((v) => v === values[0])
+        ? ''
+        : `<animate attributeName="d" dur="${duration}ms" repeatCount="${loop ? 'indefinite' : '1'}" fill="freeze" calcMode="linear" values="${values.join(';')}"/>`);
+    }
+    const first = samples[0]!;
+    const scene = stripTransforms(catScene(config, catPose(config, 0, doc)));
+    const bake = (n: SceneNode): SceneNode => (n.kind === 'path' ? { ...n, commands: first.get(n.id)! } : { ...n, children: n.children.map(bake) });
+    body = nodeSvg(bake(scene), prefix, new Map([...animatedD].filter(([, v]) => v)));
+  } else {
+    body = nodeSvg(catScene(config, catPose(config, opts.timeMs ?? 0, doc)), prefix);
+  }
+  const bg = config.background ? `<rect id="${prefix}cat-background" x="${x}" y="${y}" width="${width}" height="${height}" fill="${esc(config.background)}"/>` : '';
+  const meta = opts.metadata === false ? '' : `<metadata id="${prefix}cat-rig">${esc(JSON.stringify({ config, animation: doc }))}</metadata>`;
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${x} ${y} ${width} ${height}" width="${w}" height="${h}">`,
+    `<title>Cat</title><desc>${esc(CAT_CREDIT)}</desc>${meta}`,
+    bg + body,
+    '</svg>',
+  ].join('\n') + '\n';
+}

package/src/motion/configurable/config.ts

@@ -0,0 +1,420 @@
+import type { Control, ListSpec } from './controls';
+
+/**
+ * **The canonical-config machinery of a configurable-motion template** — defaults, validation, patches,
+ * diffs and the JSON Schema, all derived from the template's control table. People (the Remotion
+ * Studio, the site editor) and agents (patches) read and write the same object through these functions.
+ *
+ * Generalized from promo-product-showcase (`../promo/config.ts`, which keeps its own copy for its scene
+ * overrides). Pure: no React, no DOM. Nothing here throws on bad input — validation returns errors.
+ */
+export type ConfigError = { path: string; message: string };
+export type Obj = Record<string, unknown>;
+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: { 'content.top.headline': '…' } }` (all replaces). */
+export type ConfigPatch = PatchOp[] | { patch: Record<string, unknown> };
+export type PatchResult<C> = { valid: true; config: C; changed: string[] } | { valid: false; errors: ConfigError[] };
+
+export const isObj = (v: unknown): v is Obj => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const clone = <T>(v: T): T => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+
+/** Read a dotted path; numeric segments index arrays (`folds.0.peakAngle`). */
+export function getPath(obj: unknown, path: string): unknown {
+  if (path === '') return obj;
+  let cur: unknown = obj;
+  for (const k of path.split('.')) {
+    if (Array.isArray(cur) && /^\d+$/.test(k)) cur = cur[Number(k)];
+    else if (isObj(cur)) cur = cur[k];
+    else return undefined;
+  }
+  return cur;
+}
+
+export function setPath(obj: Obj, path: string, value: unknown) {
+  const keys = path.split('.');
+  let cur: Obj | unknown[] = obj;
+  for (const k of keys.slice(0, -1)) {
+    const next: unknown = Array.isArray(cur) ? cur[Number(k)] : cur[k];
+    if (!isObj(next) && !Array.isArray(next)) {
+      const made = {};
+      if (Array.isArray(cur)) cur[Number(k)] = made; else cur[k] = made;
+      cur = made;
+    } else cur = next as Obj | unknown[];
+  }
+  const last = keys.at(-1)!;
+  if (Array.isArray(cur)) cur[Number(last)] = value; else cur[last] = value;
+}
+
+const HEX = /^#[0-9a-fA-F]{6}$/;
+// eslint-disable-next-line no-control-regex -- rejecting control characters is the point
+const UNSAFE_TEXT = /[\u0000-\u001f\u007f]/;
+// eslint-disable-next-line no-control-regex -- as above, but a line break is allowed in multiline text
+const UNSAFE_MULTILINE = /[\u0000-\u0009\u000b-\u001f\u007f]/;
+/**
+ * An asset is a reference, never markup: a file in the render's public folder (`static:`), an https
+ * URL, or a raster data URL. SVG (which can carry script) and every other scheme are refused.
+ */
+const ASSET = /^(static:[A-Za-z0-9._\-/]+|https:\/\/[^\s"'<>\\]+|data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+)$/;
+export function isAssetRef(v: string) {
+  return v === '' || (ASSET.test(v) && !v.includes('..'));
+}
+
+export type ConfigApiSpec<C> = {
+  /** Template id, used in messages. */
+  name: string;
+  /** The `schema` value a config may carry (`paper-fold-promo/1`). */
+  schemaId: string;
+  title: string;
+  controls: readonly Control[];
+  lists: readonly ListSpec[];
+  /** Cross-field rules, run on a complete config whose every leaf is valid. */
+  relations?: (config: C, errors: ConfigError[]) => void;
+};
+
+/** Build the config API of one template from its control table. */
+export function createConfigApi<C extends Obj>(spec: ConfigApiSpec<C>) {
+  const { name: NAME, schemaId, controls: CONTROLS, lists: LISTS } = spec;
+  const CONTROL_BY_PATH = new Map(CONTROLS.map((c) => [c.path, c]));
+  const LIST_BY_PATH = new Map(LISTS.map((l) => [l.path, l]));
+  const isPrimitive = (l: ListSpec) => l.item.length === 1 && l.item[0]!.path === '';
+
+  function defaultItem(list: ListSpec): unknown {
+    if (isPrimitive(list)) return clone(list.item[0]!.default);
+    const out: Obj = {};
+    for (const c of list.item) out[c.path] = clone(c.default);
+    return out;
+  }
+
+  /** The reference config: every control and list at its default. A fresh copy each call. */
+  function defaultConfig(): C {
+    const out: Obj = { schema: schemaId };
+    for (const c of CONTROLS) setPath(out, c.path, clone(c.default));
+    for (const l of LISTS) setPath(out, l.path, clone(l.default));
+    return out as C;
+  }
+
+  /** `folds.top.peakAngle` → `folds.0.peakAngle` for keyed lists; any other path is returned as is. */
+  function canonicalPath(path: string): string {
+    for (const l of LISTS) {
+      if (!l.keys || !path.startsWith(`${l.path}.`)) continue;
+      const [key, ...rest] = path.slice(l.path.length + 1).split('.');
+      const i = l.keys.indexOf(key!);
+      if (i >= 0) return [l.path, String(i), ...rest].join('.');
+    }
+    return path;
+  }
+
+  function checkLeaf(c: Control, p: string, v: unknown, errors: ConfigError[]) {
+    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':
+      case 'easing':
+        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 ((c.multiline ? UNSAFE_MULTILINE : UNSAFE_TEXT).test(v)) {
+          return void errors.push({ path: p, message: c.multiline ? `${p} must be plain text (line breaks are allowed; other control characters are not).` : `${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}).` });
+        return;
+      }
+      case 'asset':
+        if (typeof v !== 'string' || v.length > c.maxLength! || !isAssetRef(v)) errors.push({ path: p, message: `${p} must be an asset reference: "" (procedural), "static:<file>", "https://…" or a PNG/JPEG/WebP data: URL (got ${JSON.stringify(typeof v === 'string' ? v.slice(0, 60) : v)}).` });
+        return;
+      case 'overrides':
+        if (!isObj(v)) errors.push({ path: p, message: `${p} must be an object.` });
+    }
+  }
+
+  /** Resolve a concrete config path (with list indexes or keys) to its control. */
+  function controlAt(rawPath: string): { control: Control; list?: ListSpec; index?: number } | undefined {
+    const path = canonicalPath(rawPath);
+    const direct = CONTROL_BY_PATH.get(path);
+    if (direct) return { control: direct };
+    for (const l of LISTS) {
+      if (!path.startsWith(`${l.path}.`)) continue;
+      const [idx, ...rest] = path.slice(l.path.length + 1).split('.');
+      if (!/^\d+$/.test(idx!)) return undefined;
+      const field = rest.join('.');
+      const control = l.item.find((c) => c.path === field);
+      return control ? { control, list: l, index: Number(idx) } : undefined;
+    }
+    return undefined;
+  }
+
+  function checkList(l: ListSpec, v: unknown, errors: ConfigError[]): unknown[] | undefined {
+    const p = l.path;
+    if (!Array.isArray(v)) return void errors.push({ path: p, message: `${p} must be an array (${l.minItems}–${l.maxItems} items).` });
+    if (v.length < l.minItems || v.length > l.maxItems) errors.push({ path: p, message: l.minItems === l.maxItems ? `${p} must have exactly ${l.minItems} items (got ${v.length}).` : `${p} must have ${l.minItems}–${l.maxItems} items (got ${v.length}).` });
+    const out: unknown[] = [];
+    v.forEach((item, i) => {
+      const ip = `${p}.${i}`;
+      if (isPrimitive(l)) {
+        checkLeaf(l.item[0]!, ip, item, errors);
+        out.push(clone(item));
+        return;
+      }
+      if (!isObj(item)) return void errors.push({ path: ip, message: `${ip} must be an object.` });
+      const extra = Object.keys(item).filter((k) => !l.item.some((c) => c.path === k));
+      for (const k of extra) errors.push({ path: `${ip}.${k}`, message: `${ip}.${k} is not a field of ${p} items (fields: ${l.item.map((c) => c.path).join(', ')}). No code, CSS, SVG, HTML or shader can be set.` });
+      const merged = (l.keys && l.default[i] ? clone(l.default[i]) : defaultItem(l)) as Obj;
+      for (const c of l.item) {
+        if (item[c.path] === undefined) continue;
+        const before = errors.length;
+        checkLeaf(c, `${ip}.${c.path}`, item[c.path], errors);
+        if (errors.length === before) merged[c.path] = clone(item[c.path]);
+      }
+      out.push(merged);
+    });
+    if (l.keys && l.keyField) {
+      out.forEach((item, i) => {
+        const key = (item as Obj)[l.keyField!];
+        if (key !== l.keys![i]) errors.push({ path: `${p}.${i}.${l.keyField}`, message: `${p}.${i}.${l.keyField} must be "${l.keys![i]}": ${p} always lists ${l.keys!.map((k) => `"${k}"`).join(', ')} in that order.` });
+      });
+    }
+    return out;
+  }
+
+  const isGroupPath = (path: string) => CONTROLS.some((c) => c.path.startsWith(`${path}.`)) || LISTS.some((l) => l.path.startsWith(`${path}.`));
+
+  /** Keys in `value` that no control, list 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;
+      if (CONTROL_BY_PATH.has(path) || LIST_BY_PATH.has(path)) continue;
+      if (!isGroupPath(path)) 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.
+   */
+  function validateConfig(input: unknown): { valid: boolean; errors: ConfigError[]; config?: C } {
+    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 !== schemaId) errors.push({ path: 'schema', message: `schema must be "${schemaId}" (got ${JSON.stringify(input.schema)}).` });
+    for (const path of unknownKeys(input)) {
+      errors.push({ path, message: `${path} is not a ${NAME} 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, c.path, v, errors);
+      if (errors.length === before) setPath(merged, c.path, clone(v));
+    }
+    for (const l of LISTS) {
+      const v = getPath(input, l.path);
+      if (v === undefined) continue;
+      const items = checkList(l, v, errors);
+      if (items) setPath(merged, l.path, items);
+    }
+    if (!errors.length) spec.relations?.(merged as C, errors);
+    return errors.length ? { valid: false, errors } : { valid: true, errors, config: merged as C };
+  }
+
+  /** A path to one list item: `<list>.<index>` or `<list>.<key>`. */
+  function listItemAt(rawPath: string): { list: ListSpec; index: number } | undefined {
+    const path = canonicalPath(rawPath);
+    for (const l of LISTS) {
+      const m = path.startsWith(`${l.path}.`) ? /^(\d+)$/.exec(path.slice(l.path.length + 1)) : null;
+      if (m) return { list: l, index: Number(m[1]) };
+    }
+    return undefined;
+  }
+
+  /**
+   * Apply a patch and validate the result. The input is never modified. Nothing is applied unless
+   * every operation is well formed and the result is valid.
+   */
+  function applyPatch(config: unknown, patch: unknown): PatchResult<C> {
+    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 replace = (rawPath: string, value: unknown): string | undefined => {
+      const path = canonicalPath(rawPath);
+      if (CONTROL_BY_PATH.has(path) || LIST_BY_PATH.has(path)) { setPath(next, path, clone(value)); return; }
+      const item = listItemAt(path);
+      if (item) {
+        const arr = getPath(next, item.list.path) as unknown[];
+        if (item.index > arr.length) return `${rawPath}: ${item.list.path} has ${arr.length} items; use index ${arr.length} to add one.`;
+        arr[item.index] = isPrimitive(item.list) ? clone(value) : isObj(value) ? { ...(defaultItem(item.list) as Obj), ...clone(value) } : value;
+        return;
+      }
+      const hit = controlAt(path);
+      if (hit?.list) {
+        const arr = getPath(next, hit.list.path) as Obj[];
+        if (hit.index! >= arr.length) {
+          if (hit.index! > arr.length) return `${rawPath}: ${hit.list.path} has ${arr.length} items; use index ${arr.length} to add one.`;
+          arr.push(defaultItem(hit.list) as Obj);
+        }
+        setPath(next, path, clone(value));
+        return;
+      }
+      return `${rawPath} is not a ${NAME} control${isGroupPath(path) ? ' (it is a group: use "merge")' : ''}.`;
+    };
+    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') {
+        const err = replace(o.path, o.value);
+        if (err) errors.push({ path: o.path, message: err }); else changed.push(canonicalPath(o.path));
+      } else if (o.op === 'merge') {
+        if (!isObj(o.value)) return void errors.push({ path: o.path, message: 'merge needs an object value.' });
+        const path = canonicalPath(o.path);
+        if (!isGroupPath(path) && !listItemAt(path)) return void errors.push({ path: o.path, message: `merge needs a group path (such as "content.top") or a list item (such as "folds.0").` });
+        const walk = (value: Obj, prefix: string) => {
+          for (const [k, v] of Object.entries(value)) {
+            const p = `${prefix}.${k}`;
+            if (isObj(v) && !controlAt(p) && isGroupPath(canonicalPath(p))) { walk(v, p); continue; }
+            const err = replace(p, v);
+            if (err) errors.push({ path: p, message: err }); else changed.push(canonicalPath(p));
+          }
+        };
+        walk(o.value, path);
+      } else if (o.op === 'remove') {
+        const path = canonicalPath(o.path);
+        const item = listItemAt(path);
+        if (item) {
+          const arr = getPath(next, item.list.path) as unknown[];
+          if (item.index >= arr.length) return void errors.push({ path: o.path, message: `${o.path}: there is no item ${item.index} in ${item.list.path}.` });
+          if (item.list.keys) {
+            // A keyed list keeps its items: removing one resets it to its default.
+            arr[item.index] = clone(item.list.default[item.index]);
+          } else arr.splice(item.index, 1);
+          changed.push(path);
+          return;
+        }
+        const itemField = controlAt(path);
+        if (itemField?.list) {
+          const arr = getPath(next, itemField.list.path) as Obj[];
+          const def = (itemField.list.keys ? itemField.list.default[itemField.index!] : defaultItem(itemField.list)) as Obj;
+          if (arr[itemField.index!]) { arr[itemField.index!]![itemField.control.path] = clone(def[itemField.control.path]); changed.push(path); }
+          return;
+        }
+        const hits = CONTROLS.filter((c) => c.path === path || c.path.startsWith(`${path}.`));
+        const lists = LISTS.filter((l) => l.path === path || l.path.startsWith(`${path}.`));
+        if (!hits.length && !lists.length) return void errors.push({ path: o.path, message: `${o.path} is not a ${NAME} control, list or group.` });
+        for (const c of hits) { setPath(next, c.path, clone(c.default)); changed.push(c.path); }
+        for (const l of lists) { setPath(next, l.path, clone(l.default)); changed.push(l.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). Lists that change length are replaced whole. */
+  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);
+    }
+    for (const l of LISTS) {
+      const a = getPath(from, l.path) ?? l.default, b = getPath(to, l.path) ?? l.default;
+      if (JSON.stringify(a) === JSON.stringify(b)) continue;
+      const aa = a as unknown[], bb = b as unknown[];
+      if (aa.length !== bb.length || isPrimitive(l)) { patch[l.path] = clone(b); continue; }
+      bb.forEach((item, i) => {
+        for (const c of l.item) {
+          const x = (aa[i] as Obj)[c.path], y = (item as Obj)[c.path];
+          if (JSON.stringify(x) !== JSON.stringify(y)) patch[`${l.path}.${i}.${c.path}`] = clone(y);
+        }
+      });
+    }
+    return { patch };
+  }
+
+  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 'easing': return { enum: [...c.options!], ...meta };
+      case 'text': return { type: 'string', minLength: c.minLength ?? 0, maxLength: c.maxLength, pattern: c.multiline ? '^[^\\u0000-\\u0009\\u000b-\\u001f\\u007f]*$' : '^[^\\u0000-\\u001f\\u007f]*$', ...(c.multiline ? { 'x-multiline': true } : {}), ...meta };
+      case 'asset': return { type: 'string', maxLength: c.maxLength, pattern: ASSET.source.replace(/^\^\(/, '^$|^(').replace(/\)\$$/, ')$'), 'x-asset': true, ...meta };
+      case 'overrides': return { type: 'object', ...meta };
+    }
+  }
+
+  function listSchema(l: ListSpec): Obj {
+    const items = isPrimitive(l) ? leafSchema(l.item[0]!) : {
+      type: 'object', additionalProperties: false,
+      properties: Object.fromEntries(l.item.map((c) => [c.path, leafSchema(c)])),
+    };
+    return {
+      type: 'array', minItems: l.minItems, maxItems: l.maxItems, items, default: l.default, description: l.description, 'x-group': l.group,
+      ...(l.keys ? { 'x-keys': l.keys, 'x-keyField': l.keyField } : {}),
+    };
+  }
+
+  /** JSON Schema 2020-12 of the whole config. Every property is optional (defaults fill the gaps). */
+  function configJsonSchema(): Obj {
+    const root: Obj = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: `https://comppack.vercel.app/schemas/${NAME}.json`,
+      title: spec.title,
+      description: `The one canonical configuration of the ${NAME} configurable-motion template. People and agents edit the same object; only these values exist.`,
+      type: 'object', additionalProperties: false,
+      properties: { schema: { const: schemaId } },
+    };
+    const place = (path: string, schema: Obj) => {
+      let node = root;
+      const keys = 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)!] = schema;
+    };
+    for (const c of CONTROLS) place(c.path, leafSchema(c));
+    for (const l of LISTS) place(l.path, listSchema(l));
+    return root;
+  }
+
+  return {
+    CONTROL_BY_PATH, LIST_BY_PATH, getPath, defaultItem, defaultConfig, canonicalPath, controlAt,
+    validateConfig, applyPatch, diffConfig, configJsonSchema,
+  };
+}