@bytesbybrandon/living-docs 0.2.1 → 0.3.1

package/src/mcp/server.js

@@ -8,6 +8,7 @@ import { renderDoc, themeList } from '../render/index.js';
 import { validateDoc, formatErrors } from '../model/validate.js';
 import { BLOCKS, THEMES, STYLE, blockFieldSummary } from '../model/schema.js';
 import { createPreviewServer } from '../server/preview.js';
+import { exportVideo, FORMATS } from '../export/video.js';
 
 const quoteCell = value => {
   const text = String(value ?? '');
@@ -33,7 +34,7 @@ function textResult(text) {
 const TOOLS = [
   {
     name: 'living_docs_themes',
-    description: 'List the three living-doc themes and what each is best for.',
+    description: 'List the living-doc themes and what each is best for.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false }
   },
   {
@@ -56,7 +57,9 @@ const TOOLS = [
         text: { type: 'string', description: 'Inline source text' },
         section: { type: 'string', description: 'Return one section: 1-based index or id' },
         draft: { type: 'boolean', description: 'Include a draft document model built from the source' },
-        theme: { type: 'string', enum: Object.keys(THEMES), description: 'Theme recorded on the draft' },
+        static: { type: 'boolean', description: 'Draft without the auto-generated timeline cues' },
+        seed: { type: 'string', description: 'Hex accent seed for the draft, overriding the one derived from the title' },
+        theme: { type: 'string', enum: Object.keys(THEMES), description: 'Theme for the draft; omit to let the source pick a look' },
         out: { type: 'string', description: 'Write the draft model JSON to this path' },
         max_chars: { type: 'number', description: 'Section text limit, default 12000' }
       },
@@ -65,7 +68,7 @@ const TOOLS = [
   },
   {
     name: 'living_docs_render',
-    description: 'Validate a document model and write a self-contained HTML doc. Accepts a model object, a model path, or a source to draft from.',
+    description: 'Validate a document model and write a self-contained HTML doc, or an mp4, webm, or gif of its timeline. Accepts a model object, a model path, or a source to draft from.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -73,7 +76,10 @@ const TOOLS = [
         model_path: { type: 'string', description: 'Path to a model JSON file' },
         source: { type: 'string', description: 'Source path or URL to ingest and draft from' },
         theme: { type: 'string', enum: Object.keys(THEMES) },
-        out: { type: 'string', description: 'Output HTML path, default docs/<title>-<theme>.html' }
+        out: { type: 'string', description: 'Output path, default docs/<title>-<theme>.<format>' },
+        format: { type: 'string', enum: ['html', ...FORMATS], description: 'html (default) or a video of the timeline; video needs playwright and ffmpeg' },
+        size: { type: 'string', description: 'Video stage size, default 1080x1350' },
+        fps: { type: 'number', description: 'Video frames per second, default 30' }
       },
       additionalProperties: false
     }
@@ -161,8 +167,7 @@ async function handle(name, args = {}) {
         toon('sections', ['index', 'id', 'title', 'words'], outline.sections.map(section => [section.index, section.id, section.title, section.words]))
       ];
       if (args.draft) {
-        const theme = args.theme || 'paper-dark';
-        const model = draftModel(ingested, { theme });
+        const model = draftModel(ingested, { theme: args.theme, seed: args.seed, cues: !args.static });
         const validation = validateDoc(model);
         if (!validation.ok) return toolError(`draft model invalid:\n${formatErrors(validation.errors)}`);
         if (args.out) {
@@ -185,10 +190,29 @@ async function handle(name, args = {}) {
       if (!model && args.source) {
         const isUrl = /^https?:\/\//i.test(args.source);
         const ingested = await ingestSource(isUrl ? { url: args.source } : { path: args.source });
-        model = draftModel(ingested, { theme: args.theme || 'paper-dark' });
+        model = draftModel(ingested, { theme: args.theme });
       }
       if (!model) return toolError('pass model, model_path, or source');
       const theme = args.theme || model.theme || 'paper-light';
+      if (args.format && args.format !== 'html') {
+        const out = args.out || path.join('docs', `${slugify(model.meta?.title || 'document')}-${theme}.${args.format}`);
+        fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+        try {
+          const video = await exportVideo(model, { theme, baseDir, format: args.format, out, size: args.size, fps: args.fps });
+          return textResult([
+            'ok: true',
+            `file: ${path.resolve(out)}`,
+            `format: ${video.format}`,
+            `size: ${video.width}x${video.height}`,
+            `frames: ${video.frames}`,
+            `seconds: ${video.duration}`,
+            `bytes: ${fs.statSync(out).size}`
+          ].join('\n'));
+        } catch (error) {
+          if (error.name === 'RenderError') return toolError(`model invalid:\n${formatErrors(error.errors)}`);
+          return toolError(`${error.message}${error.hint ? `\nhint: ${error.hint}` : ''}`);
+        }
+      }
       const result = renderDoc(model, { theme, baseDir });
       if (!result.ok) return toolError(`model invalid:\n${formatErrors(result.errors)}`);
       const out = args.out || path.join('docs', `${slugify(model.meta.title)}-${theme}.html`);
@@ -235,7 +259,7 @@ export function createServer() {
     { name: 'living-docs', version: '0.1.0' },
     {
       capabilities: { tools: {} },
-      instructions: 'Turn source documents into designed living docs. Ingest to get an outline, author a document model against the schema, then render with paper-light, paper-dark, or hud.'
+      instructions: 'Turn source documents into designed living docs. Ingest to get an outline, author a document model against the schema, then render with a theme from living_docs_themes. A draft without a theme picks a look from the source.'
     }
   );
 

package/src/model/markdown.js

@@ -1,5 +1,5 @@
 // Small markdown subset: enough to ingest prose without pulling a parser stack.
-// Inline: `code`, **bold**, *italic*, ~~strike~~, [text](url), [[n]] footnote refs.
+// Inline: `code`, **bold**, *italic*, ~~strike~~, [text](url), [[n]] footnote refs, [[mark:id|text]] cue marks.
 // Blocks: ATX headings, paragraphs, fenced code, lists, blockquotes, pipe tables, rules.
 
 const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
@@ -13,6 +13,9 @@ export function safeUrl(url) {
   return null;
 }
 
+// [[mark:id|text]] wraps a source sentence so a timeline cue can point at it.
+export const MARK_RE = /\[\[mark:([a-z][a-z0-9-]*)\|([^\]\n]+)\]\]/g;
+
 export function renderInline(markdown, { allowLinks = true } = {}) {
   const source = String(markdown ?? '');
   const tokens = [];
@@ -21,7 +24,8 @@ export function renderInline(markdown, { allowLinks = true } = {}) {
     return `\u0000${tokens.length - 1}\u0000`;
   };
 
-  let text = source.replace(/`([^`\n]+)`/g, (_, code) => stash(`<code>${escapeHtml(code)}</code>`));
+  let text = source.replace(MARK_RE, (_, id, body) => stash(`<span class="ld-mark" data-mark="${id}">${renderInline(body, { allowLinks })}</span>`));
+  text = text.replace(/`([^`\n]+)`/g, (_, code) => stash(`<code>${escapeHtml(code)}</code>`));
 
   if (allowLinks) {
     text = text.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, (_, label, url) => {
@@ -155,6 +159,7 @@ export function parseMarkdown(source) {
 
 export function plainText(markdown) {
   return String(markdown ?? '')
+    .replace(MARK_RE, '$2')
     .replace(/`([^`]+)`/g, '$1')
     .replace(/\[\[(\d+)\]\]/g, '')
     .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')

package/src/model/schema.js

@@ -327,6 +327,31 @@ export const META = {
   })
 };
 
+// Any block may carry an id so timeline cues can target it.
+export const BLOCK_ID = str('cue anchor: lowercase letters, digits, hyphens; unique in the document', { optional: true });
+
+export const CUE_ACTIONS = {
+  highlight: 'sweep a highlighter across a [[mark:id|text]] sentence or a block, then leave a faint underline',
+  focus: 'light up a block or part (diagram node, panel, scene label) and dim its siblings',
+  reveal: 'fade and rise a block or part into view at the cue time; hidden before it',
+  count: 'count the numbers inside the target up from zero',
+  type: 'type the text of the target out character by character',
+  camera: 'stage video only: scroll the frame to a block or part, or back to "page" (flat at 100% unless zoom is set)',
+  activate: 'hud scene only: glide the crosshair to a scene label (target "<sceneId>/<label>")'
+};
+
+export const TIMELINE = {
+  duration: num('total seconds; default last cue end plus 1.5', { optional: true }),
+  loop: bool('restart when the timeline ends (live page only)', { optional: true }),
+  cues: arr(obj({
+    at: num('start time in seconds'),
+    dur: num('seconds the cue runs, default 1.2', { optional: true }),
+    do: oneOf(Object.keys(CUE_ACTIONS), 'action'),
+    target: str('"mark:<id>", "<blockId>", "<blockId>/<part>" (diagram node id, panel index, scene label), or "page" for camera'),
+    zoom: num('camera only: opt-in scale, default 1 (flat)', { optional: true })
+  }, 'cue'), 'cues in any order')
+};
+
 export const THEMES = {
   'paper-light': {
     summary: 'Academic paper: serif, two justified columns, drop caps, margin stamp, print rules.',
@@ -336,25 +361,52 @@ export const THEMES = {
     summary: 'Reading notes: cream on carbon, orange accent, rules, algorithm boxes, takeaway strip.',
     best: 'paper summaries, essays, annotated readings'
   },
+  'field-notes': {
+    base: 'paper-light',
+    summary: 'Warm cream paper, olive rules, italic titles.',
+    best: 'field reports, lab notes, reading journals'
+  },
+  editorial: {
+    base: 'paper-light',
+    summary: 'Magazine masthead: oversized left-set title, heavy rules, signal red.',
+    best: 'essays, features, opinion pieces'
+  },
+  blueprint: {
+    base: 'paper-dark',
+    summary: 'Drafting-table blue with a faint grid and cyan linework.',
+    best: 'architecture notes, system designs, specs'
+  },
   hud: {
     summary: 'Telemetry console: monospaced 12-panel grid, cyan accents, graph hero, live clock.',
     best: 'repo audits, skill catalogs, system snapshots, run reports'
   }
 };
 
+function describeField(name, spec) {
+  return {
+    name,
+    kind: spec.kind,
+    required: !spec.optional,
+    desc: spec.desc,
+    ...(spec.values ? { values: spec.values } : {}),
+    ...(spec.of ? { of: spec.of.kind } : {})
+  };
+}
+
+// Nested object fields are listed under dotted paths and array items under `[]`,
+// so `diagram.nodes[].x` is discoverable without reading the source.
+function flattenFields(fields, prefix = '') {
+  return Object.entries(fields).flatMap(([name, spec]) => {
+    const path = `${prefix}${name}`;
+    const row = describeField(path, spec);
+    const inner = spec.kind === 'object' ? spec : spec.kind === 'array' && spec.of?.kind === 'object' ? spec.of : null;
+    if (!inner) return [row];
+    return [row, ...flattenFields(inner.fields, `${path}${spec.kind === 'array' ? '[].' : '.'}`)];
+  });
+}
+
 export function blockFieldSummary(type) {
   const block = BLOCKS[type];
   if (!block) return null;
-  return {
-    type,
-    summary: block.summary,
-    fields: Object.entries(block.fields).map(([name, spec]) => ({
-      name,
-      kind: spec.kind,
-      required: !spec.optional,
-      desc: spec.desc,
-      ...(spec.values ? { values: spec.values } : {}),
-      ...(spec.of ? { of: spec.of.kind } : {})
-    }))
-  };
+  return { type, summary: block.summary, fields: flattenFields(block.fields) };
 }

package/src/model/validate.js

@@ -1,4 +1,5 @@
-import { BLOCKS, META, THEMES } from './schema.js';
+import { BLOCKS, META, THEMES, TIMELINE, BLOCK_ID, CUE_ACTIONS } from './schema.js';
+import { MARK_RE } from './markdown.js';
 
 const isObj = v => v !== null && typeof v === 'object' && !Array.isArray(v);
 
@@ -55,8 +56,8 @@ export function validateDoc(doc, { defaultTheme = null } = {}) {
   }
 
   for (const name of Object.keys(doc)) {
-    if (!['schemaVersion', 'theme', 'meta', 'blocks'].includes(name)) {
-      err(name, 'unknown top-level field (allowed: schemaVersion, theme, meta, blocks)');
+    if (!['schemaVersion', 'theme', 'meta', 'blocks', 'timeline'].includes(name)) {
+      err(name, 'unknown top-level field (allowed: schemaVersion, theme, meta, blocks, timeline)');
     }
   }
   if (doc.schemaVersion !== undefined && doc.schemaVersion !== 1) err('schemaVersion', 'must be 1');
@@ -69,6 +70,7 @@ export function validateDoc(doc, { defaultTheme = null } = {}) {
     return { ok: false, errors, theme: doc.theme || defaultTheme };
   }
 
+  const ids = new Set();
   doc.blocks.forEach((block, i) => {
     const path = `blocks[${i}]`;
     if (!isObj(block)) { err(path, 'must be an object with a `type`'); return; }
@@ -77,7 +79,7 @@ export function validateDoc(doc, { defaultTheme = null } = {}) {
     const def = BLOCKS[type];
     if (!def) { err(`${path}.type`, `unknown block type "${type}" (one of: ${Object.keys(BLOCKS).join(', ')})`); return; }
     for (const name of Object.keys(block)) {
-      if (name !== 'type' && !(name in def.fields)) {
+      if (name !== 'type' && name !== 'id' && !(name in def.fields)) {
         err(`${path}.${name}`, `unknown field for ${type} (allowed: ${Object.keys(def.fields).join(', ')})`);
       }
     }
@@ -85,6 +87,12 @@ export function validateDoc(doc, { defaultTheme = null } = {}) {
       checkSpec(field, block[name], `${path}.${name}`, err);
     }
     if (def.check) def.check(block, path, err);
+    checkSpec(BLOCK_ID, block.id, `${path}.id`, err);
+    if (typeof block.id === 'string') {
+      if (!ID_RE.test(block.id)) err(`${path}.id`, 'must match ^[a-z][a-z0-9-]*$');
+      else if (ids.has(block.id)) err(`${path}.id`, `duplicate block id "${block.id}"`);
+      ids.add(block.id);
+    }
     if (type === 'panels' && Array.isArray(block.items)) {
       block.items.forEach((item, j) => {
         const wanted = String(j + 1).padStart(2, '0');
@@ -95,9 +103,79 @@ export function validateDoc(doc, { defaultTheme = null } = {}) {
     }
   });
 
+  if (doc.timeline !== undefined) checkTimeline(doc, err);
+
   return { ok: errors.length === 0, errors, theme: doc.theme || defaultTheme };
 }
 
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+
+// Parts a cue can address inside a block: diagram nodes, panels, scene labels.
+function blockParts(block) {
+  if (block.type === 'figure' && block.spec === 'diagram') return (block.diagram?.nodes || []).map(node => node.id);
+  if (block.type === 'panels') return (block.items || []).map((item, i) => item.index || String(i + 1).padStart(2, '0'));
+  if (block.type === 'graphScene') return (block.graph?.labels || []).slice(0, 9); // the scene draws the first 9
+  return [];
+}
+
+function collectMarks(value, path, marks, err) {
+  if (typeof value === 'string') {
+    for (const match of value.matchAll(MARK_RE)) {
+      if (marks.has(match[1])) err(path, `duplicate mark id "${match[1]}"`);
+      marks.add(match[1]);
+    }
+  } else if (Array.isArray(value)) {
+    value.forEach((item, i) => collectMarks(item, `${path}[${i}]`, marks, err));
+  } else if (isObj(value)) {
+    for (const [key, item] of Object.entries(value)) collectMarks(item, `${path}.${key}`, marks, err);
+  }
+}
+
+function checkTimeline(doc, err) {
+  checkSpec({ kind: 'object', fields: TIMELINE }, doc.timeline, 'timeline', err);
+  if (!isObj(doc.timeline) || !Array.isArray(doc.timeline.cues)) return;
+
+  const blocks = new Map();
+  for (const block of doc.blocks) {
+    if (isObj(block) && typeof block.id === 'string' && !blocks.has(block.id)) blocks.set(block.id, block);
+  }
+  const marks = new Set();
+  collectMarks(doc.meta, 'meta', marks, err);
+  collectMarks(doc.blocks, 'blocks', marks, err);
+
+  doc.timeline.cues.forEach((cue, i) => {
+    const path = `timeline.cues[${i}]`;
+    if (!isObj(cue) || typeof cue.target !== 'string' || !CUE_ACTIONS[cue.do]) return;
+    if (typeof cue.at === 'number' && cue.at < 0) err(`${path}.at`, 'must be 0 or more');
+    if (typeof cue.dur === 'number' && cue.dur <= 0) err(`${path}.dur`, 'must be more than 0');
+    if (cue.zoom !== undefined && cue.do !== 'camera') err(`${path}.zoom`, 'only camera cues take zoom');
+    const target = cue.target;
+    if (target === 'page') {
+      if (cue.do !== 'camera') err(`${path}.target`, '"page" is only a camera target');
+      return;
+    }
+    if (target.startsWith('mark:')) {
+      const id = target.slice(5);
+      if (!marks.has(id)) err(`${path}.target`, `unknown mark "${id}" (add [[mark:${id}|text]] to a prose string)`);
+      else if (cue.do === 'camera' || cue.do === 'activate') err(`${path}.do`, `${cue.do} cannot target a mark`);
+      return;
+    }
+    const [blockId, part, extra] = target.split('/');
+    const block = blocks.get(blockId);
+    if (!block || extra !== undefined) {
+      err(`${path}.target`, `unknown block id "${blockId}" (known: ${[...blocks.keys()].join(', ') || 'none'})`);
+      return;
+    }
+    if (part !== undefined) {
+      const parts = blockParts(block);
+      if (!parts.includes(part)) err(`${path}.target`, `unknown part "${part}" in ${blockId} (known: ${parts.join(', ') || 'none'})`);
+    }
+    if (cue.do === 'activate' && (block.type !== 'graphScene' || part === undefined)) {
+      err(`${path}.target`, 'activate needs "<graphScene id>/<label>"');
+    }
+  });
+}
+
 export function formatErrors(errors, limit = 25) {
   const shown = errors.slice(0, limit);
   const lines = shown.map(e => `${e.path}: ${e.message}`);

package/src/render/blocks.js

@@ -186,7 +186,7 @@ function renderGraphScene(block, ctx) {
   const left = (active.x / payload.width) * 100;
   const top = (active.y / payload.height) * 100;
   const cardRows = (card?.rows || []).map(row => `<div class="sc-row"><span>${escapeHtml(row.k)}</span><b>${escapeHtml(row.v)}</b></div>`).join('');
-  const labels = payload.labels.map(label => `<span class="scene-label" style="left:${(label.x / payload.width) * 100}%;top:${(label.y / payload.height) * 100}%">${escapeHtml(label.text)}</span>`).join('');
+  const labels = payload.labels.map(label => `<span class="scene-label" data-part="${escapeHtml(label.text)}" style="left:${(label.x / payload.width) * 100}%;top:${(label.y / payload.height) * 100}%">${escapeHtml(label.text)}</span>`).join('');
   const status = block.status
     ? `<div class="scene-status"><span class="sc-seq">${escapeHtml(block.status.seq)}</span> <span class="sc-kind">${escapeHtml(block.status.kind)}</span> <span class="sc-sep">::</span> <span class="sc-text">${escapeHtml(block.status.text)}</span> <span class="sc-tail">${escapeHtml(block.status.tail)}</span></div>`
     : '';
@@ -209,8 +209,8 @@ function renderGraphScene(block, ctx) {
       <canvas class="scene-canvas" aria-hidden="true"></canvas>
       <div class="scene-crosshair" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%"></div>
       ${labels}
-      <span class="scene-active-label" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%">${escapeHtml(graph.active?.id || '')}</span>
-      ${graph.active?.badge ? `<span class="scene-badge" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%">${escapeHtml(graph.active.badge)}</span>` : ''}
+      <span class="scene-active-label${left > 55 ? ' to-left' : ''}" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%">${escapeHtml(graph.active?.id || '')}</span>
+      ${graph.active?.badge ? `<span class="scene-badge${left > 55 ? ' to-left' : ''}" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%">${escapeHtml(graph.active.badge)}</span>` : ''}
       ${card ? `<div class="scene-card" style="left:${left.toFixed(2)}%;top:${top.toFixed(2)}%">
         <div class="sc-card-title">${escapeHtml(card.title)}</div>
         ${cardRows}
@@ -305,7 +305,7 @@ function renderPanels(block, ctx) {
   const columns = Math.max(1, Math.min(6, block.columns || 4));
   const items = block.items.map((panel, index) => {
     const tag = panel.tag ? `<span class="panel-tag">${escapeHtml(panel.tag)}</span>` : '';
-    return `<article class="panel panel-${panel.kind}"${panel.span ? ` style="grid-column: span ${Math.min(columns, panel.span)}"` : ''}>
+    return `<article class="panel panel-${panel.kind}" data-part="${escapeHtml(panel.index || String(index + 1).padStart(2, '0'))}"${panel.span ? ` style="grid-column: span ${Math.min(columns, panel.span)}"` : ''}>
       <header class="panel-head"><span class="panel-index">${escapeHtml(panel.index || String(index + 1).padStart(2, '0'))}</span><span class="panel-title">${escapeHtml(panel.title || '')}</span>${tag}</header>
       <div class="panel-body">${renderPanelBody(panel.kind, panel.data || {}, ctx)}</div>
     </article>`;
@@ -354,8 +354,12 @@ export function renderBlock(block, ctx) {
   }
 }
 
+// A block id becomes a data-cue anchor on the block's first element.
 export function renderBlocks(blocks, ctx) {
-  return blocks.map(block => renderBlock(block, ctx)).join('\n');
+  return blocks.map(block => {
+    const html = renderBlock(block, ctx);
+    return block.id ? html.replace(/^(\s*<[a-z0-9]+)/i, `$1 data-cue="${escapeHtml(block.id)}"`) : html;
+  }).join('\n');
 }
 
 export function documentStats(model, html) {

package/src/render/index.js

@@ -2,14 +2,17 @@ import { validateDoc } from '../model/validate.js';
 import { createContext, renderBlocks, documentStats } from './blocks.js';
 import { THEMES as THEME_INFO } from '../model/schema.js';
 import { resolveStyle } from './style.js';
+import { timelineAssets } from './timeline.js';
 import * as paperLight from './themes/paper-light.js';
 import * as paperDark from './themes/paper-dark.js';
 import * as hud from './themes/hud.js';
+import { VARIANTS } from './themes/variants.js';
 
 export const THEMES = {
   'paper-light': paperLight,
   'paper-dark': paperDark,
-  hud
+  hud,
+  ...VARIANTS
 };
 
 export class RenderError extends Error {
@@ -33,24 +36,32 @@ export function themeList() {
  * Render a document model to a complete, self-contained HTML string.
  * @returns {{ok: boolean, html?: string, stats?: object, warnings?: string[], errors?: object[], theme: string}}
  */
-export function renderDoc(model, { theme, baseDir, accent } = {}) {
+export function renderDoc(model, { theme, baseDir, accent, stage = false } = {}) {
   const chosen = theme || model?.theme || 'paper-light';
   const themeModule = THEMES[chosen];
   if (!themeModule) {
     throw new RenderError(`Unknown theme "${chosen}". Available: ${Object.keys(THEMES).join(', ')}`);
   }
 
+  const base = THEME_INFO[chosen]?.base || chosen;
   const validation = validateDoc(model, { defaultTheme: chosen });
   if (!validation.ok) {
     return { ok: false, theme: chosen, errors: validation.errors, warnings: [] };
   }
 
-  const styled = resolveStyle(chosen, themeModule.palette, model.meta.style || {}, accent || model.meta.accent);
+  const styled = resolveStyle(base, themeModule.palette, model.meta.style || {}, accent || model.meta.accent);
   const palette = styled.palette;
-  const ctx = createContext({ theme: chosen, palette, baseDir, model });
+  const ctx = createContext({ theme: base, palette, baseDir, model });
   ctx.style = styled;
   const blocksHtml = renderBlocks(model.blocks, ctx);
-  const html = themeModule.document({ model, ctx, palette, blocksHtml, style: styled });
+  let html = themeModule.document({ model, ctx, palette, blocksHtml, style: styled });
+  if (base !== chosen) html = html.replace(`class="theme-${base} `, () => `class="theme-${base} theme-${chosen} `);
+  // Timeline runtime only ships when cues exist or a video stage is rendered, so static docs keep their bytes.
+  if (model.timeline || stage) {
+    html = html
+      .replace('<html lang="en">', `<html lang="en" class="ld-timed${stage ? ' ld-stage' : ''}">`)
+      .replace('</body>', () => `${timelineAssets(model)}</body>`);
+  }
   const stats = documentStats(model, html);
 
   return {

package/src/render/style.js

@@ -86,7 +86,7 @@ function rgbToHsl({ r, g, b }) {
   return { h: hue, s: saturation, l: lightness };
 }
 
-function hslToRgb({ h, s, l }) {
+export function hslToRgb({ h, s, l }) {
   if (s === 0) {
     const value = l * 255;
     return { r: value, g: value, b: value };

package/src/render/svg.js

@@ -38,23 +38,19 @@ function anchor(node, px, py) {
   return { x: cx + dx * s, y: cy + dy * s };
 }
 
-function iconMarkup(node, palette) {
-  const cx = node.x + node.w / 2;
-  const cy = node.y + node.h / 2;
+// Icons sit in a 13-unit band at the top of the node's text block, so they never touch the label.
+function iconMarkup(node, palette, top) {
+  const at = `transform="translate(${round(node.x + node.w / 2)} ${round(top)})"`;
   const stroke = palette.accent;
   switch (node.icon) {
     case 'file':
-      return `<g class="d-icon" fill="none" stroke="${stroke}" stroke-width="1.2">
-        <path d="M ${cx - 7} ${cy - 18} h 10 l 4 4 v 13 h -14 z"/><path d="M ${cx + 3} ${cy - 18} v 4 h 4"/>
-      </g>`;
+      return `<g class="d-icon" ${at} fill="none" stroke="${stroke}" stroke-width="1.2"><path d="M -6 0 h 8 l 4 4 v 9 h -12 z"/><path d="M 2 0 v 4 h 4"/></g>`;
     case 'clock':
-      return `<g class="d-icon" fill="none" stroke="${stroke}" stroke-width="1.2">
-        <circle cx="${cx}" cy="${cy - 10}" r="7"/><path d="M ${cx} ${cy - 14} v 4 l 3 2"/>
-      </g>`;
+      return `<g class="d-icon" ${at} fill="none" stroke="${stroke}" stroke-width="1.2"><circle cx="0" cy="6.5" r="6.3"/><path d="M 0 3 v 3.5 l 2.6 1.8"/></g>`;
     case 'star':
-      return `<path class="d-icon" d="M ${cx} ${cy - 20} l 2.4 5.6 6 .7 -4.4 4.2 1.2 5.9 -5.2 -2.9 -5.2 2.9 1.2 -5.9 -4.4 -4.2 6 -.7 z" fill="${stroke}" stroke="none"/>`;
+      return `<path class="d-icon" ${at} d="M 0 0 l 2 4.6 5 .6 -3.7 3.4 1 4.9 -4.3 -2.4 -4.3 2.4 1 -4.9 -3.7 -3.4 5 -.6 z" fill="${stroke}" stroke="none"/>`;
     case 'badge':
-      return `<g class="d-icon"><rect x="${cx - 9}" y="${cy - 16}" width="18" height="11" rx="1.5" fill="none" stroke="${stroke}" stroke-width="1.1"/><path d="M ${cx - 5} ${cy - 10.5} h 10" stroke="${stroke}" stroke-width="1.1"/></g>`;
+      return `<g class="d-icon" ${at} fill="none" stroke="${stroke}" stroke-width="1.1"><rect x="-9" y="1" width="18" height="11" rx="1.5"/><path d="M -5 6.5 h 10"/></g>`;
     default:
       return '';
   }
@@ -113,7 +109,7 @@ export function diagramSvg(spec, palette, { figure = 'outline', motion = 'none'
     if (edge.route === 'elbow' || (edge.style === 'dashed' && Math.abs(toCenter.y - fromCenter.y) > 40)) {
       const midX = round((start.x + end.x) / 2);
       d = `M ${round(start.x)} ${round(start.y)} H ${midX} V ${round(end.y)} H ${round(end.x)}`;
-      labelPoint = { x: midX, y: (start.y + end.y) / 2, anchor: 'middle' };
+      labelPoint = { x: midX + 8, y: (start.y + end.y) / 2 + 4, anchor: 'start' }; // beside the vertical run, not across it
     } else {
       d = `M ${round(start.x)} ${round(start.y)} L ${round(end.x)} ${round(end.y)}`;
       labelPoint = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2, anchor: 'middle' };
@@ -150,18 +146,19 @@ export function diagramSvg(spec, palette, { figure = 'outline', motion = 'none'
     const strokeWidth = node.kind === 'accent' ? 1.5 : minimal ? 0.8 : solid ? 1.3 : 1;
     const dash = node.kind === 'dashed' ? ' stroke-dasharray="5 4"' : '';
     const opacity = node.kind === 'dashed' ? ' stroke-opacity="0.75"' : '';
-    const iconSpace = node.icon && node.icon !== 'none' ? 14 : 0;
+    const iconSpace = node.icon && node.icon !== 'none' ? 18 : 0;
     const lines = wrapLabel(node.label, Math.max(8, Math.floor((node.w - 16) / 6.5)), 3);
     const lineHeight = 15;
     const blockHeight = lines.length * lineHeight + (node.sub ? 13 : 0) + iconSpace;
-    let textY = node.y + (node.h - blockHeight) / 2 + lineHeight - 4 + iconSpace;
+    const blockTop = node.y + (node.h - blockHeight) / 2;
+    let textY = blockTop + lineHeight - 4 + iconSpace;
 
-    nodeMarkup.push(`<g class="d-node d-node-${node.kind}" style="--i:${nodeIndex++}">`);
+    nodeMarkup.push(`<g class="d-node d-node-${node.kind}" data-part="${escapeHtml(node.id)}" style="--i:${nodeIndex++}">`);
     if (node.kind === 'stack') {
       nodeMarkup.push(`<rect x="${node.x + 5}" y="${node.y + 5}" width="${node.w}" height="${node.h}" rx="2" fill="${palette.surface}" stroke="${palette.muted}" stroke-opacity="0.5"/>`);
     }
     nodeMarkup.push(`<rect x="${node.x}" y="${node.y}" width="${node.w}" height="${node.h}" rx="2" fill="${fill}" stroke="${stroke}" stroke-width="${strokeWidth}"${dash}${opacity}/>`);
-    nodeMarkup.push(iconMarkup(node, palette));
+    nodeMarkup.push(iconMarkup(node, palette, blockTop));
     for (const line of lines) {
       nodeMarkup.push(`<text x="${round(node.x + node.w / 2)}" y="${round(textY)}" text-anchor="middle" font-size="13" fill="${palette.ink}" font-weight="${node.kind === 'accent' ? 600 : 400}">${escapeHtml(line)}</text>`);
       textY += lineHeight;

package/src/render/themes/hud.js

@@ -50,7 +50,9 @@ body{margin:0;background:#020409;color:var(--ink);font-family:var(--mono);font-s
 .scene-crosshair::before{content:"";position:absolute;left:50%;top:-80px;bottom:-80px;border-left:1px solid rgba(94,200,229,.14)}
 .scene-crosshair::after{content:"";position:absolute;top:50%;left:-80px;right:-80px;border-top:1px solid rgba(94,200,229,.14)}
 .scene-active-label{position:absolute;transform:translate(16px,-150%);padding:3px 9px;border:1px solid #3a7188;background:rgba(4,10,16,.86);font-size:11.5px;letter-spacing:.05em;color:#e6f7ff;white-space:nowrap}
+.scene-active-label.to-left{transform:translate(calc(-100% - 16px),-150%)}
 .scene-badge{position:absolute;transform:translate(16px,-50%);padding:2px 7px;border:1px solid #2a5568;background:#06222e;font-size:9px;letter-spacing:.14em;color:#8fd8ee}
+.scene-badge.to-left{transform:translate(calc(-100% - 16px),-50%)}
 .scene-card{position:absolute;transform:translate(26px,26px);min-width:236px;max-width:310px;border:1px solid #2a5568;background:rgba(4,12,19,.94);padding:12px 13px;font-size:10px;color:#9fc0cf;box-shadow:0 0 34px rgba(0,0,0,.65)}
 .sc-card-title{font-size:13.5px;color:#e6f7ff;margin-bottom:8px;letter-spacing:.03em}
 .sc-row{display:flex;justify-content:space-between;gap:14px;padding:2px 0;border-bottom:1px solid #0e1f2a}
@@ -217,7 +219,7 @@ tbody td{padding:5px 6px;color:#b7d4e1;border-bottom:1px solid #0a1822}
   .hud-head{flex-direction:column;gap:8px}
   .live{font-size:8px}
   .scene-stage{min-height:240px}
-  .scene-card{left:12px!important;top:auto!important;bottom:10px;transform:none;min-width:0;max-width:none;width:calc(100% - 24px)}
+  .scene-card{display:none}
   .scene-label{font-size:8px}
   .sc-tail{margin-left:0}
   .footnotes{column-count:1}
@@ -251,11 +253,14 @@ function head(model) {
 
 const RUNTIME = `
 (function(){
+  // With a timeline (ld-timed) the page clock drives everything through window.__ldHooks.
+  var timed = document.documentElement.classList.contains('ld-timed');
+  var hooks = window.__ldHooks = window.__ldHooks || [];
   var clocks = document.querySelectorAll('[data-clock]');
   var started = Date.now();
   function pad(n){ return String(n).padStart(2,'0'); }
-  function tick(){
-    var ms = Date.now() - started;
+  function tick(at){
+    var ms = timed ? at : Date.now() - started;
     var cs = Math.floor(ms / 10) % 100;
     var s = Math.floor(ms / 1000) % 60;
     var m = Math.floor(ms / 60000) % 60;
@@ -263,8 +268,8 @@ const RUNTIME = `
     var text = pad(h) + ':' + pad(m) + ':' + pad(s) + '.' + pad(cs);
     for (var i = 0; i < clocks.length; i++) clocks[i].textContent = text;
   }
-  tick();
-  setInterval(tick, 90);
+  if (timed) hooks.push(tick);
+  else { tick(); setInterval(tick, 90); }
 
   var reduce = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
   var scenes = document.querySelectorAll('.scene');
@@ -321,8 +326,10 @@ const RUNTIME = `
       }
 
       var active = nodes[data.active];
-      if (active) {
-        var ax = active.x * kx, ay = active.y * ky;
+      var moved = scene.__ldActive;
+      if (active || moved) {
+        var ax = moved ? moved.x / 100 * width : active.x * kx;
+        var ay = moved ? moved.y / 100 * height : active.y * ky;
         var pulse = reduce ? 1 : 0.5 + 0.5 * Math.sin(phase * 0.0014);
         ctx.beginPath();
         ctx.fillStyle = 'rgba(220,248,255,0.95)';
@@ -339,6 +346,10 @@ const RUNTIME = `
       }
     }
 
+    if (timed) {
+      hooks.push(draw);
+      return;
+    }
     if (reduce) {
       draw(0);
       return;

package/src/render/themes/variants.js

@@ -0,0 +1,43 @@
+import * as paperLight from './paper-light.js';
+import * as paperDark from './paper-dark.js';
+
+// A curated look is a base theme plus its own palette and a short CSS layer.
+// Blocks, figures, and the timeline all come from the base, so every look stays flat and printable.
+function variant(base, palette, css) {
+  return {
+    ...base,
+    palette: { ...base.palette, ...palette },
+    document: args => base.document(args).replace('</head>', () => `<style>${css}</style>\n</head>`)
+  };
+}
+
+export const VARIANTS = {
+  'field-notes': variant(paperLight, {
+    bg: '#f7f1e1', surface: '#f1e9d3', ink: '#25261c', muted: '#5c5a46', hair: '#d9cfb2', rule: '#33401f',
+    accent: '#486a1f', accentSoft: '#e5ebcf', box: '#f0e8d1', boxStroke: '#8f8a6a'
+  }, `
+html,body{background:#e6dcc0}
+.sheet{border-left:7px solid var(--ld-accent)}
+.doc-title{font-style:italic;font-weight:600}
+h2.sec-head{border-color:var(--ld-accent)}
+.abstract{border-color:var(--ld-accent)}`),
+
+  editorial: variant(paperLight, {
+    bg: '#fbf8f2', surface: '#f4efe5', ink: '#131313', muted: '#555048', hair: '#dcd5c8', rule: '#131313',
+    accent: '#b3122b', accentSoft: '#f7e0e1', box: '#f4efe5', boxStroke: '#8c857a'
+  }, `
+html,body{background:#ece7dd}
+.masthead{text-align:left;max-width:none;border-bottom:5px solid var(--ld-ink);padding-bottom:20px;margin-bottom:26px}
+.doc-title{font-size:clamp(38px,7vw,76px);line-height:.98;letter-spacing:-.034em}
+.doc-subtitle{margin-left:0;font-style:italic}
+h2.sec-head{border-top-width:3px}`),
+
+  blueprint: variant(paperDark, {
+    bg: '#0b1f3a', surface: '#102a4c', ink: '#e6f0ff', muted: '#9db8dd', hair: '#254a7c', rule: '#5b8fd0',
+    accent: '#7fe0ff', accentSoft: '#10335a', box: '#0f2745', boxStroke: '#4a79b5'
+  }, `
+html,body{background:#081729}
+body{background-image:linear-gradient(rgba(127,224,255,.06) 1px,transparent 1px),linear-gradient(90deg,rgba(127,224,255,.06) 1px,transparent 1px);background-size:32px 32px}
+.doc-title{letter-spacing:.01em}
+@media print{body{background-image:none}}`)
+};