@bytesbybrandon/living-docs 0.1.1 → 0.2.0

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbybrandon/living-docs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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,7 +47,7 @@
     "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",
+    "test": "node --test tests/cli.test.js tests/ingest.test.js tests/mcp.test.js tests/motion.test.js tests/render.test.js tests/style.test.js tests/validate.test.js",
     "samples": "node scripts/build-samples.js"
   },
   "dependencies": {

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/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) {

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/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 || []) {