playrig 0.0.0-stage → 0.1.0

package/lib/ae.js

@@ -0,0 +1,754 @@
+'use strict';
+// Playrig for After Effects client: submits ExtendScript (.jsx) jobs to the panel, reads results, runs the recipe library.
+
+const fs = require('fs');
+const path = require('path');
+const C = require('./common');
+const { ID_RE, USAGE, die, writeAtomic, defaultId, sleep, readResult } = C;
+const APP = C.APPS.ae;
+const rootDir = (flags) => C.rootDir(APP, flags);
+const EDITION = C.editionDir('ae');
+
+// Shared with the panel (and a later UXP port): the defined action list and its labels.
+const ACTIONS_FILE = path.join(EDITION || __dirname, 'lib', 'actions.json');
+const ACTION_DATA = (() => { try { return JSON.parse(fs.readFileSync(ACTIONS_FILE, 'utf8')); } catch (e) { return { actions: {}, recipePrefix: 'recipe.' }; } })();
+const isRecipeAction = (id) => id.startsWith(ACTION_DATA.recipePrefix || 'recipe.') && id.length > (ACTION_DATA.recipePrefix || 'recipe.').length;
+const knownAction = (id) => !!(ACTION_DATA.actions[id] || isRecipeAction(id));
+const actionLabel = (r) => r.actionLabel || (ACTION_DATA.actions[r.action] && ACTION_DATA.actions[r.action].label) || (r.action && isRecipeAction(r.action) ? `Recipe: ${r.action.slice((ACTION_DATA.recipePrefix || 'recipe.').length)}` : 'Custom action');
+
+// First \`// ...\` lines of a job: \`// @action <id>\` declares the action, the first other comment line is the description (same rule as the panel).
+function parseJobHeader(src) {
+  const out = { action: null, description: null };
+  for (const line of String(src || '').split(/\r\n|\r|\n/).slice(0, 10)) {
+    const m = /^\s*\/\/\s?(.*)$/.exec(line);
+    if (!m) { if (line.trim()) break; else continue; }
+    const t = m[1].trim(); const a = /^@action\s+([A-Za-z0-9_.-]+)/.exec(t);
+    if (a) out.action = a[1]; else if (t && !out.description) out.description = t.slice(0, 240);
+  }
+  return out;
+}
+
+function parseSnap(spec) {
+  const at = spec.lastIndexOf('@');
+  if (at < 1) die(`Bad --snap "${spec}". Expected "<comp>@t1,t2,..."`);
+  const times = spec.slice(at + 1).split(',').map((s) => Number(s.trim()));
+  if (!times.length || times.some((t) => !Number.isFinite(t))) die(`Bad times in --snap "${spec}"`);
+  return { comp: spec.slice(0, at), times };
+}
+
+function parseInspect(spec) {
+  const colon = spec.lastIndexOf(':');
+  if (colon > 0 && /^\d+$/.test(spec.slice(colon + 1))) return { comp: spec.slice(0, colon), depth: Number(spec.slice(colon + 1)) };
+  return { comp: spec, depth: 1 };
+}
+
+function printResult(root, r, opts = {}) {
+  const outDir = path.join(root, 'out', r.id);
+  const lines = [];
+  lines.push(`[${r.status}] ${r.id}${r.durationMs != null ? ` (${r.durationMs} ms)` : ''}${r.aeVersion ? ` AE ${r.aeVersion}` : ''}`);
+  if (r.action) lines.push(`action: ${actionLabel(r)} [${r.action}${r.actionSource === 'inferred' ? ', inferred: declare it with --action or a // @action header' : ''}]`);
+  if (r.description) lines.push(`about: ${r.description}`);
+  lines.push(r.project && r.project.path ? `project: ${r.project.path}${r.project.dirty ? ' (unsaved changes)' : ''}` : 'project: (unsaved project)');
+  if (r.error) {
+    lines.push(`error: ${r.error.message}${r.error.line ? ` (line ${r.error.line}${r.error.fileName ? ' of ' + r.error.fileName : ''})` : ''}`);
+    if (r.error.source != null) lines.push(`  > ${String(r.error.source).trim()}`);
+  }
+  if (r.sync) lines.push(`project log: ${r.sync.ok ? r.sync.dir : 'NOT SYNCED (' + r.sync.reason + ')'}`);
+  if (r.backup) lines.push(`backup: ${r.backup.ok ? r.backup.file : 'none (' + r.backup.reason + ')'}`);
+  if (r.log && r.log.length) { lines.push('log:'); r.log.forEach((l) => lines.push(`  ${l}`)); }
+  if (r.snapshots && r.snapshots.length) {
+    lines.push('snapshots:');
+    r.snapshots.forEach((s) => {
+      lines.push(s.ok ? `  ${path.join(outDir, s.file)}` : `  FAILED ${s.comp} @ ${s.time}: ${s.error || 'unknown'}`);
+    });
+  }
+  if (r.returnValue !== null && r.returnValue !== undefined) lines.push(`return: ${JSON.stringify(r.returnValue)}`);
+  if (r.inspect && opts.showInspect) lines.push(`inspect: ${JSON.stringify(r.inspect, null, 2)}`);
+  lines.push(`result: ${path.join(outDir, 'result.json')}`);
+  console.log(lines.join('\n'));
+}
+
+// Writes options + job into the inbox and waits for result.json. `source` is the job text (string or Buffer).
+async function submitJob(root, id, source, flags, extraOptions) {
+  if (!ID_RE.test(id)) die(`Bad id "${id}". Must match ^[A-Za-z0-9_-]{1,64}$`);
+  if (Buffer.byteLength(source) > 2 * 1024 * 1024) die('Job file is larger than 2 MB');
+
+  const inbox = path.join(root, 'inbox');
+  fs.mkdirSync(inbox, { recursive: true });
+  fs.mkdirSync(path.join(root, 'out'), { recursive: true });
+  if (fs.existsSync(path.join(root, 'out', id, 'result.json'))) die(`Job id "${id}" already has a result. Use a new --id.`);
+
+  const timeoutSec = flags.timeout !== undefined ? Number(flags.timeout) : 120;
+  if (!Number.isFinite(timeoutSec) || timeoutSec <= 0) die('--timeout must be a positive number of seconds');
+  const options = { timeoutSec, ...extraOptions };
+  if (flags['no-undo']) options.undoGroup = false;
+  if (flags.action) {
+    if (!knownAction(flags.action)) console.error(`warning: unknown action "${flags.action}"; it will show as "Custom action". Known: ${Object.keys(ACTION_DATA.actions).join(', ')}, recipe.<id>`);
+    options.action = flags.action;
+  }
+  if (flags.desc) options.description = String(flags.desc).slice(0, 240);
+  const snaps = [...(options.snapshots || []), ...flags.snap.map(parseSnap)];
+  if (snaps.length) options.snapshots = snaps;
+  if (flags.inspect) options.inspect = parseInspect(flags.inspect);
+
+  // Options first, then the job. The panel only reacts to <id>.jsx.
+  writeAtomic(path.join(inbox, `${id}.json`), JSON.stringify(options, null, 2));
+  writeAtomic(path.join(inbox, `${id}.jsx`), source);
+
+  const deadline = Date.now() + (timeoutSec + 60) * 1000;
+  let r = null;
+  while (Date.now() < deadline) {
+    r = readResult(root, id);
+    if (r) break;
+    await sleep(250);
+  }
+  if (!r) {
+    die(`No result for "${id}" after ${timeoutSec + 60} s. Is After Effects open with the Playrig panel started (press Start)?\n` +
+      `Job is still in ${inbox} or ${path.join(root, 'running')}.`, 3);
+  }
+  await settleSnapshots(root, r);
+  return r;
+}
+
+// saveFrameToPng can finish writing only after the job returns (the job's own wait blocks AE's thread), so a
+// snapshot reported as "not written" is re-checked here for up to 30 s and flipped to ok if the file appears.
+async function settleSnapshots(root, r) {
+  const late = (r.snapshots || []).filter((s) => !s.ok && s.file && /not written/.test(s.error || ''));
+  const deadline = Date.now() + 30000;
+  for (const s of late) {
+    const f = path.join(root, 'out', r.id, s.file);
+    while (Date.now() < deadline) {
+      if (fs.existsSync(f) && fs.statSync(f).size > 0) { s.ok = true; delete s.error; break; }
+      await sleep(250);
+    }
+  }
+}
+
+function finish(root, r, flags) {
+  if (flags.json) console.log(JSON.stringify(r, null, 2));
+  else printResult(root, r, { showInspect: !!flags.inspect });
+  process.exit(r.status === 'ok' ? 0 : 1);
+}
+
+// Parses --params '{json}' and repeated --param k=v into a plain object of raw values.
+function rawParams(flags) {
+  let out = {};
+  if (flags.params) {
+    try { out = JSON.parse(flags.params); } catch (e) { die(`--params is not valid JSON: ${e.message}`); }
+  }
+  for (const kv of flags.param) {
+    const eq = kv.indexOf('=');
+    if (eq < 1) die(`Bad --param "${kv}". Expected key=value`);
+    out[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+  return out;
+}
+
+async function cmdRun(pos, flags) {
+  const root = rootDir(flags);
+  const jsxPath = pos[0];
+  if (!jsxPath) die(`Missing <file.jsx>\n\n${USAGE}`);
+  if (!fs.existsSync(jsxPath)) die(`File not found: ${jsxPath}`);
+  let source = fs.readFileSync(jsxPath);
+  const header = parseJobHeader(source.toString('utf8'));
+  if (!flags.action && header.action) flags.action = header.action;
+  if (!flags.desc && header.description) flags.desc = header.description;
+  const raw = rawParams(flags);
+  // Optional parameters for plain jobs: exposed to the job as `var P = {...}`. Same line, so line numbers still match.
+  if (Object.keys(raw).length) source = Buffer.concat([Buffer.from(`var P = ${JSON.stringify(raw)}; `), source]);
+  const r = await submitJob(root, flags.id || defaultId(jsxPath), source, flags, {});
+  finish(root, r, flags);
+}
+
+function cmdStatus(pos, flags) {
+  const root = rootDir(flags);
+  const id = pos[0];
+  if (!id || !ID_RE.test(id)) die(`Missing or bad <id>\n\n${USAGE}`);
+  const r = readResult(root, id);
+  if (r) { printResult(root, r); process.exit(r.status === 'ok' ? 0 : 1); }
+  if (fs.existsSync(path.join(root, 'running', `${id}.jsx`))) { console.log(`[running] ${id}`); return; }
+  if (fs.existsSync(path.join(root, 'inbox', `${id}.jsx`))) { console.log(`[queued] ${id}`); return; }
+  die(`Unknown job "${id}"`, 1);
+}
+
+// Latest jobs of ONE project: by default the project of the most recent job (so a log is never read for the wrong project).
+function cmdTail(flags) {
+  const root = rootDir(flags);
+  const out = path.join(root, 'out');
+  if (!fs.existsSync(out)) die(`No out folder at ${out}`, 1);
+  const limit = flags.limit ? Math.max(1, Number(flags.limit) || 10) : 10;
+  const rows = fs.readdirSync(out)
+    .map((d) => ({ d, f: path.join(out, d, 'result.json') }))
+    .filter((x) => fs.existsSync(x.f))
+    .map((x) => { try { return { ...x, t: fs.statSync(x.f).mtimeMs, r: JSON.parse(fs.readFileSync(x.f, 'utf8')) }; } catch (e) { return null; } })
+    .filter(Boolean)
+    .sort((a, b) => b.t - a.t);
+  if (!rows.length) { console.log('No results yet.'); return; }
+  const projOf = (x) => (x.r.project && x.r.project.path) || null;
+  let shown = rows; let label;
+  if (flags.all) label = 'all projects';
+  else if (flags.project) {
+    const q = String(flags.project).toLowerCase();
+    shown = rows.filter((x) => projOf(x) && projOf(x).toLowerCase().includes(q));
+    label = `projects matching "${flags.project}"`;
+    if (!shown.length) { console.log(`No jobs for a project matching "${flags.project}".`); return; }
+  } else {
+    const cur = projOf(rows[0]);
+    shown = rows.filter((x) => projOf(x) === cur);
+    label = cur || '(unsaved project)';
+  }
+  console.log(`Jobs for: ${label}${flags.all ? '' : `   (--all for every project, --project <name> to pick one; ${shown.length} job${shown.length === 1 ? '' : 's'})`}`);
+  shown.slice(0, limit).forEach((x) => {
+    const r = x.r;
+    const err = r.error ? ` - ${r.error.message}` : '';
+    const what = r.description ? ` | ${r.description}` : '';
+    const proj = flags.all ? `  {${projOf(x) ? path.basename(projOf(x)) : 'unsaved'}}` : '';
+    console.log(`${new Date(x.t).toISOString()}  [${r.status}] ${r.id}  (${actionLabel(r)}${r.actionSource === 'inferred' ? ', inferred' : ''})${what}${err}${proj}`);
+  });
+}
+
+
+// ------------------------------------------------------------------ recipe library
+// One Markdown file per recipe: YAML frontmatter (metadata + params) + body (docs) + a ```jsx script block.
+// See library/README.md. Frontmatter is a small YAML subset (see parseFrontmatter), parsed here without dependencies.
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const SCRIPT_RE = /```jsx[^\n]*\r?\n([\s\S]*?)\r?\n```/;
+const STATUSES = new Set(['ready', 'experimental', 'planned']);
+const PARAM_TYPES = new Set(['string', 'number', 'boolean', 'color', 'list']);
+const INDEX_SPLIT_THRESHOLD = 40; // above this many recipes, INDEX.md lists categories only
+
+function libDir(flags) {
+  return C.libraryDir(flags);
+}
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((d) => {
+    const p = path.join(dir, d.name);
+    return d.isDirectory() ? walk(p) : [p];
+  });
+}
+
+// ---- minimal YAML subset: top-level `key: value`, `key:` + indented `sub: value` map, `key:` + `- item` list.
+// Values: "quoted", 'quoted', numbers, true/false/null, plain text, flow lists [a, b] and flow maps {a: 1, b: "x"}.
+function stripComment(line) {
+  let q = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (q) { if (c === q && line[i - 1] !== '\\') q = null; }
+    else if (c === '"' || c === "'") q = c;
+    else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+function plainScalar(t) {
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (t === 'null' || t === '~') return null;
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  return t;
+}
+
+function parseValue(text) {
+  let i = 0;
+  const s = text.trim();
+  const fail = (m) => { throw new Error(`${m} in "${s.length > 60 ? s.slice(0, 57) + '...' : s}"`); };
+  const ws = () => { while (i < s.length && /\s/.test(s[i])) i++; };
+  function quoted() {
+    const q = s[i++]; let out = '';
+    while (i < s.length && s[i] !== q) {
+      if (s[i] === '\\' && q === '"') { i++; const e = s[i++]; out += ({ n: '\n', t: '\t', '"': '"', '\\': '\\', '/': '/' })[e] ?? e; }
+      else out += s[i++];
+    }
+    if (s[i] !== q) fail('unterminated string');
+    i++;
+    return out;
+  }
+  function plain(stops) {
+    const start = i;
+    while (i < s.length && !stops.includes(s[i])) i++;
+    return plainScalar(s.slice(start, i).trim());
+  }
+  function value(stops) {
+    ws();
+    if (s[i] === '[') {
+      i++; const a = []; ws();
+      if (s[i] === ']') { i++; return a; }
+      for (;;) { a.push(value(',]')); ws(); if (s[i] === ',') { i++; continue; } if (s[i] === ']') { i++; return a; } fail('expected , or ]'); }
+    }
+    if (s[i] === '{') {
+      i++; const o = {}; ws();
+      if (s[i] === '}') { i++; return o; }
+      for (;;) {
+        ws();
+        const k = (s[i] === '"' || s[i] === "'") ? quoted() : String(plain(':'));
+        ws(); if (s[i] !== ':') fail('expected :'); i++;
+        o[k] = value(',}'); ws();
+        if (s[i] === ',') { i++; continue; }
+        if (s[i] === '}') { i++; return o; }
+        fail('expected , or }');
+      }
+    }
+    if (s[i] === '"' || s[i] === "'") return quoted();
+    return plain(stops);
+  }
+  if (!s) return '';
+  const v = value('');
+  ws();
+  if (i < s.length) fail('unexpected trailing text');
+  return v;
+}
+
+function parseFrontmatter(text) {
+  const lines = text.split(/\r?\n/).map(stripComment);
+  const out = {};
+  let i = 0;
+  while (i < lines.length) {
+    if (!lines[i].trim()) { i++; continue; }
+    const m = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+    if (!m || /^\s/.test(lines[i])) throw new Error(`cannot parse line "${lines[i].trim()}"`);
+    const key = m[1]; const rest = m[2].trim();
+    i++;
+    if (rest !== '') { out[key] = parseValue(rest); continue; }
+    const block = [];
+    while (i < lines.length && (/^\s+\S/.test(lines[i]) || !lines[i].trim())) { if (lines[i].trim()) block.push(lines[i]); i++; }
+    if (!block.length) { out[key] = null; continue; }
+    if (/^\s*-\s/.test(block[0])) out[key] = block.map((l) => parseValue(l.replace(/^\s*-\s+/, '')));
+    else {
+      const o = {};
+      for (const l of block) {
+        const mm = /^\s+([A-Za-z_][\w-]*):\s*(.*)$/.exec(l);
+        if (!mm) throw new Error(`cannot parse line "${l.trim()}"`);
+        o[mm[1]] = parseValue(mm[2]);
+      }
+      out[key] = o;
+    }
+  }
+  return out;
+}
+
+function readRecipe(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  const m = FM_RE.exec(text);
+  if (!m) throw new Error('missing --- frontmatter --- block at the top of the file');
+  const meta = parseFrontmatter(m[1]);
+  const sm = SCRIPT_RE.exec(m[2]);
+  return { ...meta, file, body: m[2], script: sm ? sm[1] : null };
+}
+
+function loadRecipes(dir) {
+  return walk(path.join(dir, 'recipes')).filter((f) => f.endsWith('.md')).sort().map((file) => {
+    try { return readRecipe(file); } catch (e) { return die(`${path.relative(dir, file)}: ${e.message}\nRun: playrig ae lib check`); }
+  });
+}
+
+function findRecipe(dir, id) {
+  const r = loadRecipes(dir).find((x) => x.id === id);
+  if (!r) die(`No recipe "${id}". Try: playrig ae lib list`, 1);
+  return r;
+}
+
+function coerce(name, spec, raw) {
+  switch (spec.type) {
+    case 'number': {
+      const n = Number(raw);
+      if (raw === '' || !Number.isFinite(n)) die(`Parameter ${name} must be a number (got "${raw}")`);
+      if (spec.min !== undefined && n < spec.min) die(`Parameter ${name} must be >= ${spec.min}`);
+      if (spec.max !== undefined && n > spec.max) die(`Parameter ${name} must be <= ${spec.max}`);
+      return n;
+    }
+    case 'boolean':
+      if (typeof raw === 'boolean') return raw;
+      if (/^(true|1|yes|on)$/i.test(raw)) return true;
+      if (/^(false|0|no|off)$/i.test(raw)) return false;
+      return die(`Parameter ${name} must be true or false (got "${raw}")`);
+    case 'color':
+      if (!/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(raw)) die(`Parameter ${name} must be a hex colour like #F7F7F5 (got "${raw}")`);
+      return raw;
+    case 'list': return Array.isArray(raw) ? raw : String(raw).split('|').map((x) => x.trim()).filter(Boolean);
+    default: return String(raw);
+  }
+}
+
+function resolveParams(recipe, flags) {
+  const specs = recipe.params || {};
+  const raw = rawParams(flags);
+  for (const k of Object.keys(raw)) {
+    if (!specs[k]) die(`Unknown parameter "${k}" for ${recipe.id}. Valid: ${Object.keys(specs).join(', ')}`);
+  }
+  const out = {};
+  for (const [k, spec] of Object.entries(specs)) out[k] = k in raw ? coerce(k, spec, raw[k]) : spec.default;
+  return out;
+}
+
+function recipeCommand(r) {
+  const eg = Object.entries(r.params || {}).slice(0, 3).map(([k, v]) => `--param ${k}=${String(v.default).replace(/\s/g, '') === String(v.default) ? v.default : JSON.stringify(String(v.default))}`);
+  return `playrig ae lib run ${r.id} ${eg.join(' ')}`.trim();
+}
+
+const rel = (dir, f) => path.relative(dir, f).split(path.sep).join('/');
+const oneLine = (s) => String(s).replace(/\s+/g, ' ').trim();
+// Preview images live next to the recipe file as <id>--t<seconds>.png and are embedded in its "Preview" section.
+const PREVIEW_START = '<!-- previews:start -->';
+const PREVIEW_END = '<!-- previews:end -->';
+function previewFiles(r) {
+  const d = path.dirname(r.file);
+  const re = new RegExp(`^${r.id}--t(\\d+(?:\\.\\d+)?)\\.png$`);
+  return fs.readdirSync(d).map((f) => ({ f, m: re.exec(f) })).filter((x) => x.m).sort((a, b) => Number(a.m[1]) - Number(b.m[1])).map((x) => x.f);
+}
+function writePreviewSection(r, files) {
+  const block = `${PREVIEW_START}\n${files.map((f) => `<img src="${f}" width="240" alt="${f.replace(/^.*--t/, 't=').replace(/\.png$/, 's')}">`).join(' ')}\n${PREVIEW_END}`;
+  let text = fs.readFileSync(r.file, 'utf8');
+  if (text.includes(PREVIEW_START)) text = text.replace(new RegExp(`${PREVIEW_START}[\\s\\S]*?${PREVIEW_END}`), () => block);
+  else text = text.replace(/^(# .+)$/m, (h) => `${h}\n\n${block}`);
+  fs.writeFileSync(r.file, text);
+}
+const bodyWithoutScript = (r) => r.body.replace(SCRIPT_RE, '_(script omitted: use `playrig ae lib show <id> --full`, or open the file)_');
+
+function loadCategories(dir) {
+  const f = path.join(dir, 'categories.json');
+  return fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')) : {};
+}
+
+// ---- INDEX.md: the level-0 router agents read first. Compact on purpose; splits per category when large.
+function recipeLine(dir, r, base) {
+  const link = path.relative(path.dirname(base), r.file).split(path.sep).join('/');
+  const aka = (r.aliases || []).length ? ` (aka ${r.aliases.slice(0, 3).join(', ')})` : '';
+  const tag = r.status === 'experimental' ? ' *[experimental]*' : '';
+  return `- [\`${r.id}\`](${link}): ${oneLine(r.summary)}${aka}${tag}`;
+}
+
+function buildIndex(dir) {
+  const recipes = loadRecipes(dir);
+  const cats = loadCategories(dir);
+  const names = [...new Set(recipes.map((x) => x.category))].sort();
+  const split = recipes.length > INDEX_SPLIT_THRESHOLD;
+  const ready = recipes.filter((r) => r.status !== 'planned').length;
+
+  const head = [
+    '# Motion Library: Index', '',
+    `${ready} usable recipes, ${recipes.length - ready} planned. Generated by \`playrig ae lib index\`: edit the recipe files, not this one.`, '',
+    '## For agents: how to use this library', '',
+    '1. **Read only this file** to find candidates (match the request against the summaries, aliases and tags).',
+    '2. **Open one recipe file** (link below) once you have chosen it. It has parameters, what each setting changes, gotchas and what it combines with. Do not read other recipes or the scripts unless you need to.',
+    '3. **Run it:** `playrig ae lib run <id> --param key=value ...` (After Effects open, Playrig panel started). Chain recipes into one comp with the shared `comp` parameter.',
+    '4. **Look at the preview frames** it prints before reporting success.',
+    '5. Nothing fits? Build it with a normal bridge job, then offer to add it as a recipe (`library/README.md`, "Add a recipe").', '',
+  ];
+
+  const lines = [...head];
+  const usable = recipes.filter((x) => x.status !== 'planned');
+  const planned = recipes.filter((x) => x.status === 'planned');
+  if (!split) {
+    for (const c of names) {
+      const inCat = usable.filter((x) => x.category === c);
+      if (!inCat.length) continue;
+      lines.push(`## ${c}`, cats[c] ? `*${cats[c]}*` : '', '');
+      for (const r of inCat) lines.push(recipeLine(dir, r, path.join(dir, 'INDEX.md')));
+      lines.push('');
+    }
+  } else {
+    lines.push('## Categories', '', 'Open a category index, then one recipe.', '');
+    fs.mkdirSync(path.join(dir, 'categories'), { recursive: true });
+    for (const c of names) {
+      const inCat = recipes.filter((x) => x.category === c);
+      const f = path.join(dir, 'categories', `${c}.md`);
+      const body = [`# ${c}`, '', cats[c] || '', '', '[Back to index](../INDEX.md)', '',
+        ...inCat.filter((r) => r.status !== 'planned').map((r) => recipeLine(dir, r, f)), '',
+        ...(inCat.some((r) => r.status === 'planned') ? ['## Planned (no script yet)', '', ...inCat.filter((r) => r.status === 'planned').map((r) => recipeLine(dir, r, f)), ''] : [])];
+      fs.writeFileSync(f, body.join('\n'));
+      lines.push(`- [\`${c}\`](categories/${c}.md) (${inCat.filter((r) => r.status !== 'planned').length} usable): ${cats[c] || ''}`);
+    }
+    lines.push('');
+  }
+  if (planned.length && !split) {
+    lines.push('## Planned (documented, no script yet)', '', 'Tell the user these exist as ideas; build with a normal bridge job if asked, using the recipe file as the brief.', '');
+    for (const r of planned) lines.push(recipeLine(dir, r, path.join(dir, 'INDEX.md')).replace(/ \(aka [^)]*\)$/, ''));
+    lines.push('');
+  }
+  fs.writeFileSync(path.join(dir, 'INDEX.md'), lines.join('\n'));
+
+  const json = recipes.map((r) => { const { file, body, script, ...meta } = r; return { ...meta, path: rel(dir, file), previews: previewFiles(r).map((f) => rel(dir, path.join(path.dirname(file), f))) }; });
+  fs.writeFileSync(path.join(dir, 'index.json'), JSON.stringify(json, null, 2) + '\n');
+  console.log(`Wrote INDEX.md${split ? ` + categories/ (${names.length})` : ''} and index.json: ${ready} usable, ${recipes.length - ready} planned`);
+}
+
+// ---- lint: keeps the library consistent as it grows
+function cmdLibCheck(dir) {
+  const errors = []; const warns = [];
+  const files = walk(path.join(dir, 'recipes')).filter((f) => f.endsWith('.md')).sort();
+  const seen = new Map(); const all = [];
+  for (const file of files) {
+    const where = rel(dir, file);
+    const err = (m) => errors.push(`${where}: ${m}`);
+    const warn = (m) => warns.push(`${where}: ${m}`);
+    let r;
+    try { r = readRecipe(file); } catch (e) { err(e.message); continue; }
+    all.push(r);
+    const id = path.basename(file, '.md');
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(String(r.id || ''))) err(`id must be lowercase-kebab (got "${r.id}")`);
+    if (r.id !== id) err(`id "${r.id}" must equal the file name "${id}"`);
+    if (seen.has(r.id)) err(`duplicate id (also in ${seen.get(r.id)})`); else seen.set(r.id, where);
+    const folder = path.basename(path.dirname(file));
+    if (r.category !== folder) err(`category "${r.category}" must equal its folder "${folder}"`);
+    for (const k of ['name', 'summary', 'category', 'status']) if (!r[k]) err(`missing "${k}"`);
+    if (r.status && !STATUSES.has(r.status)) err(`status must be ready, experimental or planned (got "${r.status}")`);
+    if (r.summary && oneLine(r.summary).length > 150) warn(`summary is ${oneLine(r.summary).length} chars; keep it to one short sentence (<= 150): it is read for every routing decision`);
+    if (!Array.isArray(r.tags) || !r.tags.length) err('tags must be a non-empty list');
+    if (r.aliases !== undefined && !Array.isArray(r.aliases)) err('aliases must be a list');
+    if (r.composes_with !== undefined && !Array.isArray(r.composes_with)) err('composes_with must be a list');
+    if (r.idempotent !== undefined && typeof r.idempotent !== 'boolean') err('idempotent must be true or false');
+    if (r.idempotent === false && !r.replace_note) err('idempotent: false needs a replace_note (how to change it instead)');
+    if (!/^#\s/m.test(r.body)) warn('body has no "# Title" heading');
+    for (const m of r.body.matchAll(/src="([^"]+\.png)"/g)) if (!fs.existsSync(path.join(path.dirname(file), m[1]))) err(`embedded image ${m[1]} does not exist`);
+    if (r.status !== 'planned') {
+      if (!r.script) err('ready/experimental recipes need a ```jsx script block');
+      if (!Array.isArray(r.preview_times) || !r.preview_times.length) warn('no preview_times');
+      if (!r.params || !r.params.comp) err('params must include "comp" (the target comp)');
+      for (const [k, s] of Object.entries(r.params || {})) {
+        if (!PARAM_TYPES.has(s.type)) { err(`param ${k}: unknown type "${s.type}"`); continue; }
+        if (s.default === undefined) err(`param ${k}: missing default`);
+        if (!s.desc) warn(`param ${k}: missing desc`);
+        if (s.default !== undefined) {
+          const ok = { number: typeof s.default === 'number', boolean: typeof s.default === 'boolean', string: typeof s.default === 'string', color: typeof s.default === 'string' && /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(s.default), list: Array.isArray(s.default) }[s.type];
+          if (!ok) err(`param ${k}: default ${JSON.stringify(s.default)} is not a valid ${s.type}`);
+          if (s.type === 'number' && typeof s.default === 'number' && ((s.min !== undefined && s.default < s.min) || (s.max !== undefined && s.default > s.max))) err(`param ${k}: default is outside min/max`);
+        }
+      }
+      if (r.script) {
+        try { new (require('vm').Script)(`(function(P){${r.script}\n})`); } catch (e) { err(`script does not parse: ${e.message}`); }
+        const es3 = [[/=>/, 'arrow function'], [/\blet\s/, 'let'], [/\bconst\s/, 'const'], [/`/, 'template literal'], [/\bJSON\./, 'JSON (not in ExtendScript)'], [/\.forEach\(|\.map\(|\.filter\(/, 'Array.forEach/map/filter']];
+        for (const [re, what] of es3) if (re.test(r.script.replace(/(["'])(?:\\.|(?!\1).)*\1/g, '""'))) err(`script uses ${what}; ExtendScript is ES3`);
+        const used = [...r.script.matchAll(/\bP\.([A-Za-z_]\w*)/g)].map((x) => x[1]);
+        for (const u of new Set(used)) if (!(r.params || {})[u]) err(`script uses P.${u} which is not declared in params`);
+        for (const k of Object.keys(r.params || {})) if (!used.includes(k) && !['width', 'height', 'duration', 'fps'].includes(k) && k !== 'comp') warn(`param ${k} is declared but never used`);
+      }
+      if (r.status === 'ready' && !previewFiles(r).length) warn('no previews yet (run with --save-preview)');
+    }
+  }
+  const ids = new Set(all.map((x) => x.id));
+  for (const r of all) for (const c of r.composes_with || []) if (!ids.has(c)) errors.push(`${rel(dir, r.file)}: composes_with "${c}" does not exist`);
+  warns.forEach((w) => console.log(`warn  ${w}`));
+  errors.forEach((e) => console.log(`ERROR ${e}`));
+  console.log(`\n${all.length} recipes checked: ${errors.length} errors, ${warns.length} warnings`);
+  process.exit(errors.length ? 1 : 0);
+}
+
+function cmdLibShow(dir, id, flags) {
+  const r = findRecipe(dir, id);
+  const out = [];
+  out.push(`${r.id}: ${r.name}  [${r.category}, ${r.status}]`);
+  out.push(`tags: ${(r.tags || []).join(', ')}${(r.aliases || []).length ? `\nalso known as: ${r.aliases.join(', ')}` : ''}`);
+  out.push(`\n${oneLine(r.summary)}`);
+  if (r.use_when) out.push(`use when: ${oneLine(r.use_when)}`);
+  if (r.composes_with && r.composes_with.length) out.push(`combines with: ${r.composes_with.join(', ')}`);
+  if (r.status !== 'planned') out.push(`edit in place (--replace): ${r.idempotent === false ? 'NO: ' + oneLine(r.replace_note || '') : 'yes (replaces only its own layers, same stacking position)'}`);
+  if (r.origin) out.push(`origin: ${r.origin}`);
+  if (r.params) {
+    out.push('\nparameters:');
+    for (const [k, v] of Object.entries(r.params)) {
+      const range = v.min !== undefined || v.max !== undefined ? ` [${v.min ?? ''}..${v.max ?? ''}]` : '';
+      out.push(`  ${k} (${v.type}${range}) = ${JSON.stringify(v.default)}  ${v.desc || ''}`);
+    }
+  }
+  out.push(`\nfile: ${r.file}`);
+  const pv = previewFiles(r);
+  if (pv.length) out.push(`previews: ${pv.map((f) => path.join(path.dirname(r.file), f)).join('\n          ')}`);
+  if (r.status !== 'planned') out.push(`run:  ${recipeCommand(r)}`);
+  console.log(out.join('\n'));
+  if (flags.full) console.log(`\n${r.body}`);
+  else console.log(`\n(open the file for the full notes: how it works, tweaks, gotchas. Add --full to print them here.)`);
+}
+
+function cmdLibList(dir, query, flags) {
+  const q = (query || '').toLowerCase();
+  const rows = loadRecipes(dir).filter((x) =>
+    (!flags.category || x.category === flags.category) &&
+    (!flags.status || x.status === flags.status) &&
+    (!q || [x.id, x.name, x.category, x.summary, ...(x.tags || []), ...(x.aliases || [])].join(' ').toLowerCase().includes(q)));
+  if (!rows.length) { console.log('No matches.'); return; }
+  const w = Math.max(...rows.map((x) => x.id.length));
+  for (const x of rows) console.log(`${x.id.padEnd(w)}  ${x.status === 'ready' ? ' ' : '·'} [${x.category}] ${oneLine(x.summary)}`);
+  console.log('\n(· = planned or experimental)');
+}
+
+// Copies the starter (helpers, README, empty recipes/) so you can add your own recipes.
+function cmdLibInit(target) {
+  const starter = EDITION && path.join(EDITION, 'library-starter');
+  if (!starter || !fs.existsSync(starter)) die('The starter library was not found next to this CLI.', 1);
+  const dest = path.resolve(target);
+  if (fs.existsSync(path.join(dest, 'recipes'))) die(`${dest} already has a library; leaving it alone.`, 1);
+  fs.mkdirSync(dest, { recursive: true });
+  fs.cpSync(starter, dest, { recursive: true });
+  buildIndex(dest);
+  console.log(`Created your recipe library at ${dest}\nAdd recipes with the create-ae-recipe skill or: playrig ae lib new <category>/<id>   then: playrig ae lib index`);
+}
+
+function cmdLibNew(dir, spec) {
+  if (!spec || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(spec)) die('Usage: playrig ae lib new <category>/<id>   (lowercase, hyphens)');
+  const [cat, id] = spec.split('/');
+  const file = path.join(dir, 'recipes', cat, `${id}.md`);
+  if (fs.existsSync(file)) die(`${file} already exists`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `---
+id: ${id}
+name: Human-readable name
+category: ${cat}
+status: experimental        # ready | experimental | planned
+summary: One short sentence: what it looks like and what it builds.
+use_when: When the user wants ...
+tags: [tag1, tag2]
+aliases: [other name, industry term]
+composes_with: []
+origin: Where this came from (project / scene)
+preview_times: [0.5]
+params:
+  comp: {type: string, default: "Scene", desc: "Target comp (created if missing)"}
+---
+
+# Human-readable name
+
+## What it looks like
+Describe the result in plain words, as you would brief an artist.
+
+## How it works
+The After Effects mechanics (effects, animators, expressions, rigs) in a few lines.
+
+## Tweaks that matter
+| Setting | Effect |
+|---|---|
+| \`param\` | what changes visually, with useful values |
+
+## Gotchas
+- Anything that bit you.
+
+## Script
+Parameters arrive as \`P.<name>\`. ES3 only. Helpers from \`_common.jsx\` (\`lib*\`) are available.
+
+\`\`\`jsx
+var comp = libTargetComp();
+PLAYRIG.log("TODO: build something in " + comp.name);
+\`\`\`
+`);
+  console.log(`Created ${file}\nEdit it, then: playrig ae lib check && playrig ae lib run ${id} --param comp=TEST --save-preview && playrig ae lib index`);
+}
+
+async function cmdLib(pos, flags) {
+  const dir = libDir(flags);
+  const [sub, arg] = pos;
+  if (sub === 'init') return cmdLibInit(arg || flags.lib || C.userLibrary());
+  if (sub !== 'new' && !fs.existsSync(path.join(dir, 'recipes'))) die(`No recipe library at ${dir}.\nPlayrig does not ship recipes. Create your own library there with: playrig ae lib init\n(or point to an existing one with --lib <folder> or $PLAYRIG_LIBRARY).`, 1);
+  if (sub === 'list') return cmdLibList(dir, pos.slice(1).join(' '), flags);
+  if (sub === 'show') return cmdLibShow(dir, arg, flags);
+  if (sub === 'index') return buildIndex(dir);
+  if (sub === 'check') return cmdLibCheck(dir);
+  if (sub === 'new') return cmdLibNew(dir, arg);
+  if (sub !== 'run') die(USAGE);
+
+  const recipe = findRecipe(dir, arg);
+  if (recipe.status === 'planned' || !recipe.script) die(`"${recipe.id}" is planned and has no script yet. See ${rel(dir, recipe.file)} for how it is built.`, 1);
+  const P = resolveParams(recipe, flags);
+  if (flags.replace && recipe.idempotent === false) {
+    die(`"${recipe.id}" can't be replaced in place: ${oneLine(recipe.replace_note || 'it changes existing layers')}`, 1);
+  }
+  const instance = flags.instance || 'default';
+  if (!/^[A-Za-z0-9_-]{1,32}$/.test(instance)) die('--instance must match ^[A-Za-z0-9_-]{1,32}$');
+  const common = fs.readFileSync(path.join(dir, '_common.jsx'), 'utf8');
+  // `var P` goes on the first line (no newline) so recipe line numbers match the script block; helpers go at the end (hoisted).
+  const recipeMeta = JSON.stringify({ recipe: recipe.id, instance, replace: !!flags.replace });
+  const source = `var P = ${JSON.stringify(P)}; var __AEB = ${recipeMeta}; __aebPre(); ${recipe.script}\n__aebPost();\n${common}`;
+  const root = rootDir(flags);
+  const options = { action: `recipe.${recipe.id}`, actionLabel: recipe.name, description: oneLine(recipe.summary).slice(0, 240) };
+  if (flags.desc) options.description = String(flags.desc).slice(0, 240);
+  if (!flags['no-snap'] && recipe.preview_times && recipe.preview_times.length) {
+    options.snapshots = [{ comp: P.comp, times: recipe.preview_times }];
+  }
+  const stamp = new Date().toISOString().replace(/\D/g, '').slice(2, 14);
+  const id = (flags.id || `${recipe.id}-${stamp}`).slice(0, 64);
+  const r = await submitJob(root, id, source, { ...flags, action: undefined, desc: undefined }, options);
+
+  if (flags['save-preview'] && r.status === 'ok') {
+    const rdir = path.dirname(recipe.file);
+    for (const f of previewFiles(recipe)) fs.rmSync(path.join(rdir, f));
+    for (const s of r.snapshots || []) {
+      if (s.ok) fs.copyFileSync(path.join(root, 'out', r.id, s.file), path.join(rdir, `${recipe.id}--t${Number(s.time).toFixed(2)}.png`));
+    }
+    const files = previewFiles(recipe);
+    writePreviewSection(recipe, files);
+    console.log(`saved ${files.length} previews next to ${rel(dir, recipe.file)} and embedded them in its Preview section`);
+  }
+  finish(root, r, flags);
+}
+
+// ------------------------------------------------------------------ scratch: track and remove experimental items
+function scratchFile(root) { return path.join(root, 'scratch-baseline.json'); }
+
+async function scratchJob(root, label, source) {
+  const stamp = new Date().toISOString().replace(/\D/g, '').slice(2, 14);
+  const clean = label === 'clean';
+  const r = await submitJob(root, `scratch-${label}-${stamp}`, source, { snap: [], 'no-undo': true }, {
+    action: clean ? 'scratch.cleanup' : 'scratch.baseline',
+    description: label === 'start' ? 'Recorded the items in the project before experimenting' : clean ? 'Removed the temporary items created while experimenting' : 'Listed the temporary items created while experimenting' });
+  if (r.status !== 'ok') { printResult(root, r); process.exit(1); }
+  return r;
+}
+
+async function cmdScratch(pos, flags) {
+  const root = rootDir(flags);
+  const sub = pos[0];
+  if (sub === 'start') {
+    const r = await scratchJob(root, 'start', 'var ids = [], i; for (i = 1; i <= app.project.numItems; i++) { ids.push(app.project.item(i).id); } PLAYRIG.ret({ project: app.project.file ? app.project.file.fsName : null, ids: ids });');
+    fs.writeFileSync(scratchFile(root), JSON.stringify(r.returnValue));
+    console.log(`Baseline recorded: ${r.returnValue.ids.length} items in ${r.returnValue.project || '(unsaved project)'}. Run \`playrig ae scratch clean --yes\` when done experimenting.`);
+    return;
+  }
+  if (sub !== 'status' && sub !== 'clean') die(USAGE);
+  if (!fs.existsSync(scratchFile(root))) die('No baseline. Run: playrig ae scratch start', 1);
+  const base = JSON.parse(fs.readFileSync(scratchFile(root), 'utf8'));
+  const remove = sub === 'clean' && flags.yes;
+  const job = `var keep = {}, ids = ${JSON.stringify(base.ids)}, i, it, found = [], out = [];
+for (i = 0; i < ids.length; i++) { keep["i" + ids[i]] = true; }
+if (${JSON.stringify(base.project)} !== (app.project.file ? app.project.file.fsName : null)) { throw new Error("A different project is open than when the baseline was recorded. Run: playrig ae scratch start"); }
+for (i = 1; i <= app.project.numItems; i++) { it = app.project.item(i); if (!keep["i" + it.id]) { found.push(it); } }
+for (i = 0; i < found.length; i++) { out.push((found[i] instanceof CompItem ? "comp" : (found[i] instanceof FolderItem ? "folder" : "footage")) + ": " + found[i].name); }
+${remove ? 'for (i = 0; i < found.length; i++) { try { found[i].remove(); } catch (e) { } }' : ''}
+PLAYRIG.ret({ items: out, removed: ${remove ? 'true' : 'false'}, remaining: app.project.numItems });`;
+  const r = await scratchJob(root, remove ? 'clean' : 'status', job);
+  const v = r.returnValue;
+  const counts = {};
+  for (const l of v.items) counts[l] = (counts[l] || 0) + 1;
+  console.log(`${v.items.length} item(s) created since the baseline:`);
+  Object.entries(counts).forEach(([k, n]) => console.log(`  ${n > 1 ? n + 'x ' : ''}${k}`));
+  if (v.removed) console.log(`\nRemoved. ${v.remaining} items remain (baseline had ${base.ids.length}).`);
+  else if (sub === 'clean') console.log('\nDry run only. Check the list is all yours, then re-run with --yes.');
+}
+
+// Subcommands for `playrig ae <sub>`. Returns a promise (or exits).
+async function main(sub, pos, flags) {
+  if (sub === 'run') return cmdRun(pos, flags);
+  if (sub === 'status') return cmdStatus(pos, flags);
+  if (sub === 'tail') return cmdTail(flags);
+  if (sub === 'lib') return cmdLib(pos, flags);
+  if (sub === 'scratch') return cmdScratch(pos, flags);
+  if (sub === 'snap') return cmdSnap(pos, flags);
+  if (sub === 'inspect') return cmdInspect(pos, flags);
+  return die(USAGE);
+}
+
+// snap / inspect: a no-op job that only carries the snapshot / inspect request.
+async function cmdSnap(pos, flags) {
+  if (!pos.length) die('Usage: playrig ae snap "<comp>@t1,t2,..." [more specs]');
+  const root = rootDir(flags);
+  const r = await submitJob(root, flags.id || defaultId('snap'), 'PLAYRIG.log("snapshot");', { ...flags, snap: [...flags.snap, ...pos], action: 'frame.export', desc: flags.desc || 'Exported frames', 'no-undo': true }, {});
+  finish(root, r, flags);
+}
+async function cmdInspect(pos, flags) {
+  if (!pos[0]) die('Usage: playrig ae inspect "<comp>:<depth>"');
+  const root = rootDir(flags);
+  const r = await submitJob(root, flags.id || defaultId('inspect'), 'PLAYRIG.log("inspect");', { ...flags, inspect: pos[0], action: 'project.inspect', desc: flags.desc || 'Inspected a comp', 'no-undo': true }, {});
+  finish(root, r, { ...flags, inspect: pos[0] });
+}
+
+module.exports = { main };