@bytesbybrandon/living-docs 0.1.1 → 0.2.1

package/README.md

@@ -12,6 +12,7 @@ Ships an AXI CLI and a stdio MCP server over the same core.
 
 * **Three themes:** `paper-light` for papers and reports, `paper-dark` for reading notes and essays, `hud` for repo audits and system snapshots.
 * **Generated visuals:** diagrams and charts render as inline SVG from a compact spec, and the console hero uses a seeded graph layout.
+* **Figure motion:** `draw`, `reveal`, and `steps` animate a generated figure with scoped CSS, then freeze for print and reduced motion. See [Document model](docs/guide/document-model.md).
 * **Per-source style tokens:** palette, seed color, type pairing, density, and figure treatment adapt a theme without arbitrary CSS. See [Style tokens](docs/guide/style-tokens.md).
 * **One self-contained file:** inline CSS, inline SVG, no network assets, and print rules. See [Guarantees](docs/guide/guarantees.md).
 * **Engine and interfaces:** the same core powers the CLI and the MCP server.
@@ -95,6 +96,7 @@ Detailed references:
 * [Guarantees](docs/guide/guarantees.md)
 * [Architecture](ARCHITECTURE.md)
 * [Decisions](docs/decisions/0001-one-model-three-themes.md)
+* [Website](https://bytesbybrandon.github.io/living-docs/), built from this repository with `npm run site`
 
 ---
 
@@ -121,7 +123,8 @@ living-docs/
     render/            block renderers, SVG generators, style resolution, themes
     server/            local preview server
   samples/             sample models and one Markdown source
-  scripts/             sample build script
+  scripts/             sample and website build scripts
+  site/                landing page template and stylesheet for the website
   tests/               Node test runner suites
   docs/
     decisions/         architecture decision records

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbybrandon/living-docs",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Turn a source document into a designed, self-contained living doc: academic paper, dark reading notes, or telemetry console. Ships an AXI CLI and an MCP server.",
   "type": "module",
   "license": "MIT",
@@ -47,8 +47,9 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test tests/cli.test.js tests/ingest.test.js tests/mcp.test.js tests/render.test.js tests/style.test.js tests/validate.test.js",
-    "samples": "node scripts/build-samples.js"
+    "test": "node --test tests/cli.test.js tests/ingest.test.js tests/mcp.test.js tests/motion.test.js tests/render.test.js tests/site.test.js tests/style.test.js tests/validate.test.js",
+    "samples": "node scripts/build-samples.js",
+    "site": "node scripts/build-site.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",

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

@@ -42,6 +42,7 @@
       "type": "figure",
       "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",
       "span": "page",
       "diagram": {
         "width": 1000,
@@ -111,6 +112,7 @@
       "type": "figure",
       "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",
       "chart": {
         "kind": "scatter",
         "height": 380,

package/samples/harness-engineering.json

@@ -41,6 +41,7 @@
       "type": "figure",
       "caption": "An agent is a model plus a harness of seven subsystems. The harness owns everything outside the weights.",
       "spec": "diagram",
+      "motion": "draw",
       "diagram": {
         "width": 1000,
         "height": 440,
@@ -118,6 +119,7 @@
       "type": "figure",
       "caption": "Extensibility standards across eleven coding harnesses. Counts include partial support, greyed in the paper's original figure.",
       "spec": "chart",
+      "motion": "steps",
       "chart": {
         "kind": "bar",
         "height": 340,
@@ -163,6 +165,7 @@
       "type": "figure",
       "caption": "Convergence becomes imitation: Codex reads Claude Code's hook vocabulary while OpenHands reads its plugin format.",
       "spec": "diagram",
+      "motion": "draw",
       "diagram": {
         "width": 1000,
         "height": 300,

package/src/ingest/index.js

@@ -1,6 +1,6 @@
 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 +79,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') {
@@ -200,16 +200,24 @@ export function blockToModelBlock(block) {
 export function draftModel(ingested, { theme = 'paper-dark', includePreamble = true, maxBlocks = 400 } = {}) {
   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;
     }

package/src/model/markdown.js

@@ -56,7 +56,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, '|'));
 }
 
 /**

package/src/model/schema.js

@@ -157,6 +157,7 @@ export const BLOCKS = {
       spec: oneOf(['diagram', 'chart'], 'which generator to use'),
       diagram: { ...diagramSpec, optional: true },
       chart: { ...chartSpec, optional: true },
+      motion: oneOf(['none', 'draw', 'reveal', 'steps'], 'static CSS animation for the figure; print and reduced motion stay static', { optional: true }),
       span: oneOf(['column', 'page'], 'column width or full page', { optional: true })
     },
     check(value, path, err) {
@@ -299,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 = {

package/src/render/blocks.js

@@ -17,19 +17,53 @@ export function createContext({ theme, palette, baseDir, model }) {
 
 const spanClass = block => (block.span === 'page' ? ' span-page' : '');
 
+function motionCss(id, motion) {
+  if (!motion || motion === 'none') return '';
+  const scope = `#${id}`;
+  const reset = `
+@media (prefers-reduced-motion: reduce){
+  ${scope} *{animation:none !important;opacity:1 !important;transform:none !important;stroke-dashoffset:0 !important}
+}
+@media print{
+  ${scope} *{animation:none !important;opacity:1 !important;transform:none !important;stroke-dashoffset:0 !important}
+}`;
+  const keyframes = `@keyframes ld-draw{to{stroke-dashoffset:0}}@keyframes ld-fade{to{opacity:1}}@keyframes ld-grow{to{transform:scaleY(1)}}`;
+  if (motion === 'draw') {
+    return `<style>${keyframes}
+${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 1000ms ease-out forwards}
+${scope} .d-node,${scope} .ch-point,${scope} .ch-bar,${scope} .ch-legend,${scope} .d-edge-labels{opacity:0.15;animation:ld-fade 420ms ease-out forwards;animation-delay:calc(var(--i,0)*70ms + 420ms)}
+${scope} .ch-bar{transform-box:fill-box;transform-origin:bottom;transform:scaleY(0);animation-name:ld-grow,ld-fade;animation-duration:500ms,300ms;animation-delay:calc(var(--i,0)*50ms + 300ms)}
+${reset}</style>`;
+  }
+  if (motion === 'steps') {
+    return `<style>${keyframes}
+${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 700ms ease-out forwards;animation-delay:calc(var(--i,0)*140ms)}
+${scope} .d-node,${scope} .ch-point,${scope} .ch-legend,${scope} .d-edge-labels{opacity:0.15;animation:ld-fade 360ms ease-out forwards;animation-delay:calc(var(--i,0)*140ms + 120ms)}
+${scope} .ch-bar{transform-box:fill-box;transform-origin:bottom;transform:scaleY(0);opacity:0.15;animation:ld-grow 420ms ease-out forwards,ld-fade 200ms ease-out forwards;animation-delay:calc(var(--i,0)*120ms),calc(var(--i,0)*120ms)}
+${reset}</style>`;
+  }
+  return `<style>${keyframes}
+${scope} .d-node,${scope} .ch-point,${scope} .ch-bar,${scope} .ch-legend,${scope} .d-edge-labels{opacity:0.15;animation:ld-fade 420ms ease-out forwards;animation-delay:calc(var(--i,0)*70ms)}
+${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 800ms ease-out forwards}
+${reset}</style>`;
+}
+
 function renderFigure(block, ctx) {
   const number = ++ctx.counters.figure;
   const span = block.span || (ctx.theme === 'hud' ? 'column' : 'page');
+  const motion = block.motion || 'none';
   let svg = '';
   try {
     svg = block.spec === 'diagram'
-      ? diagramSvg(block.diagram, ctx.palette, { figure: ctx.style?.figure })
-      : chartSvg(block.chart, ctx.palette, { figure: ctx.style?.figure });
+      ? diagramSvg(block.diagram, ctx.palette, { figure: ctx.style?.figure, motion })
+      : chartSvg(block.chart, ctx.palette, { figure: ctx.style?.figure, motion });
   } catch (error) {
     ctx.warnings.push(`figure ${number}: ${error.message}`);
     svg = `<div class="fig-error">Figure unavailable: ${escapeHtml(error.message)}</div>`;
   }
+  const motionStyle = motionCss(`fig-${number}`, motion);
   return `<figure class="fig${span === 'page' ? ' span-page' : ''}" id="fig-${number}">
+    ${motionStyle}
     <div class="fig-frame">${svg}</div>
     <figcaption><span class="fig-num">Fig. ${number}.</span> ${renderInline(block.caption)}</figcaption>
   </figure>`;

package/src/render/style.js

@@ -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}`;
 }

package/src/render/svg.js

@@ -60,7 +60,7 @@ function iconMarkup(node, palette) {
   }
 }
 
-export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
+export function diagramSvg(spec, palette, { figure = 'outline', motion = 'none' } = {}) {
   const W = spec.width || 1000;
   const H = spec.height || 520;
   const nodes = (spec.nodes || []).map(node => ({ w: 150, h: 56, kind: 'box', icon: 'none', ...node }));
@@ -126,7 +126,8 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
       }
     }
     const markerEnd = edge.style === 'line' ? '' : ` marker-end="url(#${marker})"`;
-    edges.push(`<path d="${d}" fill="none" stroke="${stroke}" stroke-width="1.1"${dash}${markerEnd}/>`);
+    const animLine = motion !== 'none' && edge.style !== 'dashed' ? ' class="ld-line" pathLength="1"' : '';
+    edges.push(`<path${animLine} d="${d}" fill="none" stroke="${stroke}" stroke-width="1.1"${dash}${markerEnd}/>`);
     if (edge.label) {
       edgeLabels.push(`<text x="${round(labelPoint.x)}" y="${round(labelPoint.y)}" text-anchor="${labelPoint.anchor}" font-size="10.5" fill="${palette.ink}" stroke="${palette.bg}" stroke-width="4" paint-order="stroke" stroke-linejoin="round">${escapeHtml(edge.label)}</text>`);
     }
@@ -135,6 +136,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
 
   // Nodes.
   const nodeMarkup = [];
+  let nodeIndex = 0;
   for (const node of nodes) {
     const minimal = figure === 'minimal';
     const solid = figure === 'solid';
@@ -154,7 +156,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
     const blockHeight = lines.length * lineHeight + (node.sub ? 13 : 0) + iconSpace;
     let textY = node.y + (node.h - blockHeight) / 2 + lineHeight - 4 + iconSpace;
 
-    nodeMarkup.push(`<g class="d-node d-node-${node.kind}">`);
+    nodeMarkup.push(`<g class="d-node d-node-${node.kind}" 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"/>`);
     }
@@ -170,7 +172,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
     nodeMarkup.push('</g>');
   }
   parts.push(`<g class="d-nodes">${nodeMarkup.join('')}</g>`);
-  if (edgeLabels.length) parts.push(`<g class="d-edge-labels">${edgeLabels.join('')}</g>`);
+  if (edgeLabels.length) parts.push(`<g class="d-edge-labels" style="--i:${nodes.length}">${edgeLabels.join('')}</g>`);
 
   if (spec.notes?.length) {
     const notes = spec.notes.map((note, i) =>
@@ -201,7 +203,7 @@ function seriesPoints(series) {
   return (series.values || []).map((value, i) => ({ x: i + 1, y: value, label: series.labels?.[i] }));
 }
 
-export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
+export function chartSvg(spec, palette, { figure = 'outline', motion = 'none' } = {}) {
   const W = spec.width || 1000;
   const H = spec.height || 420;
   const showGrid = figure !== 'minimal';
@@ -257,6 +259,7 @@ export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
   const barWidth = Math.max(4, Math.min(64, (slot * 0.55) / series.length));
 
   const legend = [];
+  let markIndex = 0;
   series.forEach((item, seriesIndex) => {
     const tone = palette[item.tone] || palette.accent;
     const points = seriesPoints(item).sort((a, b) => a.x - b.x);
@@ -267,24 +270,24 @@ export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
         const x = sx(point.x) - (series.length * barWidth) / 2 + seriesIndex * barWidth;
         const y = sy(Math.max(yMin, point.y));
         const height = Math.max(1, margin.t + plotH - y);
-        parts.push(`<rect x="${round(x)}" y="${round(y)}" width="${round(barWidth - 1.5)}" height="${round(height)}" fill="${tone}" fill-opacity="0.9"/>`);
+        parts.push(`<rect class="ch-bar" style="--i:${markIndex++}" x="${round(x)}" y="${round(y)}" width="${round(barWidth - 1.5)}" height="${round(height)}" fill="${tone}" fill-opacity="0.9"/>`);
       });
     } else if (item.kind === 'step' || spec.kind === 'steps') {
       let d = `M ${round(sx(points[0].x))} ${round(sy(points[0].y))}`;
       for (let i = 1; i < points.length; i++) {
         d += ` H ${round(sx(points[i].x))} V ${round(sy(points[i].y))}`;
       }
-      parts.push(`<path d="${d}" fill="none" stroke="${tone}" stroke-width="1.6"/>`);
-      points.forEach(point => parts.push(`<circle cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="2.6" fill="${tone}"/>`));
+      parts.push(`<path${motion !== 'none' ? ' class="ld-line" pathLength="1"' : ''} d="${d}" fill="none" stroke="${tone}" stroke-width="1.6"/>`);
+      points.forEach(point => parts.push(`<circle class="ch-point" style="--i:${markIndex++}" cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="2.6" fill="${tone}"/>`));
     } else if (item.kind === 'dot' || spec.kind === 'scatter') {
-      points.forEach(point => parts.push(`<circle cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="3.2" fill="${tone}"/>`));
+      points.forEach(point => parts.push(`<circle class="ch-point" style="--i:${markIndex++}" cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="3.2" fill="${tone}"/>`));
     } else {
       const path = points.map((point, i) => `${i ? 'L' : 'M'} ${round(sx(point.x))} ${round(sy(point.y))}`).join(' ');
-      parts.push(`<path d="${path}" fill="none" stroke="${tone}" stroke-width="1.5"/>`);
-      points.forEach(point => parts.push(`<circle cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="3.4" fill="${tone}" stroke="${palette.bg}" stroke-width="0.8"/>`));
+      parts.push(`<path${motion !== 'none' ? ' class="ld-line" pathLength="1"' : ''} d="${path}" fill="none" stroke="${tone}" stroke-width="1.5"/>`);
+      points.forEach(point => parts.push(`<circle class="ch-point" style="--i:${markIndex++}" cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="3.4" fill="${tone}" stroke="${palette.bg}" stroke-width="0.8"/>`));
     }
 
-    legend.push(`<g><rect x="0" y="-6" width="10" height="7" fill="${tone}"/><text x="15" y="0" font-size="10.5" fill="${palette.ink}">${escapeHtml(item.name)}</text></g>`);
+    legend.push(`<g class="ch-legend" style="--i:${markIndex++}"><rect x="0" y="-6" width="10" height="7" fill="${tone}"/><text x="15" y="0" font-size="10.5" fill="${palette.ink}">${escapeHtml(item.name)}</text></g>`);
   });
 
   for (const note of spec.annotations || []) {

package/src/render/themes/hud.js

@@ -43,7 +43,7 @@ body{margin:0;background:#020409;color:var(--ink);font-family:var(--mono);font-s
 .scene-head{padding:14px 16px 0}
 .scene-head .brand-row{padding-bottom:6px}
 .scene-top{display:flex;justify-content:space-between;padding:12px 16px 6px;font-size:9px;letter-spacing:.12em;color:#5f8090;text-transform:uppercase}
-.scene-stage{position:relative;aspect-ratio:16/8.6;min-height:300px;margin-top:2px;background:radial-gradient(ellipse at 55% 45%,rgba(30,90,120,.35),rgba(4,8,14,0) 66%),#03060b}
+.scene-stage{position:relative;width:100%;min-width:0;aspect-ratio:16/8.6;min-height:300px;margin-top:2px;background:radial-gradient(ellipse at 55% 45%,rgba(30,90,120,.35),rgba(4,8,14,0) 66%),#03060b}
 .scene-canvas{position:absolute;inset:0;width:100%;height:100%}
 .scene-label{position:absolute;transform:translate(-50%,-50%);font-size:9.5px;letter-spacing:.04em;color:#7fa6b8;white-space:nowrap;text-shadow:0 0 6px #03060b;pointer-events:none}
 .scene-crosshair{position:absolute;transform:translate(-50%,-50%);width:190px;height:190px;border:1px solid rgba(94,200,229,.22);border-radius:50%;pointer-events:none}
@@ -217,7 +217,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{transform:translate(12px,18px);min-width:200px;max-width:230px}
+  .scene-card{left:12px!important;top:auto!important;bottom:10px;transform:none;min-width:0;max-width:none;width:calc(100% - 24px)}
   .scene-label{font-size:8px}
   .sc-tail{margin-left:0}
   .footnotes{column-count:1}