@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/promo/config.ts

@@ -0,0 +1,479 @@
+import {
+  CONTROLS, CONTROL_BY_PATH, EASING_NAMES, LISTS, LIST_BY_PATH, OVERRIDE_SCOPES, PHASES, type AspectRatio, type Control, type ListSpec,
+} from './controls';
+
+/**
+ * **The canonical configuration** of promo-product-showcase — one nested JSON object built from the
+ * control table. People (the Studio, the site editor) and agents (patches) 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 = 'promo-product-showcase/1';
+
+export type PromoConfig = { 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);
+const clone = <T>(v: T): T => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+const NAME = 'promo-product-showcase';
+
+/** Read a dotted path; numeric segments index arrays (`productContent.cards.0.title`). */
+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;
+}
+
+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;
+}
+
+/** A new item for a list: every item control at its default. */
+export function defaultItem(list: ListSpec): unknown {
+  const only = list.item[0]!;
+  if (list.item.length === 1 && only.path === '') return clone(only.default);
+  const out: Obj = {};
+  for (const c of list.item) out[c.path] = clone(c.default);
+  return out;
+}
+
+/** The reference preset: every control and list at its default. A fresh copy each call. */
+export function defaultConfig(): PromoConfig {
+  const out: Obj = { schema: CONFIG_SCHEMA_ID };
+  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 PromoConfig;
+}
+
+/* ─── leaf checks ─────────────────────────────────────────────────────────────────────────────── */
+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]/;
+/**
+ * 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('..'));
+}
+
+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 (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}).` });
+      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':
+      checkOverrides(c, p, v, errors);
+  }
+}
+
+/** Resolve a concrete config path (with list indexes) to its control. */
+export function controlAt(path: string): { control: Control; list?: ListSpec; index?: number } | undefined {
+  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 checkOverrides(c: Control, p: string, v: unknown, errors: ConfigError[]) {
+  if (!isObj(v)) return void errors.push({ path: p, message: `${p} must be an object of { "<config path>": value }.` });
+  for (const [key, value] of Object.entries(v)) {
+    const where = `${p}["${key}"]`;
+    if (!c.allow!.some((a) => (a.endsWith('.') ? key.startsWith(a) : key === a))) {
+      errors.push({ path: where, message: `${where}: a scene's ${p.split('.').pop()} may only set ${c.allow!.map((a) => (a.endsWith('.') ? `${a}*` : a)).join(', ')}.` });
+      continue;
+    }
+    const hit = controlAt(key);
+    if (!hit || hit.control.type === 'overrides') { errors.push({ path: where, message: `${where}: ${key} is not a ${NAME} control.` }); continue; }
+    if (hit.list && hit.index! >= hit.list.maxItems) { errors.push({ path: where, message: `${where}: ${hit.list.path} has at most ${hit.list.maxItems} items.` }); continue; }
+    checkLeaf(hit.control, where, value, errors);
+  }
+}
+
+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: `${p} must have ${l.minItems}–${l.maxItems} items (got ${v.length}).` });
+  const primitive = l.item.length === 1 && l.item[0]!.path === '';
+  const out: unknown[] = [];
+  v.forEach((item, i) => {
+    const ip = `${p}.${i}`;
+    if (primitive) {
+      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 = 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);
+  });
+  return out;
+}
+
+/* ─── cross-field rules ───────────────────────────────────────────────────────────────────────── */
+const RATIOS: Record<AspectRatio, number> = { '16:9': 16 / 9, '9:16': 9 / 16, '1:1': 1 };
+
+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) {
+    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 landscape, portrait and square presets do).` });
+  }
+  const stops = getPath(cfg, 'background.gradient.stops') as { offset: number }[];
+  for (let i = 1; i < stops.length; i++) {
+    if (stops[i]!.offset < stops[i - 1]!.offset) errors.push({ path: `background.gradient.stops.${i}.offset`, message: `background.gradient.stops must be in order of offset: stop ${i} (${stops[i]!.offset}) comes before stop ${i - 1} (${stops[i - 1]!.offset}).` });
+  }
+  const nav = getPath(cfg, 'productHeader.navItems') as string[];
+  const active = getPath(cfg, 'productHeader.activeItem') as string;
+  if (active !== '' && !nav.includes(active)) errors.push({ path: 'productHeader.activeItem', message: `productHeader.activeItem "${active}" is not one of productHeader.navItems (${nav.map((x) => `"${x}"`).join(', ') || 'none'}). Set it to one of them, or to "".` });
+  if (n('particles.sizeMin') > n('particles.sizeMax')) errors.push({ path: 'particles.sizeMin', message: `particles.sizeMin (${n('particles.sizeMin')}) must not exceed particles.sizeMax (${n('particles.sizeMax')}).` });
+  if (n('particles.opacityMin') > n('particles.opacityMax')) errors.push({ path: 'particles.opacityMin', message: `particles.opacityMin (${n('particles.opacityMin')}) must not exceed particles.opacityMax (${n('particles.opacityMax')}).` });
+  // Phases run in order; a negative delay overlaps the previous phase but may not start before frame 0.
+  let end = 0;
+  for (const id of PHASES) {
+    const start = end + n(`timeline.${id}.delayFrames`);
+    if (start < 0) errors.push({ path: `timeline.${id}.delayFrames`, message: `timeline.${id} would start at frame ${start}, before the video starts. Make timeline.${id}.delayFrames at least ${n(`timeline.${id}.delayFrames`) - start}.` });
+    end = Math.max(0, start) + n(`timeline.${id}.durationFrames`) + n(`timeline.${id}.holdFrames`);
+  }
+  if (n('productEntrance.delayFrames') + n('productEntrance.durationFrames') > end) errors.push({ path: 'productEntrance.durationFrames', message: `The product entrance (delay + duration ${n('productEntrance.delayFrames') + n('productEntrance.durationFrames')}) runs past the end of the timeline (${end} frames).` });
+  const scenes = getPath(cfg, 'scenes') as Obj[];
+  const ids = new Set<string>();
+  scenes.forEach((s, i) => {
+    if (ids.has(s.id as string)) errors.push({ path: `scenes.${i}.id`, message: `scenes.${i}.id "${String(s.id)}" is used by another scene; ids must be unique.` });
+    ids.add(s.id as string);
+    if ((s.durationFrames as number) <= n('sceneTransition.durationFrames') && i > 0) errors.push({ path: `scenes.${i}.durationFrames`, message: `scenes.${i}.durationFrames (${String(s.durationFrames)}) must be longer than sceneTransition.durationFrames (${n('sceneTransition.durationFrames')}).` });
+    for (const key of Object.keys(OVERRIDE_SCOPES)) {
+      for (const path of Object.keys((s[key] as Obj) ?? {})) {
+        const hit = controlAt(path);
+        if (hit?.list && hit.index! >= (getPath(cfg, hit.list.path) as unknown[]).length) {
+          errors.push({ path: `scenes.${i}.${key}["${path}"]`, message: `scenes.${i}.${key}: ${path} points past the end of ${hit.list.path} (${(getPath(cfg, hit.list.path) as unknown[]).length} items).` });
+        }
+      }
+      // A scene's own overrides must leave a valid config (e.g. an activeItem that still names a nav item).
+    }
+  });
+}
+
+/** 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;
+    const isGroup = CONTROLS.some((c) => c.path.startsWith(`${path}.`)) || LISTS.some((l) => l.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?: PromoConfig } {
+  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 ${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) checkRelations(merged, errors);
+  if (!errors.length) {
+    // Each scene, applied over the base, must itself be a valid config.
+    (getPath(merged, 'scenes') as Obj[]).forEach((_, i) => {
+      const scene = sceneConfig(merged as PromoConfig, i);
+      const inner: ConfigError[] = [];
+      checkRelations(scene as Obj, inner);
+      for (const e of inner) errors.push({ path: `scenes.${i}`, message: `With scene ${i}'s overrides: ${e.message}` });
+    });
+  }
+  return errors.length ? { valid: false, errors } : { valid: true, errors, config: merged as PromoConfig };
+}
+
+/** A valid, complete config, or an error listing every problem. */
+export class PromoConfigError extends Error {
+  constructor(readonly errors: ConfigError[]) {
+    super(`Invalid ${NAME} configuration:\n${errors.map((e) => `  ${e.path || '(root)'}: ${e.message}`).join('\n')}`);
+  }
+}
+export function resolveConfig(input: unknown): PromoConfig {
+  const r = validateConfig(input);
+  if (!r.valid) throw new PromoConfigError(r.errors);
+  return r.config!;
+}
+
+/** The base config with scene `i`'s overrides applied (no blending). */
+export function sceneConfig(config: PromoConfig, i: number): PromoConfig {
+  const scene = (getPath(config, 'scenes') as Obj[])[i];
+  if (!scene) return config;
+  const out = clone(config) as Obj;
+  for (const key of Object.keys(OVERRIDE_SCOPES)) {
+    for (const [path, value] of Object.entries((scene[key] as Obj) ?? {})) setPath(out, path, clone(value));
+  }
+  return out as PromoConfig;
+}
+
+/* ─── patches ─────────────────────────────────────────────────────────────────────────────────── */
+/**
+ * One change to the config. `replace` sets a control, a list, a list item or an item field
+ * (`productContent.cards.1.title`; index = length appends). `merge` sets several fields under a group
+ * or a list item, or adds keys to a scene's override map. `remove` resets a control, group or list to
+ * its default, or deletes a list item (`productContent.cards.2`).
+ */
+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.title': 'Launch faster.' } }` (all replaces). */
+export type ConfigPatch = PatchOp[] | { patch: Record<string, unknown> };
+
+const isGroupPath = (path: string) => CONTROLS.some((c) => c.path.startsWith(`${path}.`)) || LISTS.some((l) => l.path.startsWith(`${path}.`));
+/** A path to one list item: `<list>.<index>`. */
+function listItemAt(path: string): { list: ListSpec; index: number } | undefined {
+  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 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: PromoConfig; 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 replace = (path: string, value: unknown): string | undefined => {
+    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 `${path}: ${item.list.path} has ${arr.length} items; use index ${arr.length} to add one.`;
+      const primitive = item.list.item.length === 1 && item.list.item[0]!.path === '';
+      arr[item.index] = primitive ? 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 `${path}: ${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 `${path} 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(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 target = controlAt(o.path);
+      if (target?.control.type === 'overrides') {
+        const cur = (getPath(next, o.path) as Obj) ?? {};
+        setPath(next, o.path, { ...cur, ...clone(o.value) });
+        changed.push(o.path);
+        return;
+      }
+      if (!isGroupPath(o.path) && !listItemAt(o.path)) return void errors.push({ path: o.path, message: `merge needs a group path (such as "content.cta"), a list item (such as "productContent.cards.0") or a scene override map.` });
+      const walk = (value: Obj, prefix: string) => {
+        for (const [k, v] of Object.entries(value)) {
+          const path = `${prefix}.${k}`;
+          if (isObj(v) && !controlAt(path) && isGroupPath(path)) { walk(v, path); continue; }
+          const err = replace(path, v);
+          if (err) errors.push({ path, message: err }); else changed.push(path);
+        }
+      };
+      walk(o.value, o.path);
+    } else if (o.op === 'remove') {
+      const item = listItemAt(o.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}.` });
+        arr.splice(item.index, 1);
+        changed.push(o.path);
+        return;
+      }
+      const hits = CONTROLS.filter((c) => c.path === o.path || c.path.startsWith(`${o.path}.`));
+      const lists = LISTS.filter((l) => l.path === o.path || l.path.startsWith(`${o.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 differ are replaced whole. */
+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);
+  }
+  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[];
+    const primitive = l.item.length === 1 && l.item[0]!.path === '';
+    if (aa.length !== bb.length || primitive) { 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 };
+}
+
+/* ─── JSON Schema ─────────────────────────────────────────────────────────────────────────────── */
+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: [...EASING_NAMES], ...meta };
+    case 'text': return { type: 'string', minLength: c.minLength ?? 0, maxLength: c.maxLength, pattern: '^[^\\u0000-\\u001f\\u007f]*$', ...meta };
+    case 'asset': return { type: 'string', maxLength: c.maxLength, pattern: ASSET.source.replace(/^\^\(/, '^$|^(').replace(/\)\$$/, ')$'), 'x-asset': true, ...meta };
+    case 'overrides': return {
+      type: 'object', 'x-overrides': c.allow,
+      propertyNames: { pattern: `^(${c.allow!.map((a) => a.replace(/\./g, '\\.') + (a.endsWith('.') ? '.+' : '')).join('|')})$` },
+      ...meta,
+    };
+  }
+}
+
+function listSchema(l: ListSpec): Obj {
+  const primitive = l.item.length === 1 && l.item[0]!.path === '';
+  const items = primitive ? 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 };
+}
+
+/** 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/${NAME}.json`,
+    title: 'Promo product showcase configuration',
+    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: CONFIG_SCHEMA_ID } },
+  };
+  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;
+}