@bytesbybrandon/living-docs 0.3.0 → 0.3.1

package/README.md

@@ -50,7 +50,7 @@ Install the package globally or run it without installing.
 
 1. **Install from npm:**
    ```bash
-   npm install -g @bytesbybrandon/living-docs
+   npm install -g living-docs-axi
    ```
 2. **Or clone the repository:**
    ```bash
@@ -85,7 +85,7 @@ node bin/living-docs-axi.js render docs/note.model.json --theme paper-dark -o do
 node bin/living-docs-axi.js preview docs
 ```
 
-With the published package, use `npx -y -p @bytesbybrandon/living-docs living-docs-axi` for each command.
+With the published package, use `npx -y living-docs-axi` for each command.
 
 Detailed references:
 

package/docs/guide/cli.md

@@ -0,0 +1,61 @@
+# CLI reference
+
+The `living-docs-axi` command follows the AXI principles: compact TOON-style output, a content-first home view, and `help[]` next-step lines.
+
+```text
+living-docs-axi                         home: themes, built docs, next steps
+living-docs-axi themes                  theme list with when to use each
+living-docs-axi schema [--block figure] block fields and types
+living-docs-axi ingest <path|url|->     outline, or --section <n|id> for one section
+living-docs-axi ingest <path> --draft   write a model, with a drafted timeline, from the source
+living-docs-axi render <model.json>     validate and write HTML, or --format mp4|webm|gif for video
+living-docs-axi validate <model.json>   validation only
+living-docs-axi preview [dir]           serve built docs with an index
+```
+
+## Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--theme <name>` | `paper-light`, `paper-dark`, `hud`, or a curated look: `field-notes`, `editorial`, `blueprint`. With `--draft`, omitted means the source picks |
+| `--seed <hex>` | with `--draft`: accent seed, overriding the one derived from the title |
+| `-o`, `--out <file>` | output path |
+| `--section <n\|id>` | ingest one section |
+| `--max-chars <n>` | cap section text, default 12000 |
+| `--full` | disable truncation |
+| `--stdout` | print HTML instead of writing a file |
+| `--url <url>` | ingest a URL |
+| `--text <text>` | ingest inline text |
+| `--port <n>` | preview port, default 4600 |
+| `--no-open` | do not open a browser |
+| `--static` | draft without timeline cues |
+| `--format <f>` | `html` (default), `mp4`, `webm`, or `gif` |
+| `--size <WxH>` | video stage, default `1080x1350` |
+| `--fps <n>` | video frames per second, default 30 |
+| `--scale <n>` | device pixel ratio for the stage, default 1 |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | success |
+| 1 | invalid model or runtime failure |
+| 2 | usage error, including unknown flags |
+
+Errors are structured on standard output.
+Unknown flags fail loud instead of being ignored.
+
+## Examples
+
+```bash
+npx -y living-docs-axi themes
+npx -y living-docs-axi ingest samples/source/harness-notes.md --draft -o docs/draft.model.json
+npx -y living-docs-axi render docs/draft.model.json --theme paper-dark -o docs/draft.html
+npx -y living-docs-axi preview docs --no-open
+```
+
+## See also
+
+- [Pipeline](pipeline.md)
+- [Document model](document-model.md)
+- [Timeline and video](timeline.md)

package/docs/guide/document-model.md

@@ -0,0 +1,117 @@
+# Document model
+
+A model is `{ schemaVersion: 1, theme?, meta, blocks }`.
+Validation is strict: unknown fields, unknown block types, and unresolved references fail with an exact path.
+
+## Meta
+
+`meta` accepts `title`, `subtitle`, `kicker`, `runningHead`, `author`, `affiliation`, `date`, `stamps`, `abstract`, `indexTerms`, `footer`, `accent`, and `style`.
+`style` carries the [style tokens](style-tokens.md).
+
+## Blocks
+
+| Block | Purpose |
+| --- | --- |
+| `prose` | body text with inline markdown and `[[1]]` footnote refs |
+| `heading` | numbered section (`level: 2`) or subsection (`level: 3`) |
+| `figure` | generated diagram or chart, auto-numbered |
+| `table` | rule-based table with small-caps head |
+| `algorithm` | numbered pseudocode with an optional highlighted line |
+| `callout` | `takeaway`, `note`, or `warn` aside |
+| `stats` | row of headline numbers |
+| `list`, `quote`, `code` | supporting text blocks |
+| `image` | supplied file, inlined as a data URI |
+| `footnotes` | footnote list printed at the foot |
+| `ticker` | one-line console status strip |
+| `graphScene` | console hero: tabs, prompt, graph, active-node card |
+| `panels` | console grid with 13 panel kinds |
+
+## Figures
+
+A figure takes either a `diagram` spec or a `chart` spec.
+Diagrams place nodes and edges on a 1000-unit canvas, with optional groups and notes.
+Charts accept `line`, `scatter`, `bar`, and `steps` series, with ticks, bounds, legend, and annotations.
+Both render as inline SVG, so no image assets are required.
+
+`ingest --draft` never writes figures.
+It drafts text, lists, stats, and a timeline from the source, so every figure is authored into the model by hand or by an agent.
+Run `living-docs-axi schema --block figure` for every nested field.
+
+### Diagram
+
+Nodes sit at fixed `x` and `y` positions on a canvas that is 1000 units wide by default.
+There is no auto layout, so choose positions that leave room for labels.
+Node ids must be unique, and every edge and group member must name an existing node id.
+Node `kind` is `box`, `accent`, `plain`, `dashed`, or `stack`.
+Edge `route` is `straight` or `elbow`.
+
+```json
+{
+  "type": "figure",
+  "id": "segments",
+  "caption": "Appends go to the active segment. Sealed segments stay read-only.",
+  "spec": "diagram",
+  "span": "page",
+  "motion": "draw",
+  "diagram": {
+    "width": 1000,
+    "height": 360,
+    "nodes": [
+      { "id": "writer", "label": "writer", "sub": "append", "x": 40, "y": 150, "w": 160, "h": 64 },
+      { "id": "dir", "label": "segment directory", "x": 280, "y": 150, "w": 200, "h": 64, "kind": "accent" },
+      { "id": "hot", "label": "active segment", "x": 580, "y": 60, "w": 180, "h": 64 },
+      { "id": "cold", "label": "sealed segments", "x": 580, "y": 240, "w": 180, "h": 64, "kind": "dashed" }
+    ],
+    "edges": [
+      { "from": "writer", "to": "dir", "label": "publish" },
+      { "from": "dir", "to": "hot", "route": "elbow" },
+      { "from": "dir", "to": "cold", "route": "elbow" }
+    ],
+    "groups": [{ "label": "segment store", "nodes": ["hot", "cold"] }],
+    "notes": ["Sealing copies no payload."]
+  }
+}
+```
+
+### Chart
+
+Chart `kind` is `line`, `scatter`, `bar`, or `steps`.
+A series carries `points` of `{ x, y }`, or `values` and `labels` for bars.
+Series `tone` is `accent`, `ink`, `muted`, `kept`, or `rejected`.
+
+```json
+{
+  "type": "figure",
+  "caption": "Lookup probes grow with segment count.",
+  "spec": "chart",
+  "chart": {
+    "kind": "line",
+    "xLabel": "segments",
+    "yLabel": "probes",
+    "series": [
+      { "name": "nacre", "tone": "accent", "points": [{ "x": 1, "y": 1 }, { "x": 32, "y": 32 }, { "x": 128, "y": 128 }] }
+    ]
+  }
+}
+```
+
+Use an `image` block instead when the graphic already exists as a raster or SVG file.
+
+### Motion
+
+`motion` is optional and accepts `none`, `draw`, `reveal`, or `steps`.
+Motion is scoped CSS on the generated SVG: edges draw, marks fade in, and bars grow.
+Print and `prefers-reduced-motion` freeze the final frame, and content stays visible while the animation runs.
+
+## Console blocks
+
+`graphScene` accepts a title, meta chips, tabs, a prompt line, a graph payload, an action strip, and a status line.
+The graph layout is seeded, so the same model produces the same scene.
+`panels` holds numbered panels with one of 13 kinds: `repo`, `bars`, `list`, `radar`, `tree`, `log`, `heat`, `big`, `spark`, `code`, `hist`, `metrics`, and `diff`.
+
+Other themes render console blocks as annotated cards, so a model can switch themes without losing content.
+
+## See also
+
+- [Pipeline](pipeline.md)
+- [Style tokens](style-tokens.md)

package/docs/guide/guarantees.md

@@ -0,0 +1,31 @@
+# Guarantees
+
+## One file per document
+
+CSS, SVG, and the console runtime are inlined.
+No CDN, fonts, or remote images are loaded.
+
+## Deterministic output
+
+Identical model and theme produce identical bytes, including generated SVG ids, graph layout, and derived palette values.
+
+## Curated styling
+
+`meta.style` only accepts known palettes, type pairings, densities, and figure treatments.
+Accent colors are contrast corrected.
+No arbitrary CSS is injected.
+
+## Escaped content
+
+Document text is HTML escaped.
+Only `http(s)`, `mailto:`, `#`, and relative URLs survive as links.
+
+## Print ready
+
+Paper themes ship `@page` rules and keep figures, tables, algorithms, and callouts unbroken across pages.
+Figure motion freezes to its final frame in print and under reduced-motion preferences.
+
+## Known limits
+
+PDF ingestion depends on the optional `unpdf` package and reports a typed error when it is unavailable.
+There is no visual regression suite and no per-theme versioning.

package/docs/guide/mcp.md

@@ -0,0 +1,47 @@
+# MCP server
+
+The package ships a stdio MCP server over the same core as the CLI.
+
+## Published package
+
+```json
+{
+  "mcpServers": {
+    "living-docs": {
+      "command": "npx",
+      "args": ["-y", "-p", "living-docs-axi", "living-docs-mcp"]
+    }
+  }
+}
+```
+
+## Local checkout
+
+```json
+{
+  "mcpServers": {
+    "living-docs": {
+      "command": "node",
+      "args": ["<absolute-checkout>/bin/living-docs-mcp.js"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `living_docs_themes` | list the themes (three structural bases plus curated looks) and what each is best for |
+| `living_docs_schema` | block fields, or one block in detail |
+| `living_docs_ingest` | outline a source, optionally draft a model with timeline cues (`static` skips them) |
+| `living_docs_render` | validate and write HTML, or `format` mp4, webm, or gif, from a model, a model path, or a source |
+| `living_docs_preview` | serve built docs and return the URL |
+
+`living_docs_render` accepts a model object, a model path, or a source to draft from.
+Tools return compact text, and errors are marked with `isError`.
+
+## See also
+
+- [CLI reference](cli.md)
+- [Document model](document-model.md)

package/docs/guide/pipeline.md

@@ -0,0 +1,36 @@
+# Pipeline
+
+The engine turns one source into one self-contained HTML document.
+
+```text
+source -> ingest -> outline + normalized blocks
+                 |
+                 +-> --draft -> valid document model
+                 |
+                 +-> author a richer model against the schema
+                                      |
+                                render --theme -> single HTML file
+```
+
+## Ingest
+
+`ingest` accepts a file path (Markdown, plain text, HTML, or PDF), a URL, inline text, or standard input.
+It returns an outline with section ids, titles, and word counts.
+Large sources stay bounded: read the outline, then pull one section at a time with `--section <n|id>`.
+
+## Draft models
+
+`ingest --draft` is the zero-judgment path.
+It writes a document model that validates and renders immediately.
+An author then adds figures, charts, callouts, stats, and console panels against the schema.
+
+## Render
+
+`render` validates the model, resolves style tokens, and writes one file with inline CSS, inline SVG, and the console runtime.
+The file loads no fonts, images, or scripts from the network.
+
+## See also
+
+- [CLI reference](cli.md)
+- [Document model](document-model.md)
+- [Style tokens](style-tokens.md)

package/docs/guide/reactive-workflow.md

@@ -0,0 +1,21 @@
+# Reactive workflow
+
+An optional reactive skill wraps the same pipeline: intake, outline, theme and style plan, model authoring, validation, render, human review, and finalize.
+It calls the CLI and does not reimplement rendering.
+
+## Boundary
+
+The skill is maintained separately from this package.
+`src/model/schema.js` and the AXI commands are the stable engine surface.
+
+## Plan and review
+
+The workflow holds two human gates.
+The first approves the theme, style tokens, sections, and figures.
+The second reviews the rendered page.
+Model revisions are bounded at four attempts before the run ends in an error state.
+
+## See also
+
+- [CLI reference](cli.md)
+- [Style tokens](style-tokens.md)

package/docs/guide/style-tokens.md

@@ -0,0 +1,60 @@
+# Style tokens
+
+`meta.style` adapts a theme to its source without accepting arbitrary CSS.
+Every choice is curated and validated, so the page stays coherent, printable, and deterministic.
+
+| Token | Values | Effect |
+| --- | --- | --- |
+| `palette` | `default`, `ember`, `ocean`, `moss`, `graphite`, `ink`, `plum` | curated accent family |
+| `seed` | hex color, for example `#2f6f8f` | derives the accent, tinted surfaces, and figure fills; lightness is corrected until the accent clears WCAG contrast against the page |
+| `type` | papers: `classic`, `editorial`, `technical`; console: `mono`, `hybrid`, `terminal` | curated font stacks, no web fonts |
+| `density` | `compact`, `normal`, `roomy` | body size, leading, figure margins, panel height |
+| `figure` | `outline`, `solid`, `minimal` | diagram fill and stroke; `minimal` also drops chart gridlines |
+| `layout` | `columns`, `single` | paper themes only: two columns by default, or one reading column for code and wide tables |
+
+`meta.accent` remains available as a direct accent override.
+Invalid tokens fail validation at `meta.style`.
+
+## Looks and designed drafts
+
+Three themes set the structure: `paper-light`, `paper-dark`, and `hud`.
+Curated looks sit on a structure with their own palette and type: `field-notes` and `editorial` on `paper-light`, `blueprint` on `paper-dark`.
+A look is only a palette and a short stylesheet, so blocks, figures, timelines, and print behave exactly like the base theme.
+
+`ingest --draft` designs the doc from its source.
+Code-heavy sources get `blueprint`, papers get `paper-light`, long prose gets `editorial`, short notes get `field-notes`, and the rest get `paper-dark`.
+Paper themes also get an accent seed derived from the title, and density follows length.
+The draft writes these as ordinary `meta.style` tokens, so edit them freely.
+Pass `--theme` or `--seed` to override the choice.
+
+## Motion
+
+Motion has two layers.
+
+`figure.motion` animates one generated figure with `draw`, `reveal`, or `steps`.
+It is scoped CSS on the SVG, freezes for print, and disables under `prefers-reduced-motion`.
+The content stays visible while the animation runs.
+
+The console theme also animates its graph, pulse, and clock.
+Those animations are theme owned, not tokens.
+
+## Example
+
+```json
+{
+  "meta": {
+    "title": "Example",
+    "style": {
+      "seed": "#2f6f8f",
+      "type": "editorial",
+      "density": "roomy",
+      "figure": "minimal"
+    }
+  }
+}
+```
+
+## See also
+
+- [Document model](document-model.md)
+- [Guarantees](guarantees.md)

package/docs/guide/timeline.md

@@ -0,0 +1,75 @@
+# Timeline and video
+
+A timeline makes a doc move in step with its own text.
+Cues highlight a source sentence, light up the figure part it describes, count numbers up, type text out, and scroll the video frame to a block.
+The same timeline plays on the live page and records to MP4, WebM, or GIF.
+
+## Marks and ids
+
+Wrap a sentence in any prose string, the abstract included, with `[[mark:id|text]]`.
+Give any block an `id` so cues can point at it.
+Ids use lowercase letters, digits, and hyphens, and must be unique.
+
+```json
+{ "type": "figure", "id": "loop", "caption": "...", "spec": "diagram", "diagram": { "nodes": [{ "id": "editor", "label": "4B editor", "x": 552, "y": 28 }] } }
+```
+
+## Cues
+
+`timeline.cues` is a list of `{ at, dur, do, target }`.
+`at` and `dur` are seconds; `dur` defaults to 1.2.
+
+| `do` | What it does |
+| --- | --- |
+| `highlight` | Sweeps a highlighter across a mark or block, then leaves a faint underline. |
+| `focus` | Outlines a block or part and dims its siblings. The glow stays inside the block. |
+| `reveal` | Fades a block or part in at the cue time, without moving it. |
+| `count` | Counts the numbers inside the target up from zero. |
+| `type` | Types the target's text out. The full text keeps its space, so nothing reflows. |
+| `camera` | Video only: scrolls the frame to a block or part, or back to `page`. The page stays flat at 100%; `zoom` is an opt-in that scales it. |
+| `activate` | HUD only: glides the scene crosshair to a label. |
+
+Targets are `mark:<id>`, `<blockId>`, `<blockId>/<part>`, or `page` for the camera.
+A part is a diagram node id, a panel index such as `08`, or a scene label.
+Validation rejects a cue whose target does not exist.
+
+`timeline.duration` defaults to the last cue end plus 1.5 seconds.
+`timeline.loop` restarts the live page when it ends; reveals, counts, and typing stay settled after the first pass.
+On the live page, a block whose cue comes up while it is still below the fold waits, with its cues in order, until the reader scrolls to it.
+
+## Drafted cues
+
+`ingest --draft` writes a timeline from the source: up to four abstract sentences and five section leads are marked and highlighted in reading order, the frame scrolls to each lead, and stats count up.
+Pass `--static` for a draft without cues.
+Edit or replace the drafted cues like any other part of the model.
+
+## Video
+
+```bash
+living-docs-axi render docs/notes.model.json --format mp4 -o docs/notes.mp4
+living-docs-axi render docs/notes.model.json --format gif --size 1080x1350 --fps 30
+```
+
+The renderer lays the doc out on a fixed stage, seeks the timeline frame by frame in headless Chromium, and pipes the frames to ffmpeg.
+Every frame is a pure function of time, so two renders on one machine produce the same frames.
+MP4 is the default for sharing; GIF is 720 wide at 15 fps for READMEs.
+Video needs the optional `playwright` package with Chromium, and `ffmpeg` on `PATH` or in `LIVING_DOCS_FFMPEG`.
+In a project, run `npm i -D playwright`; with npx, add it to the same call:
+
+```bash
+npx -y -p living-docs-axi -p playwright living-docs-axi render notes.model.json --format mp4
+npx playwright install chromium
+```
+
+## Driving a live doc from another page
+
+A same-origin page that embeds a timed doc in an iframe can take over its clock through `window.__ld`.
+`pause()` hands the clock to the host, and `seek(t)` then renders the frame at `t` seconds.
+`play()` resumes from the last shown time, `replay()` restarts from zero, and `time()` reads the current time.
+The home page of this site pins one doc and scrubs it as the reader scrolls.
+The controls exist only on a live page; under reduced motion, in print, and in video capture the doc shows its final state or seeks per frame, so a host should check that `pause` is a function first.
+
+## Accessibility and print
+
+Under `prefers-reduced-motion`, print, or with scripts off, the page shows its final state: everything revealed, counted, and typed, with narrated sentences underlined.
+Docs without a timeline ship no runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbybrandon/living-docs",
-  "version": "0.3.0",
+  "version": "0.3.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",
@@ -40,6 +40,7 @@
     "bin",
     "src",
     "samples",
+    "docs/guide",
     "README.md",
     "LICENSE"
   ],

package/src/export/video.js

@@ -33,7 +33,7 @@ async function loadChromium() {
   } catch {
     throw new ExportError('video export needs the optional playwright package', {
       code: 'missing-playwright',
-      hint: 'install playwright beside living-docs (npm i -D playwright, or npx -p @bytesbybrandon/living-docs -p playwright living-docs-axi ...), then npx playwright install chromium'
+      hint: 'install playwright beside living-docs (npm i -D playwright, or npx -y -p living-docs-axi -p playwright living-docs-axi ...), then npx playwright install chromium'
     });
   }
 }

package/src/model/schema.js

@@ -382,19 +382,31 @@ export const THEMES = {
   }
 };
 
+function describeField(name, spec) {
+  return {
+    name,
+    kind: spec.kind,
+    required: !spec.optional,
+    desc: spec.desc,
+    ...(spec.values ? { values: spec.values } : {}),
+    ...(spec.of ? { of: spec.of.kind } : {})
+  };
+}
+
+// Nested object fields are listed under dotted paths and array items under `[]`,
+// so `diagram.nodes[].x` is discoverable without reading the source.
+function flattenFields(fields, prefix = '') {
+  return Object.entries(fields).flatMap(([name, spec]) => {
+    const path = `${prefix}${name}`;
+    const row = describeField(path, spec);
+    const inner = spec.kind === 'object' ? spec : spec.kind === 'array' && spec.of?.kind === 'object' ? spec.of : null;
+    if (!inner) return [row];
+    return [row, ...flattenFields(inner.fields, `${path}${spec.kind === 'array' ? '[].' : '.'}`)];
+  });
+}
+
 export function blockFieldSummary(type) {
   const block = BLOCKS[type];
   if (!block) return null;
-  return {
-    type,
-    summary: block.summary,
-    fields: Object.entries(block.fields).map(([name, spec]) => ({
-      name,
-      kind: spec.kind,
-      required: !spec.optional,
-      desc: spec.desc,
-      ...(spec.values ? { values: spec.values } : {}),
-      ...(spec.of ? { of: spec.of.kind } : {})
-    }))
-  };
+  return { type, summary: block.summary, fields: flattenFields(block.fields) };
 }