paper-motion 0.2.7 → 0.4.0

package/lib/edit.mjs

@@ -0,0 +1,326 @@
+// Your video: the piece as the user edits it in the studio. Everything here needs no judgment, so the studio does it
+// itself and the agent only reads what happened: the words and numbers of a part, how it arrives, its background and
+// settings, its length, the transition after it, the order, adding, duplicating, swapping and removing parts, the
+// brand's colours, type and pace, and building the first version from the inventory. Every change can be undone.
+//
+// The files stay the source of truth: chain.json (order, seconds, joins), each part's scene.html CONFIG (its content
+// and settings), brand/tokens.json and brand/motion.json (the style).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fillConfig, evalFill, normalize, loadRaw, propose, writePlan, describe } from './inventory.mjs';
+
+const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+const writeJson = (f, v) => fs.writeFileSync(f, JSON.stringify(v, null, 2) + '\n');
+const human = (k) => k.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ').replace(/^./, (c) => c.toUpperCase());
+
+// ── a part's CONFIG ────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The CONFIG object of a scene, read as data (it is a literal: no code of the scene runs). */
+export function readConfig(html) {
+  const start = html.indexOf('const CONFIG = {'), end = html.indexOf('\n};', start);
+  if (start < 0 || end < 0) return {};
+  try { return vm.runInNewContext(`(${html.slice(start + 15, end + 2)})`, Object.create(null), { timeout: 200 }); } catch { return {}; }
+}
+const partFile = (dir, part) => path.join(dir, part.dir, 'scene.html');
+
+// What a person may edit in a part, by how it is edited: words (`text`, `lines`, `rows`, `numbers`, `image`), and the
+// labels they read. The block's own content keys come from its `needs`; its other words from its main text params.
+const LABEL = {
+  text: 'Sentence', mark: 'Words in your accent colour', caption: 'Caption', title: 'Title', line: 'Line under it', label: 'What it counts',
+  command: 'Command', output: 'What it prints', cwd: 'Folder', working: 'While it works', stats: 'Numbers', image: 'Picture', url: 'Address',
+  word: 'The word', name: 'Your name', domain: 'Where to go', corner: 'In the corner', a: 'First line', b: 'Then', bLine: 'Line under it',
+  before: 'Before', after: 'After', words: 'The words that change', items: 'Items', toasts: 'Notifications', bars: 'Bars', points: 'Values',
+  labels: 'Labels', tag: 'Note', value: 'Number', rows: 'Rows', fields: 'Fields', button: 'The button', done: 'When it is done', answer: 'What it shows',
+  query: 'What is typed', placeholder: 'Placeholder', script: 'Script', emphasis: 'Words to stress', shots: 'Words, one per beat', toggle: 'The switch',
+  file: 'File name', code: 'Code', highlight: 'Line to light up', add: 'New lines', remove: 'Lines that go', svg: 'Logo (SVG)', columns: 'Columns', move: 'The move',
+};
+const SKIP = new Set(['background', 'format', 'entrance', 'metal']);
+function asField(key, value) {
+  if (Array.isArray(value)) {
+    if (value.every((x) => typeof x === 'string' || typeof x === 'number')) return { key, kind: 'lines', value: value.join('\n') };
+    if (value.every((x) => Array.isArray(x))) {
+      // a column empty in every row (a unit nobody uses) is left out of what the person edits, and put back on save
+      const shape = value[0]?.map((c) => (typeof c === 'number' ? 'n' : Array.isArray(c) ? 'list' : 's')) ?? [];
+      const hide = shape.map((_, i) => value.every((r) => r[i] === '' || r[i] == null));
+      return { key, kind: 'rows', value: value.map((r) => r.filter((_, i) => !hide[i]).map((c) => (Array.isArray(c) ? c.join(', ') : c)).join(' | ')).join('\n'), shape, hide, columns: shape.length - hide.filter(Boolean).length };
+    }
+    if (value.every((x) => x && typeof x === 'object' && 'text' in x)) return { key, kind: 'lines', value: value.map((x) => x.text).join('\n'), objects: true };
+    return null;
+  }
+  if (value && typeof value === 'object') return Object.entries(value).filter(([, v]) => typeof v !== 'object').map(([k, v]) => ({ key: `${key}.${k}`, kind: typeof v === 'number' ? 'number' : 'text', value: String(v ?? ''), label: `${LABEL[key] ?? human(key)}: ${(LABEL[k] ?? human(k)).toLowerCase()}` }));
+  if (typeof value === 'number') return { key, kind: 'number', value: String(value) };
+  if (typeof value === 'string') return { key, kind: key === 'image' || /\.(jpe?g|png|webp)$/i.test(value) ? 'image' : value.includes('\n') ? 'block' : 'text', value };
+  return null;
+}
+export function wordFields(block, cfg) {
+  // the content a block always shows (an optional need, such as a track's tempo, is a setting, not words)
+  const keys = new Set(block.needs?.filter((n) => !n.optional).flatMap((n) => Object.keys(n.fill ?? {})) ?? []);
+  for (const p of block.params ?? []) if (p.type === 'string' && p.group === 'main' && p.control === 'text') keys.add(p.name);
+  return [...keys].filter((k) => !SKIP.has(k) && k in cfg).flatMap((k) => [asField(k, cfg[k])].flat().filter(Boolean)).map((f) => ({ ...f, label: f.label ?? LABEL[f.key] ?? human(f.key) }));
+}
+/** A field's text back into its CONFIG value, shaped like the value it replaces. */
+function fromField(key, text, cfg) {
+  const [k, sub] = key.split('.'), old = cfg[k];
+  if (sub) { const o = { ...(old ?? {}) }; o[sub] = typeof old?.[sub] === 'number' && Number.isFinite(Number(text)) ? Number(text) : text; return [k, o]; }
+  const f = asField(k, old);
+  const rows = String(text ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+  if (!f || f.kind === 'text' || f.kind === 'block' || f.kind === 'image') return [k, String(text ?? '')];
+  if (f.kind === 'number') { const n = Number(text); if (!Number.isFinite(n)) throw new Error('a number, please'); return [k, n]; }
+  if (f.kind === 'lines' && f.objects) return [k, rows.map((t, i) => ({ check: true, text: t.replace(/^[✓✔√]\s*/, ''), ...(i === rows.length - 1 ? { result: true } : {}) }))];
+  if (f.kind === 'lines') return [k, rows.map((t) => (typeof old?.[0] === 'number' && Number.isFinite(Number(t)) ? Number(t) : t))];
+  return [k, rows.map((l) => {
+    const typed = l.split(/\s*\|\s*/); let j = 0;
+    return f.shape.map((t, i) => { if (f.hide[i]) return t === 'n' ? 0 : ''; const c = typed[j++]; return t === 'n' ? Number(String(c ?? '0').replace(/,/g, '')) || 0 : t === 'list' ? String(c ?? '').split(/\s*,\s*/).filter(Boolean) : c ?? ''; });
+  })];
+}
+
+// What of a block a person may tune: its numbers and its either/or choices. The setting a repeating block varies
+// (a sentence's entrance) is its Motion, chosen by watching each; the rest are Tune.
+const NOT_TUNED = new Set(['format', 'background', 'fps', 'codec', 'winner', 'mark', 'detail', 'highlight']);
+export function tunables(block, cfg = {}) {
+  const content = new Set(block.needs?.filter((n) => !n.optional).flatMap((n) => Object.keys(n.fill ?? {})) ?? []);
+  return (block.params ?? []).filter((p) => !content.has(p.name) && !NOT_TUNED.has(p.name) && p.name !== block.repeat?.param && (p.type === 'enum' || p.type === 'number')).map((p) => {
+    const d = p.default, num = p.type === 'number', min = num ? p.min ?? +(d * 0.4).toFixed(2) : null, max = num ? p.max ?? +(d * 1.8).toFixed(2) : null;
+    return { name: p.name, label: (p.description ?? p.name).replace(/^./, (c) => c.toUpperCase()), kind: num ? 'number' : 'enum', options: p.options ?? null, min, max, step: num ? +Math.max((max - min) / 40, 0.01).toFixed(2) : null, default: d, value: cfg[p.name] ?? d };
+  });
+}
+
+// ── undo ───────────────────────────────────────────────────────────────────────────────────────────────────────
+// Before a change, the files it will touch are kept; undo puts the last set back. Forty steps.
+const histFile = (dir) => path.join(dir, '.history.json');
+export function snapshot(cwd, dir, files, label) {
+  const h = readJson(histFile(dir), []);
+  h.push({ label, at: new Date().toISOString(), files: Object.fromEntries(files.map((f) => [path.relative(cwd, f), fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : null])) });
+  writeJson(histFile(dir), h.slice(-40));
+}
+export function undo(cwd, dir) {
+  const h = readJson(histFile(dir), []), last = h.pop();
+  if (!last) throw new Error('nothing to undo');
+  for (const [rel, content] of Object.entries(last.files)) { const f = path.join(cwd, rel); if (content === null) fs.rmSync(f, { force: true }); else { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, content); } }
+  writeJson(histFile(dir), h);
+  return last.label;
+}
+export const canUndo = (dir) => readJson(histFile(dir), []).at(-1)?.label ?? null;
+
+// ── reading the video ──────────────────────────────────────────────────────────────────────────────────────────
+
+/** The parts as the editor shows them: each with its block, its words, motion, background, settings and join. */
+export function videoView(cwd, dir, scenes) {
+  const chain = readJson(path.join(dir, 'chain.json'), null);
+  if (!chain) return null;
+  const byId = new Map(scenes.map((b) => [b.id, b]));
+  const parts = (chain.parts ?? []).filter((p) => p.dir && fs.existsSync(partFile(dir, p))).map((p, i, all) => {
+    const html = fs.readFileSync(partFile(dir, p), 'utf8'), cfg = readConfig(html), b = byId.get(p.id) ?? { id: p.id, params: [], needs: [] };
+    const motion = b.repeat ? { param: b.repeat.param, value: cfg[b.repeat.param] ?? null, options: (b.params ?? []).find((x) => x.name === b.repeat.param)?.options ?? [], previews: b.repeat.previews ?? {} } : null;
+    return {
+      dir: p.dir, id: p.id, title: b.title ?? p.id, kind: b.needs?.[0]?.kind ?? null, summary: b.summary ?? '', seconds: p.seconds ?? b.duration ?? 4, duration: b.duration ?? null,
+      join: i < all.length - 1 ? p.join ?? chain.join ?? 'whip' : null, shows: p.shows ?? [], what: p.what ?? '',
+      words: wordFields(b, cfg), motion, background: cfg.background ?? null, takesBackground: (b.params ?? []).some((x) => x.name === 'background'), tune: tunables(b, cfg),
+      mtime: Math.round(fs.statSync(partFile(dir, p)).mtimeMs),
+    };
+  });
+  return { title: chain.title, format: chain.format, parts, total: +parts.reduce((t, p) => t + Number(p.seconds || 0), 0).toFixed(1) };
+}
+
+/** A sentence made ready for any block that shows one: the words to mark (its last few, when none were chosen) and
+ *  the text around them, worked out again from the sentence as it is now. */
+function complete(i) {
+  if (i.kind !== 'line' || !i.text) return i;
+  let mark = i.mark && i.text.includes(i.mark) ? i.mark : null;
+  if (!mark) { const w = i.text.trim().split(/\s+/); mark = w.slice(-Math.max(1, Math.ceil(w.length / 3))).join(' '); }
+  const at = i.text.lastIndexOf(mark);
+  return { ...i, mark, before: i.text.slice(0, at).trimEnd(), after: i.text.slice(at + mark.length).trimStart() };
+}
+
+/** The reverse of a fill: which item fields a part's CONFIG holds, for the plain "$field" entries of its template. */
+function unfill(tpl, cfg) {
+  const out = {};
+  for (const [k, v] of Object.entries(tpl ?? {})) if (typeof v === 'string' && v.startsWith('$') && !v.startsWith('$brief.') && cfg[k] !== undefined && typeof cfg[k] !== 'object') out[v.slice(1)] = cfg[k];
+  return out;
+}
+
+// ── changing it ────────────────────────────────────────────────────────────────────────────────────────────────
+
+const pad = (n) => String(n).padStart(2, '0');
+async function install(cwd, dir, blockId, format) {
+  const { add, getItem } = await import('./registry.mjs');
+  const it = await getItem(blockId);
+  const nums = fs.readdirSync(dir).map((d) => Number(d.match(/^(\d+)-/)?.[1] ?? 0)), sub = `${pad(Math.max(0, ...nums) + 1)}-${blockId}`;
+  const hasFormat = (it.params ?? []).some((x) => x.name === 'format');
+  await add([blockId], { cwd, force: true, name: path.join(path.relative(path.join(cwd, 'pieces'), dir), sub), set: hasFormat && format ? [`format=${format}`] : [] });
+  return { sub, item: it };
+}
+
+/**
+ * One edit to the video, from the studio. Returns { say } (what happened, in the user's words) and what to redraw.
+ * a: { type, part?, key?, value?, at?, block?, to? }
+ */
+export async function editVideo(cwd, dir, a, scenes, brief = {}) {
+  const chainFile = path.join(dir, 'chain.json'), chain = readJson(chainFile, null);
+  if (!chain && !['build'].includes(a.type)) throw new Error('there is no video yet');
+  const find = () => { const p = chain.parts.find((x) => x.dir === a.part); if (!p) throw new Error('no such part'); return p; };
+  const byId = new Map(scenes.map((b) => [b.id, b]));
+  const keep = (files, label) => snapshot(cwd, dir, files, label);
+  const setCfg = (p, values) => { const f = partFile(dir, p); fs.writeFileSync(f, fillConfig(fs.readFileSync(f, 'utf8'), values)); };
+  const cfgOf = (p) => readConfig(fs.readFileSync(partFile(dir, p), 'utf8'));
+  const title = (p) => byId.get(p.id)?.title ?? p.id;
+  switch (a.type) {
+    case 'word': {
+      const p = find(); keep([partFile(dir, p)], `the words of ${title(p)}`);
+      const [k, v] = fromField(a.key, a.value, cfgOf(p)); setCfg(p, { [k]: v });
+      return { say: `Changed the words of ${title(p)}`, part: p.dir };
+    }
+    case 'motion': case 'tune': {
+      const p = find(), b = byId.get(p.id); keep([partFile(dir, p)], `${a.type === 'motion' ? 'how' : 'a setting of'} ${title(p)}`);
+      const t = a.type === 'motion' ? { name: b?.repeat?.param, kind: 'enum', options: (b?.params ?? []).find((x) => x.name === b?.repeat?.param)?.options } : tunables(b ?? {}, cfgOf(p)).find((x) => x.name === a.key);
+      if (!t?.name) throw new Error('that is not a setting of this part');
+      let v = a.value;
+      if (v === '' || v == null) v = (b.params ?? []).find((x) => x.name === t.name)?.default;
+      else if (t.kind === 'number') { v = Math.min(t.max, Math.max(t.min, Number(v))); if (!Number.isFinite(v)) throw new Error('a number, please'); }
+      else if (!t.options.includes(v)) throw new Error('not one of the choices');
+      setCfg(p, { [t.name]: v });
+      return { say: `${title(p)}: ${a.type === 'motion' ? 'arrives' : (t.label ?? t.name).toLowerCase()} ${v}`, part: p.dir };
+    }
+    case 'background': {
+      const takes = (p) => (byId.get(p.id)?.params ?? []).some((x) => x.name === 'background');
+      const targets = (a.all ? chain.parts.filter((x) => x.dir) : [find()]).filter(takes);
+      if (!targets.length) throw new Error('this part draws its own background');
+      keep(targets.map((p) => partFile(dir, p)), a.all ? 'the background of every part' : `the background of ${title(targets[0])}`);
+      for (const p of targets) setCfg(p, { background: a.value || null });
+      return { say: a.all ? `Background on every part: ${a.value || "the brand's first"}` : `${title(targets[0])}: background ${a.value || "the brand's first"}`, part: a.all ? null : targets[0].dir };
+    }
+    case 'seconds': {
+      const p = find(), n = Number(a.value); if (!Number.isFinite(n)) throw new Error('give a length in seconds');
+      keep([chainFile], `the length of ${title(p)}`); p.seconds = Math.max(1, Math.min(30, +n.toFixed(1))); writeJson(chainFile, chain);
+      return { say: `${title(p)}: ${p.seconds} s`, part: p.dir };
+    }
+    case 'join': {
+      const { JOINS } = await import('./chain.mjs'); if (!(a.value in JOINS)) throw new Error('bad transition');
+      keep([chainFile], 'a transition');
+      if (a.all) { for (const p of chain.parts) p.join = a.value; chain.join = a.value; } else find().join = a.value;
+      writeJson(chainFile, chain);
+      return { say: a.all ? `Every transition: ${a.value}` : `Transition after ${title(find())}: ${a.value}` };
+    }
+    case 'order': {
+      const by = new Map(chain.parts.map((x) => [x.dir, x]));
+      if (a.value.length !== chain.parts.length || a.value.some((d) => !by.has(d))) throw new Error('bad order');
+      keep([chainFile], 'the order'); chain.parts = a.value.map((d) => by.get(d)); writeJson(chainFile, chain);
+      return { say: 'New order' };
+    }
+    case 'remove': {
+      if (chain.parts.length < 2) throw new Error('a video needs one part at least');
+      const p = find(); keep([chainFile], `removing ${title(p)}`);
+      chain.parts = chain.parts.filter((x) => x !== p); writeJson(chainFile, chain);
+      return { say: `Removed ${title(p)}` };
+    }
+    case 'duplicate': {
+      const p = find(); keep([chainFile], `duplicating ${title(p)}`);
+      const nums = fs.readdirSync(dir).map((d) => Number(d.match(/^(\d+)-/)?.[1] ?? 0)), sub = `${pad(Math.max(0, ...nums) + 1)}-${p.id}`;
+      fs.mkdirSync(path.join(dir, sub), { recursive: true });
+      for (const f of fs.readdirSync(path.join(dir, p.dir))) if (fs.statSync(path.join(dir, p.dir, f)).isFile()) fs.copyFileSync(path.join(dir, p.dir, f), path.join(dir, sub, f));
+      chain.parts.splice(chain.parts.indexOf(p) + 1, 0, { ...p, dir: sub }); writeJson(chainFile, chain);
+      return { say: `Duplicated ${title(p)}`, part: sub };
+    }
+    case 'add': case 'swap': {
+      // a new block, filled with something true: the content of the part it replaces, else a kept inventory item it
+      // can show that is not in the video yet, else the block's own sample words for the user to replace
+      const b = byId.get(a.block); if (!b) throw new Error('no such block');
+      const old = a.type === 'swap' ? find() : null;
+      keep([chainFile], a.type === 'swap' ? `showing ${title(old)} another way` : `adding ${b.title}`);
+      const { sub } = await install(cwd, dir, b.id, chain.format);
+      const items = normalize(loadRaw(dir), { cwd }).items, shown = new Set(chain.parts.flatMap((x) => x.shows ?? []));
+      const need = b.needs?.[0], fits = (i) => need && i.kind === need.kind && (need.has ?? []).every((f) => i[f] !== undefined && i[f] !== '') && Object.entries(need.where ?? {}).every(([k, v]) => i[k] === v);
+      // what the old part says now (the user may have changed its words since): read back through its own fill
+      const back = old ? unfill(byId.get(old.id)?.needs?.[0]?.fill, cfgOf(old)) : {};
+      if (back.mark !== undefined && back.before !== undefined) back.text = [back.before, back.mark, back.after].filter(Boolean).join(' ');   // a marked sentence, whole again
+      if (typeof back.text === 'string') back.text = back.text.replace(/\s+/g, ' ').trim();
+      const from = (old?.shows ?? []).map((id) => items.find((i) => i.id === id)).filter(Boolean).map((i, k) => (k === 0 ? complete({ ...i, ...back }) : i));
+      // showing the same thing another way keeps its content, even when the new way wants a little more of it
+      const same = from.length && from.every((i) => i.kind === need?.kind);
+      const pool = same ? from : [...items.filter((i) => fits(i) && !shown.has(i.id))];
+      const group = need ? pool.slice(0, need.count ?? 1) : [];
+      const part = { id: b.id, dir: sub, name: b.title, seconds: b.duration ?? 4, ...(group.length ? { shows: group.map((i) => i.id), what: group.map(describe).join(' · ') } : {}) };
+      if (group.length >= (need?.count ?? 1)) {
+        const fill = evalFill(need.fill, group, brief);
+        for (const n of b.needs.slice(1)) if (n.kind === 'name') Object.assign(fill, evalFill(n.fill, [], brief));
+        setCfg(part, fill);
+      } else if (old && byId.get(old.id)?.needs?.[0]?.kind === need?.kind) {
+        // the same kind of content: carry the words over field by field where the names match
+        const prev = cfgOf(old), next = cfgOf(part), carry = Object.fromEntries(Object.keys(next).filter((k) => k in prev && !['format'].includes(k)).map((k) => [k, prev[k]]));
+        setCfg(part, carry);
+      }
+      if (old) { const bg = cfgOf(old).background; if (bg) setCfg(part, { background: bg }); part.join = old.join; part.seconds = old.seconds; chain.parts.splice(chain.parts.indexOf(old), 1, part); }
+      else chain.parts.splice(Math.max(0, Math.min(chain.parts.length, Number(a.at ?? chain.parts.length))), 0, part);
+      writeJson(chainFile, chain);
+      return { say: old ? `${title(old)} is now ${b.title}` : `Added ${b.title}${group.length ? `, showing ${part.what}` : ': write its words'}`, part: sub };
+    }
+    case 'build': {
+      // the first version, from what the user kept: the planner's structure, installed with its content
+      const items = normalize(loadRaw(dir), { cwd }).items;
+      if (!items.length) throw new Error('keep something to show first');
+      const secs = Number(String(brief.format ?? '').match(/(\d+(?:\.\d+)?)\s*(?:s\b|sec|seconds?)/i)?.[1]) || 25;
+      const options = propose(items, scenes, { seconds: secs, brief });
+      if (!options.length) throw new Error('nothing kept can be shown by a ready-made part yet');
+      writePlan(dir, options, { seconds: secs });
+      const o = options.find((x) => x.letter === (a.value ?? 'A')) ?? options[0];
+      if (chain) keep([chainFile], 'building it again');
+      const f = String(brief.format ?? ''), format = /9\s*:\s*16/.test(f) ? '1080x1920' : /1\s*:\s*1/.test(f) ? '1080x1080' : chain?.format ?? '1920x1080';
+      const look = await ensureLook(cwd, brief.title ?? chain?.title);
+      const { initChain } = await import('./chain.mjs');
+      const parts = o.beats.map((bt) => ({ id: bt.id, name: bt.name, seconds: +(bt.to - bt.from).toFixed(1), what: bt.what, ...(bt.items.length ? { shows: bt.items } : {}) }));
+      const r = await initChain({ cwd, piece: path.relative(path.join(cwd, 'pieces'), dir), title: brief.title ?? chain?.title, parts, format, force: true });
+      r.chain.parts.forEach((p, i) => { if (p.dir && o.beats[i]?.fill && Object.keys(o.beats[i].fill).length) setCfg(p, o.beats[i].fill); });
+      return { say: `Built your video: ${o.title.toLowerCase()}, ${o.beats.length} parts${look ? ` (no look yet: ${look.join(', ')}; change it in Style)` : ''}`, options: options.map((x) => ({ letter: x.letter, title: x.title, why: x.why })) };
+    }
+    default: throw new Error(`unknown edit ${a.type}`);
+  }
+}
+
+// ── the style: the brand's colours, type and pace ──────────────────────────────────────────────────────────────
+
+export function styleView(cwd) {
+  const t = readJson(path.join(cwd, 'brand/tokens.json'), {}), m = readJson(path.join(cwd, 'brand/motion.json'), {});
+  const c = (k) => t.colors?.[k]?.hex ?? null;
+  const stamp = ['brand/tokens.json', 'brand/motion.json', 'brand/shader-set/set.json'].map((f) => { try { return Math.round(fs.statSync(path.join(cwd, f)).mtimeMs); } catch { return 0; } }).join('-');
+  // the brand's own pictures, for a part that shows one
+  const dir = path.join(cwd, 'brand/assets'), images = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /\.(jpe?g|png|webp)$/i.test(f) && !/wordmark|logo/i.test(f)).map((f) => `/brand/assets/${f}`) : [];
+  return { colors: { ground: c('ground'), figure: c('figure'), accent: c('accent') }, fonts: { display: t.fonts?.display?.family ?? null, text: t.fonts?.text?.family ?? null }, pace: m.pace ?? 'medium', stamp, images };
+}
+/**
+ * A project with no look yet (no colours in brand/tokens.json) renders grey on grey and calls itself "brand".
+ * Before a video is built, give it a quiet default named after the piece, which the user changes in Style:
+ * a palette, a font pair and one background. Returns what was installed, or null when it already had a look.
+ */
+export async function ensureLook(cwd, name) {
+  const t = readJson(path.join(cwd, 'brand/tokens.json'), {});
+  if (Object.keys(t.colors ?? {}).length) return null;
+  const { add } = await import('./registry.mjs');
+  await add(['graphite', 'geist-serif'], { cwd, ...(name ? { brand: name } : {}) });
+  const set = readJson(path.join(cwd, 'brand/shader-set/set.json'), {});
+  const installed = ['graphite', 'geist-serif'];
+  if (!(Array.isArray(set) ? set : set.entries ?? []).length) { await add(['mesh-graphite'], { cwd, palette: 'brand' }); installed.push('mesh-graphite'); }
+  return installed;
+}
+
+export async function editStyle(cwd, dir, a) {
+  const tokens = path.join(cwd, 'brand/tokens.json'), motion = path.join(cwd, 'brand/motion.json');
+  snapshot(cwd, dir, [tokens, motion, path.join(cwd, 'brand/fonts.css')], 'the style');
+  if (a.type === 'palette' || a.type === 'font') {
+    const { add } = await import('./registry.mjs');
+    await add([a.value], { cwd, force: true });
+    return { say: `${a.type === 'palette' ? 'Colours' : 'Type'}: ${a.value}` };
+  }
+  if (a.type === 'color') {
+    if (!/^#[0-9a-f]{6}$/i.test(a.value) || !['ground', 'figure', 'accent'].includes(a.key)) throw new Error('bad colour');
+    const t = readJson(tokens, {}); t.colors ??= {}; t.colors[a.key] = { ...(t.colors[a.key] ?? {}), hex: a.value.toUpperCase() }; writeJson(tokens, t);
+    return { say: `${{ ground: 'Background', figure: 'Text', accent: 'Accent' }[a.key]} colour ${a.value}` };
+  }
+  if (a.type === 'pace') {
+    if (!['calm', 'medium', 'fast'].includes(a.value)) throw new Error('bad pace');
+    const m = readJson(motion, {}); m.pace = a.value; writeJson(motion, m);
+    return { say: `Pace: ${a.value}` };
+  }
+  throw new Error(`unknown style edit ${a.type}`);
+}

package/lib/gather.mjs

@@ -0,0 +1,241 @@
+// Gathering an inventory: reads what the user already has (their site, a README, the brand's Facts, a folder of
+// assets) and proposes items for pieces/<piece>/inventory.json. Everything it finds is a proposal: it carries its
+// source and waits for the user, who keeps or removes each one in the studio. Nothing here guesses a claim; it only
+// copies what is written or shown, and says what a proposal still lacks (a command's real output, for one).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+const slug = (s, n = 4) => clean(s).toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').trim().split(/\s+/).filter(Boolean).slice(0, n).join('-') || 'item';
+const CLI = /^(npx|npm|pnpm|yarn|bun|bunx|pip|pipx|uv|brew|curl|wget|git|docker|cargo|go|deno|gem|apt|composer|make)\b/;
+const NUM = /^([~≈<>+]?\$?)(\d[\d.,]*)\s?(%|[kKmMbB]|x|×|ms|s|min|h|hrs?|\+)?(\+?)$/;
+const IMG = /\.(jpe?g|png|webp)$/i, VID = /\.(mp4|mov|webm)$/i, AUD = /\.(wav|mp3|m4a|aac|flac)$/i;
+
+/** A number as written ("1,284", "2 min", "87%") into a figure or a share. */
+function figureFrom(raw, label, source) {
+  const m = clean(raw).match(NUM); if (!m || !clean(label)) return null;
+  const n = Number(m[2].replace(/,/g, '')); if (!Number.isFinite(n)) return null;
+  if (m[3] === '%' && n >= 0 && n <= 100) return { kind: 'share', value: n, label: clean(label), source };
+  const unit = `${m[3] ? (/^[a-z]/i.test(m[3]) && m[3].length > 1 ? ` ${m[3]}` : m[3]) : ''}${m[4] ?? ''}`;
+  return { kind: 'figure', value: n, ...(unit ? { unit } : {}), label: clean(label), source };
+}
+const commandFrom = (line, source) => ({ kind: 'command', command: clean(line.replace(/^\$\s*/, '')), source });
+// a command worth showing runs the product; cloning a repository or moving between folders shows nothing of it
+const showable = (line) => { const c = line.replace(/^\$\s*/, ''); return CLI.test(c) && !/^(git\s+(clone|pull|checkout|init)|make\s*$|apt\b)/.test(c) && c.length <= 110; };
+// a sentence a screen can hold; longer ones are for reading, not for showing
+const LINE_MAX = 110;
+
+// ── a web page ──────────────────────────────────────────────────────────────────────────────────────────────────
+
+// runs in the page: what is written on it, as plain data
+function readPage() {
+  const vis = (el) => { const r = el.getBoundingClientRect(), s = getComputedStyle(el); return r.width > 1 && r.height > 1 && s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) > 0.05; };
+  const txt = (el) => (el.innerText ?? '').replace(/\s+/g, ' ').trim();
+  const all = (q) => [...document.querySelectorAll(q)].filter(vis);
+  const NUM = /^([~≈<>+]?\$?)(\d[\d.,]*)\s?(%|[kKmMbB]|x|×|ms|s|min|h|hrs?|\+)?(\+?)$/;
+  // figures: a short number set large, and the words next to it
+  const stats = [];
+  for (const el of all('body *')) {
+    if (el.children.length || stats.length >= 12) continue;
+    const t = txt(el); if (!t || t.length > 12 || !NUM.test(t) || parseFloat(getComputedStyle(el).fontSize) < 20) continue;
+    let label = '', up = el;
+    // the label: the words around the number, without what can be clicked (a button's text is not what the figure counts)
+    for (let i = 0; i < 3 && !label && up.parentElement; i++) {
+      up = up.parentElement;
+      let rest = txt(up);   // innerText: only what is really drawn (a hidden twin of the number is not)
+      for (const b of up.querySelectorAll('button, a, [role="button"]')) rest = rest.replace(txt(b), '');
+      rest = rest.replace(t, '').replace(/\s+/g, ' ').trim();
+      if (rest.length >= 3 && rest.length <= 70 && /[a-z]{3}/i.test(rest)) label = rest;
+    }
+    // a lone word after a number is a step or a tab ("1 Brief"), not a figure
+    if (label && label.split(' ').length >= 2) stats.push([t, label]);
+  }
+  const pres = all('pre').map((p) => p.innerText.trim()).filter((t) => t && t.length <= 900).slice(0, 8);
+  const inline = all('code').filter((c) => !c.closest('pre')).map(txt).filter((t) => t.length >= 6 && t.length <= 140);
+  const lists = all('ul,ol').map((l) => [...l.children].filter((c) => c.tagName === 'LI').map(txt)).filter((it) => it.length >= 3 && it.length <= 6 && it.every((x) => x.length >= 2 && x.length <= 28));
+  const h1 = all('h1').map(txt).find(Boolean) ?? '';
+  const lead = all('main p, header p, section p, p').map(txt).find((t) => t.length >= 40 && t.length <= 240) ?? '';
+  const icon = document.querySelector('link[rel~="icon"][type="image/svg+xml"], link[rel~="icon"][href$=".svg"]')?.href ?? null;
+  return {
+    title: document.title, site: document.querySelector('meta[property="og:site_name"]')?.content ?? '', desc: document.querySelector('meta[name="description"]')?.content ?? '',
+    h1, lead, h2: all('h2').map(txt).filter((t) => t.length >= 10 && t.length <= 90).slice(0, 5), stats, pres, inline, lists: lists.slice(0, 3), icon,
+    height: Math.max(document.documentElement.scrollHeight, document.body.scrollHeight),
+  };
+}
+
+/** Proposals from a live page: what it says, its figures, its commands, and screenshots of it on a desktop and a phone. */
+export async function fromUrl(url, { cwd = process.cwd(), assets = 'brand/assets' } = {}) {
+  const { launch } = await import('./browser.mjs');
+  const u = new URL(url), where = `${u.host}${u.pathname === '/' ? '' : u.pathname}`, name = slug(where.replace(/[./]/g, ' '), 5);
+  const out = [], dir = path.join(cwd, assets);
+  fs.mkdirSync(dir, { recursive: true });
+  const browser = await launch();
+  try {
+    const shot = async (file, viewport, mobile, maxH) => {
+      const ctx = await browser.newContext({ viewport, deviceScaleFactor: mobile ? 2 : 1, isMobile: mobile, hasTouch: mobile });
+      const page = await ctx.newPage();
+      await page.goto(url, { waitUntil: 'load', timeout: 45000 });
+      await page.waitForLoadState('networkidle', { timeout: 8000 }).catch(() => {});
+      await page.waitForTimeout(900);
+      // numbers that count up on load are read once they stop moving: a figure caught mid-count would be a false claim
+      let data = await page.evaluate(readPage);
+      for (let i = 0; i < 10; i++) { await page.waitForTimeout(700); const again = await page.evaluate(readPage); const same = JSON.stringify(again.stats) === JSON.stringify(data.stats) && again.h1 === data.h1; data = again; if (same) break; }
+      await page.screenshot({ path: path.join(dir, file), type: 'jpeg', quality: 86, clip: { x: 0, y: 0, width: viewport.width, height: Math.min(data.height, maxH) } });
+      await ctx.close();
+      return data;
+    };
+    const d = await shot(`${name}-desktop.jpg`, { width: 1440, height: 900 }, false, 3200);
+    await shot(`${name}-phone.jpg`, { width: 390, height: 844 }, true, 2200);
+    const src = (part) => `${where}, ${part}`, siteName = clean(d.site) || clean(d.title).split(/\s[·|—–-]\s/)[0];
+    if (d.h1 && d.h1.length <= LINE_MAX) out.push({ kind: 'line', text: clean(d.h1), source: src('the headline') });
+    const about = [[clean(d.desc), 'its description'], [d.lead, 'the first paragraph']].find(([t]) => t && t !== clean(d.h1) && t.length <= LINE_MAX);
+    if (about) out.push({ kind: 'line', text: about[0], source: src(about[1]) });
+    for (const h of d.h2.filter((x) => x !== d.h1).slice(0, 2)) out.push({ kind: 'line', text: h, source: src('a heading') });
+    for (const [n, label] of d.stats.slice(0, 6)) { const f = figureFrom(n, label, src('a number on the page')); if (f) out.push(f); }
+    for (const pre of d.pres) {
+      const lines = pre.split('\n').map((l) => l.trim()).filter(Boolean), cmd = lines.find(showable);
+      if (cmd && lines.length <= 4) out.push(commandFrom(cmd, src('a command on the page')));
+    }
+    for (const c of d.inline.filter(showable).slice(0, 3)) out.push(commandFrom(c, src('a command on the page')));
+    for (const l of d.lists) out.push({ kind: 'words', items: l, source: src('a list') });
+    out.push({ kind: 'screen', image: `${assets}/${name}-desktop.jpg`, url: where, title: siteName, ...(d.h1 ? { caption: clean(d.h1) } : {}), device: 'desktop', source: `a screenshot of ${where}` });
+    out.push({ kind: 'screen', image: `${assets}/${name}-phone.jpg`, url: where, title: siteName, device: 'phone', source: `a screenshot of ${where} on a phone` });
+    if (d.icon) { try { const svg = await (await fetch(d.icon, { signal: AbortSignal.timeout(8000) })).text(); if (/<svg[\s>]/.test(svg) && svg.length < 20000) out.push({ kind: 'logo', svg: svg.trim(), name: siteName, source: src('its icon') }); } catch { /* no icon to read */ } }
+  } finally { await browser.close(); }
+  return out;
+}
+
+// ── a markdown file (a README, a doc) ───────────────────────────────────────────────────────────────────────────
+
+const EXT = { js: 'js', javascript: 'js', ts: 'ts', typescript: 'ts', tsx: 'tsx', jsx: 'jsx', py: 'py', python: 'py', rb: 'rb', go: 'go', rust: 'rs', rs: 'rs', json: 'json', yaml: 'yml', yml: 'yml', html: 'html', css: 'css' };
+const bare = (s) => clean(s.replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/<[^>]+>/g, '').replace(/[*_`]/g, ''));
+
+export function fromMarkdown(file, { cwd = process.cwd() } = {}) {
+  const rel = path.relative(cwd, path.resolve(cwd, file)), md = fs.readFileSync(path.resolve(cwd, file), 'utf8'), out = [], src = (p) => `${rel}, ${p}`;
+  const lines = md.split('\n');
+  let lead = false, cmds = 0, codes = 0, figs = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    const fence = l.match(/^```+\s*([\w+-]*)/);
+    if (fence) {
+      const body = []; i++;
+      while (i < lines.length && !/^```+\s*$/.test(lines[i])) body.push(lines[i++]);
+      const lang = fence[1].toLowerCase(), real = body.map((x) => x.trim()).filter((x) => x && !x.startsWith('#'));
+      const shell = ['sh', 'bash', 'shell', 'zsh', 'console', 'terminal'].includes(lang) || real.some((x) => x.startsWith('$ ')) || (lang === '' && real.every((x) => CLI.test(x)));
+      if (shell) { for (const c of real.filter(showable).slice(0, 2)) if (cmds++ < 4) out.push(commandFrom(c, src('a command'))); }
+      else if (EXT[lang] && real.length >= 3 && real.length <= 18 && codes++ < 2) out.push({ kind: 'code', file: `example${EXT[lang] ? `.${EXT[lang]}` : ''}`, code: body.join('\n').trim(), source: src('a code example') });
+      continue;
+    }
+    if (/^\s*\|.+\|\s*$/.test(l) && /^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1] ?? '')) {
+      const rows = []; i += 2;
+      const cells = [];
+      while (i < lines.length && /^\s*\|.+\|\s*$/.test(lines[i])) { cells.push(lines[i].split('|').slice(1, -1).map(bare)); i++; }
+      // a first column that only counts the rows (1, 2, 3…) is not a name: the pair starts after it
+      const skip = cells.length && cells.every((c) => /^\d+\.?$/.test(c[0] ?? '')) ? 1 : 0;
+      for (const c of cells) if (c[skip] && c[skip + 1]) rows.push([c[skip], c[skip + 1]]);
+      i--; if (rows.length >= 2 && rows.length <= 8 && rows.every((r) => r[0].length <= 32 && r[1].length <= 32)) out.push({ kind: 'table', rows, source: src('a table') });
+      continue;
+    }
+    if (/^\s*[-*+]\s+/.test(l)) {
+      const items = [];
+      while (i < lines.length && /^\s*[-*+]\s+/.test(lines[i])) items.push(bare(lines[i++].replace(/^\s*[-*+]\s+/, '')));
+      i--;
+      if (items.length >= 3 && items.length <= 6 && items.every((x) => x.length >= 2 && x.length <= 28)) out.push({ kind: 'words', items, source: src('a list') });
+      for (const it of items) { const m = it.match(/^([~≈<>+]?\$?\d[\d.,]*\s?(?:%|[kKmMbB]|x|×|ms|s|min|h|hrs?|\+)?\+?)\s+(.{3,60})$/); const f = m && figs < 6 ? figureFrom(m[1], m[2].replace(/[.;,]$/, ''), src('a list')) : null; if (f) { figs++; out.push(f); } }
+      continue;
+    }
+    const t = bare(l);
+    if (!lead && t.length >= 30 && t.length <= LINE_MAX && !/^#/.test(l) && !/^\s*[>|]/.test(l)) { lead = true; out.push({ kind: 'line', text: t, source: src('the first paragraph') }); }
+  }
+  return out;
+}
+
+/** The brand's Facts (IDENTITY.md): its true claims, as lines, figures and commands. */
+export function fromFacts(file, { cwd = process.cwd() } = {}) {
+  const abs = path.resolve(cwd, file); if (!fs.existsSync(abs)) return [];
+  const md = fs.readFileSync(abs, 'utf8'), m = md.match(/^##\s+Facts\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/m);
+  if (!m) return [];
+  const out = [], source = "your brand's facts";
+  for (const raw of m[1].split('\n').filter((l) => /^\s*[-*+]\s+/.test(l))) {
+    const l = raw.replace(/^\s*[-*+]\s+/, '');
+    for (const c of [...l.matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter(showable)) out.push(commandFrom(c, source));
+    const t = bare(l).replace(/\.$/, ''), n = t.match(/^([~≈<>+]?\$?\d[\d.,]*\s?(?:%|[kKmMbB]|x|×|ms|s|min|h|hrs?|\+)?\+?)\s+(.{3,60})$/);
+    const f = n ? figureFrom(n[1], n[2], source) : null;
+    if (f) out.push(f); else if (t.length >= 12 && t.length <= LINE_MAX) out.push({ kind: 'line', text: t, source });
+  }
+  return out;
+}
+
+// ── a folder of the user's own material ─────────────────────────────────────────────────────────────────────────
+
+// width and height of a JPEG or PNG, read from its header (no image library needed)
+function imageSize(file) {
+  try {
+    const b = fs.readFileSync(file);
+    if (b.readUInt32BE(0) === 0x89504e47) return [b.readUInt32BE(16), b.readUInt32BE(20)];
+    if (b.readUInt16BE(0) === 0xffd8) { let i = 2; while (i < b.length) { const marker = b.readUInt16BE(i), len = b.readUInt16BE(i + 2); if (marker >= 0xffc0 && marker <= 0xffcf && ![0xffc4, 0xffc8, 0xffcc].includes(marker)) return [b.readUInt16BE(i + 7), b.readUInt16BE(i + 5)]; i += 2 + len; } }
+  } catch { /* not readable */ }
+  return null;
+}
+
+export function fromFolder(folder, { cwd = process.cwd() } = {}) {
+  const abs = path.resolve(cwd, folder); if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return [];
+  const out = [];
+  for (const f of fs.readdirSync(abs).sort()) {
+    const full = path.join(abs, f), rel = path.relative(cwd, full).split(path.sep).join('/');
+    if (f.startsWith('.') || fs.statSync(full).isDirectory()) continue;
+    const source = `your file ${f}`, base = f.replace(/\.\w+$/, '');
+    if (IMG.test(f)) {
+      const size = imageSize(full), tall = size && size[1] / size[0] > 1.5;
+      // a picture named like a capture, or shaped like a page, is the product; anything else is a photograph
+      if (/screen|shot|capture|site|page|app|ui|dashboard|desktop|phone|mobile/i.test(f) || (size && size[1] / size[0] > 1.9)) out.push({ kind: 'screen', image: rel, title: clean(base.replace(/[-_]+/g, ' ')), device: tall && size[0] < 900 ? 'phone' : 'desktop', source });
+      else if (!/wordmark|logo|favicon|icon/i.test(f)) out.push({ kind: 'photo', image: rel, source });   // the brand's own marks are not photographs
+    } else if (/\.svg$/i.test(f) && /logo|mark|icon|brand/i.test(f)) { const svg = fs.readFileSync(full, 'utf8').trim(); if (svg.length < 30000) out.push({ kind: 'logo', svg, source }); }
+    else if (VID.test(f)) out.push({ kind: 'clip', file: rel, source });
+    else if (AUD.test(f)) out.push({ kind: 'music', file: rel, source });
+  }
+  return out;
+}
+
+// ── putting it together ─────────────────────────────────────────────────────────────────────────────────────────
+
+/** What makes two items the same thing, however they were found. */
+export function keyOf(it) {
+  const k = { line: it.text, figure: `${it.value}|${it.label}`, share: `${it.value}|${it.label}`, change: `${it.from}|${it.to}`, command: it.command, code: it.code, screen: it.image, photo: it.image, clip: it.file, music: it.file ?? it.bpm, logo: (it.svg ?? '').slice(0, 200), words: (it.items ?? []).join('|'), table: JSON.stringify(it.rows ?? []) }[it.kind];
+  return `${it.kind}|${clean(k ?? JSON.stringify(it)).toLowerCase()}`;
+}
+const idFor = (it) => ({ line: slug(it.text ?? '', 3), figure: slug(it.label ?? '', 3), share: slug(it.label ?? '', 3), command: `run-${slug((it.command ?? '').replace(CLI, ''), 2)}`, screen: `${it.device ?? 'screen'}-${slug(it.url ?? it.title ?? it.image ?? '', 3)}`, photo: slug(path.basename(it.image ?? 'photo').replace(/\.\w+$/, ''), 3), clip: slug(path.basename(it.file ?? 'clip').replace(/\.\w+$/, ''), 3), words: slug((it.items ?? []).join(' '), 3), code: slug(it.file ?? 'code', 2), table: 'table', logo: 'logo', music: 'music' }[it.kind] ?? it.kind);
+
+/**
+ * Gathers proposals from every source: a URL, a .md file, a folder, or "brand" (the brand's Facts and its assets).
+ * Returns what is new against `existing` (anything already there, kept or removed, is not proposed again).
+ * `plain` leaves commands and code out, for a brand whose audience does not code.
+ */
+export async function gather(sources, { cwd = process.cwd(), existing = [], plain = false, log = () => {} } = {}) {
+  const found = [], notes = [];
+  for (const s of sources) {
+    try {
+      let got;
+      if (/^https?:\/\//i.test(s)) { log(`reading ${s} …`); got = await fromUrl(s, { cwd }); }
+      else if (s === 'brand') got = [...fromFacts('brand/IDENTITY.md', { cwd }), ...fromFolder('brand/assets', { cwd })];
+      else if (!fs.existsSync(path.resolve(cwd, s))) { notes.push(`${s}: not found`); continue; }
+      else if (fs.statSync(path.resolve(cwd, s)).isDirectory()) got = fromFolder(s, { cwd });
+      else if (/IDENTITY\.md$/i.test(s)) got = fromFacts(s, { cwd });
+      else got = fromMarkdown(s, { cwd });
+      // a brand whose audience does not code: commands and code are left out, however many its files hold
+      if (plain) got = got.filter((i) => !['command', 'code', 'rewrite'].includes(i.kind));
+      notes.push(`${s}: ${got.length} found`);
+      found.push(...got);
+    } catch (e) { notes.push(`${s}: ${e.message.split('\n')[0]}`); }
+  }
+  const have = new Set(existing.map(keyOf)), ids = new Set(existing.map((i) => i.id)), fresh = [];
+  for (const it of found) {
+    const k = keyOf(it); if (have.has(k)) continue;
+    have.add(k);
+    let id = idFor(it), n = 2; while (ids.has(id)) id = `${idFor(it)}-${n++}`;
+    ids.add(id);
+    fresh.push({ id, ...it, status: 'proposed' });
+  }
+  return { fresh, notes };
+}

package/lib/host.mjs

@@ -0,0 +1,25 @@
+// The app the agent runs in, so the studio can send the user back to it ("your agent asked you something").
+// On macOS the CLI walks up its own process tree to the first .app bundle (Claude, Cursor, a terminal…); the studio
+// brings that app to the front with `open -a`. Anywhere, PAPER_MOTION_RETURN (or --return) gives a link instead:
+// the page of a browser-based agent.
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export function hostApp({ url } = {}) {
+  const link = url ?? process.env.PAPER_MOTION_RETURN;
+  if (link && /^https?:\/\//i.test(link)) return { url: link };
+  if (process.platform !== 'darwin') return null;
+  // the topmost .app above this process is the window the user sees (Claude, Cursor, a terminal); bundles further
+  // down are helpers and command-line tools packed as apps
+  let pid = process.ppid, found = null;
+  for (let i = 0; i < 30 && pid > 1; i++) {
+    let out;
+    try { out = execFileSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { break; }
+    const m = out.match(/^(\d+)\s+(.*)$/);
+    if (!m) break;
+    const app = m[2].match(/^(.*?\.app)\//);
+    if (app) found = { app: path.basename(app[1], '.app'), path: app[1] };
+    pid = Number(m[1]);
+  }
+  return found;
+}