@bytesbybrandon/living-docs 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +145 -144
  3. package/package.json +57 -57
  4. package/samples/end-of-harness-engineering.json +2 -0
  5. package/samples/harness-engineering.json +3 -0
  6. package/src/model/schema.js +1 -0
  7. package/src/render/blocks.js +38 -4
  8. package/src/render/svg.js +15 -12
  9. package/src/render/themes/hud.js +2 -1
  10. package/src/render/themes/paper-dark.js +2 -1
  11. package/src/render/themes/paper-light.js +2 -1
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Brandon D. Phillips
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Brandon D. Phillips
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,144 +1,145 @@
1
- # living-docs
2
-
3
- [![CI](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
-
6
- Turns a source document into a designed, self-contained HTML doc in one of three styles: an academic paper, dark reading notes, or a telemetry console.
7
- Ships an AXI CLI and a stdio MCP server over the same core.
8
-
9
- ---
10
-
11
- ### Key Features
12
-
13
- * **Three themes:** `paper-light` for papers and reports, `paper-dark` for reading notes and essays, `hud` for repo audits and system snapshots.
14
- * **Generated visuals:** diagrams and charts render as inline SVG from a compact spec, and the console hero uses a seeded graph layout.
15
- * **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).
16
- * **One self-contained file:** inline CSS, inline SVG, no network assets, and print rules. See [Guarantees](docs/guide/guarantees.md).
17
- * **Engine and interfaces:** the same core powers the CLI and the MCP server.
18
-
19
- ### Tech Stack
20
-
21
- * **Language:** JavaScript on Node.js 20 or newer, ECMAScript modules.
22
- * **Rendering:** no UI framework and no build step; blocks, SVG, and theme CSS are plain JavaScript.
23
- * **Dependencies:** `@modelcontextprotocol/sdk` for the MCP server and `unpdf` for PDF text extraction.
24
- * **Tests:** the Node.js built-in test runner.
25
-
26
- ### Table of Contents
27
-
28
- 1. [Getting Started](#getting-started)
29
- 2. [Usage](#usage)
30
- 3. [Running Tests](#running-tests)
31
- 4. [Project Structure](#project-structure)
32
- 5. [Contributing](#contributing)
33
- 6. [License](#license)
34
-
35
- ---
36
-
37
- ### Getting Started
38
-
39
- Install the package globally or run it without installing.
40
-
41
- #### Prerequisites
42
-
43
- * Node.js 20 or newer.
44
- * npm 10 or newer.
45
-
46
- #### Installation
47
-
48
- 1. **Install from npm:**
49
- ```bash
50
- npm install -g @bytesbybrandon/living-docs
51
- ```
52
- 2. **Or clone the repository:**
53
- ```bash
54
- git clone https://github.com/bytesbybrandon/living-docs.git
55
- cd living-docs
56
- ```
57
- 3. **Install dependencies for a checkout:**
58
- ```bash
59
- npm install
60
- ```
61
- 4. **Environment setup:** none. The engine reads files and URLs only.
62
-
63
- ---
64
-
65
- ### Usage
66
-
67
- #### Running Locally
68
-
69
- Render the bundled samples:
70
-
71
- ```bash
72
- npm run samples
73
- ```
74
-
75
- That writes one HTML file per sample model into `docs/`.
76
-
77
- #### Code Example
78
-
79
- ```bash
80
- node bin/living-docs-axi.js ingest samples/source/harness-notes.md --draft --theme paper-dark -o docs/note.model.json
81
- node bin/living-docs-axi.js render docs/note.model.json --theme paper-dark -o docs/note.html
82
- node bin/living-docs-axi.js preview docs
83
- ```
84
-
85
- With the published package, use `npx -y -p @bytesbybrandon/living-docs living-docs-axi` for each command.
86
-
87
- Detailed references:
88
-
89
- * [Pipeline](docs/guide/pipeline.md)
90
- * [CLI reference](docs/guide/cli.md)
91
- * [Document model](docs/guide/document-model.md)
92
- * [Style tokens](docs/guide/style-tokens.md)
93
- * [MCP server](docs/guide/mcp.md)
94
- * [Reactive workflow](docs/guide/reactive-workflow.md)
95
- * [Guarantees](docs/guide/guarantees.md)
96
- * [Architecture](ARCHITECTURE.md)
97
- * [Decisions](docs/decisions/0001-one-model-three-themes.md)
98
-
99
- ---
100
-
101
- ### Running Tests
102
-
103
- ```bash
104
- npm test
105
- ```
106
-
107
- The suite covers rendering determinism and self-containment, escaping and link sanitization, schema validation, ingest of Markdown, HTML, and text, CLI behavior and exit codes, an in-memory MCP client round trip, and style token resolution.
108
-
109
- ---
110
-
111
- ### Project Structure
112
-
113
- ```text
114
- living-docs/
115
- bin/ CLI and MCP entry points
116
- src/
117
- axi/ command parsing, compact output, file writes, preview
118
- ingest/ Markdown, text, HTML, URL, and PDF intake
119
- mcp/ stdio MCP server and tool definitions
120
- model/ document model schema, validator, safe inline Markdown
121
- render/ block renderers, SVG generators, style resolution, themes
122
- server/ local preview server
123
- samples/ sample models and one Markdown source
124
- scripts/ sample build script
125
- tests/ Node test runner suites
126
- docs/
127
- decisions/ architecture decision records
128
- guide/ user and contributor guides
129
- ```
130
-
131
- ---
132
-
133
- ### Contributing
134
-
135
- Contributions are welcome.
136
- Read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the fork, branch, test, and pull request workflow.
137
- Repository agent rules live in [AGENTS.md](AGENTS.md), and module boundaries live in [ARCHITECTURE.md](ARCHITECTURE.md).
138
-
139
- ---
140
-
141
- ### License
142
-
143
- Released under the MIT License.
144
- See [LICENSE](LICENSE).
1
+ # living-docs
2
+
3
+ [![CI](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ Turns a source document into a designed, self-contained HTML doc in one of three styles: an academic paper, dark reading notes, or a telemetry console.
7
+ Ships an AXI CLI and a stdio MCP server over the same core.
8
+
9
+ ---
10
+
11
+ ### Key Features
12
+
13
+ * **Three themes:** `paper-light` for papers and reports, `paper-dark` for reading notes and essays, `hud` for repo audits and system snapshots.
14
+ * **Generated visuals:** diagrams and charts render as inline SVG from a compact spec, and the console hero uses a seeded graph layout.
15
+ * **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).
16
+ * **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).
17
+ * **One self-contained file:** inline CSS, inline SVG, no network assets, and print rules. See [Guarantees](docs/guide/guarantees.md).
18
+ * **Engine and interfaces:** the same core powers the CLI and the MCP server.
19
+
20
+ ### Tech Stack
21
+
22
+ * **Language:** JavaScript on Node.js 20 or newer, ECMAScript modules.
23
+ * **Rendering:** no UI framework and no build step; blocks, SVG, and theme CSS are plain JavaScript.
24
+ * **Dependencies:** `@modelcontextprotocol/sdk` for the MCP server and `unpdf` for PDF text extraction.
25
+ * **Tests:** the Node.js built-in test runner.
26
+
27
+ ### Table of Contents
28
+
29
+ 1. [Getting Started](#getting-started)
30
+ 2. [Usage](#usage)
31
+ 3. [Running Tests](#running-tests)
32
+ 4. [Project Structure](#project-structure)
33
+ 5. [Contributing](#contributing)
34
+ 6. [License](#license)
35
+
36
+ ---
37
+
38
+ ### Getting Started
39
+
40
+ Install the package globally or run it without installing.
41
+
42
+ #### Prerequisites
43
+
44
+ * Node.js 20 or newer.
45
+ * npm 10 or newer.
46
+
47
+ #### Installation
48
+
49
+ 1. **Install from npm:**
50
+ ```bash
51
+ npm install -g @bytesbybrandon/living-docs
52
+ ```
53
+ 2. **Or clone the repository:**
54
+ ```bash
55
+ git clone https://github.com/bytesbybrandon/living-docs.git
56
+ cd living-docs
57
+ ```
58
+ 3. **Install dependencies for a checkout:**
59
+ ```bash
60
+ npm install
61
+ ```
62
+ 4. **Environment setup:** none. The engine reads files and URLs only.
63
+
64
+ ---
65
+
66
+ ### Usage
67
+
68
+ #### Running Locally
69
+
70
+ Render the bundled samples:
71
+
72
+ ```bash
73
+ npm run samples
74
+ ```
75
+
76
+ That writes one HTML file per sample model into `docs/`.
77
+
78
+ #### Code Example
79
+
80
+ ```bash
81
+ node bin/living-docs-axi.js ingest samples/source/harness-notes.md --draft --theme paper-dark -o docs/note.model.json
82
+ node bin/living-docs-axi.js render docs/note.model.json --theme paper-dark -o docs/note.html
83
+ node bin/living-docs-axi.js preview docs
84
+ ```
85
+
86
+ With the published package, use `npx -y -p @bytesbybrandon/living-docs living-docs-axi` for each command.
87
+
88
+ Detailed references:
89
+
90
+ * [Pipeline](docs/guide/pipeline.md)
91
+ * [CLI reference](docs/guide/cli.md)
92
+ * [Document model](docs/guide/document-model.md)
93
+ * [Style tokens](docs/guide/style-tokens.md)
94
+ * [MCP server](docs/guide/mcp.md)
95
+ * [Reactive workflow](docs/guide/reactive-workflow.md)
96
+ * [Guarantees](docs/guide/guarantees.md)
97
+ * [Architecture](ARCHITECTURE.md)
98
+ * [Decisions](docs/decisions/0001-one-model-three-themes.md)
99
+
100
+ ---
101
+
102
+ ### Running Tests
103
+
104
+ ```bash
105
+ npm test
106
+ ```
107
+
108
+ The suite covers rendering determinism and self-containment, escaping and link sanitization, schema validation, ingest of Markdown, HTML, and text, CLI behavior and exit codes, an in-memory MCP client round trip, and style token resolution.
109
+
110
+ ---
111
+
112
+ ### Project Structure
113
+
114
+ ```text
115
+ living-docs/
116
+ bin/ CLI and MCP entry points
117
+ src/
118
+ axi/ command parsing, compact output, file writes, preview
119
+ ingest/ Markdown, text, HTML, URL, and PDF intake
120
+ mcp/ stdio MCP server and tool definitions
121
+ model/ document model schema, validator, safe inline Markdown
122
+ render/ block renderers, SVG generators, style resolution, themes
123
+ server/ local preview server
124
+ samples/ sample models and one Markdown source
125
+ scripts/ sample build script
126
+ tests/ Node test runner suites
127
+ docs/
128
+ decisions/ architecture decision records
129
+ guide/ user and contributor guides
130
+ ```
131
+
132
+ ---
133
+
134
+ ### Contributing
135
+
136
+ Contributions are welcome.
137
+ Read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the fork, branch, test, and pull request workflow.
138
+ Repository agent rules live in [AGENTS.md](AGENTS.md), and module boundaries live in [ARCHITECTURE.md](ARCHITECTURE.md).
139
+
140
+ ---
141
+
142
+ ### License
143
+
144
+ Released under the MIT License.
145
+ See [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,57 +1,57 @@
1
- {
2
- "name": "@bytesbybrandon/living-docs",
3
- "version": "0.1.0",
4
- "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.",
5
- "type": "module",
6
- "license": "MIT",
7
- "author": "Brandon D. Phillips",
8
- "engines": {
9
- "node": ">=20"
10
- },
11
- "repository": {
12
- "type": "git",
13
- "url": "git+https://github.com/bytesbybrandon/living-docs.git"
14
- },
15
- "homepage": "https://github.com/bytesbybrandon/living-docs#readme",
16
- "bugs": {
17
- "url": "https://github.com/bytesbybrandon/living-docs/issues"
18
- },
19
- "keywords": [
20
- "agent",
21
- "axi",
22
- "mcp",
23
- "documentation",
24
- "html",
25
- "pdf",
26
- "living-docs",
27
- "telemetry",
28
- "paper"
29
- ],
30
- "bin": {
31
- "living-docs-axi": "bin/living-docs-axi.js",
32
- "living-docs-mcp": "bin/living-docs-mcp.js"
33
- },
34
- "exports": {
35
- ".": "./src/index.js",
36
- "./render": "./src/render/index.js",
37
- "./ingest": "./src/ingest/index.js"
38
- },
39
- "files": [
40
- "bin",
41
- "src",
42
- "samples",
43
- "README.md",
44
- "LICENSE"
45
- ],
46
- "publishConfig": {
47
- "access": "public"
48
- },
49
- "scripts": {
50
- "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",
51
- "samples": "node scripts/build-samples.js"
52
- },
53
- "dependencies": {
54
- "@modelcontextprotocol/sdk": "^1.32.2",
55
- "unpdf": "^2.1.0"
56
- }
57
- }
1
+ {
2
+ "name": "@bytesbybrandon/living-docs",
3
+ "version": "0.2.0",
4
+ "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.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "Brandon D. Phillips",
8
+ "engines": {
9
+ "node": ">=20"
10
+ },
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "git+https://github.com/bytesbybrandon/living-docs.git"
14
+ },
15
+ "homepage": "https://github.com/bytesbybrandon/living-docs#readme",
16
+ "bugs": {
17
+ "url": "https://github.com/bytesbybrandon/living-docs/issues"
18
+ },
19
+ "keywords": [
20
+ "agent",
21
+ "axi",
22
+ "mcp",
23
+ "documentation",
24
+ "html",
25
+ "pdf",
26
+ "living-docs",
27
+ "telemetry",
28
+ "paper"
29
+ ],
30
+ "bin": {
31
+ "living-docs-axi": "bin/living-docs-axi.js",
32
+ "living-docs-mcp": "bin/living-docs-mcp.js"
33
+ },
34
+ "exports": {
35
+ ".": "./src/index.js",
36
+ "./render": "./src/render/index.js",
37
+ "./ingest": "./src/ingest/index.js"
38
+ },
39
+ "files": [
40
+ "bin",
41
+ "src",
42
+ "samples",
43
+ "README.md",
44
+ "LICENSE"
45
+ ],
46
+ "publishConfig": {
47
+ "access": "public"
48
+ },
49
+ "scripts": {
50
+ "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",
51
+ "samples": "node scripts/build-samples.js"
52
+ },
53
+ "dependencies": {
54
+ "@modelcontextprotocol/sdk": "^1.32.2",
55
+ "unpdf": "^2.1.0"
56
+ }
57
+ }
package/samples/end-of-harness-engineering.json CHANGED
@@ -42,6 +42,7 @@
42
42
  "type": "figure",
43
43
  "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.",
44
44
  "spec": "diagram",
45
+ "motion": "draw",
45
46
  "span": "page",
46
47
  "diagram": {
47
48
  "width": 1000,
@@ -111,6 +112,7 @@
111
112
  "type": "figure",
112
113
  "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.",
113
114
  "spec": "chart",
115
+ "motion": "steps",
114
116
  "chart": {
115
117
  "kind": "scatter",
116
118
  "height": 380,
package/samples/harness-engineering.json CHANGED
@@ -41,6 +41,7 @@
41
41
  "type": "figure",
42
42
  "caption": "An agent is a model plus a harness of seven subsystems. The harness owns everything outside the weights.",
43
43
  "spec": "diagram",
44
+ "motion": "draw",
44
45
  "diagram": {
45
46
  "width": 1000,
46
47
  "height": 440,
@@ -118,6 +119,7 @@
118
119
  "type": "figure",
119
120
  "caption": "Extensibility standards across eleven coding harnesses. Counts include partial support, greyed in the paper's original figure.",
120
121
  "spec": "chart",
122
+ "motion": "steps",
121
123
  "chart": {
122
124
  "kind": "bar",
123
125
  "height": 340,
@@ -163,6 +165,7 @@
163
165
  "type": "figure",
164
166
  "caption": "Convergence becomes imitation: Codex reads Claude Code's hook vocabulary while OpenHands reads its plugin format.",
165
167
  "spec": "diagram",
168
+ "motion": "draw",
166
169
  "diagram": {
167
170
  "width": 1000,
168
171
  "height": 300,
package/src/model/schema.js CHANGED
@@ -157,6 +157,7 @@ export const BLOCKS = {
157
157
  spec: oneOf(['diagram', 'chart'], 'which generator to use'),
158
158
  diagram: { ...diagramSpec, optional: true },
159
159
  chart: { ...chartSpec, optional: true },
160
+ motion: oneOf(['none', 'draw', 'reveal', 'steps'], 'static CSS animation for the figure; print and reduced motion stay static', { optional: true }),
160
161
  span: oneOf(['column', 'page'], 'column width or full page', { optional: true })
161
162
  },
162
163
  check(value, path, err) {
package/src/render/blocks.js CHANGED
@@ -17,19 +17,53 @@ export function createContext({ theme, palette, baseDir, model }) {
17
17
 
18
18
  const spanClass = block => (block.span === 'page' ? ' span-page' : '');
19
19
 
20
+ function motionCss(id, motion) {
21
+ if (!motion || motion === 'none') return '';
22
+ const scope = `#${id}`;
23
+ const reset = `
24
+ @media (prefers-reduced-motion: reduce){
25
+ ${scope} *{animation:none !important;opacity:1 !important;transform:none !important;stroke-dashoffset:0 !important}
26
+ }
27
+ @media print{
28
+ ${scope} *{animation:none !important;opacity:1 !important;transform:none !important;stroke-dashoffset:0 !important}
29
+ }`;
30
+ const keyframes = `@keyframes ld-draw{to{stroke-dashoffset:0}}@keyframes ld-fade{to{opacity:1}}@keyframes ld-grow{to{transform:scaleY(1)}}`;
31
+ if (motion === 'draw') {
32
+ return `<style>${keyframes}
33
+ ${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 1000ms ease-out forwards}
34
+ ${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)}
35
+ ${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)}
36
+ ${reset}</style>`;
37
+ }
38
+ if (motion === 'steps') {
39
+ return `<style>${keyframes}
40
+ ${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 700ms ease-out forwards;animation-delay:calc(var(--i,0)*140ms)}
41
+ ${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)}
42
+ ${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)}
43
+ ${reset}</style>`;
44
+ }
45
+ return `<style>${keyframes}
46
+ ${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)}
47
+ ${scope} .ld-line{stroke-dasharray:1;stroke-dashoffset:1;animation:ld-draw 800ms ease-out forwards}
48
+ ${reset}</style>`;
49
+ }
50
+
20
51
  function renderFigure(block, ctx) {
21
52
  const number = ++ctx.counters.figure;
22
53
  const span = block.span || (ctx.theme === 'hud' ? 'column' : 'page');
54
+ const motion = block.motion || 'none';
23
55
  let svg = '';
24
56
  try {
25
57
  svg = block.spec === 'diagram'
26
- ? diagramSvg(block.diagram, ctx.palette, { figure: ctx.style?.figure })
27
- : chartSvg(block.chart, ctx.palette, { figure: ctx.style?.figure });
58
+ ? diagramSvg(block.diagram, ctx.palette, { figure: ctx.style?.figure, motion })
59
+ : chartSvg(block.chart, ctx.palette, { figure: ctx.style?.figure, motion });
28
60
  } catch (error) {
29
61
  ctx.warnings.push(`figure ${number}: ${error.message}`);
30
62
  svg = `<div class="fig-error">Figure unavailable: ${escapeHtml(error.message)}</div>`;
31
63
  }
64
+ const motionStyle = motionCss(`fig-${number}`, motion);
32
65
  return `<figure class="fig${span === 'page' ? ' span-page' : ''}" id="fig-${number}">
66
+ ${motionStyle}
33
67
  <div class="fig-frame">${svg}</div>
34
68
  <figcaption><span class="fig-num">Fig. ${number}.</span> ${renderInline(block.caption)}</figcaption>
35
69
  </figure>`;
@@ -47,7 +81,7 @@ function renderTable(block, ctx) {
47
81
  }).join('')}</tr>`).join('');
48
82
  return `<figure class="tbl${spanClass(block)}">
49
83
  ${caption}
50
- <table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>
84
+ <div class="tbl-scroll"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>
51
85
  </figure>`;
52
86
  }
53
87
 
@@ -300,7 +334,7 @@ export function renderBlock(block, ctx) {
300
334
  : `${ctx.counters.section}.${ctx.counters.sub}`;
301
335
  const subtitle = block.subtitle ? `<p class="sec-subtitle">${renderInline(block.subtitle)}</p>` : '';
302
336
  return `<h${level} class="${level === 2 ? 'sec-head' : 'sub-head'}" id="sec-${number.replace('.', '-')}">
303
- <span class="sec-num">${number}</span><span class="sec-title">${renderInline(block.title)}</span>
337
+ <span class="sec-num">${number}</span> <span class="sec-title">${renderInline(block.title)}</span>
304
338
  </h${level}>${subtitle}`;
305
339
  }
306
340
  case 'figure': return renderFigure(block, ctx);
package/src/render/svg.js CHANGED
@@ -60,7 +60,7 @@ function iconMarkup(node, palette) {
60
60
  }
61
61
  }
62
62
 
63
- export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
63
+ export function diagramSvg(spec, palette, { figure = 'outline', motion = 'none' } = {}) {
64
64
  const W = spec.width || 1000;
65
65
  const H = spec.height || 520;
66
66
  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' } = {}) {
126
126
  }
127
127
  }
128
128
  const markerEnd = edge.style === 'line' ? '' : ` marker-end="url(#${marker})"`;
129
- edges.push(`<path d="${d}" fill="none" stroke="${stroke}" stroke-width="1.1"${dash}${markerEnd}/>`);
129
+ const animLine = motion !== 'none' && edge.style !== 'dashed' ? ' class="ld-line" pathLength="1"' : '';
130
+ edges.push(`<path${animLine} d="${d}" fill="none" stroke="${stroke}" stroke-width="1.1"${dash}${markerEnd}/>`);
130
131
  if (edge.label) {
131
132
  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>`);
132
133
  }
@@ -135,6 +136,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
135
136
 
136
137
  // Nodes.
137
138
  const nodeMarkup = [];
139
+ let nodeIndex = 0;
138
140
  for (const node of nodes) {
139
141
  const minimal = figure === 'minimal';
140
142
  const solid = figure === 'solid';
@@ -154,7 +156,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
154
156
  const blockHeight = lines.length * lineHeight + (node.sub ? 13 : 0) + iconSpace;
155
157
  let textY = node.y + (node.h - blockHeight) / 2 + lineHeight - 4 + iconSpace;
156
158
 
157
- nodeMarkup.push(`<g class="d-node d-node-${node.kind}">`);
159
+ nodeMarkup.push(`<g class="d-node d-node-${node.kind}" style="--i:${nodeIndex++}">`);
158
160
  if (node.kind === 'stack') {
159
161
  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"/>`);
160
162
  }
@@ -170,7 +172,7 @@ export function diagramSvg(spec, palette, { figure = 'outline' } = {}) {
170
172
  nodeMarkup.push('</g>');
171
173
  }
172
174
  parts.push(`<g class="d-nodes">${nodeMarkup.join('')}</g>`);
173
- if (edgeLabels.length) parts.push(`<g class="d-edge-labels">${edgeLabels.join('')}</g>`);
175
+ if (edgeLabels.length) parts.push(`<g class="d-edge-labels" style="--i:${nodes.length}">${edgeLabels.join('')}</g>`);
174
176
 
175
177
  if (spec.notes?.length) {
176
178
  const notes = spec.notes.map((note, i) =>
@@ -201,7 +203,7 @@ function seriesPoints(series) {
201
203
  return (series.values || []).map((value, i) => ({ x: i + 1, y: value, label: series.labels?.[i] }));
202
204
  }
203
205
 
204
- export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
206
+ export function chartSvg(spec, palette, { figure = 'outline', motion = 'none' } = {}) {
205
207
  const W = spec.width || 1000;
206
208
  const H = spec.height || 420;
207
209
  const showGrid = figure !== 'minimal';
@@ -257,6 +259,7 @@ export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
257
259
  const barWidth = Math.max(4, Math.min(64, (slot * 0.55) / series.length));
258
260
 
259
261
  const legend = [];
262
+ let markIndex = 0;
260
263
  series.forEach((item, seriesIndex) => {
261
264
  const tone = palette[item.tone] || palette.accent;
262
265
  const points = seriesPoints(item).sort((a, b) => a.x - b.x);
@@ -267,24 +270,24 @@ export function chartSvg(spec, palette, { figure = 'outline' } = {}) {
267
270
  const x = sx(point.x) - (series.length * barWidth) / 2 + seriesIndex * barWidth;
268
271
  const y = sy(Math.max(yMin, point.y));
269
272
  const height = Math.max(1, margin.t + plotH - y);
270
- parts.push(`<rect x="${round(x)}" y="${round(y)}" width="${round(barWidth - 1.5)}" height="${round(height)}" fill="${tone}" fill-opacity="0.9"/>`);
273
+ 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"/>`);
271
274
  });
272
275
  } else if (item.kind === 'step' || spec.kind === 'steps') {
273
276
  let d = `M ${round(sx(points[0].x))} ${round(sy(points[0].y))}`;
274
277
  for (let i = 1; i < points.length; i++) {
275
278
  d += ` H ${round(sx(points[i].x))} V ${round(sy(points[i].y))}`;
276
279
  }
277
- parts.push(`<path d="${d}" fill="none" stroke="${tone}" stroke-width="1.6"/>`);
278
- points.forEach(point => parts.push(`<circle cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="2.6" fill="${tone}"/>`));
280
+ parts.push(`<path${motion !== 'none' ? ' class="ld-line" pathLength="1"' : ''} d="${d}" fill="none" stroke="${tone}" stroke-width="1.6"/>`);
281
+ 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}"/>`));
279
282
  } else if (item.kind === 'dot' || spec.kind === 'scatter') {
280
- points.forEach(point => parts.push(`<circle cx="${round(sx(point.x))}" cy="${round(sy(point.y))}" r="3.2" fill="${tone}"/>`));
283
+ 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}"/>`));
281
284
  } else {
282
285
  const path = points.map((point, i) => `${i ? 'L' : 'M'} ${round(sx(point.x))} ${round(sy(point.y))}`).join(' ');
283
- parts.push(`<path d="${path}" fill="none" stroke="${tone}" stroke-width="1.5"/>`);
284
- 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"/>`));
286
+ parts.push(`<path${motion !== 'none' ? ' class="ld-line" pathLength="1"' : ''} d="${path}" fill="none" stroke="${tone}" stroke-width="1.5"/>`);
287
+ 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"/>`));
285
288
  }
286
289
 
287
- 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>`);
290
+ 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>`);
288
291
  });
289
292
 
290
293
  for (const note of spec.annotations || []) {
package/src/render/themes/hud.js CHANGED
@@ -153,13 +153,14 @@ body{margin:0;background:#020409;color:var(--ink);font-family:var(--mono);font-s
153
153
  .prose.lead{font-size:14.4px;color:#c8dee9}
154
154
  .sec-head{display:flex;gap:10px;align-items:baseline;font-size:10.5px;font-weight:600;letter-spacing:.18em;text-transform:uppercase;color:#9fc7d8;border-top:1px solid #12242e;padding-top:8px;margin:24px 0 9px;break-after:avoid}
155
155
  .sec-num{color:var(--accent)}
156
- .sub-head{font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:#9fc7d8;margin:16px 0 6px;break-after:avoid}
156
+ .sub-head{display:flex;gap:.6em;align-items:baseline;font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:#9fc7d8;margin:16px 0 6px;break-after:avoid}
157
157
  .sec-subtitle{font-family:var(--sans);font-size:11.5px;color:#6f8f9f;margin:-3px 0 8px}
158
158
  .fig{margin:16px 0;border:1px solid #12242e;background:#050a12;padding:10px;break-inside:avoid}
159
159
  .fig-frame svg,.fig-frame img{display:block;width:100%;height:auto}
160
160
  figcaption{font-size:9.5px;line-height:1.5;color:#6f8f9f;margin-top:7px;letter-spacing:.03em}
161
161
  .fig-num,.tbl-num{color:var(--accent)}
162
162
  .tbl{margin:16px 0;break-inside:avoid}
163
+ .tbl-scroll{max-width:100%;overflow-x:auto}
163
164
  .tbl figcaption{font-size:8.5px;letter-spacing:.12em;text-transform:uppercase;color:#5f8090;margin:0 0 6px;text-align:right}
164
165
  table{width:100%;border-collapse:collapse;font-size:10.5px;line-height:1.5}
165
166
  thead th{font-size:8.5px;letter-spacing:.1em;text-transform:uppercase;color:#6f8f9f;text-align:left;border-top:1px solid var(--line);border-bottom:1px solid var(--line);padding:5px 6px}
package/src/render/themes/paper-dark.js CHANGED
@@ -40,13 +40,14 @@ p.prose{margin:0 0 .72em}
40
40
  p.prose.lead::first-letter{float:left;font-size:52px;line-height:.76;padding:6px 8px 0 0;font-weight:700;color:#e5ded0}
41
41
  h2.sec-head{display:flex;gap:10px;align-items:baseline;font-family:var(--sans);font-size:11px;font-weight:600;letter-spacing:.16em;text-transform:uppercase;color:#b6ada0;border-top:1px solid #4a443c;padding-top:8px;margin:22px 0 9px;break-after:avoid}
42
42
  .sec-num{color:#ddd5c6;font-variant-numeric:tabular-nums}
43
- h3.sub-head{font-size:14px;font-weight:600;margin:15px 0 5px;break-after:avoid}
43
+ h3.sub-head{display:flex;gap:.5em;align-items:baseline;font-size:14px;font-weight:600;margin:15px 0 5px;break-after:avoid}
44
44
  .sec-subtitle{font-style:italic;font-size:12.5px;color:#948c7f;margin:-4px 0 8px}
45
45
  .fig{margin:16px 0;break-inside:avoid}
46
46
  .fig-frame svg,.fig-frame img{display:block;width:100%;height:auto}
47
47
  figcaption{font-family:var(--sans);font-size:10.4px;line-height:1.5;color:#a49b8d;margin-top:7px}
48
48
  .fig-num,.tbl-num{color:#ddd5c6;font-weight:600}
49
49
  .tbl{margin:16px 0;break-inside:avoid}
50
+ .tbl-scroll{max-width:100%;overflow-x:auto}
50
51
  .tbl figcaption{font-family:var(--sans);font-size:10.2px;letter-spacing:.08em;text-transform:uppercase;color:#948c7f;text-align:right;margin:0 0 6px}
51
52
  table{width:100%;border-collapse:collapse;font-size:11.6px;line-height:1.5}
52
53
  thead th{font-family:var(--sans);font-variant:small-caps;letter-spacing:.08em;font-weight:500;color:#bcb3a5;text-align:left;border-top:1px solid #6a6256;border-bottom:1px solid #6a6256;padding:5px 6px}
package/src/render/themes/paper-light.js CHANGED
@@ -41,13 +41,14 @@ p.prose{margin:0 0 .68em}
41
41
  p.prose.lead::first-letter{float:left;font-size:48px;line-height:.78;padding:5px 7px 0 0;font-weight:700}
42
42
  h2.sec-head{display:flex;gap:10px;align-items:baseline;font-family:var(--sans);font-size:11.5px;font-weight:700;letter-spacing:.11em;text-transform:uppercase;border-top:1px solid #1a1a1a;padding-top:7px;margin:20px 0 8px;break-after:avoid}
43
43
  .sec-num{font-variant-numeric:tabular-nums;color:#1a1a1a}
44
- h3.sub-head{font-size:13.5px;font-weight:700;margin:14px 0 5px;break-after:avoid}
44
+ h3.sub-head{display:flex;gap:.5em;align-items:baseline;font-size:13.5px;font-weight:700;margin:14px 0 5px;break-after:avoid}
45
45
  .sec-subtitle{font-size:12px;color:#555;margin:-4px 0 8px}
46
46
  .fig{margin:14px 0;break-inside:avoid}
47
47
  .fig-frame svg,.fig-frame img{display:block;width:100%;height:auto}
48
48
  figcaption{font-family:var(--sans);font-size:10.2px;line-height:1.45;color:#3a3630;margin-top:6px}
49
49
  .fig-num,.tbl-num{font-weight:700}
50
50
  .tbl{margin:14px 0;break-inside:avoid}
51
+ .tbl-scroll{max-width:100%;overflow-x:auto}
51
52
  .tbl figcaption{font-family:var(--sans);font-size:10.2px;line-height:1.4;margin:0 0 5px;color:#3a3630}
52
53
  table{width:100%;border-collapse:collapse;font-size:11px;line-height:1.4}
53
54
  thead th{font-family:var(--sans);font-variant:small-caps;letter-spacing:.07em;font-weight:600;text-align:left;border-top:1.4px solid #1a1a1a;border-bottom:1px solid #1a1a1a;padding:5px}