@bytesbybrandon/living-docs 0.2.1 → 0.3.1

package/samples/end-of-harness-engineering.json

@@ -9,7 +9,7 @@
     "date": "2026",
     "kicker": "Reading notes · The End of Harness Engineering (2026)",
     "runningHead": "Harness engineering · loop engineering",
-    "abstract": "A harness is the program written around a model, and writing it by hand has been the skill. The paper argues that this is ending. A hand-written harness is one guess about one task on one afternoon; once it ships, it runs for months, unread and unscored. In the loop the paper describes, the harness is a file that grades itself: a small 4B model reads what failed and proposes 8 edits, and only the edit that scores best on held-out questions survives. This repeats every round. The big model stays frozen; only the file around it changes.",
+    "abstract": "A harness is the program written around a model, and writing it by hand has been the skill. The paper argues that this is ending. [[mark:guess|A hand-written harness is one guess about one task on one afternoon;]] once it ships, it runs for months, unread and unscored. In the loop the paper describes, the harness is a file that grades itself: [[mark:editor|a small 4B model reads what failed and proposes 8 edits]], and [[mark:best|only the edit that scores best on held-out questions survives]]. This repeats every round. [[mark:frozen|The big model stays frozen; only the file around it changes.]]",
     "indexTerms": [
       "harness engineering",
       "self-improving harness",
@@ -40,6 +40,7 @@
     },
     {
       "type": "figure",
+      "id": "loop",
       "caption": "Two ways to write a harness. The hand-written path is a single guess; the loop-written path reads failures, proposes edits, and keeps only what survives held-out scoring.",
       "spec": "diagram",
       "motion": "draw",
@@ -52,11 +53,11 @@
           { "id": "v0", "label": "harness v0", "sub": "one guess", "x": 214, "y": 130, "w": 140, "h": 62, "icon": "file" },
           { "id": "unscored", "label": "unscored", "sub": "never graded", "x": 78, "y": 240, "w": 150, "h": 52, "kind": "dashed" },
           { "id": "frozen", "label": "frozen big model", "sub": "e.g. Claude, never updated", "x": 402, "y": 130, "w": 180, "h": 62, "kind": "accent", "icon": "star" },
-          { "id": "failures", "label": "failures", "sub": "what went wrong", "x": 402, "y": 28, "w": 150, "h": 54, "kind": "accent" },
-          { "id": "editor", "label": "4B editor", "sub": "reads the failures", "x": 592, "y": 28, "w": 160, "h": 54 },
-          { "id": "held", "label": "held-out questions", "x": 786, "y": 28, "w": 170, "h": 54 },
-          { "id": "best", "label": "best edit kept", "sub": "1 of 8 survives", "x": 786, "y": 130, "w": 170, "h": 54 },
-          { "id": "file", "label": "harness file", "sub": "now v3", "x": 786, "y": 236, "w": 170, "h": 56, "icon": "file" }
+          { "id": "failures", "label": "failures", "sub": "what went wrong", "x": 384, "y": 28, "w": 140, "h": 54, "kind": "accent" },
+          { "id": "editor", "label": "4B editor", "sub": "reads the failures", "x": 552, "y": 28, "w": 150, "h": 54 },
+          { "id": "held", "label": "held-out questions", "x": 826, "y": 28, "w": 150, "h": 54 },
+          { "id": "best", "label": "best edit kept", "sub": "1 of 8 survives", "x": 826, "y": 130, "w": 150, "h": 54 },
+          { "id": "file", "label": "harness file", "sub": "now v3", "x": 826, "y": 236, "w": 150, "h": 56, "icon": "file" }
         ],
         "edges": [
           { "from": "person", "to": "v0", "style": "arrow" },
@@ -110,6 +111,7 @@
     },
     {
       "type": "figure",
+      "id": "score",
       "caption": "Held-out score by round. Each round the editor proposes eight edits; the seven rejected are grey, the kept one is orange. The harness changes only when an edit wins.",
       "spec": "chart",
       "motion": "steps",
@@ -176,5 +178,26 @@
         "Held-out questions are kept out of the editing step and used only for scoring."
       ]
     }
-  ]
+  ],
+  "timeline": {
+    "cues": [
+      { "at": 0.4, "dur": 2.2, "do": "highlight", "target": "mark:guess" },
+      { "at": 0.6, "dur": 1, "do": "focus", "target": "loop/person" },
+      { "at": 1.4, "dur": 1.1, "do": "focus", "target": "loop/v0" },
+      { "at": 2.8, "dur": 2.2, "do": "highlight", "target": "mark:editor" },
+      { "at": 3, "dur": 1, "do": "focus", "target": "loop/failures" },
+      { "at": 3.8, "dur": 1.1, "do": "focus", "target": "loop/editor" },
+      { "at": 5.2, "dur": 2.2, "do": "highlight", "target": "mark:best" },
+      { "at": 5.4, "dur": 1, "do": "focus", "target": "loop/held" },
+      { "at": 6.2, "dur": 1.1, "do": "focus", "target": "loop/best" },
+      { "at": 7.6, "dur": 2.2, "do": "highlight", "target": "mark:frozen" },
+      { "at": 7.8, "dur": 1, "do": "focus", "target": "loop/frozen" },
+      { "at": 8.6, "dur": 1.1, "do": "focus", "target": "loop/file" },
+      { "at": 10.2, "dur": 1.6, "do": "camera", "target": "loop/editor" },
+      { "at": 12.2, "dur": 1.4, "do": "camera", "target": "loop/best" },
+      { "at": 14, "dur": 1.8, "do": "camera", "target": "score" },
+      { "at": 15.4, "dur": 2, "do": "focus", "target": "score" },
+      { "at": 17.8, "dur": 1.8, "do": "camera", "target": "page" }
+    ]
+  }
 }

package/samples/harness-engineering.json

@@ -11,7 +11,7 @@
     "stamps": [
       "arXiv:2609.00006v1 [cs.SE] 15 Jul 2026"
     ],
-    "abstract": "An agent is a model plus a harness: the runtime that couples an LLM to the world through a loop, tools, context management, safety controls, orchestration, and extension surfaces. This paper defines the harness, maps its seven canonical subsystems with the minimal and maximal implementation of each, and dissects eleven production coding harnesses along those subsystems. It does not benchmark or rank them; it describes and compares how the systems are built. Two absences and three extensibility standards survive a threefold corpus expansion across roughly four million lines of Python, TypeScript, and Rust.",
+    "abstract": "[[mark:agent|An agent is a model plus a harness: the runtime that couples an LLM to the world through a loop, tools, context management, safety controls, orchestration, and extension surfaces.]] This paper defines the harness, [[mark:maps|maps its seven canonical subsystems with the minimal and maximal implementation of each]], and dissects eleven production coding harnesses along those subsystems. It does not benchmark or rank them; it describes and compares how the systems are built. [[mark:standards|Two absences and three extensibility standards survive a threefold corpus expansion]] across roughly four million lines of Python, TypeScript, and Rust.",
     "indexTerms": [
       "coding agents",
       "harness engineering",
@@ -39,6 +39,7 @@
     },
     {
       "type": "figure",
+      "id": "anatomy",
       "caption": "An agent is a model plus a harness of seven subsystems. The harness owns everything outside the weights.",
       "spec": "diagram",
       "motion": "draw",
@@ -117,6 +118,7 @@
     },
     {
       "type": "figure",
+      "id": "standards",
       "caption": "Extensibility standards across eleven coding harnesses. Counts include partial support, greyed in the paper's original figure.",
       "spec": "chart",
       "motion": "steps",
@@ -163,6 +165,7 @@
     },
     {
       "type": "figure",
+      "id": "convergence",
       "caption": "Convergence becomes imitation: Codex reads Claude Code's hook vocabulary while OpenHands reads its plugin format.",
       "spec": "diagram",
       "motion": "draw",
@@ -182,6 +185,7 @@
     },
     {
       "type": "stats",
+      "id": "counts",
       "caption": "Counts stated in the abstract of the study.",
       "items": [
         { "label": "Cross-cutting observations", "value": "13" },
@@ -203,5 +207,31 @@
         "Adoption counts include partial support and are reported as fractions of eleven systems."
       ]
     }
-  ]
+  ],
+  "timeline": {
+    "cues": [
+      { "at": 0.4, "dur": 4.2, "do": "highlight", "target": "mark:agent" },
+      { "at": 0.6, "dur": 0.9, "do": "focus", "target": "anatomy/model" },
+      { "at": 1.05, "dur": 0.9, "do": "focus", "target": "anatomy/loop" },
+      { "at": 1.5, "dur": 0.9, "do": "focus", "target": "anatomy/tools" },
+      { "at": 1.9500000000000002, "dur": 0.9, "do": "focus", "target": "anatomy/context" },
+      { "at": 2.4, "dur": 0.9, "do": "focus", "target": "anatomy/safety" },
+      { "at": 2.85, "dur": 0.9, "do": "focus", "target": "anatomy/orchestration" },
+      { "at": 3.3000000000000003, "dur": 0.9, "do": "focus", "target": "anatomy/extensions" },
+      { "at": 3.75, "dur": 0.9, "do": "focus", "target": "anatomy/integration" },
+      { "at": 4.8, "dur": 1.6, "do": "camera", "target": "anatomy" },
+      { "at": 5, "dur": 2.4, "do": "highlight", "target": "mark:maps" },
+      { "at": 5.6, "dur": 2, "do": "focus", "target": "anatomy" },
+      { "at": 7.8, "dur": 1.8, "do": "camera", "target": "standards" },
+      { "at": 8, "dur": 2.6, "do": "highlight", "target": "mark:standards" },
+      { "at": 9.4, "dur": 2, "do": "focus", "target": "standards" },
+      { "at": 11.6, "dur": 1.8, "do": "camera", "target": "convergence" },
+      { "at": 12.6, "dur": 1, "do": "focus", "target": "convergence/cc" },
+      { "at": 13.4, "dur": 1, "do": "focus", "target": "convergence/codex" },
+      { "at": 14.2, "dur": 1, "do": "focus", "target": "convergence/openhands" },
+      { "at": 15.4, "dur": 1.6, "do": "camera", "target": "counts" },
+      { "at": 15.8, "dur": 1.6, "do": "count", "target": "counts" },
+      { "at": 18, "dur": 1.8, "do": "camera", "target": "page" }
+    ]
+  }
 }

package/src/axi/cli.js

@@ -8,6 +8,7 @@ import { renderDoc, themeList } from '../render/index.js';
 import { validateDoc, formatErrors } from '../model/validate.js';
 import { BLOCKS, THEMES, META, STYLE, blockFieldSummary } from '../model/schema.js';
 import { createPreviewServer } from '../server/preview.js';
+import { exportVideo, FORMATS } from '../export/video.js';
 
 const HOME = os.homedir();
 const BIN = fileURLToPath(new URL('../../bin/living-docs-axi.js', import.meta.url));
@@ -16,6 +17,7 @@ class UsageError extends Error {}
 
 const FLAGS = {
   '--theme': 'value',
+  '--seed': 'value',
   '--out': 'value', '-o': 'value',
   '--section': 'value',
   '--url': 'value',
@@ -24,11 +26,16 @@ const FLAGS = {
   '--port': 'value',
   '--outline': 'bool',
   '--draft': 'bool',
+  '--static': 'bool',
   '--json': 'bool',
   '--stdout': 'bool',
   '--no-open': 'bool',
   '--full': 'bool',
   '--block': 'value',
+  '--format': 'value',
+  '--size': 'value',
+  '--fps': 'value',
+  '--scale': 'value',
   '--help': 'bool', '-h': 'bool'
 };
 
@@ -215,9 +222,10 @@ async function ingest({ args, flags }) {
   ];
 
   if (flags.draft) {
-    const theme = flags.theme || 'paper-dark';
-    if (!THEMES[theme]) throw new UsageError(`unknown theme "${theme}" (one of: ${Object.keys(THEMES).join(', ')})`);
-    const model = draftModel(ingested, { theme });
+    if (flags.theme && !THEMES[flags.theme]) throw new UsageError(`unknown theme "${flags.theme}" (one of: ${Object.keys(THEMES).join(', ')})`);
+    if (flags.seed && !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(flags.seed)) throw new UsageError('--seed must be a hex color like #2f6f8f');
+    const model = draftModel(ingested, { theme: flags.theme, seed: flags.seed, cues: !flags.static });
+    const theme = model.theme;
     const validation = validateDoc(model);
     if (!validation.ok) {
       return [`error: draft model is invalid`, formatErrors(validation.errors)].join('\n');
@@ -293,9 +301,47 @@ function runRender(flags, { quiet = false } = {}) {
   return { ok: true, status: lines.join('\n'), file: out, result };
 }
 
-function renderCommand({ args, flags }) {
+async function renderVideo(flags) {
+  const format = flags.format;
+  const { model, baseDir } = loadModel(flags._input);
+  const theme = flags.theme || model.theme || 'paper-light';
+  const out = flags.out && flags.out !== '-' ? flags.out : path.join('docs', `${slugify(model.meta?.title || 'document')}-${theme}.${format}`);
+  fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+  const started = Date.now();
+  let result;
+  try {
+    result = await exportVideo(model, {
+      theme, baseDir, format, out,
+      size: flags.size,
+      fps: flags.fps ? Number(flags.fps) : undefined,
+      scale: flags.scale ? Number(flags.scale) : undefined
+    });
+  } catch (error) {
+    if (error.name !== 'RenderError') throw error;
+    process.exitCode = 1;
+    return ['error: model invalid', formatErrors(error.errors)].join('\n');
+  }
+  return [
+    'ok: true',
+    `file: ${displayPath(out)}`,
+    `format: ${format}`,
+    `theme: ${result.theme}`,
+    `size: ${result.width}x${result.height}`,
+    `frames: ${result.frames}`,
+    `seconds: ${result.duration}`,
+    `bytes: ${fs.statSync(out).size}`,
+    `render_ms: ${Date.now() - started}`
+  ].join('\n') + helpLines([`Run \`living-docs-axi render ${displayPath(flags._input)} --theme ${theme}\` for the live HTML`]);
+}
+
+async function renderCommand({ args, flags }) {
   flags._input = args[0];
   if (!flags._input) throw new UsageError('render needs a model path (or `-` for stdin)');
+  if (flags.format && flags.format !== 'html') {
+    if (!FORMATS.includes(flags.format)) throw new UsageError(`--format must be one of: html, ${FORMATS.join(', ')}`);
+    if (flags.stdout) throw new UsageError('--stdout only works with html');
+    return renderVideo(flags);
+  }
   const rendered = runRender(flags);
   process.exitCode = rendered.ok ? 0 : 1;
   return rendered.status;
@@ -343,8 +389,8 @@ async function preview({ args, flags }) {
 }
 
 const COMMAND_HELP = {
-  ingest: 'ingest <path|url|-> [--url <url>] [--text <text>] [--outline] [--section <n|id>] [--draft] [--theme <name>] [-o <file>] [--max-chars <n>] [--full]',
-  render: 'render <model.json|-> [--theme <name>] [-o <file>] [--stdout]',
+  ingest: 'ingest <path|url|-> [--url <url>] [--text <text>] [--outline] [--section <n|id>] [--draft] [--static] [--theme <name>] [--seed <hex>] [-o <file>] [--max-chars <n>] [--full]',
+  render: 'render <model.json|-> [--theme <name>] [-o <file>] [--stdout] [--format html|mp4|webm|gif] [--size 1080x1350] [--fps 30] [--scale 1]',
   validate: 'validate <model.json|->',
   preview: 'preview [file|dir] [--port <n>] [--no-open]',
   themes: 'themes',
@@ -384,7 +430,7 @@ export async function main(argv) {
       case 'ingest':
         return await ingest({ args, flags });
       case 'render':
-        return renderCommand({ args, flags });
+        return await renderCommand({ args, flags });
       case 'validate':
         return validateCommand({ args, flags });
       case 'preview':

package/src/export/video.js

@@ -0,0 +1,150 @@
+// Video export: render the doc as a fixed stage, seek the timeline frame by frame in headless
+// Chromium, and pipe PNG frames to ffmpeg. Playwright and ffmpeg are optional, found at run time.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { renderDoc, RenderError } from '../render/index.js';
+import { timelineDuration } from '../render/timeline.js';
+
+export const FORMATS = ['mp4', 'webm', 'gif'];
+
+export class ExportError extends Error {
+  constructor(message, { code, hint } = {}) {
+    super(message);
+    this.name = 'ExportError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+export function parseSize(value = '1080x1350') {
+  const match = /^(\d{2,4})x(\d{2,4})$/.exec(String(value));
+  if (!match) throw new ExportError(`size must look like 1080x1350, got "${value}"`, { code: 'bad-size' });
+  const [width, height] = [Number(match[1]), Number(match[2])];
+  // yuv420p needs even dimensions.
+  if (width % 2 || height % 2) throw new ExportError('size needs even width and height', { code: 'bad-size' });
+  return { width, height };
+}
+
+async function loadChromium() {
+  try {
+    return (await import('playwright')).chromium;
+  } catch {
+    throw new ExportError('video export needs the optional playwright package', {
+      code: 'missing-playwright',
+      hint: 'install playwright beside living-docs (npm i -D playwright, or npx -y -p living-docs-axi -p playwright living-docs-axi ...), then npx playwright install chromium'
+    });
+  }
+}
+
+function ffmpegPath() {
+  const bin = process.env.LIVING_DOCS_FFMPEG || 'ffmpeg';
+  const probe = spawnSync(bin, ['-version'], { stdio: 'ignore' });
+  if (probe.error || probe.status !== 0) {
+    throw new ExportError(`ffmpeg not found (${bin})`, {
+      code: 'missing-ffmpeg',
+      hint: 'install ffmpeg on PATH or set LIVING_DOCS_FFMPEG'
+    });
+  }
+  return bin;
+}
+
+/**
+ * Seek the stage frame by frame and hand each PNG to onFrame(buffer, index).
+ * Frames are a pure function of t, so two runs on one machine match.
+ */
+export async function captureFrames({ html, width, height, scale = 1, fps = 30, duration, image = 'png' }, onFrame) {
+  const chromium = await loadChromium();
+  let browser;
+  try {
+    browser = await chromium.launch();
+  } catch (error) {
+    throw new ExportError(`could not start Chromium: ${error.message.split('\n')[0]}`, {
+      code: 'missing-browser',
+      hint: 'npx playwright install chromium'
+    });
+  }
+  try {
+    const page = await browser.newPage({
+      viewport: { width: Math.round(width / scale), height: Math.round(height / scale) },
+      deviceScaleFactor: scale
+    });
+    const pageErrors = [];
+    page.on('pageerror', error => pageErrors.push(error.message));
+    // The flag must exist before the runtime script runs; setContent skips init scripts.
+    await page.setContent(html.replace('<head>', '<head><script>window.__ldCapture = true;</script>'), { waitUntil: 'load' });
+    if (!(await page.evaluate(() => window.__ld && window.__ldCapture))) throw new ExportError('stage runtime did not start in capture mode', { code: 'stage-error' });
+    await page.evaluate(() => document.fonts.ready);
+    if (pageErrors.length) throw new ExportError(`stage script failed: ${pageErrors[0]}`, { code: 'stage-error' });
+    const total = Math.max(1, Math.round(duration * fps));
+    for (let i = 0; i < total; i++) {
+      await page.evaluate(t => window.__ld.seek(t), i / fps);
+      await onFrame(await page.screenshot(image === 'jpeg' ? { type: 'jpeg', quality: 95 } : { type: 'png' }), i);
+    }
+    return { frames: total };
+  } finally {
+    await browser.close();
+  }
+}
+
+function encoderArgs(format, { fps, gifWidth, gifFps }) {
+  if (format === 'mp4') {
+    return ['-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '22', '-movflags', '+faststart'];
+  }
+  if (format === 'webm') {
+    return ['-c:v', 'libvpx-vp9', '-pix_fmt', 'yuv420p', '-crf', '33', '-b:v', '0', '-row-mt', '1'];
+  }
+  // One pass: build a palette from every frame, then dither against it.
+  return ['-vf', `fps=${Math.min(gifFps, fps)},scale=${gifWidth}:-2:flags=lanczos,split[a][b];[a]palettegen=stats_mode=full[p];[b][p]paletteuse=dither=sierra2_4a`, '-loop', '0'];
+}
+
+/** Always hand ffmpeg a local file: never an option, a URL, or a pipe, whatever the caller passed as `out`. */
+export function ffmpegTarget(out) {
+  if (typeof out !== 'string' || !out.trim()) throw new ExportError('out must be a file path', { code: 'bad-output' });
+  return `file:${path.resolve(out)}`;
+}
+
+/**
+ * Render a model to mp4, webm, or gif.
+ * @returns {Promise<{file: string, format: string, frames: number, duration: number, width: number, height: number, framesSha256: string, theme: string}>}
+ */
+export async function exportVideo(model, { theme, baseDir, format = 'mp4', size, fps = 30, scale = 1, out, gifWidth = 720, gifFps = 15 } = {}) {
+  if (!FORMATS.includes(format)) throw new ExportError(`format must be one of: html, ${FORMATS.join(', ')}`, { code: 'bad-format' });
+  const { width, height } = parseSize(size);
+  const rendered = renderDoc(model, { theme, baseDir, stage: true });
+  if (!rendered.ok) throw new RenderError('model invalid', { errors: rendered.errors });
+  const bin = ffmpegPath();
+  const duration = timelineDuration(model);
+  const ffmpeg = spawn(bin, [
+    '-y', '-loglevel', 'error',
+    '-f', 'image2pipe', '-framerate', String(fps), '-i', '-',
+    ...encoderArgs(format, { fps, gifWidth, gifFps }),
+    '-fflags', '+bitexact', '-map_metadata', '-1',
+    '-f', format, ffmpegTarget(out)
+  ], { stdio: ['pipe', 'ignore', 'pipe'] });
+  let stderr = '';
+  ffmpeg.stderr.on('data', chunk => { stderr += chunk; });
+  const done = new Promise((resolve, reject) => {
+    ffmpeg.on('error', reject);
+    ffmpeg.on('close', code => (code === 0 ? resolve() : reject(new ExportError(`ffmpeg failed: ${stderr.trim().split('\n').pop()}`, { code: 'ffmpeg-failed' }))));
+  });
+  const hash = createHash('sha256');
+  let captured;
+  try {
+    // JPEG frames are ~4x faster to grab; GIF keeps lossless PNG so the palette is not built from artifacts.
+    const image = format === 'gif' ? 'png' : 'jpeg';
+    captured = await captureFrames({ html: rendered.html, width, height, scale, fps, duration, image }, buffer => {
+      hash.update(buffer);
+      if (ffmpeg.stdin.write(buffer)) return null;
+      return new Promise(resolve => ffmpeg.stdin.once('drain', resolve));
+    });
+  } catch (error) {
+    ffmpeg.stdin.end();
+    await done.catch(() => {});
+    throw error;
+  }
+  ffmpeg.stdin.end();
+  await done;
+  return { file: out, format, frames: captured.frames, duration, width, height, framesSha256: hash.digest('hex'), theme: rendered.theme };
+}

package/src/ingest/cues.js

@@ -0,0 +1,81 @@
+// Draft a timeline from the source itself: mark key sentences in reading order,
+// highlight them one after another, pan the stage camera to section leads,
+// and count up headline numbers. Deterministic: same model in, same cues out.
+
+const STEP = 2.4;
+const HOLD = 2.2;
+const MAX_ABSTRACT = 4;
+const MAX_LEADS = 5;
+
+// Sentences that would collide with inline markup are left unmarked.
+const SAFE = /^[^[\]|`*~]{40,240}$/;
+
+function sentences(text) {
+  return String(text).split(/(?<=[.!?])\s+(?=[A-Z0-9"(])/).map(s => s.trim()).filter(Boolean);
+}
+
+function pick(text, limit) {
+  return sentences(text).filter(s => SAFE.test(s)).slice(0, limit);
+}
+
+function wrap(text, sentence, id) {
+  return text.replace(sentence, () => `[[mark:${id}|${sentence}]]`);
+}
+
+/**
+ * Return a copy of the model with marks, block ids, and a timeline.
+ * A model that already has a timeline is returned unchanged.
+ */
+export function draftCues(model) {
+  if (model.timeline) return model;
+  const next = structuredClone(model);
+  const cues = [];
+  let at = 0.6;
+  let n = 0;
+  const usedIds = new Set(next.blocks.map(block => block.id).filter(Boolean));
+  const blockId = (block, prefix) => {
+    if (block.id) return block.id;
+    let i = 1;
+    while (usedIds.has(`${prefix}-${i}`)) i++;
+    block.id = `${prefix}-${i}`;
+    usedIds.add(block.id);
+    return block.id;
+  };
+
+  if (next.meta.abstract) {
+    for (const sentence of pick(next.meta.abstract, MAX_ABSTRACT)) {
+      const id = `s${++n}`;
+      next.meta.abstract = wrap(next.meta.abstract, sentence, id);
+      cues.push({ at, dur: HOLD, do: 'highlight', target: `mark:${id}` });
+      at += STEP;
+    }
+  }
+
+  let leads = 0;
+  let afterHeading = false;
+  let moved = false;
+  for (const block of next.blocks) {
+    if (block.type === 'heading' && (block.level || 2) === 2) { afterHeading = true; continue; }
+    if (block.type === 'stats') {
+      cues.push({ at, dur: 1.6, do: 'count', target: blockId(block, 'stats') });
+      at += 1;
+      continue;
+    }
+    if (!afterHeading || block.type !== 'prose' || leads >= MAX_LEADS) continue;
+    afterHeading = false;
+    const [sentence] = pick(block.markdown, 1);
+    if (!sentence) continue;
+    const id = `s${++n}`;
+    block.markdown = wrap(block.markdown, sentence, id);
+    cues.push({ at, dur: 1.4, do: 'camera', target: blockId(block, 'lead') });
+    cues.push({ at: at + 0.5, dur: HOLD, do: 'highlight', target: `mark:${id}` });
+    at += STEP + 0.6;
+    leads++;
+    moved = true;
+  }
+  if (moved) cues.push({ at, dur: 1.6, do: 'camera', target: 'page' });
+
+  if (!cues.length) return model;
+  next.timeline = { cues };
+  return next;
+}

package/src/ingest/index.js

@@ -1,3 +1,5 @@
+import { draftCues } from './cues.js';
+import { draftDesign } from './style.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parseMarkdown, slug, wordCount } from '../model/markdown.js';
@@ -197,7 +199,7 @@ export function blockToModelBlock(block) {
  * Build a valid draft model straight from a source. This is the zero-judgment path:
  * it renders, then an agent upgrades sections, figures, and callouts.
  */
-export function draftModel(ingested, { theme = 'paper-dark', includePreamble = true, maxBlocks = 400 } = {}) {
+export function draftModel(ingested, { theme, seed, includePreamble = true, maxBlocks = 400, cues = true } = {}) {
   const { meta, sections, preamble } = ingested;
   const blocks = [];
   let abstractPending = Boolean(meta.abstract);
@@ -224,9 +226,9 @@ export function draftModel(ingested, { theme = 'paper-dark', includePreamble = t
     if (blocks.length >= maxBlocks) break;
   }
 
-  return {
+  const model = {
     schemaVersion: 1,
-    theme,
+    theme: 'paper-dark',
     meta: {
       title: meta.title,
       ...(meta.subtitle ? { subtitle: meta.subtitle } : {}),
@@ -236,6 +238,10 @@ export function draftModel(ingested, { theme = 'paper-dark', includePreamble = t
     },
     blocks: blocks.length ? blocks : [{ type: 'prose', markdown: meta.title }]
   };
+  const design = draftDesign(model, { theme, seed });
+  model.theme = design.theme;
+  if (Object.keys(design.style).length) model.meta.style = design.style;
+  return cues ? draftCues(model) : model;
 }
 
 /**

package/src/ingest/style.js

@@ -0,0 +1,57 @@
+import { THEMES } from '../model/schema.js';
+import { toHex, hslToRgb, parseHex } from '../render/style.js';
+
+// Design a doc from its own source: pick a look from the shape of the content and
+// derive an accent from the title. Deterministic, validated tokens only, always overridable.
+
+const BASES = new Set(['paper-light', 'paper-dark']);
+
+function hash(text) {
+  let h = 2166136261;
+  for (const ch of text) h = Math.imul(h ^ ch.codePointAt(0), 16777619);
+  return h >>> 0;
+}
+
+function words(blocks) {
+  return blocks.reduce((sum, b) => sum + (typeof b.markdown === 'string' ? b.markdown.split(/\s+/).length : 0), 0);
+}
+
+/** Pick a theme from the content shape. */
+export function chooseTheme(model) {
+  const body = model.blocks.filter(b => b.type !== 'heading');
+  const count = type => body.filter(b => b.type === type).length;
+  const code = count('code');
+  const tables = count('table');
+  const dense = count('table') + count('list');
+  if (code >= 3 || (body.length && code / body.length >= 0.15)) return 'blueprint';
+  if (model.meta.abstract && (tables >= 1 || model.blocks.some(b => b.type === 'heading' && /^\d/.test(b.title)))) return 'paper-light';
+  if (words(body) >= 1500 && tables === 0) return 'editorial';
+  if (body.length >= 10 && dense / body.length >= 0.4) return 'paper-dark';
+  if (body.length <= 14) return 'field-notes';
+  return 'paper-dark';
+}
+
+/** Accent seed from the title: a stable hue at a tuned saturation and lightness. */
+export function seedFromTitle(title, theme) {
+  const hue = (hash(title) % 360) / 360;
+  return toHex(hslToRgb({ h: hue, s: 0.5, l: theme === 'paper-dark' ? 0.62 : 0.38 }));
+}
+
+/**
+ * Return { theme, style } for a drafted model.
+ * `theme` and `seed` are explicit overrides; curated looks keep their own accent.
+ */
+export function draftDesign(model, { theme, seed } = {}) {
+  if (theme && !THEMES[theme]) throw new Error(`unknown theme "${theme}"`);
+  const chosen = theme || chooseTheme(model);
+  const base = THEMES[chosen].base || chosen;
+  const style = {};
+  const accent = seed && parseHex(seed) ? seed : BASES.has(chosen) ? seedFromTitle(model.meta.title, chosen) : null;
+  if (accent) style.seed = accent;
+  const body = model.blocks.length;
+  if (body <= 12) style.density = 'roomy';
+  else if (body >= 80) style.density = 'compact';
+  if (chosen === 'blueprint') style.type = 'technical';
+  if (chosen === 'editorial') style.figure = 'minimal';
+  return { theme: chosen, base, style };
+}