From 9c07f8157bc9eb73fd4e3a1556ff891ebd9e4390 Mon Sep 17 00:00:00 2001
From: srivtx <crypticcc101@gmail.com>
Date: Sat, 24 Oct 2026 01:50:17 +0530
Subject: [PATCH 1/2] morpho: build from scratch, timing, layout notes, video
 and fit

From making a poster with nothing but morpho, the gaps were: adding
things, seeing when things move, judging layout, exporting video, and
matching a reference without guessing. Now:

- new / add (text, shape, line, path, modifier, group, font, image) /
  remove / duplicate / arrange, with presets, recipes and placement;
  Layer.preset= and Layer.recipe= work in any assignment
- align: lines layers up by what they draw, not their anchors
- timing: entrances, exits, loops and keyframes as bars on the clock,
  with notes on rhythm (all at once, dead air, cut off by the clock)
- layout, and in check: boxes and margins, near-miss edges, nearly
  centred, crowded edges, no clear lead, visual weight and palette
- video: MP4, WebM, GIF or PNG frames, drawn frame by frame and piped
  to ffmpeg (a 4 s loop exports in about 3 s)
- fit: tunes settings until the design matches a reference picture

Fixes found on the way: a new loop or entrance kind takes its own
default amount (spin was 16 turns); motion pops are judged against the
frames either side, so fast smooth moves aren't flagged; loop seams
against the frame before; embedded fonts survive reloads; weight is
measured from pixel centres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/morpho.mjs         | 203 +++++++++++++++++++++++++-
 ui/src/agent/agent.test.ts | 161 +++++++++++++++++++-
 ui/src/agent/build.ts      | 292 +++++++++++++++++++++++++++++++++++++
 ui/src/agent/check.ts      |  27 ++--
 ui/src/agent/edit.ts       |  40 ++---
 ui/src/agent/find.ts       |  26 ++++
 ui/src/agent/layout.ts     | 150 +++++++++++++++++++
 ui/src/agent/node.ts       |   2 +
 ui/src/agent/page.ts       | 191 ++++++++++++++++++++++--
 ui/src/agent/timing.ts     | 108 ++++++++++++++
 10 files changed, 1143 insertions(+), 57 deletions(-)
 create mode 100644 ui/src/agent/build.ts
 create mode 100644 ui/src/agent/find.ts
 create mode 100644 ui/src/agent/layout.ts
 create mode 100644 ui/src/agent/timing.ts

diff --git a/scripts/morpho.mjs b/scripts/morpho.mjs
index 8423b0c..5e9db86 100644
--- a/scripts/morpho.mjs
+++ b/scripts/morpho.mjs
@@ -7,6 +7,11 @@
 //   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 -- new <file> / add / remove / duplicate / arrange   build a design from scratch
+//   npm run morpho -- timing <scene>              when everything moves, as a text chart
+//   npm run morpho -- layout <scene>              every layer's box and margins, and layout notes
+//   npm run morpho -- video <scene> [-o f.mp4]    MP4, WebM, GIF or PNG frames (needs ffmpeg for video)
+//   npm run morpho -- fit <file> <ref> <a.b>…     tune settings until the design matches a reference
 //   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…
@@ -33,6 +38,27 @@ const HELP = `morpho <command> [args] [options]
   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)
+                           also Layer.preset="Ice chrome" and Layer.recipe=Glitch
+  new <file>               a blank design: --canvas 1080x1350 | "Instagram post", --bg "#111" |
+                           "#a,#b" | Midnight, --name, --duration 4
+  add <file> text "HI"     a layer: text "…" | shape star | line "<svg d>" | path "<svg d>", with
+                           --name --at x,y --size --font --color --material chrome | --preset "Ice
+                           chrome" --recipe Glitch --rotation --scale --width (lines) and
+                           --above L | --below L | --into Group (default: on top)
+  add <file> modifier glitch --to L [--fields '{"amount":0.6}']   (or a recipe name)
+  add <file> group A B [--name G] [--merge]
+  add <file> font f.ttf    embed a font; prints the id for --font
+  add <file> image p.png   a picture in a rectangle, or --to L to fill that layer with it
+  remove <file> L…         · duplicate <file> L [--name --at]
+  arrange <file> L top|bottom|up|down|above M|below M
+  align <file> L… [--to canvas|M] [--edge centre]   by what's drawn; edges: left, right, centre,
+                           top, bottom, middle (comma-separated for both axes)
+  layout <scene>           every layer's box and margins, plus near-misses, crowding and hierarchy
+  timing <scene>           when everything moves: bars on the clock and notes on rhythm
+  video <scene>            -o f.mp4 | f.webm | f.gif | dir/ (PNG frames); --fps (30, GIF 20),
+                           --size (GIF default 480) or --scale
+  fit <scene> <ref> L.k…   tune each setting until the design matches the reference picture;
+                           writes the file (or --out), prints before → after
   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
@@ -65,7 +91,7 @@ options:
 
 function parse(argv) {
   const pos = [], opt = { set: [], vary: [], variant: [] };
-  const flags = new Set(['cpu', 'json', 'dry', 'transparent']);
+  const flags = new Set(['cpu', 'json', 'dry', 'transparent', 'merge', 'force']);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-o') opt.out = argv[++i];
@@ -190,9 +216,16 @@ async function startApp(gpu) {
 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) : [];
+    // Later batches of a video reuse the design the first one loaded.
+    const key = JSON.stringify([scene, set]);
+    let changes = [];
+    if (!(op === 'frames' && opts.from > 0 && window.__morphoKey === key)) {
+      window.__morphoKey = null;
+      if (scene.template) await a.open(scene.template);
+      else await a.load(scene.project);
+      changes = set.length ? await a.edit(set) : [];
+      window.__morphoKey = key;
+    }
     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));
@@ -201,6 +234,12 @@ async function runInPage({ scene, set, op, 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 })) };
+    if (op === 'align') return { changes, name, ...(await a.align(opts.targets, opts.to, opts.edges)) };
+    if (op === 'layout') return { changes, name, text: await a.layout() };
+    if (op === 'frames') return { changes, name, ...(await a.frameBatch(opts)) };
+    if (op === 'font') return { changes, name, ...(await a.importFont(opts.data)) };
+    if (op === 'image') return { changes, name, ...(await a.importImage(opts.data, opts.name, opts.to)) };
+    if (op === 'fit') return { changes, name, ...(await a.fit(opts.ref, opts.targets)) };
     throw new Error(`Unknown job ${op}`);
   });
 }
@@ -269,6 +308,89 @@ async function writePng(b64, opt, sceneName, cmd) {
   return rel && !rel.startsWith('..') ? rel : out;
 }
 
+const num = (v) => (v === undefined ? undefined : Number(v));
+
+/** Read a .morpho file, change it, apply any --set, write it back (unless --dry) and say what changed. */
+async function editFile(file, opt, change) {
+  if (!file || !existsSync(file)) throw new Error(`Needs a .morpho file${file ? `; "${file}" doesn't exist` : ''} (start one with: morpho new <file>, or morpho scene <template>)`);
+  const a = await nodeAgent();
+  const before = a.migrate(JSON.parse(await readFile(file, 'utf8')));
+  const r = await change(a, before);
+  let { project } = r;
+  const lines = [r.change];
+  if (opt.set.length) {
+    const e = a.applyEdits(project, opt.set);
+    project = e.project;
+    lines.push(...e.changes);
+  }
+  if (!opt.dry) await writeFile(file, JSON.stringify(project, null, 1));
+  return lines.join('\n') + (opt.dry ? '\n(dry run: file unchanged)' : '');
+}
+
+/** Options shared by add and duplicate. */
+const placeOpts = (opt) => ({ name: opt.name, at: opt.at, rotation: num(opt.rotation), scale: num(opt.scale), material: opt.material, preset: opt.preset, recipe: opt.recipe, above: opt.above, below: opt.below, into: opt.into, size: num(opt.size), font: opt.font, width: num(opt.width), color: opt.color });
+
+/** A page job that changes a file: send the design, write back what comes back. */
+async function pageEdit(file, opt, op, opts) {
+  if (!file || !existsSync(file)) throw new Error(`Needs a .morpho file${file ? `; "${file}" doesn't exist` : ''}`);
+  const r = await drawJob({ scene: { project: JSON.parse(await readFile(file, 'utf8')) }, set: opt.set, op, opts }, !(opt.cpu || process.env.MORPHO_CPU));
+  const out = opt.out ?? file;
+  if (!opt.dry) await writeFile(out, JSON.stringify(r.project, null, 1));
+  return [...(r.changes ?? []).map((c) => `set ${c}`), r.change ?? r.text, out !== file ? `wrote ${out}` : ''].filter(Boolean).join('\n');
+}
+
+/** ffmpeg arguments for an output file, by its extension. */
+function encoder(out, fps, w) {
+  const ext = path.extname(out).toLowerCase();
+  const input = ['-y', '-loglevel', 'error', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-'];
+  if (ext === '.gif') return [...input, '-vf', `split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=sierra2_4a`, '-loop', '0', out];
+  if (ext === '.webm') return [...input, '-c:v', 'libvpx-vp9', '-crf', '30', '-b:v', '0', '-pix_fmt', 'yuv420p', out];
+  if (ext === '.mp4' || ext === '.mov') return [...input, '-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '17', '-preset', 'medium', '-movflags', '+faststart', out];
+  throw new Error(`video writes .mp4, .mov, .webm or .gif, or PNG frames into a folder ending in /; not "${out}"`);
+}
+
+async function video(s, opt) {
+  const { spawn } = await import('node:child_process');
+  const out = path.resolve(opt.out ?? path.join(OUT_DIR, `${slug(s.name)}.mp4`));
+  const pngDir = out.endsWith('/') || out.endsWith(path.sep);
+  const gif = out.toLowerCase().endsWith('.gif');
+  const fps = Number(opt.fps ?? (gif ? 20 : 30));
+  const size = opt.size ? Number(opt.size) : gif && !opt.scale ? 480 : undefined;
+  await mkdir(pngDir ? out : path.dirname(out), { recursive: true });
+  let ff = null, failed = null;
+  if (!pngDir) {
+    ff = spawn('ffmpeg', encoder(out, fps), { stdio: ['pipe', 'inherit', 'pipe'] });
+    let err = '';
+    ff.stderr.on('data', (d) => (err += d));
+    ff.on('error', (e) => (failed = e.code === 'ENOENT' ? new Error('video needs ffmpeg (brew install ffmpeg), or write PNG frames with -o frames/') : e));
+    ff.on('exit', (code) => code && (failed ??= new Error(`ffmpeg failed: ${err.trim().split('\n').pop()}`)));
+  }
+  const job = (from) => drawJob({ scene: { template: s.template, project: s.project }, set: opt.set, op: 'frames', opts: { fps, from, count: 15, size, scale: opt.scale ? Number(opt.scale) : undefined } }, !(opt.cpu || process.env.MORPHO_CPU));
+  let from = 0, total = 1, info = null;
+  while (from < total) {
+    const r = await job(from);
+    if (failed) throw failed;
+    info ??= r;
+    total = r.total;
+    for (const [i, f] of r.frames.entries()) {
+      const bytes = Buffer.from(f, 'base64');
+      if (pngDir) await writeFile(path.join(out, `frame-${String(from + i).padStart(4, '0')}.png`), bytes);
+      else if (!ff.stdin.write(bytes)) await new Promise((ok) => ff.stdin.once('drain', ok));
+    }
+    from += r.frames.length;
+    process.stderr.write(`\r${from}/${total} frames`);
+    if (!r.frames.length) break;
+  }
+  process.stderr.write('\n');
+  if (ff) {
+    ff.stdin.end();
+    await new Promise((ok) => ff.on('close', ok));
+    if (failed) throw failed;
+  }
+  const shown = path.relative(process.cwd(), out);
+  return `wrote ${shown && !shown.startsWith('..') ? shown : out}: ${total} frames at ${fps} fps, ${info.width}×${info.height}, ${info.duration}s${info.loop ? ' (loops seamlessly)' : ''}`;
+}
+
 async function main() {
   const { cmd, args, opt } = parse(process.argv.slice(2));
   const t0 = performance.now();
@@ -292,6 +414,78 @@ async function main() {
       say(a.describe(p));
       break;
     }
+    case 'timing': {
+      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.timing(p));
+      break;
+    }
+    case 'new': {
+      const [file] = args;
+      if (!file) throw new Error('new needs a file name: morpho new poster.morpho --canvas 1080x1350 --bg "#111111"');
+      if (existsSync(file) && !opt.force) throw new Error(`${file} already exists (add --force to replace it)`);
+      const a = await nodeAgent();
+      let p = a.blank({ name: opt.name ?? slug(file).replace(/-/g, ' '), canvas: opt.canvas, background: opt.bg, duration: num(opt.duration) });
+      if (opt.set.length) p = a.applyEdits(p, opt.set).project;
+      await writeFile(file, JSON.stringify(p, null, 1));
+      say(`wrote ${file}: "${p.name}" ${p.canvas.width}×${p.canvas.height}, no layers yet. Next: morpho add ${file} text "HELLO" --size 200`);
+      break;
+    }
+    case 'add': {
+      const [file, kind, ...rest] = args;
+      const what = rest.join(' ');
+      if (kind === 'font' || kind === 'image') {
+        if (!what || !existsSync(what)) throw new Error(`add ${kind} needs a file${what ? `; "${what}" doesn't exist` : ''}`);
+        const data = (await readFile(what)).toString('base64');
+        say(await pageEdit(file, opt, kind, { data, name: path.basename(what), to: opt.to }));
+        break;
+      }
+      say(
+        await editFile(file, opt, (a, p) => {
+          if (kind === 'modifier' || kind === 'mod') {
+            if (!opt.to) throw new Error('add modifier needs --to <layer>');
+            return a.addModifier(p, opt.to, what, opt.fields ? JSON.parse(opt.fields) : {});
+          }
+          if (kind === 'group') return a.addGroup(p, rest, { ...placeOpts(opt), merge: !!opt.merge });
+          if (!kind || !what) throw new Error('add <file> text "HELLO" | shape star | line "<svg d>" | path "<svg d>" | modifier <kind> --to L | group A B | font f.ttf | image p.png');
+          return a.addLayer(p, kind, what, placeOpts(opt));
+        }),
+      );
+      break;
+    }
+    case 'remove':
+      say(await editFile(args[0], opt, (a, p) => a.removeLayers(p, args.slice(1))));
+      break;
+    case 'duplicate':
+      say(await editFile(args[0], opt, (a, p) => a.duplicateLayer(p, args[1], placeOpts(opt))));
+      break;
+    case 'arrange':
+      say(await editFile(args[0], opt, (a, p) => a.arrange(p, args[1], args[2], args[3])));
+      break;
+    case 'fit': {
+      const [file, ref, ...targets] = args;
+      if (!ref || !existsSync(ref)) throw new Error(`fit needs a reference picture after the design${ref ? `; "${ref}" doesn't exist` : ''}`);
+      if (!targets.length) throw new Error('fit needs the settings to tune: Layer.x Layer.size Layer.gloss …');
+      const s = await scene(file);
+      if (s.template) {
+        opt.out ??= `${slug(s.name)}.morpho`;
+        const a = await nodeAgent();
+        await writeFile(opt.out, JSON.stringify(a.template(s.template), null, 1));
+        say(await pageEdit(opt.out, opt, 'fit', { ref: (await readFile(ref)).toString('base64'), targets }));
+      } else say(await pageEdit(file, opt, 'fit', { ref: (await readFile(ref)).toString('base64'), targets }));
+      break;
+    }
+    case 'align': {
+      const [file, ...targets] = args;
+      if (!targets.length) throw new Error('align <file> <layer>… [--to canvas|Layer] [--edge centre,middle]');
+      say(await pageEdit(file, opt, 'align', { targets, to: opt.to ?? 'canvas', edges: String(opt.edge ?? 'centre').split(',') }));
+      break;
+    }
+    case 'video':
+      say(await video(await scene(args[0]), opt));
+      break;
     case 'scene': {
       const a = await nodeAgent();
       if (!args[0]) throw new Error('Which template? (catalog templates lists them)');
@@ -314,6 +508,7 @@ async function main() {
     case 'render':
     case 'vary':
     case 'check':
+    case 'layout':
     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) };
diff --git a/ui/src/agent/agent.test.ts b/ui/src/agent/agent.test.ts
index 0cdae3a..5ac6e92 100644
--- a/ui/src/agent/agent.test.ts
+++ b/ui/src/agent/agent.test.ts
@@ -1,6 +1,10 @@
 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 { group as groupNode, lineLayer, MODIFIER_UI, mods, newModifier, style, SYMBOL_UI, symbolLayer, textLayer, type Group, type Project, type ShapeLayer } from '../state/model';
+import { newMotion } from '../state/motion';
+import { addGroup, addLayer, addModifier, arrange, blank, duplicateLayer, removeLayers } from './build';
+import { boxTable, itemsOf, layoutFindings, lookFindings } from './layout';
+import { timing } from './timing';
 import { SHAPE_RECIPES } from '../state/recipes';
 import { TEMPLATES } from '../state/templates';
 import type { BuildResult } from '../engine/client';
@@ -171,12 +175,15 @@ group('check', () => {
     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('finds pops and loop seams in the motion, not fast smooth moves', () => {
+    const smooth = Array.from({ length: 10 }, (_, i) => ({ t: i, a: 1, b: 1 }));
+    expect(motionFindings(smooth, { a: 1, b: 1, c: 1 }, true)).toEqual([{ level: 'info', text: 'the loop joins smoothly' }]);
+    expect(motionFindings(smooth, { a: 1, b: 12, c: 1 }, true)[0].text).toMatch(/loop jumps where it starts over/);
+    // An entrance that replays: still before the restart, moving fast after it.
+    expect(motionFindings(smooth, { a: 0, b: 20, c: 25 }, true)[0].text).toMatch(/loop jumps/);
+    expect(motionFindings([...smooth, { t: 4.5, a: 0.2, b: 12 }], null, true)[0].text).toMatch(/pop at 4.5s/);
+    expect(motionFindings([{ t: 0.2, a: 30, b: 26 }, ...smooth], null, true)).toEqual([]);
+    expect(motionFindings(smooth.map((s) => ({ ...s, a: 0, b: 0 })), { a: 0, b: 0, c: 0 }, true)[0].text).toMatch(/nothing visibly changes/);
   });
 
   it('measures presence and contrast from pixels', () => {
@@ -197,3 +204,143 @@ 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' }");
 });
+
+group('build', () => {
+  const ids = (p: Project) => p.layers.map((n) => n.name);
+
+  it('starts blank at a size and background', () => {
+    const p = blank({ name: 'Gig', canvas: '1080x1350', background: '#111111,#222222', duration: 4 });
+    expect(p).toMatchObject({ name: 'Gig', canvas: { width: 1080, height: 1350 }, layers: [], timeline: { duration: 4, loop: true } });
+    expect(p.background.fill).toMatchObject({ kind: 'linear', colors: ['#111111', '#222222'] });
+    expect(blank({ canvas: 'Instagram post' }).canvas.width).toBeGreaterThan(0);
+    expect(() => blank({ canvas: 'Nowhere' })).toThrow(/WxH or one of/);
+    expect(() => blank({ background: 'Plaid' })).toThrow(/No background/);
+  });
+
+  it('adds text, shapes and lines with unique names, looks and places', () => {
+    let p = blank();
+    p = addLayer(p, 'text', 'HELLO', { size: 200, preset: 'Ice chrome', at: '10,-20' }).project;
+    p = addLayer(p, 'shape', 'star', { color: '#ff0000' }).project;
+    p = addLayer(p, 'shape', 'Star', { material: 'inflate', recipe: 'Wavy', below: 'HELLO' }).project;
+    p = addLayer(p, 'line', 'M-0.5 0 L0.5 0', { width: 20 }).project;
+    expect(ids(p)).toEqual(['Star 2', 'HELLO', 'Star', 'Line']);
+    const [s2, t, s] = p.layers as ShapeLayer[];
+    expect(t).toMatchObject({ x: 10, y: -20, style: { effect: 'chrome' }, content: { size: 200 } });
+    expect(s.style).toMatchObject({ effect: 'flat', params: { fill: '#ff0000' } });
+    expect(s2.style.effect).toBe('inflate');
+    expect(s2.modifiers.map((m) => m.kind)).toEqual(['wave']);
+    expect(() => addLayer(p, 'text', 'x', { font: 'comic' })).toThrow(/No font "comic". Bundled: archivo/);
+    expect(() => addLayer(p, 'shape', 'hexagonz')).toThrow(/Shapes: circle/);
+    expect(() => addLayer(p, 'line', 'hello')).toThrow(/isn't SVG path data/);
+  });
+
+  it('adds modifiers and recipes, checking fields', () => {
+    const p = addLayer(blank(), 'text', 'HI').project;
+    const a = addModifier(p, 'HI', 'glitch', { amount: 0.8 }).project;
+    expect((a.layers[0] as ShapeLayer).modifiers[0]).toMatchObject({ kind: 'glitch', amount: 0.8, size: 0.05, on: true });
+    expect(addModifier(p, 'HI', 'Melting').change).toMatch(/recipe Melting/);
+    expect(() => addModifier(p, 'HI', 'glitch', { nope: 1 })).toThrow(/glitch has no nope/);
+    expect(() => addModifier(p, 'HI', 'zap')).toThrow(/No modifier "zap"/);
+  });
+
+  it('groups, duplicates, restacks and removes', () => {
+    let p = blank();
+    for (const t of ['A', 'B', 'C']) p = addLayer(p, 'text', t).project;
+    p = addModifier(p, 'B', 'wave').project;
+    const uid = (p.layers[1] as ShapeLayer).modifiers[0].uid;
+    p = applyEdit(p, `B.animate.mod:${uid}:phase={"to":1,"period":2,"phase":0,"mode":"ramp"}`).project;
+    p = duplicateLayer(p, 'B', { at: '50,0' }).project;
+    expect(ids(p)).toEqual(['A', 'B', 'B 2', 'C']);
+    const [b, b2] = [p.layers[1], p.layers[2]] as ShapeLayer[];
+    expect(b2.id).not.toBe(b.id);
+    expect(b2.modifiers[0].uid).not.toBe(uid);
+    expect(Object.keys(b2.animate!)).toEqual([`mod:${b2.modifiers[0].uid}:phase`]);
+    expect(b2.x).toBe(50);
+    p = arrange(p, 'A', 'top').project;
+    expect(ids(p)).toEqual(['B', 'B 2', 'C', 'A']);
+    p = arrange(p, 'A', 'below', 'B').project;
+    expect(ids(p)).toEqual(['A', 'B', 'B 2', 'C']);
+    p = addGroup(p, ['B', 'C'], { name: 'Pair' }).project;
+    expect(ids(p)).toEqual(['A', 'B 2', 'Pair']);
+    expect((p.layers[2] as Group).children.map((n) => n.name)).toEqual(['B', 'C']);
+    p = addLayer(p, 'shape', 'heart', { into: 'Pair' }).project;
+    expect((p.layers[2] as Group).children.map((n) => n.name)).toEqual(['B', 'C', 'Heart']);
+    p = removeLayers(p, ['A', 'Heart']).project;
+    expect(ids(p)).toEqual(['B 2', 'Pair']);
+    expect(() => arrange(p, 'Pair', 'sideways')).toThrow(/top, bottom, up, down/);
+  });
+
+  it('applies presets and recipes by assignment, and gives each loop its own amount', () => {
+    let p = addLayer(blank(), 'text', 'HI').project;
+    p = applyEdits(p, ['HI.preset="Molten"', 'HI.recipe=Heavy', 'HI.motion.loop="spin"']).project;
+    const t = p.layers[0] as ShapeLayer;
+    expect(t.style).toMatchObject({ effect: 'chrome', params: { c3: '#ff6a00' } });
+    expect(t.modifiers.map((m) => m.kind)).toEqual(['weight']);
+    expect(t.motion).toMatchObject({ loop: 'spin', amount: 1 });
+    expect(applyEdits(p, ['HI.motion.loop="sway"', 'HI.motion.amount=20']).project.layers[0]).toMatchObject({ motion: { amount: 20 } });
+    expect(() => applyEdit(p, 'HI.preset="Nope"')).toThrow(/No preset/);
+  });
+});
+
+group('layout', () => {
+  const W = 1000, H = 1000;
+  const p = (layers: Project['layers']): Project => ({ ...project(layers), canvas: { width: W, height: H } });
+  const build = (boxes: Record<string, [number, number, number, number]>): BuildResult => ({ renders: [], bbox: null, points: 0, ms: 0, layers: Object.entries(boxes).map(([id, bbox]) => ({ id, bbox, error: null, d: null, local: null, frames: [] })) });
+
+  it('finds near-miss edges, nearly-centred things and crowded edges', () => {
+    const q = p([textLayer('Headline', 'archivo', { id: 'a', name: 'A' }), symbolLayer('star', 100, { id: 'b', name: 'B' }), symbolLayer('circle', 100, { id: 'c', name: 'C' })]);
+    const items = itemsOf(q, build({ a: [-300, -200, 300, -100], b: [-305, 0, -205, 100], c: [380, 350, 490, 460] }));
+    const f = layoutFindings(q, items).map((x) => x.text).join('\n');
+    expect(f).toContain('"A" and "B": lefts 5px apart, nearly lined up');
+    expect(f).toContain('"C": only 10px from the right edge');
+    expect(f).not.toContain('"A": ');
+  });
+
+  it('ignores differences nobody can see', () => {
+    const q = p([textLayer('One', 'archivo', { id: 'a' }), textLayer('Two', 'archivo', { id: 'b' })]);
+    const f = layoutFindings(q, itemsOf(q, build({ a: [-100, -50, 100, 0], b: [-101, 50, 99, 90] })));
+    expect(f.filter((x) => /nearly/.test(x.text))).toEqual([]);
+  });
+
+  it('notes a missing lead among the biggest texts', () => {
+    const q = p([textLayer('Big words', 'archivo', { id: 'a' }, { size: 200 }), textLayer('Also big', 'archivo', { id: 'b' }, { size: 190 }), textLayer('K', 'archivo', { id: 'k' }, { size: 600 })]);
+    const boxes = build({ a: [-300, -300, 300, -100], b: [-300, 0, 300, 180], k: [-100, 200, 100, 480] });
+    expect(layoutFindings(q, itemsOf(q, boxes)).some((x) => /no clear lead/.test(x.text))).toBe(false);
+    const r = p(q.layers.slice(0, 2));
+    expect(layoutFindings(r, itemsOf(r, boxes)).find((x) => /no clear lead/.test(x.text))?.text).toContain('"Big words" (200px) and "Also big" (190px)');
+  });
+
+  it('tables every box with its margins', () => {
+    const q = p([symbolLayer('star', 100, { id: 'b', name: 'B' })]);
+    expect(boxTable(q, itemsOf(q, build({ b: [-500, -500, -400, -400] })))).toContain('margins L 0 R 900 T 0 B 900');
+  });
+
+  it('reads balance and palette from pixels', () => {
+    const w = 10, h = 10;
+    const img = (f: (x: number, y: number) => number[]) => ({ data: new Uint8ClampedArray(Array.from({ length: w * h }, (_, i) => [...f(i % w, Math.floor(i / w)), 255]).flat()), width: w, height: h });
+    const bare = img(() => [0, 0, 0]);
+    const left = lookFindings(img((x) => (x < 3 ? [255, 0, 0] : [0, 0, 0])), bare).map((f) => f.text);
+    expect(left[0]).toMatch(/sits left/);
+    expect(left[1]).toBe('palette: 1 main hue (red), mostly neutrals');
+    const rainbow = lookFindings(img((x) => [[255, 0, 0], [255, 150, 0], [255, 255, 0], [0, 200, 0], [0, 200, 255], [0, 0, 255], [160, 0, 255], [255, 0, 160], [255, 0, 0], [0, 0, 255]][x]), bare);
+    expect(rainbow[1]).toMatchObject({ level: 'warn' });
+    expect(lookFindings(img(() => [200, 200, 200]), bare)[0].text).toBe('visual weight: balanced around the centre');
+  });
+});
+
+group('timing', () => {
+  it('charts every move and notes rhythm', () => {
+    const stars = [0, 1, 2].map((i) => symbolLayer('star', 100, { name: `S${i}`, motion: { ...newMotion({ enter: 'rise' }) } }));
+    const q: Project = { ...project(stars), timeline: { duration: 6, loop: true } };
+    const t = timing(q);
+    expect(t).toContain('in rise');
+    expect(t).toContain('3 entrances start together at 0s');
+    expect(t).toMatch(/nothing moves from 0\.\d+s to 6s \(then it loops\)/);
+    expect(timing(project([textLayer('Still')]))).toContain('nothing moves');
+  });
+
+  it('flags moves the clock cuts off', () => {
+    const s = symbolLayer('star', 100, { motion: newMotion({ enter: 'rise', delay: 5.8 }) });
+    expect(timing({ ...project([s]), timeline: { duration: 6, loop: false } })).toContain('gets cut off');
+  });
+});
diff --git a/ui/src/agent/build.ts b/ui/src/agent/build.ts
new file mode 100644
index 0000000..d59a65e
--- /dev/null
+++ b/ui/src/agent/build.ts
@@ -0,0 +1,292 @@
+// Making a design from scratch, as data: a blank project, new layers (text,
+// shapes, pen lines, outlines, groups), modifiers, presets and recipes,
+// removing, duplicating and restacking. Like edit.ts, every function returns
+// a changed copy and a line saying what it did, and bad names fail with the
+// names that would have worked.
+import { EFFECTS, PRESETS, defaultParams, effectById } from '../render/effects';
+import { BUNDLED } from '../fonts/library';
+import { BG_PRESETS, SHAPE_RECIPES } from '../state/recipes';
+import { background, CANVAS_PRESETS, fill, group, isGroup, lineLayer, MODIFIER_DEFAULTS, MODIFIER_UI, newModifier, nodeLabel, pathLayer, style, SYMBOL_UI, symbolLayer, textLayer, uid, type Group, type Node, type Project, type ShapeLayer } from '../state/model';
+import type { Modifier, ModifierKind, SymbolKind } from '../engine/types';
+import { EditError, findNode } from './find';
+
+export interface Change {
+  project: Project;
+  change: string;
+}
+
+const norm = (s: string) => s.toLowerCase().replace(/[\s_·-]+/g, '');
+
+/** A canvas size: "1080x1350", or a preset's label ("Instagram post"). */
+export function canvasSize(spec: string): { width: number; height: number } {
+  const m = /^(\d+)\s*[x×]\s*(\d+)$/i.exec(spec.trim());
+  if (m) return { width: +m[1], height: +m[2] };
+  const c = CANVAS_PRESETS.find((x) => norm(x.label) === norm(spec)) ?? CANVAS_PRESETS.find((x) => norm(x.label).includes(norm(spec)));
+  if (!c) throw new EditError(`No canvas size "${spec}". Use WxH or one of: ${CANVAS_PRESETS.map((x) => x.label).join(', ')}`);
+  return { width: c.w, height: c.h };
+}
+
+/** A background: a colour, two colours for a gradient ("#000,#333"), or a preset's name. */
+export function backgroundOf(spec: string) {
+  const cols = spec.split(',').map((s) => s.trim());
+  if (cols.every((c) => /^#[0-9a-f]{6}$/i.test(c))) return background(cols.length > 1 ? fill('linear', ...cols) : fill('solid', cols[0]));
+  const b = BG_PRESETS.find((x) => norm(x.name) === norm(spec));
+  if (!b) throw new EditError(`No background "${spec}". Use #rrggbb, "#a,#b" for a gradient, or one of: ${BG_PRESETS.map((x) => x.name).join(', ')}`);
+  return structuredClone(b.bg);
+}
+
+export function blank(o: { name?: string; canvas?: string; background?: string; duration?: number } = {}): Project {
+  return {
+    version: 2,
+    name: o.name ?? 'Untitled',
+    canvas: o.canvas ? canvasSize(o.canvas) : { width: 1080, height: 1080 },
+    background: o.background ? backgroundOf(o.background) : background(fill('solid', '#0b0b0d')),
+    layers: [],
+    fonts: [],
+    ...(o.duration ? { timeline: { duration: o.duration, loop: true } } : {}),
+  };
+}
+
+function all(nodes: Node[], out: Node[] = []): Node[] {
+  for (const n of nodes) {
+    out.push(n);
+    if (isGroup(n)) all(n.children, out);
+  }
+  return out;
+}
+
+/** The list a node sits in, and its index there. */
+function home(p: Project, id: string): { list: Node[]; i: number; parent: Group | null } {
+  const look = (list: Node[], parent: Group | null): ReturnType<typeof home> | null => {
+    for (const [i, n] of list.entries()) {
+      if (n.id === id) return { list, i, parent };
+      if (isGroup(n)) {
+        const r = look(n.children, n);
+        if (r) return r;
+      }
+    }
+    return null;
+  };
+  const r = look(p.layers, null);
+  if (!r) throw new EditError(`No layer #${id}`);
+  return r;
+}
+
+/** A name nobody else in the design has: "Star", then "Star 2"… */
+function freeName(p: Project, want: string): string {
+  const taken = new Set(all(p.layers).map((n) => n.name ?? nodeLabel(n)));
+  if (!taken.has(want)) return want;
+  for (let i = 2; ; i++) if (!taken.has(`${want} ${i}`)) return `${want} ${i}`;
+}
+
+export interface Place {
+  name?: string;
+  /** "x,y" in px from the canvas centre. */
+  at?: string;
+  rotation?: number;
+  scale?: number;
+  /** Material id, or a preset's name. */
+  material?: string;
+  preset?: string;
+  recipe?: string;
+  /** Put it above / below this layer, or last inside this group (default: on top). */
+  above?: string;
+  below?: string;
+  into?: string;
+}
+
+function look(n: ShapeLayer | Group, o: Place) {
+  if (o.preset) applyPreset(n, o.preset);
+  else if (o.material) {
+    const m = o.material;
+    const pre = PRESETS.find((x) => norm(x.name) === norm(m));
+    if (pre) applyPreset(n, pre.name);
+    else {
+      if (!EFFECTS.some((e) => e.id === m)) throw new EditError(`No material "${m}". Materials: ${EFFECTS.map((e) => e.id).join(', ')}; or a preset name (catalog presets)`);
+      n.style = style(m);
+    }
+  }
+  if (o.recipe) applyRecipe(n, o.recipe);
+}
+
+function applyPreset(n: { style: ShapeLayer['style'] }, name: string) {
+  const pre = PRESETS.find((x) => norm(x.name) === norm(name));
+  if (!pre) throw new EditError(`No preset "${name}". Presets: ${PRESETS.map((x) => x.name).join(', ')}`);
+  n.style = { ...n.style, effect: pre.effect, params: { ...defaultParams(effectById(pre.effect)), ...pre.params }, animate: undefined };
+}
+
+function applyRecipe(n: { modifiers: ShapeLayer['modifiers'] }, name: string) {
+  const r = SHAPE_RECIPES.find((x) => norm(x.name) === norm(name));
+  if (!r) throw new EditError(`No recipe "${name}". Recipes: ${SHAPE_RECIPES.map((x) => x.name).join(', ')}`);
+  n.modifiers = [...n.modifiers, ...r.mods.map((m) => newModifier(m.kind, m as Partial<Modifier>))];
+}
+
+function insert(p: Project, n: Node, o: Place) {
+  if (o.into) {
+    const g = findNode(p, o.into);
+    if (!isGroup(g)) throw new EditError(`${o.into} isn't a group`);
+    g.children.push(n);
+  } else if (o.above || o.below) {
+    const ref = findNode(p, (o.above ?? o.below)!);
+    const h = home(p, ref.id);
+    h.list.splice(o.above ? h.i + 1 : h.i, 0, n);
+  } else p.layers.push(n);
+}
+
+function place(n: ShapeLayer, o: Place) {
+  if (o.at) {
+    const [x, y] = o.at.split(',').map(Number);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) throw new EditError(`--at is x,y in px from the centre, got "${o.at}"`);
+    n.x = x;
+    n.y = y;
+  }
+  if (o.rotation !== undefined) n.rotation = o.rotation;
+  if (o.scale !== undefined) n.scale = o.scale;
+}
+
+export type LayerKind = 'text' | 'shape' | 'line' | 'path';
+
+export interface Add extends Place {
+  size?: number;
+  font?: string;
+  /** Pen lines: stroke width in px. */
+  width?: number;
+  /** Flat colour shortcut (sets the material's fill, or flat with that fill). */
+  color?: string;
+}
+
+/**
+ * A new layer. `what` is the text, the shape kind, or the path data (em
+ * units, y down, centred on 0,0) for lines and outlines.
+ */
+export function addLayer(p0: Project, kind: LayerKind, what: string, o: Add = {}): Change {
+  const p = structuredClone(p0);
+  let n: ShapeLayer;
+  if (kind === 'text') {
+    const font = o.font ?? 'archivo';
+    if (!BUNDLED.some((f) => f.id === font) && !p.fonts.some((f) => f.id === font)) throw new EditError(`No font "${font}". Bundled: ${BUNDLED.map((f) => f.id).join(', ')}${p.fonts.length ? `; in this design: ${p.fonts.map((f) => f.id).join(', ')}` : ''}`);
+    n = textLayer(what.replace(/\\n/g, '\n'), font, {}, o.size ? { size: o.size } : {});
+  } else if (kind === 'shape') {
+    const k = (Object.keys(SYMBOL_UI) as SymbolKind[]).find((s) => norm(s) === norm(what) || norm(SYMBOL_UI[s].label) === norm(what));
+    if (!k) throw new EditError(`No shape "${what}". Shapes: ${Object.keys(SYMBOL_UI).join(', ')}`);
+    n = symbolLayer(k, o.size ?? 420);
+  } else if (kind === 'line') {
+    n = lineLayer(what, o.size ?? 400, o.width ?? 12);
+  } else if (kind === 'path') {
+    n = pathLayer(what, o.size ?? 400, 'Outline');
+  } else throw new EditError(`add makes text, shape, line or path layers (or a modifier, group, font or image), not "${kind}"`);
+  if (!/^[MmLlCcQqHhVvZzAaSsTt0-9\s.,-]+$/.test(what) && (kind === 'line' || kind === 'path')) throw new EditError(`"${what}" isn't SVG path data (em units, e.g. "M-0.5 0 C-0.2 -0.3 0.2 0.3 0.5 0")`);
+  n.name = freeName(p, o.name ?? (kind === 'text' ? what.replace(/\\n|\n/g, ' ').slice(0, 24) : nodeLabel(n)));
+  place(n, o);
+  look(n, o);
+  if (o.color) {
+    if (!/^#[0-9a-f]{6}$/i.test(o.color)) throw new EditError(`--color is #rrggbb, got "${o.color}"`);
+    if ('fill' in n.style.params) n.style.params.fill = o.color;
+    else n.style = style('flat', { fill: o.color });
+  }
+  insert(p, n, o);
+  return { project: p, change: `added "${n.name}" #${n.id}: ${kind} ${kind === 'text' ? `"${what.replace(/\\n/g, '⏎')}"` : kind === 'shape' ? what : 'path'} · ${n.style.effect}${n.modifiers.length ? ` · ${n.modifiers.map((m) => m.kind).join('+')}` : ''}` };
+}
+
+/** A modifier on a layer, with its defaults and any `fields` over them. */
+export function addModifier(p0: Project, target: string, kind: string, fields: Record<string, unknown> = {}): Change {
+  const p = structuredClone(p0);
+  const n = findNode(p, target);
+  const k = (Object.keys(MODIFIER_UI) as ModifierKind[]).find((m) => norm(m) === norm(kind) || norm(MODIFIER_UI[m].label) === norm(kind));
+  if (!k) {
+    const r = SHAPE_RECIPES.find((x) => norm(x.name) === norm(kind));
+    if (r) {
+      applyRecipe(n, r.name);
+      return { project: p, change: `"${n.name ?? n.id}": added recipe ${r.name} (${r.mods.map((m) => m.kind).join(' + ')})` };
+    }
+    throw new EditError(`No modifier "${kind}". Modifiers: ${Object.keys(MODIFIER_UI).join(', ')}; or a recipe (catalog recipes)`);
+  }
+  const known = new Set(Object.keys(MODIFIER_DEFAULTS[k]));
+  const bad = Object.keys(fields).filter((f) => !known.has(f));
+  if (bad.length) throw new EditError(`${k} has no ${bad.join(', ')}. Fields: ${[...known].filter((f) => f !== 'kind').join(', ')}`);
+  const m = newModifier(k, fields as Partial<Modifier>);
+  n.modifiers = [...n.modifiers, m];
+  return { project: p, change: `"${n.name ?? n.id}": added ${k}[${m.uid}]${Object.keys(fields).length ? ` ${JSON.stringify(fields)}` : ''}` };
+}
+
+/** Wrap layers in a group, where the topmost of them was. */
+export function addGroup(p0: Project, members: string[], o: Place & { merge?: boolean } = {}): Change {
+  const p = structuredClone(p0);
+  if (!members.length) throw new EditError('group needs the layers to put in it');
+  const nodes = members.map((m) => findNode(p, m));
+  const homes = nodes.map((n) => home(p, n.id));
+  if (homes.some((h) => h.list !== homes[0].list)) throw new EditError('Grouped layers must sit side by side in the same list (not some inside other groups)');
+  const order = homes.map((h, k) => ({ h, n: nodes[k] })).sort((a, b) => a.h.i - b.h.i);
+  const g = group(order.map((x) => x.n), { name: freeName(p, o.name ?? (o.merge ? 'Merged shape' : 'Group')), merge: !!o.merge });
+  const list = homes[0].list;
+  const at = order[order.length - 1].h.i - (order.length - 1);
+  for (const x of [...order].reverse()) list.splice(x.h.i, 1);
+  list.splice(at, 0, g);
+  if (o.merge) look(g, o);
+  return { project: p, change: `grouped ${nodes.map((n) => n.name ?? n.id).join(', ')} as "${g.name}" #${g.id}${o.merge ? ' (merged into one shape)' : ''}` };
+}
+
+export function removeLayers(p0: Project, targets: string[]): Change {
+  const p = structuredClone(p0);
+  const gone = targets.map((t) => {
+    const n = findNode(p, t);
+    const h = home(p, n.id);
+    h.list.splice(h.i, 1);
+    return n.name ?? `#${n.id}`;
+  });
+  return { project: p, change: `removed ${gone.join(', ')}` };
+}
+
+/** A copy just above the original, with new ids (and modifier uids) throughout. */
+export function duplicateLayer(p0: Project, target: string, o: Place = {}): Change {
+  const p = structuredClone(p0);
+  const n = findNode(p, target);
+  const copy = structuredClone(n);
+  const fresh = (x: Node) => {
+    x.id = uid(isGroup(x) ? 'g' : 'l');
+    const uids = new Map(x.modifiers.map((m) => [m.uid, uid('m')]));
+    x.modifiers = x.modifiers.map((m) => ({ ...m, uid: uids.get(m.uid)! }));
+    // Modifier keyframes follow their modifier's new uid.
+    if (x.animate) x.animate = Object.fromEntries(Object.entries(x.animate).map(([k, v]) => [k.replace(/^mod:([^:]+):/, (s, u: string) => (uids.has(u) ? `mod:${uids.get(u)}:` : s)), v]));
+    if (isGroup(x)) x.children.forEach(fresh);
+  };
+  fresh(copy);
+  copy.name = freeName(p, o.name ?? n.name ?? nodeLabel(n));
+  if (!isGroup(copy)) place(copy, o);
+  look(copy as ShapeLayer, o);
+  if (o.above || o.below || o.into) insert(p, copy, o);
+  else {
+    const h = home(p, n.id);
+    h.list.splice(h.i + 1, 0, copy);
+  }
+  return { project: p, change: `duplicated "${n.name ?? n.id}" as "${copy.name}" #${copy.id}` };
+}
+
+/** Restack: top, bottom, up, down, or above / below another layer (in its own list). */
+export function arrange(p0: Project, target: string, where: string, other?: string): Change {
+  const p = structuredClone(p0);
+  const n = findNode(p, target);
+  const h = home(p, n.id);
+  h.list.splice(h.i, 1);
+  if (where === 'top') h.list.push(n);
+  else if (where === 'bottom') h.list.unshift(n);
+  else if (where === 'up') h.list.splice(Math.min(h.list.length, h.i + 1), 0, n);
+  else if (where === 'down') h.list.splice(Math.max(0, h.i - 1), 0, n);
+  else if (where === 'above' || where === 'below') {
+    if (!other) throw new EditError(`arrange ${target} ${where} needs another layer`);
+    const ref = findNode(p, other);
+    const r = home(p, ref.id);
+    r.list.splice(where === 'above' ? r.i + 1 : r.i, 0, n);
+  } else throw new EditError(`arrange takes top, bottom, up, down, above <layer> or below <layer>, not "${where}"`);
+  const pos = home(p, n.id);
+  return { project: p, change: `"${n.name ?? n.id}" is now ${pos.i + 1} of ${pos.list.length} from the bottom${pos.parent ? ` in "${pos.parent.name ?? pos.parent.id}"` : ''}` };
+}
+
+/** Presets and recipes by assignment: Layer.preset="Ice chrome", Layer.recipe=Glitch. */
+export function applyLook(p0: Project, target: string, key: 'preset' | 'recipe', name: string): Change {
+  const p = structuredClone(p0);
+  const n = findNode(p, target);
+  if (key === 'preset') applyPreset(n, name);
+  else applyRecipe(n, name);
+  return { project: p, change: `"${n.name ?? n.id}" ${key}: ${name}${key === 'preset' ? ` (${n.style.effect})` : ''}` };
+}
diff --git a/ui/src/agent/check.ts b/ui/src/agent/check.ts
index 2a7d715..5ea1d19 100644
--- a/ui/src/agent/check.ts
+++ b/ui/src/agent/check.ts
@@ -152,22 +152,29 @@ export function spread(p: Pixels): number {
 }
 
 /**
- * Motion from pairs of frames one video frame apart: `steps` sampled across
- * the clock, `seam` the last frame against the first.
+ * Motion from runs of three frames one video frame apart: a pop is one step
+ * far bigger than the steps either side of it (fast but smooth motion has
+ * neighbours just as big). `seam` is the same around the loop's restart:
+ * the step into it (a), across it (b) and out of it (c).
  */
-export function motionFindings(steps: { t: number; d: number }[], seam: number | null, animated: boolean): Finding[] {
+export function motionFindings(runs: { t: number; a: number; b: number }[], seam: { a: number; b: number; c: 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);
+  const moving = runs.some((r) => Math.max(r.a, r.b) > 0.05) || (seam && Math.max(seam.a, seam.b, seam.c) > 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' });
+  const floor = 0.15;
+  for (const r of runs) {
+    const [big, small] = r.a > r.b ? [r.a, r.b] : [r.b, r.a];
+    if (big > 2 && big > (small + floor) * 6) out.push({ level: 'warn', text: `pop at ${num(r.t)}s: one frame changes ${num(big / (small + floor))}× more than the next` });
+  }
+  if (seam) {
+    // Across a smooth seam the last frame flows into the first like any other step, so the step before is the measure.
+    const near = seam.a;
+    if (seam.b > 1.5 && seam.b > (near + floor) * 4) out.push({ level: 'warn', text: `the loop jumps where it starts over: ${num(seam.b / (near + floor))}× the frames around it (something that ends differently from how it starts, like an entrance that replays)` });
+    else out.push({ level: 'info', text: 'the loop joins smoothly' });
+  }
   return out;
 }
 
diff --git a/ui/src/agent/edit.ts b/ui/src/agent/edit.ts
index a005778..ce0a005 100644
--- a/ui/src/agent/edit.ts
+++ b/ui/src/agent/edit.ts
@@ -12,11 +12,13 @@
 // 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 { ENTER_UI, LEAVE_UI, LOOP_UI, 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';
+import { applyLook } from './build';
+import { allNodes, EditError, findNode } from './find';
 
-export class EditError extends Error {}
+export { EditError, findNode };
 
 export interface Edit {
   project: Project;
@@ -55,28 +57,6 @@ export function parseAssignment(a: string): { target: string; path: string[]; va
   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)) {
@@ -168,6 +148,10 @@ export function applyEdit(p: Project, assignment: string): Edit {
     put(project as unknown as Obj, full, value, target);
     return { project, change: `${full.join('.')}: ${fmtv(before)} → ${fmtv(value)}` };
   }
+  if (path.length === 1 && (path[0] === 'preset' || path[0] === 'recipe')) {
+    if (typeof value !== 'string') throw new EditError(`${path[0]} takes a name (catalog ${path[0]}s)`);
+    return applyLook(p, target, path[0], value);
+  }
   const n = findNode(project, target);
   const r = resolve(n, path);
   r.check?.(value);
@@ -182,6 +166,14 @@ export function applyEdit(p: Project, assignment: string): Edit {
     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);
+    // A new loop, entrance or exit kind starts at its own amount (spin is in turns, sway in degrees…).
+    const m = n.motion;
+    const k = r.path.join('.');
+    if (m && typeof value === 'string' && value !== before) {
+      if (k === 'motion.loop' && value in LOOP_UI) m.amount = LOOP_UI[value as keyof typeof LOOP_UI].default;
+      if (k === 'motion.enter' && value in ENTER_UI) m.distance = ENTER_UI[value as keyof typeof ENTER_UI].default;
+      if (k === 'motion.leave' && value in LEAVE_UI) m.leaveDistance = LEAVE_UI[value as keyof typeof LEAVE_UI].default;
+    }
   }
   return { project, change: `${n.name ? `"${n.name}"` : '#' + n.id} ${r.path.join('.')}: ${fmtv(before)} → ${fmtv(value)}` };
 }
diff --git a/ui/src/agent/find.ts b/ui/src/agent/find.ts
new file mode 100644
index 0000000..7fbf9df
--- /dev/null
+++ b/ui/src/agent/find.ts
@@ -0,0 +1,26 @@
+// Finding layers by name or id, for edits and new layers alike.
+import { isGroup, type Node, type Project } from '../state/model';
+
+export class EditError extends Error {}
+
+export 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(', ')}`);
+}
diff --git a/ui/src/agent/layout.ts b/ui/src/agent/layout.ts
new file mode 100644
index 0000000..bb6353c
--- /dev/null
+++ b/ui/src/agent/layout.ts
@@ -0,0 +1,150 @@
+// Layout and taste, measured: where every layer's box sits, edges that nearly
+// line up (the off-by-3-px that reads as sloppy), content that's nearly but
+// not quite centred, things crowding an edge, text sizes too close to give a
+// clear lead, and from the pixels where the visual weight sits and how many
+// hues the palette really uses. These are notes, not rules: a poster may
+// break any of them on purpose.
+import type { BuildResult } from '../engine/client';
+import type { Box } from '../engine/types';
+import { isGroup, nodeLabel, type Node, type Project } from '../state/model';
+import type { Finding, Pixels } from './check';
+import { num } from './describe';
+
+export interface Item {
+  id: string;
+  name: string;
+  text: boolean;
+  /** Text: its font size on the canvas, px, and how many characters it has. */
+  size?: number;
+  chars?: number;
+  box: Box;
+}
+
+/** What draws, with its box: visible leaves and merged groups, top layer last. */
+export function itemsOf(p: Project, build: BuildResult | null): Item[] {
+  const boxes = new Map<string, Box | null>([...(build?.layers ?? []), ...(build?.renders ?? [])].map((l) => [l.id, l.bbox]));
+  const out: Item[] = [];
+  const go = (nodes: Node[], k: number) => {
+    for (const n of nodes) {
+      if (!n.visible) continue;
+      if (isGroup(n) && !n.merge) go(n.children, k);
+      else if (isGroup(n) || !n.guide) {
+        const box = boxes.get(n.id);
+        if (!box) continue;
+        const text = !isGroup(n) && n.content.type === 'text';
+        const c = !isGroup(n) && n.content.type === 'text' ? n.content : null;
+        out.push({ id: n.id, name: nodeLabel(n), text, size: c ? c.size * (n as { scale: number }).scale * k : undefined, chars: c ? c.text.replace(/\s/g, '').length : undefined, box });
+      }
+    }
+  };
+  go(p.layers, 1);
+  return out;
+}
+
+const who = (i: Item) => `"${i.name}"`;
+
+/** Each layer's box and its distance to every edge, as a table. */
+export function boxTable(p: Project, items: Item[]): string {
+  const { width: W, height: H } = p.canvas;
+  const rows = [...items].reverse().map((i) => {
+    const [x0, y0, x1, y1] = i.box;
+    const m = [x0 + W / 2, W / 2 - x1, y0 + H / 2, H / 2 - y1].map((v) => num(Math.round(v)));
+    return `${who(i).padEnd(26)} ${`${num(Math.round(x1 - x0))}×${num(Math.round(y1 - y0))}`.padEnd(10)} centre ${num(Math.round((x0 + x1) / 2))},${num(Math.round((y0 + y1) / 2))}`.padEnd(54) + `  margins L ${m[0]} R ${m[1]} T ${m[2]} B ${m[3]}${i.size ? ` · ${num(Math.round(i.size))}px type` : ''}`;
+  });
+  return [`boxes on ${W}×${H} (px; x,y from the centre; negative margins are off the canvas), top first:`, ...rows].join('\n');
+}
+
+/** Findings from the boxes alone. */
+export function layoutFindings(p: Project, items: Item[]): Finding[] {
+  const { width: W, height: H } = p.canvas;
+  const tol = Math.max(2, Math.min(W, H) * 0.012);
+  // Below this nobody sees it (and glyph shapes alone shift text boxes this much).
+  const seen = Math.max(1.5, Math.min(W, H) * 0.002);
+  const out: Finding[] = [];
+  const inside = items.filter((i) => i.box[0] < W / 2 && i.box[2] > -W / 2 && i.box[1] < H / 2 && i.box[3] > -H / 2);
+  // Edges that nearly line up.
+  const edges = (b: Box) => ({ left: b[0], 'centre (x)': (b[0] + b[2]) / 2, right: b[2], top: b[1], 'middle (y)': (b[1] + b[3]) / 2, bottom: b[3] });
+  const misses: { d: number; text: string }[] = [];
+  for (let a = 0; a < inside.length; a++) {
+    for (let b = a + 1; b < inside.length; b++) {
+      const ea = edges(inside[a].box), eb = edges(inside[b].box);
+      let best: { d: number; text: string } | null = null;
+      for (const k of Object.keys(ea) as (keyof typeof ea)[]) {
+        const d = Math.abs(ea[k] - eb[k]);
+        if (d > seen && d <= tol && (!best || d < best.d)) best = { d, text: `${who(inside[a])} and ${who(inside[b])}: ${k.replace(/ \(.\)/, '')}s ${num(d)}px apart, nearly lined up` };
+        if (d <= seen) {
+          best = null;
+          break;
+        }
+      }
+      if (best) misses.push(best);
+    }
+    const c = edges(inside[a].box);
+    for (const [k, v] of [['horizontally', c['centre (x)']], ['vertically', c['middle (y)']]] as const) {
+      if (Math.abs(v) > seen && Math.abs(v) <= tol) misses.push({ d: Math.abs(v), text: `${who(inside[a])}: ${num(Math.abs(v))}px off centre ${k}, nearly centred` });
+    }
+  }
+  misses.sort((x, y) => x.d - y.d);
+  for (const m of misses.slice(0, 6)) out.push({ level: 'warn', text: m.text });
+  if (misses.length > 6) out.push({ level: 'info', text: `${misses.length - 6} more near-misses like these` });
+  // Content as a whole: off centre by a little, or crowding an edge.
+  if (inside.length) {
+    const u = inside.reduce<Box>((b, i) => [Math.min(b[0], i.box[0]), Math.min(b[1], i.box[1]), Math.max(b[2], i.box[2]), Math.max(b[3], i.box[3])], [Infinity, Infinity, -Infinity, -Infinity]);
+    const [L, R] = [u[0] + W / 2, W / 2 - u[2]];
+    if (L > 0 && R > 0 && u[2] - u[0] > W * 0.5 && Math.abs(L - R) > tol && Math.abs(L - R) < W * 0.08) out.push({ level: 'info', text: `the design sits ${num(Math.round(Math.abs(L - R) / 2))}px ${L > R ? 'right' : 'left'} of centre (margins left ${num(Math.round(L))}, right ${num(Math.round(R))})` });
+    const close = Math.min(W, H) * 0.025;
+    for (const i of inside) {
+      const m: [string, number][] = [['left', i.box[0] + W / 2], ['right', W / 2 - i.box[2]], ['top', i.box[1] + H / 2], ['bottom', H / 2 - i.box[3]]];
+      const near = m.filter(([, v]) => v > 0.75 && v < close);
+      if (near.length) out.push({ level: 'warn', text: `${who(i)}: only ${near.map(([s, v]) => `${num(Math.round(v))}px from the ${s}`).join(' and ')} edge: crowded (bleed it off or give it room)` });
+    }
+  }
+  // Type sizes.
+  // Single letters often make a word together (a "2" and a "K"): leave them out.
+  const texts = items.filter((i) => i.text && i.size && (i.chars ?? 0) >= 3).sort((a, b) => b.size! - a.size!);
+  const biggest = Math.max(0, ...items.filter((i) => i.size).map((i) => i.size!));
+  if (texts.length >= 2) {
+    const [a, b] = texts;
+    if (b.size! / a.size! > 0.88 && a.name !== b.name && a.size! > biggest * 0.6) out.push({ level: 'warn', text: `no clear lead: ${who(a)} (${num(Math.round(a.size!))}px) and ${who(b)} (${num(Math.round(b.size!))}px) are about the same size` });
+    const sizes = new Set(texts.map((t) => Math.round(Math.log(t.size!) / Math.log(1.08))));
+    if (sizes.size > 4) out.push({ level: 'info', text: `${sizes.size} different text sizes: fewer reads cleaner` });
+  }
+  if (items.length > 30) out.push({ level: 'info', text: `${items.length} separate things on the canvas: busy` });
+  return out;
+}
+
+const HUES = ['red', 'orange', 'yellow', 'lime', 'green', 'teal', 'cyan', 'azure', 'blue', 'violet', 'magenta', 'pink'];
+
+/** Where the visual weight sits and the main hues, from the design against its bare background. */
+export function lookFindings(design: Pixels, bare: Pixels): Finding[] {
+  const { width: w, height: h } = design;
+  const d = design.data, e = bare.data;
+  let m = 0, mx = 0, my = 0, colored = 0;
+  const hues = new Array<number>(12).fill(0);
+  for (let y = 0, i = 0; y < h; y++) {
+    for (let x = 0; x < w; x++, i += 4) {
+      const ink = (Math.abs(d[i] - e[i]) + Math.abs(d[i + 1] - e[i + 1]) + Math.abs(d[i + 2] - e[i + 2])) / 765;
+      m += ink;
+      mx += ink * (x + 0.5);
+      my += ink * (y + 0.5);
+      const r = d[i] / 255, g = d[i + 1] / 255, b = d[i + 2] / 255;
+      const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2;
+      const s = max === min ? 0 : (max - min) / (1 - Math.abs(2 * l - 1));
+      if (s < 0.3 || l < 0.12 || l > 0.92) continue;
+      const hue = max === r ? ((g - b) / (max - min) + 6) % 6 : max === g ? (b - r) / (max - min) + 2 : (r - g) / (max - min) + 4;
+      hues[Math.floor(((hue * 60 + 15) % 360) / 30)]++;
+      colored++;
+    }
+  }
+  const out: Finding[] = [];
+  if (m > 0) {
+    const ox = (mx / m / w - 0.5) * 2, oy = (my / m / h - 0.5) * 2;
+    const off = Math.hypot(ox, oy);
+    const side = `${Math.abs(oy) > 0.08 ? (oy < 0 ? 'upper' : 'lower') : ''}${Math.abs(oy) > 0.08 && Math.abs(ox) > 0.08 ? ' ' : ''}${Math.abs(ox) > 0.08 ? (ox < 0 ? 'left' : 'right') : ''}`;
+    out.push({ level: 'info', text: off < 0.1 ? 'visual weight: balanced around the centre' : `visual weight sits ${side || 'off centre'} (${num(Math.round(off * 50))}% of the way to the edge)` });
+  }
+  const main = hues.map((n, k) => ({ n, k })).filter((x) => colored && x.n / colored > 0.04).sort((a, b) => b.n - a.n);
+  const neutral = 1 - colored / (w * h);
+  out.push({ level: main.length >= 6 ? 'warn' : 'info', text: `palette: ${main.length ? `${main.length} main hue${main.length > 1 ? 's' : ''} (${main.map((x) => HUES[x.k]).join(', ')})` : 'no strong hues'}${neutral > 0.5 ? ', mostly neutrals' : ''}${main.length >= 6 ? ': busy, try fewer' : ''}` });
+  return out;
+}
diff --git a/ui/src/agent/node.ts b/ui/src/agent/node.ts
index 7650d86..fb72fa2 100644
--- a/ui/src/agent/node.ts
+++ b/ui/src/agent/node.ts
@@ -12,3 +12,5 @@ export { migrate };
 
 export const catalog = (q = '') => catalogText(q, TEMPLATES);
 export const template = (name: string): Project => findTemplate(TEMPLATES, name).make();
+export { timing } from './timing';
+export { addGroup, addLayer, addModifier, arrange, blank, duplicateLayer, removeLayers } from './build';
diff --git a/ui/src/agent/page.ts b/ui/src/agent/page.ts
index 6ed0541..80c49e4 100644
--- a/ui/src/agent/page.ts
+++ b/ui/src/agent/page.ts
@@ -4,15 +4,17 @@
 // 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 type { Box } from '../engine/types';
+import { fontId, fromBase64 } from '../fonts/library';
 import { effectById } from '../render/effects';
-import { getRenderer, loadProjectFonts } from '../app/actions';
+import { getRenderer, loadProjectFonts, placeReference } from '../app/actions';
+import { fitToReference, tunables, type Tunable } from '../app/compare';
 import { geometryFrames, holdLiveGeometry } from '../app/geoMotion';
-import { unpackImages } from '../state/assets';
+import { addImage, encodeImage, imageElement, packImages, 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 { isGroup, style, symbolLayer, type Node, type Project, type ShapeLayer } from '../state/model';
 import { isStill } from '../state/motion';
 import { replaceProject, store } from '../state/store';
 import { loadedTemplates, loadTemplates } from '../state/templateCatalog';
@@ -20,7 +22,8 @@ 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';
+import { applyEdits, findNode } from './edit';
+import { boxTable, itemsOf, layoutFindings, lookFindings } from './layout';
 
 /** Geometry quality for output (the preview builds at 120), as exports use. */
 const OUTPUT_QUALITY = 360;
@@ -43,7 +46,8 @@ async function load(raw: unknown, quality = OUTPUT_QUALITY): Promise<{ ms: numbe
   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 });
+  // Embedded fonts stay in the project (the editor's own Open leaves them out), so reloads and saves keep them.
+  replaceProject({ ...p, 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.
@@ -271,20 +275,26 @@ async function checkAll(o: { size?: number; layers?: number }): Promise<string>
   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.
+    // Motion: runs of three frames one video frame apart, across the clock and around 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 starts = Array.from({ length: n }, (_, i) => ((i + 0.5) * D) / n).filter((t) => t + 2 * dt <= D);
+      const at = starts.flatMap((t) => [t, t + dt, t + 2 * dt]);
+      if (tl.loop) at.push(D - 2 * dt, D - dt, 0, dt);
       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));
+      const runs = starts.map((t, i) => ({ t: t + dt, a: diff(imgs[3 * i], imgs[3 * i + 1]), b: diff(imgs[3 * i + 1], imgs[3 * i + 2]) }));
+      const k = starts.length * 3;
+      const seam = tl.loop ? { a: diff(imgs[k], imgs[k + 1]), b: diff(imgs[k + 1], imgs[k + 2]), c: diff(imgs[k + 2], imgs[k + 3]) } : null;
+      findings.push(...motionFindings(runs, seam, 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' });
+    findings.push(...layoutFindings(p, itemsOf(p, store.get().build)));
+    await load({ ...p, layers: [] }, PREVIEW_QUALITY);
+    const [bare] = await frames([null], scale);
+    findings.push(...lookFindings(still, bare));
     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);
@@ -307,6 +317,157 @@ async function checkAll(o: { size?: number; layers?: number }): Promise<string>
   return report(`"${p.name}" ${p.canvas.width}×${p.canvas.height}${moves(p) ? `, ${num(tl.duration)}s${tl.loop ? ' loop' : ''}` : ''}`, findings);
 }
 
+/** The current design as a file would save it: imported fonts and pictures packed in. */
+function saved(extraFonts: Project['fonts'] = []): Project {
+  const p = structuredClone(store.get().project);
+  const fonts = new Map([...(p.fonts ?? []), ...extraFonts].map((f) => [f.id, f]));
+  p.fonts = [...fonts.values()];
+  const images = packImages(p);
+  if (images.length) p.images = images;
+  return p;
+}
+
+/** Embed a font file (base64) in the design; returns its id for content.font. */
+async function importFont(b64: string) {
+  const bytes = fromBase64(b64);
+  const id = await fontId(bytes);
+  await loadProjectFonts([{ id, bytes }]);
+  const name = store.get().fonts.find((f) => f.id === id)?.name ?? id;
+  return { project: saved([{ id, name, data: b64 }]), change: `embedded font "${name}" as ${id} (use: --font ${id})` };
+}
+
+async function decode(b64: string): Promise<ImageBitmap> {
+  return createImageBitmap(await (await fetch(`data:image/*;base64,${b64}`)).blob());
+}
+
+/** A picture (base64) as a Photo-filled rectangle, or inside an existing layer. */
+async function importImage(b64: string, name: string, target?: string) {
+  const bmp = await decode(b64);
+  const c = new OffscreenCanvas(bmp.width, bmp.height);
+  c.getContext('2d')!.drawImage(bmp, 0, 0);
+  const enc = encodeImage(c as unknown as HTMLCanvasElement, !/\.(png|webp|svg)$/i.test(name));
+  const id = addImage(enc.data, enc.w, enc.h, name);
+  let change: string;
+  if (target) {
+    // The picture isn't a listed setting of the Photo material, so it's set here rather than through an edit.
+    const project = structuredClone(store.get().project);
+    const n = findNode(project, target);
+    const was = n.style.effect;
+    n.style = { ...style('photo', { image: id }), stroke: n.style.stroke, depth: n.style.depth, opacity: n.style.opacity };
+    await load(project);
+    change = `"${n.name ?? n.id}": material ${was} → photo, filled with a ${enc.w}×${enc.h} picture`;
+  } else {
+    const p = store.get().project;
+    const side = Math.min(p.canvas.width, p.canvas.height) * 0.7;
+    const l = symbolLayer('roundRect', side, { name: name.replace(/\.[a-z]+$/i, ''), style: style('photo', { image: id }) }, { radius: 0, aspect: enc.w / enc.h });
+    await load({ ...p, layers: [...p.layers, l] });
+    change = `added "${l.name}" #${l.id}: a ${enc.w}×${enc.h} picture in a rectangle (shape roundRect, material photo)`;
+  }
+  return { project: saved(), change };
+}
+
+const EDGES: Record<string, { axis: 0 | 1; at: (b: Box) => number }> = {
+  left: { axis: 0, at: (b) => b[0] },
+  right: { axis: 0, at: (b) => b[2] },
+  centre: { axis: 0, at: (b) => (b[0] + b[2]) / 2 },
+  top: { axis: 1, at: (b) => b[1] },
+  bottom: { axis: 1, at: (b) => b[3] },
+  middle: { axis: 1, at: (b) => (b[1] + b[3]) / 2 },
+};
+
+/**
+ * Line layers up by what they draw (not their anchors): each edge of `edges`
+ * (left, right, centre, top, bottom, middle) of each target meets the same
+ * edge of `to` (the canvas, or another layer).
+ */
+async function align(targets: string[], to: string, edges: string[]) {
+  const p = store.get().project;
+  const { width: W, height: H } = p.canvas;
+  const boxOf = (id: string) => store.get().build?.layers.find((l) => l.id === id)?.bbox ?? null;
+  const ref = to === 'canvas' ? ([-W / 2, -H / 2, W / 2, H / 2] as Box) : boxOf(findNode(p, to).id);
+  if (!ref) throw new Error(`${to} has no outline to align to`);
+  const edits: string[] = [];
+  for (const t of targets) {
+    const n = findNode(p, t);
+    if (isGroup(n)) throw new Error(`align moves layers; ${n.name ?? n.id} is a group (align its layers)`);
+    const b = boxOf(n.id);
+    if (!b) throw new Error(`${n.name ?? n.id} has no outline to align`);
+    const move = [0, 0];
+    for (const e of edges) {
+      const E = EDGES[e === 'center' ? 'centre' : e];
+      if (!E) throw new Error(`align edges are ${Object.keys(EDGES).join(', ')}; not "${e}"`);
+      move[E.axis] = E.at(ref) - E.at(b);
+    }
+    const id = JSON.stringify('#' + n.id);
+    if (Math.abs(move[0]) > 0.01) edits.push(`${id}.x=${+(n.x + move[0]).toFixed(2)}`);
+    if (Math.abs(move[1]) > 0.01) edits.push(`${id}.y=${+(n.y + move[1]).toFixed(2)}`);
+  }
+  const { project, changes } = applyEdits(p, edits);
+  await load(project);
+  return { project: saved(), change: changes.length ? changes.join('\n') : 'already aligned' };
+}
+
+/** Every layer's box and the layout notes, in words. */
+async function layout(): Promise<string> {
+  const p = store.get().project;
+  const items = itemsOf(p, store.get().build);
+  const notes = layoutFindings(p, items);
+  return [boxTable(p, items), ...notes.map((f) => `${f.level === 'warn' ? '!' : '·'} ${f.text}`)].join('\n');
+}
+
+/**
+ * A run of video frames as PNGs (base64): `count` from frame `from`, at
+ * `fps`. A looping clock leaves out its last frame (it's the first again).
+ */
+async function frameBatch(o: { fps: number; from: number; count: number; scale?: number; size?: number }) {
+  const p = store.get().project;
+  const tl = timelineOf(p);
+  const total = Math.max(1, Math.round(tl.duration * o.fps)) + (tl.loop ? 0 : 1);
+  const times = Array.from({ length: Math.max(0, Math.min(o.count, total - o.from)) }, (_, i) => Math.min((o.from + i) / o.fps, tl.duration));
+  const scale = o.scale ?? (o.size ? fit(p, o.size) : 1);
+  const imgs = times.length ? await frames(times, scale) : [];
+  const out: string[] = [];
+  for (const img of imgs) out.push(await png(toCanvas(img)));
+  return { frames: out, total, duration: tl.duration, loop: tl.loop, width: imgs[0]?.width ?? 0, height: imgs[0]?.height ?? 0 };
+}
+
+/** Where `Layer.key` lands among a layer's tunable settings. */
+function tunable(n: ShapeLayer, key: string): Tunable {
+  const all = tunables(n);
+  const t = all.find((x) => x.key === key) ?? all.find((x) => x.key === `content.${key}`) ?? all.find((x) => x.key === `style.${key}`) ?? all.find((x) => x.key.endsWith(`.${key}`));
+  if (!t) throw new Error(`fit can't tune ${n.name ?? n.id}.${key}. Numbers it can: ${all.map((x) => x.key.replace(/^(content|style)\./, '')).join(', ')}`);
+  return t;
+}
+
+/**
+ * Tune settings until the design matches a reference picture: each
+ * `Layer.setting` in turn, searching around its value. Returns the design
+ * without the reference, and before → after for each.
+ */
+async function fitTo(ref: string, targets: string[]) {
+  const bmp = await decode(ref);
+  const c = new OffscreenCanvas(bmp.width, bmp.height);
+  const g = c.getContext('2d')!;
+  g.drawImage(bmp, 0, 0);
+  placeReference(g.getImageData(0, 0, bmp.width, bmp.height), 'reference');
+  const refLayer = store.get().project.layers[0];
+  await until(() => !!imageElement(String(refLayer.style.params.image))?.complete && !!store.get().build?.layers.some((l) => l.id === refLayer.id && l.bbox), 'the reference picture');
+  const lines: string[] = [];
+  for (const target of targets) {
+    const dot = target.lastIndexOf('.');
+    if (dot < 0) throw new Error(`fit takes Layer.setting, got "${target}"`);
+    const n = findNode(store.get().project, target.slice(0, dot).replace(/^"|"$/g, ''));
+    if (isGroup(n)) throw new Error(`fit tunes layers, and ${n.name ?? n.id} is a group`);
+    const t = tunable(n, target.slice(dot + 1));
+    const r = await fitToReference(n.id, t);
+    if (!r) throw new Error(`${n.name ?? n.id} doesn't overlap the reference`);
+    lines.push(`${n.name ?? '#' + n.id} ${t.key}: ${num(t.get(n))} → ${num(r.value)} (difference ${num(r.before)} → ${num(r.after)})`);
+  }
+  const p = store.get().project;
+  await load({ ...p, layers: p.layers.filter((l) => l.id !== refLayer.id) });
+  return { project: saved(), text: lines.join('\n') };
+}
+
 /**
  * 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
@@ -341,4 +502,10 @@ export const agent = {
   vary,
   check,
   compare,
+  importFont,
+  importImage,
+  fit: fitTo,
+  frameBatch,
+  layout,
+  align,
 };
diff --git a/ui/src/agent/timing.ts b/ui/src/agent/timing.ts
new file mode 100644
index 0000000..1f0db83
--- /dev/null
+++ b/ui/src/agent/timing.ts
@@ -0,0 +1,108 @@
+// When everything moves, as a text chart: one row per moving layer (the
+// timeline dock's rows, top first) with entrances and exits as bars on the
+// clock, loops and keyframes as their cycles, and a few notes on rhythm: many
+// things starting at once, or long stretches where nothing happens.
+import { timelineOf } from '../state/clock';
+import { feelOf, HOLD_GO, HOLD_IN, HOLD_OUT } from '../state/motion';
+import type { Project } from '../state/model';
+import { nodeLabel } from '../state/model';
+import { rowsOf, type Track } from '../state/tracks';
+import { num } from './describe';
+
+const COLS = 48;
+
+function bar(a: number, b: number, D: number, steps?: { start: number; end: number }[]): string {
+  const cell = (t: number) => Math.max(0, Math.min(COLS - 1, Math.floor((t / D) * COLS)));
+  const out = Array<string>(COLS).fill('·');
+  for (let i = cell(a); i <= cell(Math.min(b, D - 1e-6)); i++) out[i] = '█';
+  for (const s of steps?.slice(1) ?? []) out[cell(s.start)] = '▌';
+  return out.join('');
+}
+
+function cycles(period: number, D: number, ch: string): string {
+  const out = Array<string>(COLS).fill(ch);
+  for (let t = 0; t <= D + 1e-6; t += Math.max(period, D / COLS)) out[Math.min(COLS - 1, Math.round((t / D) * COLS))] = '|';
+  return out.join('');
+}
+
+/** A hold keyframe across the clock: _ at rest, / going, ‾ at To, \ coming back. */
+function holds(period: number, phase: number, D: number): string {
+  return Array.from({ length: COLS }, (_, i) => {
+    const u = ((i + 0.5) / COLS) * (D / period) + phase;
+    const f = u - Math.floor(u);
+    return f < HOLD_GO ? '_' : f < HOLD_IN ? '/' : f < HOLD_OUT ? '‾' : '\\';
+  }).join('');
+}
+
+function trackLine(t: Track, D: number): [string, string, string] {
+  switch (t.kind) {
+    case 'enter':
+    case 'leave': {
+      const feel = feelOf(t.motion.transition);
+      const how = feel ?? t.motion.transition.type;
+      return [`${t.kind === 'enter' ? 'in' : 'out'} ${t.label}`.toLowerCase(), bar(t.start, t.end, D, t.steps), `${num(t.start)}–${num(t.end)}s ${how}${t.from ? ` (from group "${t.from}")` : ''}`];
+    }
+    case 'loop':
+      return [`loop ${t.label}`.toLowerCase(), cycles(t.period, D, '~'), `every ${num(t.period)}s, ${num(t.motion.amount)}`];
+    case 'param':
+      return [t.label.toLowerCase(), t.anim.mode === 'hold' ? holds(t.period, t.anim.phase, D) : cycles(t.period, D, t.anim.mode === 'ramp' ? '/' : t.anim.mode === 'flicker' ? ':' : '∿'), `${t.anim.mode} ${String(t.from)}→${String(t.anim.to)} every ${num(t.period)}s`];
+    case 'flow':
+      return [t.title.toLowerCase(), '═'.repeat(COLS), t.label];
+  }
+}
+
+const pad = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '…' : s.padEnd(n));
+
+export function timing(p: Project): string {
+  const tl = timelineOf(p);
+  const D = Math.max(0.1, tl.duration);
+  const rows = rowsOf(p, []);
+  if (!rows.length) return `"${p.name}": nothing moves.`;
+  const ruler = Array<string>(COLS).fill(' ');
+  const marks = Math.min(8, Math.floor(D));
+  for (let s = 0; s <= marks; s++) {
+    const t = (s * D) / marks;
+    const label = `${num(t)}s`;
+    const at = Math.min(COLS - label.length, Math.round((t / D) * COLS));
+    for (let i = 0; i < label.length; i++) ruler[at + i] = label[i];
+  }
+  const out = [`"${p.name}" clock ${num(D)}s${tl.loop ? ' loop' : ''} · █ in/out, | cycle starts, ∿ swing, / ramp, : flicker, hold _/‾\\ (rest, go, at To, back)`, `${' '.repeat(24 + 24)}${ruler.join('')}`];
+  for (const r of rows) {
+    const name = `${'  '.repeat(r.depth)}${nodeLabel(r.node)}`;
+    if (!r.tracks.length) out.push(pad(name, 24));
+    r.tracks.forEach((t, i) => {
+      const [kind, b, note] = trackLine(t, D);
+      out.push(`${pad(i === 0 ? name : '', 24)}${pad(kind, 24)}${b}  ${note}`);
+    });
+  }
+  out.push(...rhythm(rows.flatMap((r) => r.tracks), D, tl.loop));
+  return out.join('\n');
+}
+
+/** Notes on how the moves sit together in time. */
+export function rhythm(tracks: Track[], D: number, loop: boolean): string[] {
+  const notes: string[] = [];
+  const clips = tracks.filter((t): t is Extract<Track, { kind: 'enter' | 'leave' }> => t.kind === 'enter' || t.kind === 'leave');
+  const starts = clips.filter((c) => c.kind === 'enter').map((c) => c.start).sort((a, b) => a - b);
+  for (let i = 0; i < starts.length; ) {
+    let j = i;
+    while (j + 1 < starts.length && starts[j + 1] - starts[i] < 0.05) j++;
+    if (j - i + 1 >= 3) notes.push(`· ${j - i + 1} entrances start together at ${num(starts[i])}s: a stagger gives them rhythm`);
+    i = j + 1;
+  }
+  const always = tracks.some((t) => t.kind === 'loop' || t.kind === 'param' || t.kind === 'flow');
+  if (clips.length && !always) {
+    const spans = clips.map((c) => [c.start, c.end] as const).sort((a, b) => a[0] - b[0]);
+    let edge = 0;
+    const gaps: [number, number][] = [];
+    for (const [a, b] of spans) {
+      if (a - edge > D * 0.3) gaps.push([edge, a]);
+      edge = Math.max(edge, b);
+    }
+    if (D - edge > D * 0.3) gaps.push([edge, D]);
+    for (const [a, b] of gaps) notes.push(`· nothing moves from ${num(a)}s to ${num(b)}s${loop && b === D ? ' (then it loops)' : ''}`);
+  }
+  const late = clips.filter((c) => c.end > D + 1e-3);
+  for (const c of late) notes.push(`! a move ends at ${num(c.end)}s, after the ${num(D)}s clock: it gets cut off`);
+  return notes;
+}

From b137cff5dc8922175223fe23205211aab68fbb75 Mon Sep 17 00:00:00 2001
From: srivtx <crypticcc101@gmail.com>
Date: Sat, 24 Oct 2026 01:50:17 +0530
Subject: [PATCH 2/2] morpho: document the new commands; cover them end to end

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md           |  7 +++++++
 docs/AGENT-TOOLS.md | 46 +++++++++++++++++++++++++++++++++++++++++++--
 scripts/e2e.mjs     |  8 +++++++-
 3 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b79883e..4872f13 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,6 +16,13 @@ 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
+
+npm run morpho -- new poster.morpho --canvas 1080x1350 --bg "#111111"   # from scratch
+npm run morpho -- add poster.morpho text "HELLO" --size 200 --preset "Ice chrome"
+npm run morpho -- align poster.morpho HELLO                            # centre by what's drawn
+npm run morpho -- layout poster.morpho                                 # boxes and margins as text
+npm run morpho -- timing poster.morpho                                 # when everything moves
+npm run morpho -- video poster.morpho -o poster.mp4
 ```
 
 Prefer `check`, `describe` and text output over images. When you do need to look, ask for one contact sheet (`--frames`, `vary`), not several renders.
diff --git a/docs/AGENT-TOOLS.md b/docs/AGENT-TOOLS.md
index c29bfba..af7cbf5 100644
--- a/docs/AGENT-TOOLS.md
+++ b/docs/AGENT-TOOLS.md
@@ -18,10 +18,38 @@ npm run morpho -- help
 | `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 |
+| `new <file>` | A blank design: `--canvas 1080x1350` or a preset name (`"Instagram post"`), `--bg "#111111"`, `"#a,#b"` (a gradient) or a background preset, `--duration 4`. | no |
+| `add <file> text "HI"` · `shape star` · `line "<d>"` · `path "<d>"` | A new layer. Options: `--name`, `--at x,y`, `--size`, `--font`, `--color`, `--material chrome` or `--preset "Ice chrome"`, `--recipe Glitch`, `--rotation`, `--scale`, `--width` (lines), and `--above L`, `--below L` or `--into Group` (the default is on top). Lines and outlines take SVG path data in em units, centred on 0,0. | no |
+| `add <file> modifier glitch --to L` | A modifier with its defaults; `--fields '{"amount":0.6}'` overrides them. A recipe name adds that recipe. | no |
+| `add <file> group A B` | Wraps layers in a group where the topmost one was (`--merge` fuses them into one shape). | no |
+| `add <file> font f.ttf` · `image p.png` | Embeds a font and prints its id for `--font`. Places a picture in a rectangle, or with `--to L` fills that layer with it. | yes |
+| `remove` · `duplicate` · `arrange` | `remove <file> L…`. `duplicate <file> L` (new ids, so its keyframes follow its own modifiers). `arrange <file> L top\|bottom\|up\|down\|above M\|below M`. | no |
+| `align <file> L… [--to canvas\|M] [--edge centre,middle]` | Lines layers up by what they actually draw, not their anchors. A wavy or italic word that looks off centre gets centred by its ink. | yes |
+| `layout <scene>` | Every layer's box, centre and margins to each edge as text, plus the layout notes `check` gives. | yes |
+| `timing <scene>` | When everything moves: entrances and exits as bars on the clock, loops and keyframes as their cycles (hold keyframes as rest, go, at To, back), with notes on rhythm (entrances all starting at once, long stretches where nothing moves, moves cut off by the clock). | no |
+| `video <scene> -o f.mp4` | MP4, MOV, WebM or GIF (needs ffmpeg), or PNG frames into a folder ending in `/`. Every frame is drawn at its exact time, so a 4 s loop exports in about 3 s and joins seamlessly. `--fps` (default 30, GIF 20), `--size` (GIF default 480) or `--scale`. | yes |
+| `fit <file> <ref> L.setting…` | Tunes each setting in turn until the design matches a reference picture, writes the file (or `--out`), and prints before → after. Settings: position, rotation, scale, and any number in the content or material. | 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.
 
+## A design from scratch
+
+```sh
+morpho new gig.morpho --canvas 1080x1350 --bg "#0d0d12" --name "Night Drive" --duration 4
+morpho add gig.morpho text "NIGHT\nDRIVE" --font unbounded --size 300 --preset "Ice chrome" --at 0,-150 --name Title
+morpho add gig.morpho shape ring --size 900 --at 0,-150 --color "#5a17d6" --below Title --name Halo
+morpho add gig.morpho shape sparkle --size 220 --at 320,-490 --preset Plasma --name Spark
+morpho add gig.morpho text "LIVE · 21.11 · WAREHOUSE 9" --font space-grotesk --size 34 --color "#e8e8f0" --at 0,420 --name Info
+morpho add gig.morpho modifier wave --to Title --fields '{"amplitude":0.04,"wavelength":1.4}'
+morpho set gig.morpho 'Spark.motion.loop="spin"' 'Spark.motion.period=4' 'Halo.motion.loop="pulse"' 'Title.motion.enter="rise"'
+morpho check gig.morpho     # → title 10% off both edges; the loop jumps (the entrance replays)
+morpho set gig.morpho 'Title.size=250' 'Title.motion.leave="fade"' 'Title.motion.leaveAt=3.3'
+morpho align gig.morpho Title Info          # centre by what's drawn
+morpho check gig.morpho     # → no problems; the loop joins smoothly
+morpho video gig.morpho -o gig.mp4
+```
+
 ## 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):
@@ -40,6 +68,8 @@ morpho set y2k.morpho 'canvas.width=1080' 'timeline.duration=4' 'background.grai
 - **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.
+- **Presets and recipes.** `Layer.preset="Ice chrome"` switches to that look. `Layer.recipe=Glitch` adds that recipe's modifiers.
+- **Motion kinds.** Setting `motion.loop`, `motion.enter` or `motion.leave` also sets that kind's own default amount (spin counts turns, sway counts degrees). Set the amount after the kind.
 - **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.
 
@@ -54,12 +84,21 @@ morpho set y2k.morpho 'canvas.width=1080' 'timeline.duration=4' 'background.grai
 - keyframes that point at nothing;
 - entrances or exits timed after the clock ends.
 
+**From the boxes (layout notes):**
+- edges and centres that nearly line up, 0.2–1.2% of the canvas apart (closer than that, nobody sees it);
+- layers that are nearly centred on the canvas;
+- things crowding an edge;
+- a design that sits a little off centre;
+- two headlines of about the same size (no clear lead);
+- too many text sizes.
+
 **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.
+- pops in the motion: one frame step far bigger than the steps either side of it, so fast but smooth moves aren't flagged;
+- a loop that jumps where it starts over (for example an entrance that replays every loop);
+- where the visual weight sits, and how many hues the palette really uses.
 
 ## Speed
 
@@ -85,6 +124,9 @@ Under `serve`, edits to the app's TypeScript reload the page by themselves. Afte
 | `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/build.ts` | New designs, layers, modifiers, groups, duplicates and restacking. |
+| `ui/src/agent/layout.ts` | Boxes, layout notes, balance and palette. |
+| `ui/src/agent/timing.ts` | The timing chart and rhythm notes (from the timeline dock's own tracks). |
 | `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. |
diff --git a/scripts/e2e.mjs b/scripts/e2e.mjs
index 7bd6a36..52d8960 100644
--- a/scripts/e2e.mjs
+++ b/scripts/e2e.mjs
@@ -904,12 +904,18 @@ try {
       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() };
+      const layout = await a.layout();
+      const video = await a.frameBatch({ fps: 10, from: 0, count: 3, size: 120 });
+      const aligned = await a.align(['Caption'], 'canvas', ['centre']);
+      return { changes, still: [still.width, still.height], strip: [strip.width, strip.height], grid: [grid.width, grid.height], report, text: a.describe(), layout, video: [video.frames.length, video.total], aligned: aligned.change };
     });
   });
   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]}`);
+  check(/margins L .* R /.test(agent.layout) && /palette: /.test(agent.report), 'agent layout lists boxes and margins, and check reads the palette');
+  check(agent.video[0] === 3 && agent.video[1] === 40, `agent draws video frames in batches (${agent.video.join(' of ')})`);
+  check(/Caption" x:|already aligned/.test(agent.aligned), `agent aligns by what's drawn (${agent.aligned})`);
 } catch (e) {
   errors.push(`crashed: ${e.message.split('\n').slice(0, 12).join(' / ')}`);
   const pages = browser.contexts().flatMap((c) => c.pages());