@bytesbybrandon/living-docs 0.2.0 → 0.3.0

package/src/ingest/index.js

@@ -1,6 +1,8 @@
+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, plainText } from '../model/markdown.js';
+import { parseMarkdown, slug, wordCount } from '../model/markdown.js';
 import { htmlToMarkdown, htmlTitle } from './html.js';
 import { textToMarkdown } from './text.js';
 
@@ -79,8 +81,8 @@ function normalizeBlocks(blocks) {
       if (block.type === 'table') {
         return {
           type: 'table',
-          columns: block.columns.map(c => plainText(c)),
-          rows: block.rows.map(row => row.map(cell => plainText(cell)))
+          columns: block.columns.map(c => c.trim()),
+          rows: block.rows.map(row => row.map(cell => cell.trim()))
         };
       }
       if (block.type === 'list') {
@@ -197,28 +199,36 @@ 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);
+  const takeBlock = block => {
+    if (abstractPending && block.type === 'paragraph' && block.text === meta.abstract) {
+      abstractPending = false;
+      return null;
+    }
+    return blockToModelBlock(block);
+  };
   if (includePreamble && preamble.length) {
     for (const block of preamble) {
-      const mapped = blockToModelBlock(block);
+      const mapped = takeBlock(block);
       if (mapped) blocks.push(mapped);
     }
   }
   for (const section of sections) {
     blocks.push({ type: 'heading', title: section.title, level: 2 });
     for (const block of section.blocks) {
-      const mapped = blockToModelBlock(block);
+      const mapped = takeBlock(block);
       if (mapped) blocks.push(mapped);
       if (blocks.length >= maxBlocks) break;
     }
     if (blocks.length >= maxBlocks) break;
   }
 
-  return {
+  const model = {
     schemaVersion: 1,
-    theme,
+    theme: 'paper-dark',
     meta: {
       title: meta.title,
       ...(meta.subtitle ? { subtitle: meta.subtitle } : {}),
@@ -228,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 };
+}

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) => {
@@ -56,7 +60,8 @@ const olRe = /^\s*\d+[.)]\s+(.*)$/;
 const hrRe = /^\s*([-*_])(?:\s*\1){2,}\s*$/;
 
 function splitRow(line) {
-  return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(cell => cell.trim());
+  const body = line.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
+  return body.split(/(?<!\\)\|/).map(cell => cell.trim().replace(/\\\|/g, '|'));
 }
 
 /**
@@ -154,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

@@ -300,7 +300,8 @@ export const STYLE = {
   seed: str('hex color that derives the accent family, e.g. #2f6f8f', { optional: true }),
   type: oneOf(['classic', 'editorial', 'technical', 'mono', 'hybrid', 'terminal'], 'curated type pairing', { optional: true }),
   density: oneOf(['compact', 'normal', 'roomy'], 'vertical rhythm', { optional: true }),
-  figure: oneOf(['outline', 'solid', 'minimal'], 'diagram and chart treatment', { optional: true })
+  figure: oneOf(['outline', 'solid', 'minimal'], 'diagram and chart treatment', { optional: true }),
+  layout: oneOf(['columns', 'single'], 'paper themes only: two columns (default) or one reading column for code and wide tables', { optional: true })
 };
 
 export const META = {
@@ -326,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.',
@@ -335,6 +361,21 @@ 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'

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 };
@@ -173,13 +173,15 @@ export function resolveStyle(theme, basePalette, style = {}, accentOverride) {
 
   const density = DENSITIES.has(style.density) ? style.density : 'normal';
   const figure = FIGURES.has(style.figure) ? style.figure : 'outline';
+  const layout = !isConsole && style.layout === 'single' ? 'single' : 'columns';
 
   return {
     palette,
     type,
     density,
     figure,
-    className: `density-${density} type-${type} fig-${figure}`
+    layout,
+    className: `density-${density} type-${type} fig-${figure} layout-${layout}`
   };
 }
 
@@ -287,5 +289,8 @@ export function styleCss(theme, palette, resolved) {
   const overrides = theme === 'hud' ? CONSOLE_OVERRIDES : PAPER_OVERRIDES;
   const density = DENSITY[theme]?.[resolved.density] || '';
   const type = TYPE[theme]?.[resolved.type] || '';
-  return `${palettes(palette)}${overrides}${density}${type}`;
+  const layout = resolved.layout === 'single'
+    ? '.columns{column-count:1;max-width:880px;margin-left:auto;margin-right:auto}.span-page{column-span:none}.footnotes{column-count:1}'
+    : '';
+  return `${palettes(palette)}${overrides}${density}${type}${layout}`;
 }