From 2e55691fbed0e45dc076e5737886073340092f06 Mon Sep 17 00:00:00 2001
From: srivtx <crypticcc101@gmail.com>
Date: Sat, 24 Oct 2026 01:19:07 +0530
Subject: [PATCH 1/2] morpho: the app from the command line, for AI agents

Designing in the app as an agent meant reading effect and template
sources to learn what exists, and judging work through screenshot after
screenshot. morpho answers in short text or one PNG instead:

- catalog: every material, modifier, shape, preset, recipe, motion and
  keyframe option with ranges and defaults, generated from the
  Inspector's own registries
- describe: a design as a text tree, settings changed from defaults only
- scene / set: templates as .morpho files, edited by Layer.setting=value
  with range checks and errors that list what would work
- render: a frame, or a captioned filmstrip with --at / --frames
- vary: a grid of variations in one image
- check: problems in words (engine errors, off canvas, unseen layers,
  low-contrast text, blank frames, motion jumps, loop seams)
- compare: scores and a difference image against a reference
- serve: a warm browser, so drawing commands take under a second

Catalog, describe and set run in Node through Vite's SSR loader; drawing
runs the app headless on the GPU (SwiftShader with --cpu or as a
fallback), with the live preview held still while a job runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 package.json               |   1 +
 scripts/morpho.mjs         | 357 +++++++++++++++++++++++++++++++++++++
 ui/src/agent/agent.test.ts | 199 +++++++++++++++++++++
 ui/src/agent/catalog.ts    | 240 +++++++++++++++++++++++++
 ui/src/agent/check.ts      | 180 +++++++++++++++++++
 ui/src/agent/describe.ts   | 145 +++++++++++++++
 ui/src/agent/edit.ts       | 200 +++++++++++++++++++++
 ui/src/agent/node.ts       |  14 ++
 ui/src/agent/page.ts       | 344 +++++++++++++++++++++++++++++++++++
 ui/src/main.tsx            |   2 +
 10 files changed, 1682 insertions(+)
 create mode 100644 scripts/morpho.mjs
 create mode 100644 ui/src/agent/agent.test.ts
 create mode 100644 ui/src/agent/catalog.ts
 create mode 100644 ui/src/agent/check.ts
 create mode 100644 ui/src/agent/describe.ts
 create mode 100644 ui/src/agent/edit.ts
 create mode 100644 ui/src/agent/node.ts
 create mode 100644 ui/src/agent/page.ts

diff --git a/package.json b/package.json
index 61a35d0..d5f5d87 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,7 @@
     "preview": "vite preview",
     "test": "cargo test --workspace --exclude morphotype-app && vitest run",
     "test:e2e": "node scripts/e2e.mjs",
+    "morpho": "node scripts/morpho.mjs",
     "typecheck": "tsc --noEmit -p ui",
     "tauri": "tauri"
   },
diff --git a/scripts/morpho.mjs b/scripts/morpho.mjs
new file mode 100644
index 0000000..8423b0c
--- /dev/null
+++ b/scripts/morpho.mjs
@@ -0,0 +1,357 @@
+// morpho: the app from the command line, for AI agents and scripts. Every
+// command answers in short text or one PNG, so learning what exists, reading a
+// design, editing it and judging it doesn't take source reading or a pile of
+// screenshots.
+//
+//   npm run morpho -- catalog [name|section]     what materials, modifiers, shapes, motion… exist
+//   npm run morpho -- describe <scene>            the design as a text tree (changed settings only)
+//   npm run morpho -- scene <template> [-o f]     save a template as an editable .morpho file
+//   npm run morpho -- set <file> <a=b>…           edit a .morpho file; prints what changed
+//   npm run morpho -- render <scene> [opts]       PNG at rest, or a filmstrip with --at / --frames
+//   npm run morpho -- vary <scene> --vary a=1,2   a grid of variations in one PNG
+//   npm run morpho -- check <scene>               problems in words: off canvas, unseen, low contrast, loop jumps…
+//   npm run morpho -- compare <scene> <ref.png>   scores against a reference, and reference | design | difference
+//   npm run morpho -- serve                       keep a browser warm; the drawing commands then take a second
+//
+// <scene> is a template name (or a unique part of one) or a .morpho/.json file.
+// Run `npm run morpho -- help` for every option.
+import { createServer as createHttp } from 'node:http';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PORT = Number(process.env.MORPHO_PORT ?? 7801);
+const OUT_DIR = path.join(root, 'test-results/morpho');
+
+const HELP = `morpho <command> [args] [options]
+
+  catalog [query]          index; a section (materials, modifiers, shapes, motion, keyframes,
+                           layers, presets, recipes, fonts, backgrounds, canvas, templates);
+                           or any name (chrome, glitch, star, "Ice chrome")
+  describe <scene>         every layer, top first, with the settings that differ from defaults
+  scene <template> [-o f]  write a template as a .morpho file to edit (default: <slug>.morpho)
+  set <file> <a=b>…        edit a .morpho file in place (--dry to only print the changes)
+  render <scene>           PNG; one time draws the frame, several draw a captioned filmstrip
+  vary <scene>             one PNG with a captioned cell per variation
+  check <scene>            structural and visual problems, as text
+  compare <scene> <image>  how close the design is to a reference (PNG/JPEG), with a difference image
+  serve                    keep Vite and a browser running; drawing commands use it when up
+
+assignments (set, --set, --vary, --variant):
+  Layer.setting=value      by layer name or #id; bare keys find the material param, content field,
+                           shape field or modifier (Title.wave.amplitude); or a full path
+                           (Title.style.params.gloss). canvas.*, background.*, timeline.* too.
+                           Values are JSON when they parse, else text; null removes.
+
+options:
+  --set a=b         apply before drawing (repeatable; files are left alone)
+  --at 0,1.5,rest   times in seconds (rest = at rest, as a still export)
+  --frames N        N times spread over the clock (a filmstrip)
+  --scale S         output scale (render default 1; filmstrips and sheets fit --size)
+  --size PX         long side of each cell (default 360)
+  --cols N          columns in a sheet
+  --vary a=1,2,3    one cell per value; several --vary multiply (values split on | when given)
+  --variant 'a=1; b=2'  one cell per hand-made combination (repeatable)
+  --layers N        check: how many layers get the visibility check (default 16)
+  --transparent     no background
+  --out FILE        where the PNG goes (default test-results/morpho/<scene>-<command>.png)
+  --cpu             draw with SwiftShader (or set MORPHO_CPU=1): the same pixels on every machine, about 4× slower
+                    (default: the GPU, falling back to SwiftShader when WebGL won't start there)
+  --json            machine-readable output`;
+
+// ---------- arguments ----------
+
+function parse(argv) {
+  const pos = [], opt = { set: [], vary: [], variant: [] };
+  const flags = new Set(['cpu', 'json', 'dry', 'transparent']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-o') opt.out = argv[++i];
+    else if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split(/=(.*)/s);
+      const val = flags.has(k) ? true : (v ?? argv[++i]);
+      if (Array.isArray(opt[k])) opt[k].push(val);
+      else opt[k] = val;
+    } else pos.push(a);
+  }
+  return { cmd: pos[0], args: pos.slice(1), opt };
+}
+
+const slug = (s) => String(s).toLowerCase().replace(/\.(morpho|json)$/, '').replace(/^.*\//, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'design';
+
+const times = (opt) => {
+  if (opt.at) return String(opt.at).split(',').map((s) => (s.trim() === 'rest' ? null : Number(s)));
+  if (opt.frames) return { frames: Number(opt.frames) };
+  return [null];
+};
+
+/** --vary: the cartesian product of each list; --variant: hand-made combos. */
+function variants(opt) {
+  const out = opt.variant.map((v) => ({ label: v, edits: v.split(';').map((s) => s.trim()).filter(Boolean) }));
+  if (opt.vary.length) {
+    let combos = [{ label: [], edits: [] }];
+    for (const v of opt.vary) {
+      const eq = v.indexOf('=');
+      if (eq < 0) throw new Error(`--vary "${v}" needs values: Layer.setting=a,b,c`);
+      const lhs = v.slice(0, eq), rhs = v.slice(eq + 1);
+      const vals = (rhs.includes('|') ? rhs.split('|') : rhs.split(',')).map((s) => s.trim());
+      const key = lhs.replace(/^"[^"]*"\.?|^[^.]*\./, '') || lhs;
+      combos = combos.flatMap((c) => vals.map((x) => ({ label: [...c.label, `${key} ${x}`], edits: [...c.edits, `${lhs}=${x}`] })));
+    }
+    out.push(...combos.map((c) => ({ label: c.label.join(' · '), edits: c.edits })));
+  }
+  if (out.length > 48) throw new Error(`${out.length} variations is too many for one sheet (48 at most)`);
+  return out;
+}
+
+async function scene(arg) {
+  if (!arg) throw new Error('Which design? Give a template name or a .morpho file (catalog templates lists them).');
+  if (existsSync(arg) && !arg.endsWith('/')) return { project: JSON.parse(await readFile(arg, 'utf8')), name: arg };
+  return { template: arg, name: arg };
+}
+
+// ---------- Node side: no browser ----------
+
+let vite = null;
+async function nodeAgent() {
+  const { createServer } = await import('vite');
+  vite = await createServer({ configFile: path.join(root, 'vite.config.ts'), root: path.join(root, 'ui'), server: { middlewareMode: true, hmr: false, ws: false }, appType: 'custom', logLevel: 'error', optimizeDeps: { noDiscovery: true } });
+  return vite.ssrLoadModule('/src/agent/node.ts');
+}
+
+// ---------- browser side ----------
+
+async function browserPath() {
+  if (process.env.CHROMIUM_PATH) return process.env.CHROMIUM_PATH;
+  const { chromium } = await import('playwright');
+  if (existsSync(chromium.executablePath())) return undefined;
+  const mac = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  if (existsSync(mac)) return mac;
+  throw new Error('No browser found: run `npx playwright install chromium` or set CHROMIUM_PATH');
+}
+
+/** Vite's dev server and a page with the app, ready to take jobs. */
+async function startApp(gpu) {
+  if (!existsSync(path.join(root, 'ui/src/engine/pkg/morpho.js'))) throw new Error('The engine isn’t built: run `npm run wasm:dev` first');
+  const { createServer } = await import('vite');
+  const { chromium } = await import('playwright');
+  const server = await createServer({ configFile: path.join(root, 'vite.config.ts'), root: path.join(root, 'ui'), server: { port: 0, strictPort: false, host: '127.0.0.1' }, logLevel: 'error' });
+  await server.listen();
+  const url = server.resolvedUrls.local[0];
+  const args = gpu ? [process.platform === 'darwin' ? '--use-angle=metal' : '--use-gl=angle', '--enable-gpu', '--ignore-gpu-blocklist'] : ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'];
+  const browser = await chromium.launch({ executablePath: await browserPath(), args: [...args, '--disable-background-timer-throttling', '--disable-renderer-backgrounding'] });
+  // Small: the live preview redraws on every load, and output doesn't depend on it.
+  const page = await browser.newPage({ viewport: { width: 640, height: 480 } });
+  const errors = [];
+  page.on('pageerror', (e) => errors.push(e.message));
+  const ready = async () => {
+    await page.goto(`${url}?editor`);
+    await page.waitForFunction(() => window.morphotype?.renderer && window.morphotype.store.get().ready, null, { timeout: gpu ? 30_000 : 90_000 });
+  };
+  try {
+    await ready();
+  } catch (e) {
+    await browser.close().catch(() => {});
+    await server.close();
+    if (!gpu) throw e;
+    process.stderr.write('morpho: WebGL didn’t start on the GPU; drawing with SwiftShader instead\n');
+    return startApp(false);
+  }
+  return {
+    errors,
+    async run(job) {
+      // Vite reloads the page when the source changes; wait for it to come back.
+      if (!(await page.evaluate(() => !!window.morphotype?.renderer).catch(() => false))) await ready();
+      errors.length = 0;
+      try {
+        try {
+          return { ...(await page.evaluate(runInPage, job)), pageErrors: [...errors] };
+        } catch (e) {
+          // A source edit reloaded the page mid-job: once it's back, go again.
+          if (!/context was destroyed|Target closed|navigation/i.test(String(e?.message))) throw e;
+          await ready();
+          return { ...(await page.evaluate(runInPage, job)), pageErrors: [...errors] };
+        }
+      } catch (e) {
+        const msg = String(e?.message ?? e).split('\n')[0].replace(/^.*?Error: /, '');
+        throw new Error(errors.length ? `${msg}\npage errors:\n${errors.join('\n')}` : msg);
+      }
+    },
+    async close() {
+      await browser.close().catch(() => {});
+      await server.close();
+    },
+  };
+}
+
+/** Runs in the page (Playwright sends only this function's source): load the scene, apply edits, do the job. */
+async function runInPage({ scene, set, op, opts }) {
+  const a = await window.morphotype.agent();
+  return a.quietly(async () => {
+    if (scene.template) await a.open(scene.template);
+    else await a.load(scene.project);
+    const changes = set.length ? await a.edit(set) : [];
+    const p = a.project();
+    const clock = p.timeline?.duration ?? 6;
+    if (opts.at?.frames) opts.at = Array.from({ length: opts.at.frames }, (_, i) => +((i * clock) / opts.at.frames).toFixed(3));
+    const name = p.name;
+    if (op === 'render') return { changes, name, ...(await a.render(opts)) };
+    if (op === 'vary') return { changes, name, ...(await a.vary(opts.variants, { ...opts, at: opts.at?.[0] ?? null })) };
+    if (op === 'check') return { changes, name, text: await a.check(opts) };
+    if (op === 'compare') return { changes, name, ...(await a.compare(opts.ref, { ...opts, at: opts.at?.[0] ?? null })) };
+    throw new Error(`Unknown job ${op}`);
+  });
+}
+
+async function daemon() {
+  try {
+    const r = await fetch(`http://127.0.0.1:${PORT}/ping`, { signal: AbortSignal.timeout(400) });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function drawJob(job, gpu) {
+  if (await daemon()) {
+    const r = await fetch(`http://127.0.0.1:${PORT}/job`, { method: 'POST', body: JSON.stringify(job) });
+    const body = await r.json();
+    if (!r.ok) throw new Error(body.error);
+    return body;
+  }
+  const app = await startApp(gpu);
+  try {
+    return await app.run(job);
+  } finally {
+    await app.close();
+  }
+}
+
+async function serve(gpu) {
+  const app = await startApp(gpu);
+  let queue = Promise.resolve();
+  createHttp(async (req, res) => {
+    if (req.url === '/ping') return res.end('ok');
+    if (req.url === '/stop') {
+      res.end('ok');
+      await app.close();
+      process.exit(0);
+    }
+    let body = '';
+    for await (const c of req) body += c;
+    // One job at a time: they share the page.
+    queue = queue.then(async () => {
+      try {
+        res.end(JSON.stringify(await app.run(JSON.parse(body))));
+      } catch (e) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: String(e?.message ?? e).replace(/^.*?Error: /, '') }));
+      }
+    });
+  }).listen(PORT, '127.0.0.1', () => console.log(`morpho serve on 127.0.0.1:${PORT}${gpu ? '' : ' (SwiftShader)'}: drawing commands now use this browser. Stop with Ctrl-C or \`morpho stop\`.`));
+  const stop = async () => {
+    await app.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+// ---------- commands ----------
+
+async function writePng(b64, opt, sceneName, cmd) {
+  const out = path.resolve(opt.out ?? path.join(OUT_DIR, `${slug(sceneName)}-${cmd}.png`));
+  await mkdir(path.dirname(out), { recursive: true });
+  await writeFile(out, Buffer.from(b64, 'base64'));
+  const rel = path.relative(process.cwd(), out);
+  return rel && !rel.startsWith('..') ? rel : out;
+}
+
+async function main() {
+  const { cmd, args, opt } = parse(process.argv.slice(2));
+  const t0 = performance.now();
+  const say = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
+  const done = () => process.stderr.write(`(${((performance.now() - t0) / 1000).toFixed(1)} s)\n`);
+  switch (cmd) {
+    case undefined:
+    case 'help':
+    case '--help':
+      return say(HELP);
+    case 'catalog': {
+      const a = await nodeAgent();
+      say(a.catalog(args.join(' ')));
+      break;
+    }
+    case 'describe': {
+      const a = await nodeAgent();
+      const s = await scene(args[0]);
+      let p = s.project ? a.migrate(s.project) : a.template(s.template);
+      if (opt.set.length) p = a.applyEdits(p, opt.set).project;
+      say(a.describe(p));
+      break;
+    }
+    case 'scene': {
+      const a = await nodeAgent();
+      if (!args[0]) throw new Error('Which template? (catalog templates lists them)');
+      const p = a.template(args[0]);
+      const out = opt.out ?? `${slug(p.name)}.morpho`;
+      await writeFile(out, JSON.stringify(p, null, 1));
+      say(`wrote ${out}: "${p.name}", ${p.layers.length} top-level layers. Edit with: morpho set ${out} Layer.setting=value`);
+      break;
+    }
+    case 'set': {
+      const [file, ...assign] = args;
+      if (!file || !existsSync(file)) throw new Error(`set needs a .morpho file first${file ? `; "${file}" doesn't exist` : ''} (make one with: morpho scene <template>)`);
+      if (!assign.length) throw new Error('set needs at least one Layer.setting=value');
+      const a = await nodeAgent();
+      const { project, changes } = a.applyEdits(a.migrate(JSON.parse(await readFile(file, 'utf8'))), assign);
+      if (!opt.dry) await writeFile(file, JSON.stringify(project, null, 1));
+      say(changes.join('\n') + (opt.dry ? '\n(dry run: file unchanged)' : ''));
+      break;
+    }
+    case 'render':
+    case 'vary':
+    case 'check':
+    case 'compare': {
+      const s = await scene(args[0]);
+      const opts = { scale: opt.scale ? Number(opt.scale) : undefined, size: opt.size ? Number(opt.size) : undefined, cols: opt.cols ? Number(opt.cols) : undefined, transparent: !!opt.transparent, layers: opt.layers ? Number(opt.layers) : undefined, at: times(opt) };
+      if (cmd === 'compare') {
+        if (!args[1] || !existsSync(args[1])) throw new Error(`compare needs a reference image after the scene${args[1] ? `; "${args[1]}" doesn't exist` : ''}`);
+        opts.ref = (await readFile(args[1])).toString('base64');
+      }
+      if (cmd === 'vary') {
+        opts.variants = variants(opt);
+        if (!opts.variants.length) throw new Error('vary needs --vary Layer.setting=a,b,c or --variant "a=1; b=2"');
+      }
+      const r = await drawJob({ scene: { template: s.template, project: s.project }, set: opt.set, op: cmd, opts }, !(opt.cpu || process.env.MORPHO_CPU));
+      if (opt.json) {
+        const { png, ...rest } = r;
+        if (png) rest.out = await writePng(png, opt, s.name, cmd);
+        say(JSON.stringify(rest, null, 1));
+        break;
+      }
+      for (const c of r.changes ?? []) say(`set ${c}`);
+      if (r.text) say(r.text);
+      if (r.png) say(`wrote ${await writePng(r.png, opt, s.name, cmd === 'render' && (opts.at.frames || opts.at.length > 1) ? 'frames' : cmd)} (${r.width}×${r.height})`);
+      for (const e of r.pageErrors ?? []) process.stderr.write(`page error: ${e}\n`);
+      break;
+    }
+    case 'serve':
+      return serve(!(opt.cpu || process.env.MORPHO_CPU));
+    case 'stop':
+      await fetch(`http://127.0.0.1:${PORT}/stop`).catch(() => {});
+      return say('stopped');
+    default:
+      throw new Error(`Unknown command "${cmd}". Try: morpho help`);
+  }
+  done();
+}
+
+main()
+  .catch((e) => {
+    process.stderr.write(`morpho: ${String(e?.message ?? e).replace(/^.*?Error: /, '')}\n`);
+    process.exitCode = 1;
+  })
+  .finally(() => vite?.close());
diff --git a/ui/src/agent/agent.test.ts b/ui/src/agent/agent.test.ts
new file mode 100644
index 0000000..0cdae3a
--- /dev/null
+++ b/ui/src/agent/agent.test.ts
@@ -0,0 +1,199 @@
+import { describe as group, expect, it } from 'vitest';
+import { EFFECTS, PRESETS } from '../render/effects';
+import { group as groupNode, lineLayer, MODIFIER_UI, mods, newModifier, style, SYMBOL_UI, symbolLayer, textLayer, type Project, type ShapeLayer } from '../state/model';
+import { SHAPE_RECIPES } from '../state/recipes';
+import { TEMPLATES } from '../state/templates';
+import type { BuildResult } from '../engine/client';
+import { catalog, findTemplate, SECTIONS } from './catalog';
+import { contrast, diff, luminance, motionFindings, outside, presence, report, structural } from './check';
+import { describe } from './describe';
+import { applyEdit, applyEdits, EditError, parseAssignment } from './edit';
+
+const project = (layers: Project['layers']): Project => ({ version: 2, name: 'Test', canvas: { width: 1000, height: 800 }, background: { fill: { kind: 'solid', colors: ['#000000'], angle: 180 }, grain: 0, tile: null }, layers, fonts: [] });
+
+group('catalog', () => {
+  it('lists every material, modifier and shape in the index', () => {
+    const idx = catalog('', TEMPLATES);
+    for (const e of EFFECTS) expect(idx).toContain(e.id);
+    for (const m of Object.keys(MODIFIER_UI)) expect(idx).toContain(m);
+    for (const s of Object.keys(SYMBOL_UI)) expect(idx).toContain(s);
+    expect(idx).toContain(`templates (${TEMPLATES.length})`);
+  });
+
+  it('details every material, modifier, shape, preset and recipe by name', () => {
+    for (const e of EFFECTS) {
+      const t = catalog(e.id);
+      expect(t).toContain(`material ${e.id}`);
+      for (const p of e.params) expect(t, `${e.id}.${p.key}`).toContain(`  ${p.key}: `);
+    }
+    for (const m of Object.keys(MODIFIER_UI)) expect(catalog(m)).toContain(`modifier ${m}`);
+    for (const s of Object.keys(SYMBOL_UI)) expect(catalog(s)).toContain(`shape ${s}`);
+    for (const p of PRESETS) expect(catalog(p.name)).toContain(`preset ${p.name}`);
+    for (const r of SHAPE_RECIPES) expect(catalog(r.name)).toContain(`recipe ${r.name}`);
+  });
+
+  it('answers every section and searches the rest', () => {
+    for (const s of SECTIONS) expect(catalog(s, TEMPLATES).length, s).toBeGreaterThan(40);
+    expect(catalog('puff')).toContain('material inflate');
+    expect(catalog('zzzz')).toContain('Nothing matches');
+  });
+
+  it('documents every field the layer factories make', () => {
+    const doc = catalog('layers');
+    const keys = (o: object) => Object.keys(o).filter((k) => k !== 'type');
+    for (const l of [textLayer('A'), symbolLayer('star'), lineLayer('M0 0 L1 0', 100)] as ShapeLayer[]) {
+      for (const k of keys(l)) expect(doc, `layer.${k}`).toContain(k);
+      for (const k of keys(l.content)) expect(doc, `${l.content.type}.${k}`).toContain(k);
+    }
+    for (const k of keys(groupNode([]))) expect(doc, `group.${k}`).toContain(k);
+  });
+
+  it('finds templates by exact name or a unique part', () => {
+    const t = TEMPLATES[0];
+    expect(findTemplate(TEMPLATES, t.name)).toBe(t);
+    expect(findTemplate(TEMPLATES, t.name.toUpperCase())).toBe(t);
+    expect(() => findTemplate(TEMPLATES, 'no such template at all')).toThrow(/No template/);
+  });
+});
+
+group('describe', () => {
+  it('shows each layer once, top first, with only changed settings', () => {
+    const a = textLayer('Hello', 'archivo', { name: 'Title', style: style('chrome', { liquid: 1.2 }) });
+    const b = symbolLayer('star', 300, { name: 'Star', x: 120 }, { points: 7 });
+    const out = describe(project([b, a]));
+    const lines = out.split('\n');
+    expect(lines[2]).toContain('"Title"');
+    expect(lines[3]).toContain('"Star"');
+    expect(out).toContain('chrome {liquid 1.2}');
+    expect(out).toContain('shape star 300px (points 7)');
+    expect(out).toContain('at 120,0');
+    expect(out).not.toContain('bevel');
+  });
+
+  it('describes every template without throwing', () => {
+    for (const t of TEMPLATES) {
+      const p = t.make();
+      expect(describe(p), t.name).toContain(`"${p.name}"`);
+    }
+  });
+});
+
+group('edit', () => {
+  const base = () => {
+    const t = textLayer('Hi', 'archivo', { name: 'Big title', style: style('chrome'), modifiers: mods({ kind: 'wave', amplitude: 0.05, wavelength: 1, phase: 0 }) });
+    const s = symbolLayer('star', 300, { name: 'Star' });
+    return project([s, t]);
+  };
+
+  it('parses quoted names, paths and JSON values', () => {
+    expect(parseAssignment('"Big title".x=-12')).toEqual({ target: 'Big title', path: ['x'], value: -12 });
+    expect(parseAssignment('Star.fill=#ff0000').value).toBe('#ff0000');
+    expect(parseAssignment('a.b.c={"x":1}')).toEqual({ target: 'a', path: ['b', 'c'], value: { x: 1 } });
+  });
+
+  it('finds the home of bare keys', () => {
+    const { project: p, changes } = applyEdits(base(), ['Big title.liquid=1.1', 'Big title.text=Bye', 'Star.points=8', 'Big title.wave.amplitude=0.1', 'Star.x=40']);
+    const [s, t] = p.layers as ShapeLayer[];
+    expect(t.style.params.liquid).toBe(1.1);
+    expect(t.content).toMatchObject({ text: 'Bye' });
+    expect(s.content).toMatchObject({ symbol: { points: 8 } });
+    expect(t.modifiers[0]).toMatchObject({ amplitude: 0.1 });
+    expect(s.x).toBe(40);
+    expect(changes[0]).toBe('"Big title" style.params.liquid: 0.6 → 1.1');
+  });
+
+  it('leaves the input alone', () => {
+    const p = base();
+    applyEdit(p, 'Star.x=99');
+    expect((p.layers[0] as ShapeLayer).x).toBe(0);
+  });
+
+  it('refuses values out of range and unknown names, saying what works', () => {
+    expect(() => applyEdit(base(), 'Big title.liquid=9')).toThrow('chrome.liquid is a number 0…1.5, got 9');
+    expect(() => applyEdit(base(), 'Big title.c1=red')).toThrow(/colour like/);
+    expect(() => applyEdit(base(), 'Star.points=2')).toThrow(/3…24/);
+    expect(() => applyEdit(base(), 'Nope.x=1')).toThrow(/Layers: "Star", "Big title"/);
+    expect(() => applyEdit(base(), 'Star.glos=1')).toThrow(/Try: .*points/);
+    expect(() => applyEdit(base(), 'Star.wave.amplitude=1')).toThrow(/no wave modifier/);
+    expect(() => applyEdit(base(), 'Star.x')).toThrow(EditError);
+  });
+
+  it('creates motion and routes keyframes to the style or the layer', () => {
+    const anim = '{"to":1,"period":2,"phase":0,"mode":"swing"}';
+    const m = (base().layers[1] as ShapeLayer).modifiers[0].uid;
+    const { project: p } = applyEdits(base(), ['Big title.motion.loop="float"', `Big title.animate.speed=${anim}`, `Big title.animate.mod:${m}:amplitude=${anim}`]);
+    const t = p.layers[1] as ShapeLayer;
+    expect(t.motion).toMatchObject({ loop: 'float', period: 2 });
+    expect(t.style.animate?.speed).toMatchObject({ to: 1 });
+    expect(t.animate?.[`mod:${m}:amplitude`]).toMatchObject({ mode: 'swing' });
+  });
+
+  it('keeps shared settings when the material changes', () => {
+    const { project: p } = applyEdits(base(), ['Big title.bevel=80', 'Big title.effect=inflate']);
+    const t = p.layers[1] as ShapeLayer;
+    expect(t.style.effect).toBe('inflate');
+    expect(t.style.params.bevel).toBe(80);
+    expect(t.style.params.c1).toBeUndefined();
+  });
+
+  it('edits the canvas, background and clock, and removes with null', () => {
+    const { project: p } = applyEdits(base(), ['canvas.width=1080', 'background.grain=0.3', 'timeline.duration=4', 'Star.name=null']);
+    expect(p.canvas.width).toBe(1080);
+    expect(p.background.grain).toBe(0.3);
+    expect(p.timeline).toEqual({ duration: 4, loop: true });
+    expect(p.layers[0].name).toBeUndefined();
+  });
+});
+
+group('check', () => {
+  const build = (layers: { id: string; bbox: [number, number, number, number] | null; error?: string }[]): BuildResult => ({ renders: [], bbox: null, points: 0, ms: 0, layers: layers.map((l) => ({ id: l.id, bbox: l.bbox, error: l.error ?? null, d: null, local: null, frames: [] })) });
+
+  it('measures how much of a box is off the artboard', () => {
+    expect(outside([-50, -50, 50, 50], 1000, 800).share).toBe(0);
+    expect(outside([400, 0, 600, 100], 1000, 800)).toEqual({ share: 0.5, sides: ['right'] });
+    expect(outside([900, 0, 1000, 10], 1000, 800).share).toBe(1);
+  });
+
+  it('reports engine errors, layers off the canvas, bad values and dead keyframes', () => {
+    const a = textLayer('A', 'archivo', { id: 'a', name: 'Off' });
+    const b = textLayer('B', 'archivo', { id: 'b', style: style('chrome', { liquid: 4, c1: 'blue' }) });
+    const c = symbolLayer('star', 100, { id: 'c', animate: { 'mod:gone:amount': { to: 1, period: 1, phase: 0, mode: 'swing' } } });
+    const d = textLayer('D', 'archivo', { id: 'd' });
+    const g = groupNode([textLayer('hidden', 'archivo', { id: 'h', visible: false })], { id: 'g' });
+    const f = structural(project([a, b, c, d, g]), build([{ id: 'a', bbox: [900, 0, 1000, 40] }, { id: 'b', bbox: [-10, -10, 10, 10] }, { id: 'c', bbox: [0, 0, 600, 10] }, { id: 'd', bbox: null, error: 'bad font' }, { id: 'h', bbox: [5000, 0, 5001, 1] }]));
+    const text = f.map((x) => `${x.level} ${x.text}`).join('\n');
+    expect(text).toContain('error "Off" #a: entirely outside the canvas');
+    expect(text).toContain('warn #b: chrome.liquid = 4 is outside 0…1.5');
+    expect(text).toContain('error #b: chrome.c1 = "blue" is not a colour');
+    expect(text).toContain('warn #c: keyframe "mod:gone:amount" points at nothing');
+    expect(text).toContain('off the right edge');
+    expect(text).toContain("error #d: the engine couldn't build it: bad font");
+    expect(text).not.toContain('#h');
+  });
+
+  it('finds jumps and loop seams in the motion', () => {
+    const smooth = Array.from({ length: 10 }, (_, i) => ({ t: i, d: 1 }));
+    expect(motionFindings(smooth, 1, true)).toEqual([{ level: 'info', text: 'the loop joins smoothly' }]);
+    expect(motionFindings(smooth, 9, true)[0].text).toMatch(/loop jumps where it starts over/);
+    expect(motionFindings([...smooth, { t: 4.5, d: 12 }], null, true)[0].text).toMatch(/jump at 4.5s/);
+    expect(motionFindings(smooth.map((s) => ({ ...s, d: 0 })), 0, true)[0].text).toMatch(/nothing visibly changes/);
+  });
+
+  it('measures presence and contrast from pixels', () => {
+    const px = (rgb: number[], n = 4) => ({ data: new Uint8ClampedArray(Array.from({ length: n }, () => [...rgb, 255]).flat()), width: n, height: 1 });
+    expect(diff(px([0, 0, 0]), px([30, 30, 30]))).toBe(30);
+    expect(contrast(luminance(255, 255, 255), luminance(0, 0, 0))).toBeCloseTo(21);
+    expect(presence(px([255, 255, 255]), px([0, 0, 0]))).toEqual({ px: 4, contrast: 21 });
+    expect(presence(px([10, 10, 10]), px([10, 10, 10])).px).toBe(0);
+  });
+
+  it('summarises findings, problems first', () => {
+    const r = report('X', [{ level: 'info', text: 'i' }, { level: 'warn', text: 'w' }, { level: 'error', text: 'e' }]);
+    expect(r).toBe('X: 1 problem, 1 warning\n✗ e\n! w\n· i');
+  });
+});
+
+it('uses modifier entries shaped like the catalog says', () => {
+  expect(newModifier('glitch')).toMatchObject({ kind: 'glitch', on: true });
+  expect(catalog('glitch')).toContain("{ kind: 'glitch', …fields, on: true, uid: 'm1' }");
+});
diff --git a/ui/src/agent/catalog.ts b/ui/src/agent/catalog.ts
new file mode 100644
index 0000000..bf36130
--- /dev/null
+++ b/ui/src/agent/catalog.ts
@@ -0,0 +1,240 @@
+// What a design can be made of, as short plain text for an AI agent or a
+// script: materials and their settings, presets, modifiers, recipes, library
+// shapes, motion, keyframes, layers, fonts, backgrounds, canvas sizes and
+// templates. It reads the same registries the Inspector draws from, so it
+// can't drift from the app. `catalog()` is a one-screen index; ask for a
+// section or a name (`catalog('chrome')`, `catalog('glitch')`) for details.
+import { BUNDLED } from '../fonts/library';
+import { EFFECTS, PRESETS, type EffectDef, type ParamDef } from '../render/effects';
+import { BG_PRESETS, SHAPE_RECIPES } from '../state/recipes';
+import { ENTER_OPTIONS, ENTER_UI, EASES, FEELS, LEAVE_OPTIONS, LEAVE_UI, LOOP_OPTIONS, LOOP_UI, STAGGER_ORDERS } from '../state/motion';
+import { CANVAS_PRESETS, isChoice, MODIFIER_DEFAULTS, MODIFIER_UI, SYMBOL_DEFAULTS, SYMBOL_UI, type Field } from '../state/model';
+import type { ModifierKind, SymbolKind } from '../engine/types';
+import type { Template } from '../state/templates';
+
+export const SECTIONS = ['materials', 'presets', 'modifiers', 'recipes', 'shapes', 'motion', 'keyframes', 'layers', 'fonts', 'backgrounds', 'canvas', 'templates'] as const;
+export type Section = (typeof SECTIONS)[number];
+
+const fmt = (v: unknown) => (typeof v === 'number' ? String(+v.toFixed(4)) : typeof v === 'string' ? v : JSON.stringify(v));
+const first = (s: string) => s.match(/^.*?[.!?](\s|$)/)?.[0].trim() ?? s;
+const norm = (s: string) => s.toLowerCase().replace(/[\s_-]+/g, '');
+
+function paramLine(p: ParamDef): string {
+  const adv = p.advanced ? '  (advanced)' : '';
+  if (p.type === 'color') return `  ${p.key}: colour = ${p.default}  "${p.label}"${adv}`;
+  if (p.options) return `  ${p.key}: ${p.options.map((o, i) => `${i}=${o}`).join(' ')} = ${p.default}  "${p.label}"${adv}`;
+  return `  ${p.key}: ${fmt(p.min)}…${fmt(p.max)} step ${fmt(p.step)} = ${fmt(p.default)}  "${p.label}"${adv}`;
+}
+
+function fieldLine(f: Field, defaults: Record<string, unknown>): string {
+  const show = f.show ? `  (when ${Object.entries(f.show).map(([k, v]) => `${k}=${v}`).join(', ')})` : '';
+  const def = defaults[f.key] === undefined ? '' : ` = ${fmt(defaults[f.key])}`;
+  if (isChoice(f)) return `  ${f.key}: ${f.options.map((o) => o.value).join('|')}${def}  "${f.label}"${show}`;
+  const kind = f.toggle ? '0|1' : `${fmt(f.min)}…${fmt(f.max)}${f.integer ? ' whole' : ''}`;
+  return `  ${f.key}: ${kind}${def}  "${f.label}"${f.advanced ? '  (advanced)' : ''}${show}`;
+}
+
+function material(e: EffectDef): string {
+  const presets = PRESETS.filter((p) => p.effect === e.id).map((p) => p.name);
+  const flags = [e.photo && 'samples a picture (param image)', e.backdrop && 'sees what is behind it', e.spine && 'follows a pen line'].filter(Boolean);
+  return [
+    `material ${e.id} — ${e.name}`,
+    `  ${e.description}`,
+    ...(flags.length ? [`  ${flags.join('; ')}`] : []),
+    'params (key: range = default "label"):',
+    ...e.params.map(paramLine),
+    ...(presets.length ? [`presets: ${presets.join(', ')}`] : []),
+    `set as: style: { effect: '${e.id}', params: { … } }`,
+  ].join('\n');
+}
+
+function modifier(kind: ModifierKind): string {
+  const ui = MODIFIER_UI[kind];
+  const d = MODIFIER_DEFAULTS[kind] as unknown as Record<string, unknown>;
+  const extra = Object.keys(d).filter((k) => k !== 'kind' && !ui.fields.some((f) => f.key === k));
+  return [
+    `modifier ${kind} — ${ui.label} (${ui.group}): ${ui.blurb}`,
+    'fields (lengths are in em of the layer, 1 = its size):',
+    ...ui.fields.map((f) => fieldLine(f, d)),
+    ...(extra.length ? [`  also: ${extra.map((k) => `${k} = ${fmt(d[k])}`).join(', ')}`] : []),
+    `add as: modifiers: [{ kind: '${kind}', …fields, on: true, uid: 'm1' }]`,
+    `animate: animate['mod:<uid>:<field>'] = { to, period, phase, mode }`,
+  ].join('\n');
+}
+
+function shape(kind: SymbolKind): string {
+  const ui = SYMBOL_UI[kind];
+  const d = SYMBOL_DEFAULTS[kind] as unknown as Record<string, unknown>;
+  return [
+    `shape ${kind} — ${ui.label} (${ui.group})`,
+    ...(ui.fields.length ? ['fields:', ...ui.fields.map((f) => fieldLine(f, d))] : ['no fields']),
+    `content: { type: 'symbol', symbol: { kind: '${kind}', … }, size: 420 }`,
+    `animate: animate['sym:<field>']`,
+  ].join('\n');
+}
+
+const MOTION = (): string =>
+  [
+    'motion (layer.motion or group.motion; poses only, nothing is rebuilt):',
+    '  loop: ' + LOOP_OPTIONS.map((o) => o.value).join('|'),
+    ...Object.entries(LOOP_UI).map(([k, r]) => `    ${k}: amount = ${r.label} ${r.min}…${r.max}${r.unit} (${r.default})`),
+    '  period: seconds per loop · phase: 0…1 of a cycle',
+    '  enter: ' + ENTER_OPTIONS.map((o) => o.value).join('|') + ' · delay: s · distance:',
+    ...Object.entries(ENTER_UI).map(([k, r]) => `    ${k}: ${r.label} ${r.min}…${r.max}${r.unit} (${r.default})`),
+    '    move: fromX, fromY px (fade: bool)',
+    '  leave: ' + LEAVE_OPTIONS.map((o) => o.value).join('|') + ' · leaveAt: s · leaveDistance:',
+    ...Object.entries(LEAVE_UI).map(([k, r]) => `    ${k}: ${r.label} ${r.min}…${r.max}${r.unit} (${r.default})`),
+    '    move: toX, toY px; stops: [{ x, y, hold?, transition? }] for more spots',
+    '  transition: { type: easing|time|physics, duration, ease: [x1,y1,x2,y2], bounce, stiffness, damping, mass }',
+    '    feels: ' + FEELS.map((f) => `${f.label} (${f.title.toLowerCase()})`).join(', '),
+    '    eases: ' + EASES.map((e) => `${e.label} [${e.value.join(',')}]`).join(', '),
+    '  stagger: s between children (groups) or letters · order: ' + STAGGER_ORDERS.map((o) => o.value).join('|'),
+    '  letters: letters|words (text: each moves in turn) · slide: dir right|left|up|down, oneWay, easePass',
+    'scene clock: project.timeline = { duration: s, loop: bool } (default 6 s, looping)',
+  ].join('\n');
+
+const KEYFRAMES = (): string =>
+  [
+    'keyframes: values that change on the scene clock, as { to, period, phase, mode }',
+    '  mode: swing (there and back) | ramp (round and round) | flicker (random holds) | hold (rests, goes to To, comes back)',
+    '  period: s per cycle (snapped to fit the timeline) · phase: 0…1',
+    'where they go:',
+    '  style.animate[<param>]       a material setting (numbers or colours), drawn on the GPU',
+    '  animate["mod:<uid>:<field>"] a modifier number field (rebuilds the outline)',
+    '  animate["sym:<field>"]       a library shape field',
+    '  animate["morph:t"]           a font morph blend, or a morph layer',
+    '  animate["line:start|end|offset"] how much of a pen line is drawn (draw-on: end 0 → 1)',
+  ].join('\n');
+
+const LAYERS = (): string =>
+  [
+    'project: { version: 2, name, canvas: { width, height }, background, layers: [bottom … top], fonts: [], timeline? }',
+    'layer: { id, name?, visible, op: add|subtract|intersect, x, y (px from the canvas centre, y down), rotation (°), scale, sx, sy,',
+    '         modifiers: [], content, style: { effect, params, stroke?, opacity?, blend?: normal|multiply|screen, depth?, soften?, animate? },',
+    '         motion?, animate?, guide? (shown while designing, left out of exports), locked? }',
+    'content:',
+    "  { type: 'text', text, font, size (px), tracking, lineHeight, align: left|center|right, axes: {}, morph: null|{ font, axes, t }, ligatures }",
+    "  { type: 'symbol', symbol: { kind, … }, size }   (see `shapes`)",
+    "  { type: 'path', d (SVG path in em, y down), size }",
+    "  { type: 'line', d, size, width (px), cap: round|butt|square, squiggle?, dash?: { dash, gap, offset }, trim?: { start, end, offset, each } }",
+    "  { type: 'stroke', points: [[x, y, pressure]], width, taper, smooth }",
+    "  { type: 'morph', a, b (SVG paths), t }",
+    "group: { type: 'group', id, name?, visible, op, merge (fuse children into one shape with the group's style), clip, style, modifiers, children, motion?, animate?, open? (expanded in the layers panel) }",
+    'style.stroke: { width, color, align: outside|center|inside, opacity } · style.depth: { amount (px), angle (° from up), color, shade 0…1 }',
+  ].join('\n');
+
+const BACKGROUNDS = (): string =>
+  [
+    'background: { fill, grain: 0…1, tile: null | tile, pattern?: null | pattern }',
+    '  fill: { kind: none|solid|linear|radial|aura, colors: [1–4 hex], angle (°) }',
+    '  tile (app-icon plate): { shape: squircle|rounded|circle, size (of the short side), radius 0…1, fill, gloss, shadow, rim (px), rimColor, holo }',
+    '  pattern: { kind: grid|dots|lines|diagonal|checker|doodles, size (px), weight (px), color, opacity }',
+    'presets: ' + BG_PRESETS.map((b) => b.name).join(', '),
+  ].join('\n');
+
+const CANVAS = (): string => 'canvas sizes:\n' + CANVAS_PRESETS.map((c) => `  ${c.label}: ${c.w}×${c.h} (${c.group})`).join('\n');
+
+function templatesText(list: Template[] | null): string {
+  if (!list) return 'templates: not loaded';
+  const by = new Map<string, Template[]>();
+  for (const t of list) by.set(t.category, [...(by.get(t.category) ?? []), t]);
+  return [...by].map(([cat, ts]) => `${cat}:\n${ts.map((t) => `  ${t.name} — ${t.hint}`).join('\n')}`).join('\n');
+}
+
+function section(s: Section, templates: Template[] | null): string {
+  switch (s) {
+    case 'materials':
+      return EFFECTS.map((e) => `${e.id} — ${e.name}: ${first(e.description)}`).join('\n') + '\n(details: catalog <id>)';
+    case 'presets':
+      return PRESETS.map((p) => `${p.name} → ${p.effect}${p.tags ? ` (${p.tags})` : ''}`).join('\n');
+    case 'modifiers':
+      return (Object.keys(MODIFIER_UI) as ModifierKind[]).map((k) => `${k} — ${MODIFIER_UI[k].label} (${MODIFIER_UI[k].group}): ${MODIFIER_UI[k].blurb}`).join('\n') + '\n(details: catalog <kind>)';
+    case 'recipes':
+      return SHAPE_RECIPES.map((r) => `${r.name}: ${r.mods.map((m) => JSON.stringify(m)).join(' + ')}`).join('\n');
+    case 'shapes':
+      return (Object.keys(SYMBOL_UI) as SymbolKind[]).map((k) => `${k} — ${SYMBOL_UI[k].label} (${SYMBOL_UI[k].group})${SYMBOL_UI[k].fields.length ? ': ' + SYMBOL_UI[k].fields.map((f) => f.key).join(', ') : ''}`).join('\n');
+    case 'motion':
+      return MOTION();
+    case 'keyframes':
+      return KEYFRAMES();
+    case 'layers':
+      return LAYERS();
+    case 'fonts':
+      return 'bundled fonts (content.font): ' + BUNDLED.map((f) => f.id).join(', ');
+    case 'backgrounds':
+      return BACKGROUNDS();
+    case 'canvas':
+      return CANVAS();
+    case 'templates':
+      return templatesText(templates);
+  }
+}
+
+function index(templates: Template[] | null): string {
+  const names = (xs: string[]) => xs.join(', ');
+  return [
+    'Morphotype catalog. Ask for a section or any name below for details.',
+    `materials (${EFFECTS.length}): ${names(EFFECTS.map((e) => e.id))}`,
+    `presets (${PRESETS.length}): material looks by name`,
+    `modifiers (${Object.keys(MODIFIER_UI).length}): ${names(Object.keys(MODIFIER_UI))}`,
+    `recipes (${SHAPE_RECIPES.length}): modifier combos by name`,
+    `shapes (${Object.keys(SYMBOL_UI).length}): ${names(Object.keys(SYMBOL_UI))}`,
+    `motion: loops (${names(LOOP_OPTIONS.slice(1).map((o) => o.value))}), entrances, leaves, transitions`,
+    'keyframes: animating any material, modifier, shape or line setting',
+    'layers: the project and layer format',
+    `fonts (${BUNDLED.length}), backgrounds (${BG_PRESETS.length} presets), canvas (${CANVAS_PRESETS.length} sizes), templates (${templates?.length ?? '?'})`,
+  ].join('\n');
+}
+
+/**
+ * The catalog as text: the index with no query; a section by name; or any
+ * material, modifier, shape, preset, recipe or template by name. Unknown
+ * words list the closest matches.
+ */
+export function catalog(query = '', templates: Template[] | null = null): string {
+  const q = query.trim();
+  if (!q) return index(templates);
+  const k = norm(q);
+  const sec = SECTIONS.find((s) => norm(s) === k || norm(s).replace(/s$/, '') === k);
+  if (sec) return section(sec, templates);
+  const out: string[] = [];
+  const eff = EFFECTS.find((e) => norm(e.id) === k || norm(e.name) === k);
+  if (eff) out.push(material(eff));
+  const mod = (Object.keys(MODIFIER_UI) as ModifierKind[]).find((m) => norm(m) === k || norm(MODIFIER_UI[m].label) === k);
+  if (mod) out.push(modifier(mod));
+  const sym = (Object.keys(SYMBOL_UI) as SymbolKind[]).find((s) => norm(s) === k || norm(SYMBOL_UI[s].label) === k);
+  if (sym) out.push(shape(sym));
+  const pre = PRESETS.find((p) => norm(p.name) === k);
+  if (pre) out.push(`preset ${pre.name}: material ${pre.effect}, background ${pre.bg}\n  params: ${JSON.stringify(pre.params)}\n  (other params keep the material's defaults: catalog ${pre.effect})`);
+  const rec = SHAPE_RECIPES.find((r) => norm(r.name) === k);
+  if (rec) out.push(`recipe ${rec.name}: ${rec.mods.map((m) => JSON.stringify(m)).join(' + ')}`);
+  const tpl = templates?.find((t) => norm(t.name) === k);
+  if (tpl) out.push(`template ${tpl.name} (${tpl.category}) — ${tpl.hint}\n  (see it as layers: describe "${tpl.name}")`);
+  if (out.length) return out.join('\n\n');
+  return search(k, templates);
+}
+
+function search(k: string, templates: Template[] | null): string {
+  const hits: string[] = [];
+  const has = (...s: (string | undefined)[]) => s.some((x) => x && norm(x).includes(k));
+  for (const e of EFFECTS) if (has(e.id, e.name, e.description)) hits.push(`material ${e.id} — ${e.name}`);
+  for (const e of EFFECTS) for (const p of e.params) if (has(p.key, p.label)) hits.push(`param ${e.id}.${p.key} — ${p.label}`);
+  for (const p of PRESETS) if (has(p.name, p.tags)) hits.push(`preset ${p.name} → ${p.effect}`);
+  for (const [m, ui] of Object.entries(MODIFIER_UI)) if (has(m, ui.label, ui.blurb)) hits.push(`modifier ${m} — ${ui.label}`);
+  for (const r of SHAPE_RECIPES) if (has(r.name, r.tags)) hits.push(`recipe ${r.name}`);
+  for (const [s, ui] of Object.entries(SYMBOL_UI)) if (has(s, ui.label)) hits.push(`shape ${s} — ${ui.label}`);
+  for (const t of templates ?? []) if (has(t.name, t.hint)) hits.push(`template ${t.name}`);
+  if (!hits.length) return `Nothing matches "${k}". Sections: ${SECTIONS.join(', ')}.`;
+  const more = hits.length > 40 ? `\n… and ${hits.length - 40} more` : '';
+  return hits.slice(0, 40).join('\n') + more;
+}
+
+/** A template by exact name, then any case, then a unique part of a name. */
+export function findTemplate(list: Template[], name: string): Template {
+  const k = name.toLowerCase();
+  const part = list.filter((x) => x.name.toLowerCase().includes(k));
+  const t = list.find((x) => x.name === name) ?? list.find((x) => x.name.toLowerCase() === k) ?? (part.length === 1 ? part[0] : undefined);
+  if (t) return t;
+  const near = part.length ? part : list.filter((x) => k.split(/\s+/).some((w) => w.length > 2 && x.name.toLowerCase().includes(w)));
+  throw new Error(`No template "${name}"${part.length > 1 ? ' (several match)' : ''}. ${near.length ? `Did you mean: ${near.slice(0, 8).map((x) => x.name).join(', ')}` : 'List them with: catalog templates'}`);
+}
diff --git a/ui/src/agent/check.ts b/ui/src/agent/check.ts
new file mode 100644
index 0000000..2a7d715
--- /dev/null
+++ b/ui/src/agent/check.ts
@@ -0,0 +1,180 @@
+// Problems in a design, said in words so nobody has to spot them in a
+// screenshot. The structural checks read the project and the engine's build;
+// the pixel checks (page.ts renders the frames) look at what actually shows:
+// layers that can't be seen, text with too little contrast, blank frames, a
+// loop that jumps at the seam, and sudden pops in the motion.
+import type { BuildResult } from '../engine/client';
+import type { Box } from '../engine/types';
+import { effectById, EFFECTS } from '../render/effects';
+import { timelineOf } from '../state/clock';
+import { isChoice, isGroup, MODIFIER_UI, SYMBOL_UI, type Node, type Project } from '../state/model';
+import { MORPH_KEY } from '../state/geoMotion';
+import { num } from './describe';
+
+export interface Finding {
+  level: 'error' | 'warn' | 'info';
+  text: string;
+}
+
+export const label = (n: Node) => (n.name ? `"${n.name}" #${n.id}` : `#${n.id}`);
+
+function walk(nodes: Node[], f: (n: Node, hidden: boolean, merged: boolean) => void, hidden = false, merged = false) {
+  for (const n of nodes) {
+    f(n, hidden || !n.visible, merged);
+    if (isGroup(n)) walk(n.children, f, hidden || !n.visible, merged || n.merge);
+  }
+}
+
+/** Share of `b` outside the artboard (centred at 0,0), and on which sides. */
+export function outside(b: Box, w: number, h: number): { share: number; sides: string[] } {
+  const [x0, y0, x1, y1] = b;
+  const area = Math.max(1e-6, (x1 - x0) * (y1 - y0));
+  const ix = Math.max(0, Math.min(x1, w / 2) - Math.max(x0, -w / 2));
+  const iy = Math.max(0, Math.min(y1, h / 2) - Math.max(y0, -h / 2));
+  const sides = [x0 < -w / 2 && 'left', x1 > w / 2 && 'right', y0 < -h / 2 && 'top', y1 > h / 2 && 'bottom'].filter((s): s is string => !!s);
+  return { share: 1 - (ix * iy) / area, sides };
+}
+
+/** What can be told from the project and its build, without drawing anything. */
+export function structural(p: Project, build: BuildResult | null): Finding[] {
+  const out: Finding[] = [];
+  const { width: W, height: H } = p.canvas;
+  const tl = timelineOf(p);
+  const outs = new Map((build?.layers ?? []).map((l) => [l.id, l]));
+  walk(p.layers, (n, hidden, merged) => {
+    const who = label(n);
+    // Material.
+    if (!merged || isGroup(n)) {
+      if (!EFFECTS.some((e) => e.id === n.style.effect)) out.push({ level: 'error', text: `${who}: unknown material "${n.style.effect}" (drawn as flat)` });
+      const e = effectById(n.style.effect);
+      for (const [k, v] of Object.entries(n.style.params)) {
+        const d = e.params.find((x) => x.key === k);
+        if (!d) continue;
+        if (d.type === 'number' && typeof v === 'number' && (v < d.min || v > d.max)) out.push({ level: 'warn', text: `${who}: ${e.id}.${k} = ${num(v)} is outside ${d.min}…${d.max}` });
+        if (d.type === 'color' && (typeof v !== 'string' || !/^#[0-9a-f]{6}$/i.test(v))) out.push({ level: 'error', text: `${who}: ${e.id}.${k} = ${JSON.stringify(v)} is not a colour like #ff3366` });
+      }
+      for (const k of Object.keys(n.style.animate ?? {})) if (!e.params.some((x) => x.key === k)) out.push({ level: 'warn', text: `${who}: keyframe on "${k}" does nothing; ${e.id} has no such setting` });
+    }
+    // Modifiers.
+    for (const m of n.modifiers) {
+      for (const f of MODIFIER_UI[m.kind]?.fields ?? []) {
+        const v = (m as unknown as Record<string, unknown>)[f.key];
+        if (!isChoice(f) && typeof v === 'number' && (v < f.min || v > f.max)) out.push({ level: 'warn', text: `${who}: ${m.kind}.${f.key} = ${num(v)} is outside ${f.min}…${f.max}` });
+      }
+    }
+    if (!isGroup(n) && n.content.type === 'symbol') {
+      const s = n.content.symbol as unknown as Record<string, unknown>;
+      for (const f of SYMBOL_UI[n.content.symbol.kind]?.fields ?? []) {
+        const v = s[f.key];
+        if (!isChoice(f) && typeof v === 'number' && (v < f.min || v > f.max)) out.push({ level: 'warn', text: `${who}: ${n.content.symbol.kind}.${f.key} = ${num(v)} is outside ${f.min}…${f.max}` });
+      }
+    }
+    // Geometry keyframes that no longer point at anything.
+    for (const k of Object.keys(n.animate ?? {})) {
+      const m = /^mod:([^:]+):(.+)$/.exec(k);
+      const dead = m
+        ? typeof (n.modifiers.find((x) => x.uid === m[1]) as unknown as Record<string, unknown> | undefined)?.[m[2]] !== 'number'
+        : k === MORPH_KEY
+          ? isGroup(n) || !(n.content.type === 'morph' || (n.content.type === 'text' && n.content.morph))
+          : k.startsWith('line:')
+            ? isGroup(n) || n.content.type !== 'line'
+            : k.startsWith('sym:')
+              ? isGroup(n) || n.content.type !== 'symbol' || typeof (n.content.symbol as unknown as Record<string, unknown>)[k.slice(4)] !== 'number'
+              : true;
+      if (dead) out.push({ level: 'warn', text: `${who}: keyframe "${k}" points at nothing and does nothing` });
+    }
+    // Timing.
+    const mo = n.motion;
+    if (mo && mo.enter !== 'none' && mo.delay >= tl.duration) out.push({ level: 'warn', text: `${who}: enters at ${num(mo.delay)}s, after the ${num(tl.duration)}s clock ends` });
+    if (mo?.leave && mo.leave !== 'none' && (mo.leaveAt ?? 0) >= tl.duration) out.push({ level: 'warn', text: `${who}: leaves at ${num(mo.leaveAt ?? 0)}s, after the ${num(tl.duration)}s clock ends` });
+    // Geometry.
+    if (isGroup(n) || hidden || merged || (!isGroup(n) && n.guide)) return;
+    const o = outs.get(n.id);
+    if (!o) return;
+    if (o.error) out.push({ level: 'error', text: `${who}: the engine couldn't build it: ${o.error}` });
+    else if (!o.bbox) out.push({ level: 'warn', text: `${who}: has no outline (empty text or shape?)` });
+    else {
+      const { share, sides } = outside(o.bbox, W, H);
+      if (share > 0.995) out.push({ level: 'error', text: `${who}: entirely outside the canvas (box ${o.bbox.map(num).join(', ')})` });
+      else if (share > 0.02) out.push({ level: 'warn', text: `${who}: ${Math.round(share * 100)}% off the ${sides.join(' and ')} edge${sides.length > 1 ? 's' : ''}` });
+      const tall = o.bbox[3] - o.bbox[1];
+      if (n.content.type === 'text' && tall < Math.min(W, H) * 0.012) out.push({ level: 'warn', text: `${who}: text is only ${num(tall)}px tall on a ${W}×${H} canvas` });
+    }
+  });
+  return out;
+}
+
+export interface Pixels {
+  data: Uint8ClampedArray | Uint8Array;
+  width: number;
+  height: number;
+}
+
+/** Mean absolute difference per channel (0…255) between two same-size images. */
+export function diff(a: Pixels, b: Pixels): number {
+  let s = 0;
+  const n = Math.min(a.data.length, b.data.length);
+  for (let i = 0; i < n; i += 4) s += Math.abs(a.data[i] - b.data[i]) + Math.abs(a.data[i + 1] - b.data[i + 1]) + Math.abs(a.data[i + 2] - b.data[i + 2]);
+  return s / ((n / 4) * 3);
+}
+
+const lin = (c: number) => {
+  const v = c / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+export const luminance = (r: number, g: number, b: number) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+export const contrast = (a: number, b: number) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+/** How many pixels a layer changes, and its contrast against what's behind it there. */
+export function presence(shown: Pixels, without: Pixels): { px: number; contrast: number } {
+  let px = 0, fg = 0, bg = 0;
+  const d = shown.data, e = without.data;
+  for (let i = 0; i < d.length; i += 4) {
+    // Low enough to catch text a shade off its background; drawing is deterministic, so no noise.
+    if (Math.abs(d[i] - e[i]) + Math.abs(d[i + 1] - e[i + 1]) + Math.abs(d[i + 2] - e[i + 2]) < 9) continue;
+    px++;
+    fg += luminance(d[i], d[i + 1], d[i + 2]);
+    bg += luminance(e[i], e[i + 1], e[i + 2]);
+  }
+  return { px, contrast: px ? contrast(fg / px, bg / px) : 1 };
+}
+
+/** Spread of brightness: near 0 means a flat, empty-looking frame. */
+export function spread(p: Pixels): number {
+  let s = 0, s2 = 0;
+  const n = p.data.length / 4;
+  for (let i = 0; i < p.data.length; i += 4) {
+    const l = (p.data[i] + p.data[i + 1] + p.data[i + 2]) / 3;
+    s += l;
+    s2 += l * l;
+  }
+  return Math.sqrt(Math.max(0, s2 / n - (s / n) ** 2));
+}
+
+/**
+ * Motion from pairs of frames one video frame apart: `steps` sampled across
+ * the clock, `seam` the last frame against the first.
+ */
+export function motionFindings(steps: { t: number; d: number }[], seam: number | null, animated: boolean): Finding[] {
+  const out: Finding[] = [];
+  const ds = steps.map((s) => s.d).sort((a, b) => a - b);
+  const median = ds[Math.floor(ds.length / 2)] ?? 0;
+  const moving = ds.some((d) => d > 0.05);
+  if (!moving) {
+    if (animated) out.push({ level: 'warn', text: 'set to move, but nothing visibly changes over the clock' });
+    return out;
+  }
+  const floor = Math.max(median, 0.15);
+  for (const s of steps) if (s.d > floor * 6 && s.d > 2) out.push({ level: 'warn', text: `jump at ${num(s.t)}s: ${num(s.d / floor)}× a normal frame step` });
+  if (seam !== null && seam > floor * 4 && seam > 1.5) out.push({ level: 'warn', text: `the loop jumps where it starts over: ${num(seam / floor)}× a normal frame step` });
+  else if (seam !== null) out.push({ level: 'info', text: 'the loop joins smoothly' });
+  return out;
+}
+
+export function report(title: string, findings: Finding[]): string {
+  const errors = findings.filter((f) => f.level === 'error');
+  const warns = findings.filter((f) => f.level === 'warn');
+  const info = findings.filter((f) => f.level === 'info');
+  const head = `${title}: ${errors.length ? `${errors.length} problem${errors.length > 1 ? 's' : ''}` : 'no problems'}, ${warns.length} warning${warns.length === 1 ? '' : 's'}`;
+  return [head, ...errors.map((f) => `✗ ${f.text}`), ...warns.map((f) => `! ${f.text}`), ...info.map((f) => `· ${f.text}`)].join('\n');
+}
diff --git a/ui/src/agent/describe.ts b/ui/src/agent/describe.ts
new file mode 100644
index 0000000..0b8b9d5
--- /dev/null
+++ b/ui/src/agent/describe.ts
@@ -0,0 +1,145 @@
+// A project as a short text tree: one line per layer with what it is, where it
+// sits, its material and every setting that differs from the defaults, so an
+// agent can read a whole design without its source or a screenshot. Names and
+// ids in the output are what `set` (edit.ts) takes to address a layer.
+import { defaultParams, effectById } from '../render/effects';
+import { feelOf, type Motion, type ParamAnim, type Transition } from '../state/motion';
+import { isGroup, MODIFIER_DEFAULTS, SYMBOL_DEFAULTS, type Background, type Node, type Project, type Style } from '../state/model';
+import type { ModEntry } from '../engine/types';
+
+export const num = (v: number) => String(+v.toFixed(3));
+export const val = (v: unknown): string => (typeof v === 'number' ? num(v) : typeof v === 'string' ? v : JSON.stringify(v));
+const clip = (s: string, n = 48) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+
+/** Keys of `o` whose values differ from `d` (all of them when there's no default). */
+function changed(o: Record<string, unknown>, d: Record<string, unknown> | undefined, skip: string[] = []): string[] {
+  return Object.keys(o)
+    .filter((k) => !skip.includes(k) && o[k] !== undefined && (d === undefined || JSON.stringify(o[k]) !== JSON.stringify(d[k])))
+    .map((k) => `${k} ${val(o[k])}`);
+}
+
+function anim(k: string, a: ParamAnim): string {
+  return `${k}→${val(a.to)} ${a.mode} ${num(a.period)}s${a.phase ? ` @${num(a.phase)}` : ''}`;
+}
+
+function transition(t: Transition): string {
+  const feel = feelOf(t);
+  if (feel) return `${feel} ${num(t.duration)}s`;
+  if (t.type === 'physics') return `spring k${num(t.stiffness)} c${num(t.damping)} m${num(t.mass)}`;
+  if (t.type === 'time') return `spring ${num(t.duration)}s bounce ${num(t.bounce)}`;
+  return `ease [${t.ease.map(num).join(',')}] ${num(t.duration)}s`;
+}
+
+export function motionText(m: Motion | undefined): string {
+  if (!m) return '';
+  const out: string[] = [];
+  if (m.loop !== 'none') out.push(`loop ${m.loop} ${num(m.amount)} every ${num(m.period)}s${m.phase ? ` @${num(m.phase)}` : ''}${m.loop === 'slide' && m.dir ? ` ${m.dir}` : ''}${m.oneWay ? ' one-way' : ''}`);
+  if (m.enter !== 'none') out.push(`enter ${m.enter}${m.enter === 'move' ? ` from ${num(m.fromX ?? 0)},${num(m.fromY ?? 0)}` : m.enter === 'fade' ? '' : ` ${num(m.distance)}`}${m.delay ? ` after ${num(m.delay)}s` : ''} (${transition(m.transition)})`);
+  if (m.leave && m.leave !== 'none') out.push(`leave ${m.leave}${m.leave === 'move' ? ` to ${num(m.toX ?? 0)},${num(m.toY ?? 0)}` : ''} at ${num(m.leaveAt ?? 0)}s${m.stops?.length ? ` +${m.stops.length} stops` : ''}`);
+  if (m.stagger) out.push(`stagger ${num(m.stagger)}s${m.order && m.order !== 'first' ? ` ${m.order}` : ''}${m.letters ? ` by ${m.letters}` : ''}`);
+  return out.join(', ');
+}
+
+export function styleText(s: Style): string {
+  const d = defaultParams(effectById(s.effect));
+  const params = changed(s.params, d);
+  const out = [`${s.effect}${params.length ? ` {${params.join(', ')}}` : ''}`];
+  if (s.stroke) out.push(`stroke ${num(s.stroke.width)} ${s.stroke.color} ${s.stroke.align}`);
+  if (s.depth) out.push(`depth ${num(s.depth.amount)} ${s.depth.color} ${num(s.depth.angle)}°`);
+  if (s.opacity !== undefined && s.opacity !== 1) out.push(`opacity ${num(s.opacity)}`);
+  if (s.blend && s.blend !== 'normal') out.push(s.blend);
+  if (s.soften) out.push(`soften ${num(s.soften)}`);
+  const a = Object.entries(s.animate ?? {});
+  if (a.length) out.push(`animate ${a.map(([k, v]) => anim(k, v)).join('; ')}`);
+  return out.join(' · ');
+}
+
+function modsText(mods: ModEntry[]): string {
+  return mods
+    .map((m) => {
+      const rest = changed(m as unknown as Record<string, unknown>, MODIFIER_DEFAULTS[m.kind] as unknown as Record<string, unknown>, ['kind', 'on', 'uid']);
+      return `${m.kind}[${m.uid}]${m.on === false ? ' off' : ''}${rest.length ? `(${rest.join(', ')})` : ''}`;
+    })
+    .join(' ')
+    .trim();
+}
+
+function contentText(n: Exclude<Node, { type: 'group' }>): string {
+  const c = n.content;
+  switch (c.type) {
+    case 'text': {
+      const extra = [c.tracking && `tracking ${num(c.tracking)}`, c.lineHeight !== 1 && c.text.includes('\n') && `leading ${num(c.lineHeight)}`, c.align !== 'center' && c.align, c.morph && `morph→${c.morph.font} ${num(c.morph.t)}`].filter(Boolean);
+      return `text "${clip(c.text.replace(/\n/g, '⏎'))}" ${c.font} ${num(c.size)}px${extra.length ? ` ${extra.join(' ')}` : ''}`;
+    }
+    case 'symbol': {
+      const f = changed(c.symbol as unknown as Record<string, unknown>, SYMBOL_DEFAULTS[c.symbol.kind] as unknown as Record<string, unknown>, ['kind']);
+      return `shape ${c.symbol.kind} ${num(c.size)}px${f.length ? ` (${f.join(', ')})` : ''}`;
+    }
+    case 'path':
+      return `outline${c.name ? ` "${c.name}"` : ''} ${num(c.size)}px (${(c.d.match(/[a-z]/gi) ?? []).length} commands)`;
+    case 'line': {
+      const t = c.trim;
+      const extra = [c.cap !== 'round' && c.cap, c.squiggle && `squiggle ${c.squiggle.kind}`, c.dash && `dash ${num(c.dash.dash)}/${num(c.dash.gap)}`, t && (t.start !== 0 || t.end !== 1 || t.offset) && `trim ${num(t.start)}–${num(t.end)}${t.offset ? `+${num(t.offset)}` : ''}`].filter(Boolean);
+      return `pen line ${num(c.width)}px wide, ${(c.d.match(/[a-z]/gi) ?? []).length} commands, ${num(c.size)}px${extra.length ? ` ${extra.join(' ')}` : ''}`;
+    }
+    case 'stroke':
+      return `brush ${c.points.length} points ${num(c.width)}px`;
+    case 'morph':
+      return `morph t ${num(c.t)}`;
+  }
+}
+
+function placeText(n: Node): string {
+  if (isGroup(n)) return '';
+  const out = [`at ${num(n.x)},${num(n.y)}`];
+  if (n.rotation) out.push(`rot ${num(n.rotation)}°`);
+  if (n.scale !== 1) out.push(`×${num(n.scale)}`);
+  if (n.sx !== 1 || n.sy !== 1) out.push(`stretch ${num(n.sx)}×${num(n.sy)}`);
+  return out.join(' ');
+}
+
+function flags(n: Node): string {
+  return [!n.visible && 'hidden', n.op !== 'add' && n.op, n.locked && 'locked', !isGroup(n) && n.guide && 'guide'].filter(Boolean).join(' ');
+}
+
+function nodeLines(n: Node, depth: number, out: string[]) {
+  const pad = '  '.repeat(depth);
+  const name = n.name ? `"${n.name}" ` : '';
+  const head = `${pad}- ${name}#${n.id}`;
+  const parts: string[] = [];
+  if (isGroup(n)) {
+    parts.push(`group of ${n.children.length}${n.merge ? ' merged' : ''}${n.clip ? ' clipping' : ''}`);
+    if (n.merge) parts.push(styleText(n.style));
+  } else {
+    parts.push(contentText(n), placeText(n), styleText(n.style));
+  }
+  const f = flags(n);
+  if (f) parts.push(f);
+  if (n.modifiers.length) parts.push(`mods ${modsText(n.modifiers)}`);
+  const m = motionText(n.motion);
+  if (m) parts.push(`motion ${m}`);
+  const a = Object.entries(n.animate ?? {});
+  if (a.length) parts.push(`animate ${a.map(([k, v]) => anim(k, v)).join('; ')}`);
+  out.push(`${head} ${parts.filter(Boolean).join(' · ')}`);
+  if (isGroup(n)) for (const c of [...n.children].reverse()) nodeLines(c, depth + 1, out);
+}
+
+export function backgroundText(b: Background): string {
+  const out = [`${b.fill.kind}${b.fill.kind === 'none' ? '' : ` ${b.fill.colors.join(' ')}`}${b.fill.kind === 'linear' ? ` ${num(b.fill.angle)}°` : ''}`];
+  if (b.grain) out.push(`grain ${num(b.grain)}`);
+  if (b.tile) out.push(`tile ${b.tile.shape} ${b.tile.fill.colors.join(' ')}`);
+  if (b.pattern) out.push(`pattern ${b.pattern.kind} ${b.pattern.color}`);
+  return out.join(' · ');
+}
+
+/** The whole project, top layer first (as the layers panel lists them). */
+export function describe(p: Project): string {
+  const tl = p.timeline ?? { duration: 6, loop: true };
+  const out = [
+    `"${p.name}" ${p.canvas.width}×${p.canvas.height} · background ${backgroundText(p.background)} · clock ${num(tl.duration)}s${tl.loop ? ' loop' : ''}`,
+    'layers, top first (x,y = px from the canvas centre; {…} = settings changed from the defaults):',
+  ];
+  for (const n of [...p.layers].reverse()) nodeLines(n, 0, out);
+  if (p.fonts.length) out.push(`fonts: ${p.fonts.map((f) => f.id + (f.data ? ' (embedded)' : '')).join(', ')}`);
+  return out.join('\n');
+}
diff --git a/ui/src/agent/edit.ts b/ui/src/agent/edit.ts
new file mode 100644
index 0000000..a005778
--- /dev/null
+++ b/ui/src/agent/edit.ts
@@ -0,0 +1,200 @@
+// Small, checked edits to a project, one assignment at a time:
+//
+//   Star.gloss=0.4              a material setting (bare keys find their home)
+//   "Big star".x=-120           a layer by name (quote names with dots) …
+//   #l12.content.text="HELLO"   … or by id; any path into the layer works
+//   Title.wave.amplitude=0.08   the layer's first modifier of that kind
+//   Title.motion.loop=float     motion is created when missing
+//   Title.animate.speed={"to":1,"period":4,"phase":0,"mode":"ramp"}
+//   canvas.width=1080 · background.fill.colors=["#000"] · timeline.duration=4
+//
+// Values are JSON when they parse as JSON, else plain text; null removes a
+// key. Numbers are checked against the setting's range, and unknown layers
+// or settings fail with the names that would have worked.
+import { defaultParams, EFFECTS, effectById } from '../render/effects';
+import { newMotion } from '../state/motion';
+import { isChoice, isGroup, MODIFIER_UI, SYMBOL_UI, type Field, type Node, type Project } from '../state/model';
+import type { ModifierKind } from '../engine/types';
+
+export class EditError extends Error {}
+
+export interface Edit {
+  project: Project;
+  /** What changed, as "Star style.params.gloss: 0.6 → 0.4". */
+  change: string;
+}
+
+type Obj = Record<string, unknown>;
+
+export function parseValue(raw: string): unknown {
+  const s = raw.trim();
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
+/** Split `target.path=value`, keeping quoted targets whole. */
+export function parseAssignment(a: string): { target: string; path: string[]; value: unknown } {
+  const eq = a.indexOf('=');
+  if (eq < 0) throw new EditError(`"${a}" needs a value: target.setting=value`);
+  const lhs = a.slice(0, eq).trim();
+  let target: string, rest: string;
+  if (lhs.startsWith('"')) {
+    const end = lhs.indexOf('"', 1);
+    if (end < 0) throw new EditError(`Unclosed quote in "${lhs}"`);
+    target = lhs.slice(1, end);
+    rest = lhs.slice(end + 1).replace(/^\./, '');
+  } else {
+    const dot = lhs.indexOf('.');
+    target = dot < 0 ? lhs : lhs.slice(0, dot);
+    rest = dot < 0 ? '' : lhs.slice(dot + 1);
+  }
+  if (!rest) throw new EditError(`"${lhs}" needs a setting after the layer: ${target}.<setting>=…`);
+  return { target, path: rest.split('.'), value: parseValue(a.slice(eq + 1)) };
+}
+
+function allNodes(nodes: Node[], out: Node[] = []): Node[] {
+  for (const n of nodes) {
+    out.push(n);
+    if (isGroup(n)) allNodes(n.children, out);
+  }
+  return out;
+}
+
+export function findNode(p: Project, target: string): Node {
+  const all = allNodes(p.layers);
+  const id = target.replace(/^#/, '');
+  const byId = all.find((n) => n.id === id);
+  if (byId) return byId;
+  for (const same of [(n: Node) => n.name === target, (n: Node) => n.name?.toLowerCase() === target.toLowerCase()]) {
+    const hits = all.filter(same);
+    if (hits.length === 1) return hits[0];
+    if (hits.length > 1) throw new EditError(`${hits.length} layers are called "${target}"; use an id: ${hits.map((n) => '#' + n.id).join(', ')}`);
+  }
+  const names = all.map((n) => (n.name ? `"${n.name}"` : `#${n.id}`));
+  throw new EditError(`No layer "${target}". Layers: ${names.join(', ')}`);
+}
+
+function checkField(f: Field | undefined, key: string, v: unknown, where: string) {
+  if (!f || v === null) return;
+  if (isChoice(f)) {
+    if (!f.options.some((o) => o.value === v)) throw new EditError(`${where}.${key} is one of ${f.options.map((o) => o.value).join('|')}`);
+  } else if (typeof v !== 'number' || v < f.min || v > f.max) {
+    throw new EditError(`${where}.${key} is a number ${f.min}…${f.max}${f.integer ? ' (whole)' : ''}, got ${JSON.stringify(v)}`);
+  }
+}
+
+function checkParam(effect: string, key: string, v: unknown) {
+  const e = effectById(effect);
+  const p = e.params.find((x) => x.key === key);
+  if (!p) throw new EditError(`${e.id} has no setting "${key}". Settings: ${e.params.map((x) => x.key).join(', ')}`);
+  if (v === null) return;
+  if (p.type === 'color') {
+    if (typeof v !== 'string' || !/^#[0-9a-f]{6}$/i.test(v)) throw new EditError(`${e.id}.${key} is a colour like "#ff3366", got ${JSON.stringify(v)}`);
+  } else if (typeof v !== 'number' || v < p.min || v > p.max) {
+    throw new EditError(`${e.id}.${key} is a number ${p.min}…${p.max}${p.options ? ` (${p.options.map((o, i) => `${i}=${o}`).join(' ')})` : ''}, got ${JSON.stringify(v)}`);
+  }
+}
+
+/** Where a short path goes on a node: the full path from the node. */
+function resolve(n: Node, path: string[]): { path: string[]; check?: (v: unknown) => void } {
+  const [head, ...rest] = path;
+  const o = n as unknown as Obj;
+  if (head === 'effect' && !rest.length) return { path: ['style', 'effect'] };
+  if (head === 'params' && rest.length === 1) return { path: ['style', 'params', rest[0]], check: (v) => checkParam(n.style.effect, rest[0], v) };
+  // Material settings animate on the style; modifier, shape and line keys (mod:…, sym:…, line:…) on the layer.
+  if (head === 'animate' && rest.length === 1) return { path: rest[0] in n.style.params ? ['style', 'animate', rest[0]] : ['animate', rest[0]] };
+  if (head === 'motion') return { path };
+  if (head in o) {
+    if (head === 'style' && rest[0] === 'params' && rest.length === 2) return { path, check: (v) => checkParam(n.style.effect, rest[1], v) };
+    if (head === 'modifiers' && rest.length === 2) {
+      const m = n.modifiers[Number(rest[0])];
+      if (m) return { path, check: (v) => checkField(MODIFIER_UI[m.kind].fields.find((f) => f.key === rest[1]), rest[1], v, m.kind) };
+    }
+    return { path };
+  }
+  if (!rest.length && head in n.style.params) return { path: ['style', 'params', head], check: (v) => checkParam(n.style.effect, head, v) };
+  if (head in MODIFIER_UI) {
+    const i = n.modifiers.findIndex((m) => m.kind === head);
+    if (i < 0) throw new EditError(`${n.name ?? n.id} has no ${head} modifier${n.modifiers.length ? `; it has ${n.modifiers.map((m) => m.kind).join(', ')}` : ''}. Add it with ${n.name ?? '#' + n.id}.modifiers=[…]`);
+    if (rest.length !== 1) throw new EditError(`Say which ${head} field: ${MODIFIER_UI[head as ModifierKind].fields.map((f) => f.key).join(', ')}`);
+    const kind = head as ModifierKind;
+    return { path: ['modifiers', String(i), rest[0]], check: (v) => checkField(MODIFIER_UI[kind].fields.find((f) => f.key === rest[0]), rest[0], v, kind) };
+  }
+  if (!isGroup(n)) {
+    const c = n.content as unknown as Obj;
+    if (head in c) return { path: ['content', ...path] };
+    if (n.content.type === 'symbol' && head in n.content.symbol) {
+      const kind = n.content.symbol.kind;
+      return { path: ['content', 'symbol', ...path], check: (v) => checkField(SYMBOL_UI[kind].fields.find((f) => f.key === head), head, v, kind) };
+    }
+  }
+  const content = isGroup(n) ? [] : [...Object.keys(n.content), ...(n.content.type === 'symbol' ? Object.keys(n.content.symbol) : [])];
+  const options = [...Object.keys(o), ...Object.keys(n.style.params), ...n.modifiers.map((m) => m.kind), ...content];
+  throw new EditError(`${n.name ?? '#' + n.id} has no "${head}". Try: ${[...new Set(options)].filter((k) => !['id', 'type', 'kind', 'symbol'].includes(k)).join(', ')}`);
+}
+
+function get(o: unknown, path: string[]): unknown {
+  return path.reduce<unknown>((x, k) => (x && typeof x === 'object' ? (x as Obj)[k] : undefined), o);
+}
+
+/** Set `path` on `root` in place, creating the last key only. */
+function put(root: Obj, path: string[], v: unknown, label: string) {
+  let o: unknown = root;
+  for (const k of path.slice(0, -1)) {
+    const next = (o as Obj)[k];
+    if (!next || typeof next !== 'object') throw new EditError(`${label}: nothing at "${k}" in ${path.join('.')}`);
+    o = next;
+  }
+  const last = path[path.length - 1];
+  if (Array.isArray(o) && !/^\d+$/.test(last)) throw new EditError(`${label}: ${path.slice(0, -1).join('.')} is a list; use an index`);
+  if (v === null && !Array.isArray(o)) delete (o as Obj)[last];
+  else (o as Obj)[last] = v;
+}
+
+const ROOTS: Record<string, string[]> = { canvas: ['canvas'], background: ['background'], bg: ['background'], timeline: ['timeline'], project: [] };
+
+/** Apply one assignment to a copy of `p`. */
+export function applyEdit(p: Project, assignment: string): Edit {
+  const { target, path, value } = parseAssignment(assignment);
+  const project = structuredClone(p);
+  const root = ROOTS[target.toLowerCase()];
+  if (root && !allNodes(p.layers).some((n) => n.name === target)) {
+    if (target.toLowerCase() === 'timeline') project.timeline ??= { duration: 6, loop: true };
+    const full = [...root, ...path];
+    const before = get(project, full);
+    put(project as unknown as Obj, full, value, target);
+    return { project, change: `${full.join('.')}: ${fmtv(before)} → ${fmtv(value)}` };
+  }
+  const n = findNode(project, target);
+  const r = resolve(n, path);
+  r.check?.(value);
+  if (r.path[0] === 'motion') n.motion ??= newMotion();
+  if (r.path[0] === 'animate') n.animate ??= {};
+  if (r.path[0] === 'style' && r.path[1] === 'animate') n.style.animate ??= {};
+  const before = get(n, r.path);
+  if (r.path.join('.') === 'style.effect') {
+    if (typeof value !== 'string' || !EFFECTS.some((e) => e.id === value)) throw new EditError(`effect is one of ${EFFECTS.map((e) => e.id).join(', ')}`);
+    // A new material keeps the settings both share and starts the rest at its defaults.
+    const d = defaultParams(effectById(value));
+    n.style = { ...n.style, effect: value, params: { ...d, ...Object.fromEntries(Object.entries(n.style.params).filter(([k]) => k in d)) }, animate: undefined };
+  } else {
+    put(n as unknown as Obj, r.path, value, n.name ?? n.id);
+  }
+  return { project, change: `${n.name ? `"${n.name}"` : '#' + n.id} ${r.path.join('.')}: ${fmtv(before)} → ${fmtv(value)}` };
+}
+
+const fmtv = (v: unknown) => (v === undefined ? '(unset)' : JSON.stringify(v));
+
+/** Apply several assignments in order. */
+export function applyEdits(p: Project, assignments: string[]): { project: Project; changes: string[] } {
+  const changes: string[] = [];
+  for (const a of assignments) {
+    const e = applyEdit(p, a);
+    p = e.project;
+    changes.push(e.change);
+  }
+  return { project: p, changes };
+}
diff --git a/ui/src/agent/node.ts b/ui/src/agent/node.ts
new file mode 100644
index 0000000..7650d86
--- /dev/null
+++ b/ui/src/agent/node.ts
@@ -0,0 +1,14 @@
+// The CLI's commands that don't draw (catalog, describe, scene, set) run this
+// in Node through Vite, without a browser: templates, migration and edits are
+// plain data.
+import { TEMPLATES } from '../state/templates';
+import { migrate } from '../state/migrate';
+import type { Project } from '../state/model';
+import { catalog as catalogText, findTemplate } from './catalog';
+
+export { describe } from './describe';
+export { applyEdits } from './edit';
+export { migrate };
+
+export const catalog = (q = '') => catalogText(q, TEMPLATES);
+export const template = (name: string): Project => findTemplate(TEMPLATES, name).make();
diff --git a/ui/src/agent/page.ts b/ui/src/agent/page.ts
new file mode 100644
index 0000000..6ed0541
--- /dev/null
+++ b/ui/src/agent/page.ts
@@ -0,0 +1,344 @@
+// The app side of the morpho CLI (scripts/morpho.mjs), on
+// `await window.morphotype.agent()`: load a design, draw it at any times as
+// one image (a filmstrip when there are several), draw a grid of variations,
+// and check it. Everything returns text or one PNG, so a caller spends one
+// image on what would otherwise be a dozen screenshots.
+import { engine } from '../engine/client';
+import { fromBase64 } from '../fonts/library';
+import { effectById } from '../render/effects';
+import { getRenderer, loadProjectFonts } from '../app/actions';
+import { geometryFrames, holdLiveGeometry } from '../app/geoMotion';
+import { unpackImages } from '../state/assets';
+import { clock, timelineOf } from '../state/clock';
+import { anyGeoAnim } from '../state/geoMotion';
+import { migrate } from '../state/migrate';
+import { isGroup, type Node, type Project } from '../state/model';
+import { isStill } from '../state/motion';
+import { replaceProject, store } from '../state/store';
+import { loadedTemplates, loadTemplates } from '../state/templateCatalog';
+import { buildScene } from '../state/tree';
+import { catalog, findTemplate } from './catalog';
+import { label, motionFindings, outside, presence, report, spread, structural, type Finding, type Pixels, diff } from './check';
+import { describe, num } from './describe';
+import { applyEdits } from './edit';
+
+/** Geometry quality for output (the preview builds at 120), as exports use. */
+const OUTPUT_QUALITY = 360;
+const PREVIEW_QUALITY = 120;
+
+const nextFrame = () => new Promise((r) => requestAnimationFrame(() => r(null)));
+
+async function until(ok: () => boolean, what: string, ms = 30_000) {
+  const end = performance.now() + ms;
+  while (!ok()) {
+    if (performance.now() > end) throw new Error(`Timed out waiting for ${what}`);
+    await new Promise((r) => setTimeout(r, 15));
+  }
+}
+
+/** Open a project (a .morpho file's JSON or a Project) and wait until it's drawn. */
+async function load(raw: unknown, quality = OUTPUT_QUALITY): Promise<{ ms: number }> {
+  const t0 = performance.now();
+  await until(() => store.get().ready, 'the app to start', 60_000);
+  const p = migrate(raw);
+  await loadProjectFonts((p.fonts ?? []).flatMap((f) => (f.data ? [{ id: f.id, name: f.name, bytes: fromBase64(f.data) }] : [])));
+  unpackImages(p.images);
+  replaceProject({ ...p, fonts: [], images: undefined });
+  store.set({ selection: [], toasts: [] });
+  // Let the app's build loop ask for its (preview) build first: the engine
+  // answers every waiting caller with the newest result, so ours wins.
+  await nextFrame();
+  await nextFrame();
+  const build = await engine.build(buildScene(store.get().project, quality).doc);
+  store.set({ build });
+  await until(() => store.get().build === build, 'the engine');
+  await nextFrame();
+  await nextFrame();
+  return { ms: Math.round(performance.now() - t0) };
+}
+
+async function template(name: string): Promise<Project> {
+  return findTemplate(await loadTemplates(), name).make();
+}
+
+/** Run `fn` with fields at preview density: sheets and checks don't need 2× supersampling. */
+async function draft<T>(fn: () => Promise<T>): Promise<T> {
+  const r = getRenderer();
+  const was = r?.exportSupersample;
+  if (r) r.exportSupersample = 1;
+  try {
+    return await fn();
+  } finally {
+    if (r && was !== undefined) r.exportSupersample = was;
+  }
+}
+
+/** The current design at each time (null: at rest, as a still export draws it). */
+async function frames(times: (number | null)[], scale: number, transparent = false): Promise<Pixels[]> {
+  const r = getRenderer();
+  if (!r) throw new Error('The GPU preview isn’t available (WebGL2 failed to start).');
+  const p = store.get().project;
+  const moving = times.some((t) => t !== null) ? await geometryFrames(p, times.map((t) => t ?? 0), OUTPUT_QUALITY) : null;
+  return holdLiveGeometry(async (show) => {
+    const f = r.exportFrames(scale, transparent);
+    try {
+      return times.map((t, i) => {
+        show(t === null ? null : (moving?.[i] ?? null));
+        const img = f.frame(t);
+        return { data: img.data, width: img.width, height: img.height };
+      });
+    } finally {
+      f.close();
+    }
+  });
+}
+
+async function png(c: OffscreenCanvas): Promise<string> {
+  const buf = new Uint8Array(await (await c.convertToBlob({ type: 'image/png' })).arrayBuffer());
+  let bin = '';
+  for (let i = 0; i < buf.length; i += 0x8000) bin += String.fromCharCode(...buf.subarray(i, i + 0x8000));
+  return btoa(bin);
+}
+
+function toCanvas(p: Pixels): OffscreenCanvas {
+  const c = new OffscreenCanvas(p.width, p.height);
+  c.getContext('2d')!.putImageData(new ImageData(new Uint8ClampedArray(p.data), p.width, p.height), 0, 0);
+  return c;
+}
+
+/** Cells in a grid with a caption under each, on a dark sheet. */
+async function sheet(cells: { img: Pixels; label: string }[], cols: number): Promise<{ png: string; width: number; height: number }> {
+  const w = Math.max(...cells.map((c) => c.img.width)), h = Math.max(...cells.map((c) => c.img.height));
+  const gap = 8, cap = cells.some((c) => c.label) ? 22 : 0;
+  const rows = Math.ceil(cells.length / cols);
+  const W = cols * w + (cols + 1) * gap, H = rows * (h + cap) + (rows + 1) * gap;
+  const c = new OffscreenCanvas(W, H);
+  const g = c.getContext('2d')!;
+  g.fillStyle = '#161616';
+  g.fillRect(0, 0, W, H);
+  g.font = '13px ui-monospace, Menlo, monospace';
+  g.textBaseline = 'middle';
+  cells.forEach((cell, i) => {
+    const x = gap + (i % cols) * (w + gap), y = gap + Math.floor(i / cols) * (h + cap + gap);
+    g.drawImage(toCanvas(cell.img), x, y);
+    if (!cap) return;
+    g.fillStyle = '#d8d8d8';
+    let text = cell.label;
+    while (text.length > 4 && g.measureText(text).width > w - 8) text = text.slice(0, -2) + '…';
+    g.fillText(text, x + 4, y + h + cap / 2);
+  });
+  return { png: await png(c), width: W, height: H };
+}
+
+const gridCols = (n: number) => (n <= 3 ? n : n <= 4 ? 2 : n <= 9 ? 3 : n <= 16 ? 4 : 6);
+
+/** Output scale that keeps each cell's long side near `px`. */
+const fit = (p: Project, px: number) => Math.min(4, px / Math.max(p.canvas.width, p.canvas.height));
+
+interface RenderOpts {
+  /** Seconds on the clock; null (or absent) draws the design at rest. */
+  at?: (number | null)[];
+  scale?: number;
+  /** Long side of each cell in px, when no scale is given (sheets default to 360). */
+  size?: number;
+  transparent?: boolean;
+  cols?: number;
+}
+
+async function render(o: RenderOpts = {}) {
+  const p = store.get().project;
+  const at = o.at?.length ? o.at : [null];
+  const scale = o.scale ?? (at.length > 1 ? fit(p, o.size ?? 360) : o.size ? fit(p, o.size) : 1);
+  const imgs = await frames(at, scale, o.transparent);
+  if (imgs.length === 1) return { png: await png(toCanvas(imgs[0])), width: imgs[0].width, height: imgs[0].height };
+  return sheet(
+    imgs.map((img, i) => ({ img, label: at[i] === null ? 'rest' : `${num(at[i]!)}s` })),
+    o.cols ?? Math.min(at.length, 6),
+  );
+}
+
+/** One image of `variants`, each a list of edits on the current design, at one time. */
+async function vary(variants: { label: string; edits: string[] }[], o: { at?: number | null; size?: number; cols?: number } = {}) {
+  return draft(() => varyCells(variants, o));
+}
+
+async function varyCells(variants: { label: string; edits: string[] }[], o: { at?: number | null; size?: number; cols?: number }) {
+  const base = structuredClone(store.get().project);
+  const cells: { img: Pixels; label: string }[] = [];
+  try {
+    for (const v of variants) {
+      // Cells are small: the preview's outlines are fine and much quicker.
+      await load(applyEdits(base, v.edits).project, PREVIEW_QUALITY);
+      const [img] = await frames([o.at ?? null], fit(base, o.size ?? 360));
+      cells.push({ img, label: v.label });
+    }
+  } finally {
+    await load(base);
+  }
+  return sheet(cells, o.cols ?? gridCols(cells.length));
+}
+
+function shrink(p: Pixels, side: number): Pixels {
+  const k = Math.min(1, side / Math.max(p.width, p.height));
+  if (k === 1) return p;
+  const w = Math.max(1, Math.round(p.width * k)), h = Math.max(1, Math.round(p.height * k));
+  const c = new OffscreenCanvas(w, h);
+  const g = c.getContext('2d')!;
+  g.drawImage(toCanvas(p), 0, 0, w, h);
+  return { data: g.getImageData(0, 0, w, h).data, width: w, height: h };
+}
+
+/**
+ * The design against a reference picture (PNG or JPEG, base64), drawn at the
+ * reference's size: scores in words, and one image of reference, render and
+ * where they differ.
+ */
+async function compare(ref: string, o: { at?: number | null; size?: number } = {}) {
+  const bmp = await createImageBitmap(await (await fetch(`data:image/*;base64,${ref}`)).blob());
+  const p = store.get().project;
+  const [img] = await frames([o.at ?? null], bmp.width / p.canvas.width);
+  const c = new OffscreenCanvas(img.width, img.height);
+  const g = c.getContext('2d')!;
+  g.drawImage(bmp, 0, 0, img.width, img.height);
+  const want: Pixels = { data: g.getImageData(0, 0, img.width, img.height).data, width: img.width, height: img.height };
+  const heat = new Uint8ClampedArray(img.data.length);
+  let clear = 0;
+  for (let i = 0; i < heat.length; i += 4) {
+    const d = Math.abs(img.data[i] - want.data[i]) + Math.abs(img.data[i + 1] - want.data[i + 1]) + Math.abs(img.data[i + 2] - want.data[i + 2]);
+    if (d > 60) clear++;
+    heat[i] = heat[i + 1] = heat[i + 2] = Math.min(255, d * 2);
+    heat[i + 3] = 255;
+  }
+  // Layout: the same comparison on 24-px-wide thumbnails, where only big shapes and colour areas survive.
+  const layout = diff(shrink(img, 24), shrink(want, 24));
+  const aspect = bmp.width / bmp.height / (p.canvas.width / p.canvas.height);
+  const side = o.size ?? 480;
+  const out = await sheet(
+    [
+      { img: shrink(want, side), label: 'reference' },
+      { img: shrink(img, side), label: o.at == null ? 'design' : `design at ${num(o.at)}s` },
+      { img: shrink({ data: heat, width: img.width, height: img.height }, side), label: 'difference' },
+    ],
+    3,
+  );
+  const lines = [
+    `colour difference ${num(diff(img, want))}/255 per channel · ${num((clear / (heat.length / 4)) * 100)}% of pixels clearly differ · layout difference ${num(layout)}/255 (big shapes and colour areas)`,
+    ...(Math.abs(aspect - 1) > 0.02 ? [`! the reference is ${bmp.width}×${bmp.height}, a different shape from the ${p.canvas.width}×${p.canvas.height} canvas: it was stretched to fit`] : []),
+  ];
+  return { ...out, text: lines.join('\n') };
+}
+
+function moves(p: Project): boolean {
+  let any = anyGeoAnim(p.layers);
+  const walk = (ns: Node[]) =>
+    ns.forEach((n) => {
+      if (!isStill(n.motion) || Object.keys(n.style.animate ?? {}).length || effectById(n.style.effect).animated?.(n.style.params)) any = true;
+      if (isGroup(n)) walk(n.children);
+    });
+  walk(p.layers);
+  return any;
+}
+
+/** Leaf layers (and merged groups) that draw something of their own. */
+function drawn(nodes: Node[], out: Node[] = []): Node[] {
+  for (const n of nodes) {
+    if (!n.visible) continue;
+    if (isGroup(n) && !n.merge) drawn(n.children, out);
+    else if (isGroup(n) || !n.guide) out.push(n);
+  }
+  return out;
+}
+
+function hide(p: Project, id: string): Project {
+  const q = structuredClone(p);
+  const go = (ns: Node[]) =>
+    ns.forEach((n) => {
+      if (n.id === id) n.visible = false;
+      else if (isGroup(n)) go(n.children);
+    });
+  go(q.layers);
+  return q;
+}
+
+/** Every check, as a short report. `layers` caps how many layers get the (slower) visibility check. */
+async function check(o: { size?: number; layers?: number } = {}): Promise<string> {
+  return draft(() => checkAll(o));
+}
+
+async function checkAll(o: { size?: number; layers?: number }): Promise<string> {
+  const p = structuredClone(store.get().project);
+  const findings: Finding[] = structural(p, store.get().build);
+  const scale = fit(p, o.size ?? 360);
+  const tl = timelineOf(p);
+  try {
+    // Motion: pairs of frames one video frame apart, across the clock and over the seam.
+    if (moves(p)) {
+      const dt = 1 / 30, n = 12, D = tl.duration;
+      const starts = Array.from({ length: n }, (_, i) => ((i + 0.5) * D) / n).filter((t) => t + dt <= D);
+      const at = starts.flatMap((t) => [t, t + dt]);
+      if (tl.loop) at.push(D - dt, 0);
+      const imgs = await frames(at, scale);
+      const steps = starts.map((t, i) => ({ t, d: diff(imgs[2 * i], imgs[2 * i + 1]) }));
+      findings.push(...motionFindings(steps, tl.loop ? diff(imgs[imgs.length - 2], imgs[imgs.length - 1]) : null, true));
+    } else findings.push({ level: 'info', text: 'still design: nothing moves' });
+    // What shows: the design against itself with each layer hidden, at the same quality.
+    await load(p, PREVIEW_QUALITY);
+    const [still] = await frames([null], scale);
+    if (spread(still) < 2) findings.push({ level: 'warn', text: 'the design looks empty: one flat colour' });
+    const all = drawn(p.layers);
+    const cap = o.layers ?? 16;
+    const picked = [...all.filter((n) => !isGroup(n) && n.content.type === 'text'), ...all.filter((n) => isGroup(n) || n.content.type !== 'text')].slice(0, cap);
+    const boxes = new Map([...(store.get().build?.layers ?? []), ...(store.get().build?.renders ?? [])].map((l) => [l.id, l.bbox]));
+    for (const n of picked) {
+      const b = boxes.get(n.id);
+      if (b && outside(b, p.canvas.width, p.canvas.height).share > 0.995) continue;
+      await load(hide(p, n.id), PREVIEW_QUALITY);
+      const [without] = await frames([null], scale);
+      const s = presence(still, without);
+      // Unseen: next to nothing changes, for its size (tiny marks and hairlines count too).
+      const area = b ? Math.max(0, b[2] - b[0]) * Math.max(0, b[3] - b[1]) * scale * scale : 0;
+      if (s.px < Math.max(1, Math.min(area * 0.02, 40))) findings.push({ level: 'warn', text: `${label(n)}: can't be seen at rest (covered, transparent, off the canvas or still to enter)` });
+      else if (!isGroup(n) && n.content.type === 'text' && s.contrast < 2) findings.push({ level: 'warn', text: `${label(n)}: low contrast, ${num(s.contrast)}:1 against what's behind it` });
+    }
+    findings.push({ level: 'info', text: `looked at ${picked.length} of ${all.length} layers${picked.length < all.length ? ' (raise --layers to see the rest)' : ''}` });
+  } finally {
+    await load(p);
+  }
+  return report(`"${p.name}" ${p.canvas.width}×${p.canvas.height}${moves(p) ? `, ${num(tl.duration)}s${tl.loop ? ' loop' : ''}` : ''}`, findings);
+}
+
+/**
+ * Hold the editor's live preview still while the agent works: its animation
+ * loop and moving outlines compete for the main thread and the engine, and
+ * make every step several times slower.
+ */
+async function quietly<T>(fn: () => Promise<T>): Promise<T> {
+  const playing = clock.playing;
+  clock.pause(timelineOf(store.get().project));
+  try {
+    return await holdLiveGeometry(() => fn());
+  } finally {
+    if (playing) clock.play(timelineOf(store.get().project));
+  }
+}
+
+export const agent = {
+  quietly,
+  load: (raw: unknown) => load(raw),
+  template,
+  async open(name: string) {
+    return load(await template(name));
+  },
+  project: () => store.get().project,
+  describe: () => describe(store.get().project),
+  catalog: async (q = '') => catalog(q, loadedTemplates() ?? (await loadTemplates())),
+  async edit(assignments: string[]) {
+    const { project, changes } = applyEdits(store.get().project, assignments);
+    await load(project);
+    return changes;
+  },
+  render,
+  vary,
+  check,
+  compare,
+};
diff --git a/ui/src/main.tsx b/ui/src/main.tsx
index 7481ddd..42ba021 100644
--- a/ui/src/main.tsx
+++ b/ui/src/main.tsx
@@ -25,6 +25,8 @@ import './styles.css';
   get renderer() {
     return getRenderer();
   },
+  // The morpho CLI's handle (see agent/page.ts), in its own chunk.
+  agent: () => import('./agent/page').then((m) => m.agent),
 };
 
 createRoot(document.getElementById('root')!).render(

From 1f2db2a2f7a98bdb93c1d35c95f767c39240dec5 Mon Sep 17 00:00:00 2001
From: srivtx <crypticcc101@gmail.com>
Date: Sat, 24 Oct 2026 01:19:07 +0530
Subject: [PATCH 2/2] morpho: docs, CLAUDE.md and an end-to-end check

docs/AGENT-TOOLS.md covers every command, the edit syntax, what check
looks for and the timings. CLAUDE.md points agents at morpho before the
sources or screenshots. The end-to-end test drives the agent handle in
the production build: edit, still, filmstrip, grid and check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md           | 29 +++++++++++++++
 README.md           |  4 +-
 docs/AGENT-TOOLS.md | 91 +++++++++++++++++++++++++++++++++++++++++++++
 scripts/e2e.mjs     | 17 +++++++++
 4 files changed, 140 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md
 create mode 100644 docs/AGENT-TOOLS.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b79883e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,29 @@
+# Morphotype
+
+A type and logo lab. The geometry engine is Rust (`crates/morpho-core`), compiled to WebAssembly and run in a worker. The UI is React/TypeScript (`ui/src`), and materials are WebGL2 shaders (`ui/src/render`). `docs/ARCHITECTURE.md` explains how they fit together.
+
+## Designing in the app: use morpho
+
+Don't read the template or effect sources to learn what exists, and don't screenshot the editor to judge a design. Use the CLI (`docs/AGENT-TOOLS.md`):
+
+```sh
+npm run morpho -- serve &                 # once: keeps a browser warm (drawing then takes < 1 s)
+npm run morpho -- catalog                 # what exists; then: catalog chrome / glitch / star / motion / keyframes / layers
+npm run morpho -- describe "UFO poster"   # a design as text, changed settings only
+npm run morpho -- scene "UFO poster" -o ufo.morpho
+npm run morpho -- set ufo.morpho 'Title.gloss=0.4' 'Star.x=-120'
+npm run morpho -- render ufo.morpho --frames 6           # one filmstrip image
+npm run morpho -- vary ufo.morpho --vary 'Title.liquid=0.2,0.6,1.2'
+npm run morpho -- check ufo.morpho                       # problems in words
+npm run morpho -- compare ufo.morpho reference.png
+```
+
+Prefer `check`, `describe` and text output over images. When you do need to look, ask for one contact sheet (`--frames`, `vary`), not several renders.
+
+## Commands
+
+- `npm run dev`: the app at http://localhost:1420 (builds the engine in debug first)
+- `npm test`: Rust and TypeScript unit tests
+- `npm run typecheck`
+- `npm run build && npm run test:e2e`: browser end-to-end test
+- `npm run wasm:dev`: rebuild the engine after Rust changes
diff --git a/README.md b/README.md
index 48a9db0..7e5dba5 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ npm install
 | Build the web app | `npm run build` (output in `dist/`) |
 | Rust and UI unit tests | `npm test` |
 | Browser end-to-end test | `npm run build && npm run test:e2e` |
+| Design from the command line, for AI agents and scripts (catalog, describe, edit, render, variations, checks; see [docs/AGENT-TOOLS.md](docs/AGENT-TOOLS.md)) | `npm run morpho -- help` |
 | Live render studio (templates → PNG, compare with a reference) | `node scripts/studio.mjs`, then e.g. `curl '127.0.0.1:7799/compare?tpl=UFO%20poster&ref=ref.png&out=diff.png'` |
 | Frame cost of moving geometry (1, 10, 50 animated pen lines, on the GPU) | `npx vite --port 1437`, then `node scripts/perf-geo.mjs` |
 | Measure an outline on a reference picture | `cargo run --release --example refpath -- mask.pgm` (a white-on-black PGM mask → path data) |
@@ -155,8 +156,9 @@ src-tauri            Desktop shell: system fonts, font install, dialogs
 ui/src/engine        Worker + client for the engine
 ui/src/render        WebGL2 renderer, SDF passes and effect shaders
 ui/src/components    Editor UI
+ui/src/agent         The morpho CLI's side of the app: catalog, describe, edits, checks
 ui/public/fonts      Bundled OFL fonts
-scripts              WASM build and end-to-end test
+scripts              WASM build, end-to-end test and the morpho CLI
 website              Landing page (static; Vercel deploys it from main to morphotype.srivtx.xyz)
 ```
 
diff --git a/docs/AGENT-TOOLS.md b/docs/AGENT-TOOLS.md
new file mode 100644
index 0000000..c29bfba
--- /dev/null
+++ b/docs/AGENT-TOOLS.md
@@ -0,0 +1,91 @@
+# morpho: the app from the command line
+
+`scripts/morpho.mjs` drives Morphotype without its interface. It's built for AI agents (and scripts) designing in the app: every command answers in a few lines of text or in **one** PNG, so learning what exists, reading a design, editing it and judging it doesn't mean reading source files or taking a pile of screenshots.
+
+```sh
+npm run morpho -- help
+```
+
+## Commands
+
+| Command | What it gives back | Browser? |
+| --- | --- | --- |
+| `catalog [query]` | What designs are made of. With no query, a one-screen index. With a section (`materials`, `modifiers`, `shapes`, `motion`, `keyframes`, `layers`, `presets`, `recipes`, `fonts`, `backgrounds`, `canvas`, `templates`), that whole section. With a name (`chrome`, `glitch`, `star`, `"Ice chrome"`), every setting with its range, default and label. Anything else is searched. | no |
+| `describe <scene>` | The design as a text tree, top layer first. Each layer is one line: what it is, where it sits, its material, modifiers, motion and keyframes, showing **only settings that differ from the defaults**. | no |
+| `scene <template> [-o f]` | Writes a template as an editable `.morpho` file. | no |
+| `set <file> <a=b>…` | Edits a `.morpho` file in place and prints each change (`--dry` to only print them). | no |
+| `render <scene>` | A PNG. With one time it's that frame (at rest by default). With `--at 0,1,2` or `--frames 8` it's one captioned filmstrip. | yes |
+| `vary <scene>` | One PNG with a captioned cell per variation: `--vary` multiplies lists of values, `--variant 'a=1; b=2'` adds hand-made combinations. | yes |
+| `check <scene>` | Problems, in words (see below). | yes |
+| `compare <scene> <image>` | How close the design is to a reference picture: colour, pixel and layout scores, plus one reference \| design \| difference image. | yes |
+| `serve` / `stop` | Keeps Vite and a browser running. While it's up, drawing commands take well under a second instead of 5–15 s. | — |
+
+`<scene>` is a template name (exact, any case, or a unique part of one) or a `.morpho`/`.json` file. PNGs go to `test-results/morpho/` unless you pass `--out`. `--json` gives machine-readable output.
+
+## Editing: `Layer.setting=value`
+
+Use the same assignments for `set`, and for `--set`, `--vary` and `--variant` on any command (with `--set`, files are left alone):
+
+```sh
+morpho set y2k.morpho 'Topo blob.gloss=0.8'           # a material setting
+morpho set y2k.morpho '"Serif K".fill="#ff2d55"'      # quote names that contain dots
+morpho set y2k.morpho 'Pixel 2.pixelate.size=0.1'      # the layer's first modifier of that kind
+morpho set y2k.morpho 'Spikes.rays=20'                 # a shape field
+morpho set y2k.morpho 'Caption.text="Hello"'           # a content field
+morpho set y2k.morpho 'Chrome star.motion.loop=spin'   # motion is created when missing
+morpho set y2k.morpho 'Ball.animate.liquid={"to":1,"period":4,"phase":0,"mode":"swing"}'
+morpho set y2k.morpho 'canvas.width=1080' 'timeline.duration=4' 'background.grain=0.2'
+```
+
+- **Addressing a layer.** Use its name or its `#id`. Bare keys find their own home: a material setting, a content field, a shape field, or a modifier kind. A full path (`style.params.gloss`, `modifiers.0.amount`) also works.
+- **Values.** A value is JSON when it parses as JSON, and plain text otherwise. `null` removes a key.
+- **Checks.** Numbers are checked against the setting's range. Unknown layers or settings fail with a list of the names that would have worked.
+- **Changing the material.** Setting `effect` switches the material. Settings the old and new materials share are kept; the rest start at the new material's defaults.
+- **Template ids.** They are generated afresh each time a template is made, so address template layers by name. After `scene`, the ids in the file stay fixed.
+
+## What `check` looks for
+
+**From the project and the engine's build:**
+- layers the engine couldn't build;
+- layers entirely or partly off the canvas;
+- text too small to read;
+- unknown materials and invalid colours;
+- settings outside their range;
+- keyframes that point at nothing;
+- entrances or exits timed after the clock ends.
+
+**From the pixels:**
+- layers that can't be seen at rest: each layer is hidden in turn and the image compared, scaled to the layer's size so hairlines and tiny marks count;
+- text with low contrast against what's actually behind it;
+- a blank, one-colour design;
+- sudden jumps in the motion (frame pairs one video frame apart, sampled across the clock);
+- a loop that jumps where it starts over.
+
+## Speed
+
+Drawing runs on the GPU by default, with SwiftShader as a fallback if WebGL won't start there. Pass `--cpu` (or set `MORPHO_CPU=1`) for SwiftShader everywhere: the same pixels on every machine, about 4× slower.
+
+While a job runs, the editor's live preview is held still, because its animation loop competes for the main thread.
+
+With `serve` running, timings on an M-series Mac for a 14-layer animated poster:
+
+| Command | Time |
+| --- | --- |
+| `render` | 0.2 s |
+| six-frame filmstrip | 0.3 s |
+| six-cell `vary` | 0.8 s |
+| full `check` | 1.9 s |
+
+Under `serve`, edits to the app's TypeScript reload the page by themselves. After an engine (Rust) change, run `npm run wasm:dev`.
+
+## How it fits together
+
+| File | What it does |
+| --- | --- |
+| `ui/src/agent/catalog.ts` | Generates the catalog from the same registries the Inspector draws from (`EFFECTS`, `PRESETS`, `MODIFIER_UI`, `SYMBOL_UI`, `LOOP_UI`, …), so new materials, modifiers and shapes show up without touching it. A test fails if the layer-format notes miss a field that the layer factories create. |
+| `ui/src/agent/describe.ts` | The text tree. |
+| `ui/src/agent/edit.ts` | Assignments and their checks. |
+| `ui/src/agent/check.ts` | Structural checks and the pixel measures (pure, unit-tested). |
+| `ui/src/agent/page.ts` | The in-app side, on `await window.morphotype.agent()` (its own chunk). Loads a project with its fonts and pictures, builds it at export quality, and draws frames through the renderer's export path. Contact sheets are composed in an `OffscreenCanvas`. |
+| `ui/src/agent/node.ts` | What the no-browser commands load in Node through Vite's SSR loader. |
+| `scripts/morpho.mjs` | The CLI: argument parsing, Vite and Playwright, the `serve` daemon (`MORPHO_PORT`, default 7801). |
diff --git a/scripts/e2e.mjs b/scripts/e2e.mjs
index b3b63a4..7bd6a36 100644
--- a/scripts/e2e.mjs
+++ b/scripts/e2e.mjs
@@ -893,6 +893,23 @@ try {
   check(await until((st) => st.mode === 'design' && st.fonts.some((f) => f.name.startsWith('Testa Grotesk'))), 'Use in Design adds the font under its own name');
   s = await state();
   check(layersOf(s).some((l) => l.content?.font?.startsWith('custom-')), 'a text layer is set in the new font');
+
+  // ---- The agent handle the morpho CLI drives: load, edit, draw, vary and check in words ----
+  const agent = await page.evaluate(async () => {
+    const a = await window.morphotype.agent();
+    return a.quietly(async () => {
+      await a.open('Animated · Y2K set');
+      const changes = await a.edit(['"Serif K".fill="#ff2d55"', 'Brand.x=2000']);
+      const still = await a.render({ size: 300 });
+      const strip = await a.render({ at: [0, 1, 2], size: 200 });
+      const grid = await a.vary([{ label: 'blue', edits: ['"Serif K".fill="#2347ff"'] }, { label: 'red', edits: [] }], { size: 200 });
+      const report = await a.check({ size: 240, layers: 4 });
+      return { changes, still: [still.width, still.height], strip: [strip.width, strip.height], grid: [grid.width, grid.height], report, text: a.describe() };
+    });
+  });
+  check(agent.changes.length === 2 && agent.text.includes('flat {fill #ff2d55}'), `agent edits the design (${agent.changes[0]})`);
+  check(agent.still[0] === 300 && agent.strip[0] > 600 && agent.grid[0] > 400, `agent draws a still ${agent.still.join('×')}, a filmstrip ${agent.strip.join('×')} and a grid ${agent.grid.join('×')}`);
+  check(/✗ "Brand" .*entirely outside the canvas/.test(agent.report), `agent check finds the layer moved off the canvas: ${agent.report.split('\n')[0]}`);
 } catch (e) {
   errors.push(`crashed: ${e.message.split('\n').slice(0, 12).join(' / ')}`);
   const pages = browser.contexts().flatMap((c) => c.pages());