vizmatic 0.8.1 → 0.8.3

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 (97) hide show
  1. package/PROMPT.md +10 -9
  2. package/README.md +167 -61
  3. package/ROADMAP.md +5 -4
  4. package/SCIENCE.md +1 -2
  5. package/assets/THIRD_PARTY_LICENSES.md +3 -3
  6. package/assets/fonts/SourceSerif4-24pt-SemiBold.ttf +0 -0
  7. package/assets/licenses/raster-codecs-MIT.txt +2 -2
  8. package/dist/{chunk-ZB3HK7RM.js → chunk-4MXGLMBG.js} +274 -24
  9. package/dist/chunk-GGFDBJ25.js +88 -0
  10. package/dist/{chunk-6H2KTNJ7.js → chunk-I745F4QK.js} +2322 -357
  11. package/dist/{chunk-DZHX76RS.js → chunk-JZPMGVBP.js} +32 -3
  12. package/dist/cli.js +443 -126
  13. package/dist/index.cjs +1055 -98
  14. package/dist/index.d.cts +216 -4
  15. package/dist/index.d.ts +216 -4
  16. package/dist/index.js +734 -63
  17. package/dist/scene-browser-chunks/chunk-RQNLYYJN.js +70 -0
  18. package/dist/scene-browser-chunks/{scene-browser-layout-M3XSXMV4.js → scene-browser-layout-RC3ECYRK.js} +1 -1
  19. package/dist/scene-browser.js +16 -16
  20. package/dist/scene-cli.js +1 -1
  21. package/dist/scene-runtime.cjs +24 -3
  22. package/dist/scene-runtime.js +1 -1
  23. package/dist/{server-2FYHZ4UO.js → server-Q4COUZHV.js} +3 -3
  24. package/dist/stage-browser/browser.d.ts +8240 -315
  25. package/dist/stage-browser/stage.js +22 -5
  26. package/dist/stage-export.cjs +3620 -329
  27. package/dist/stage-export.d.cts +56 -3
  28. package/dist/stage-export.d.ts +56 -3
  29. package/dist/stage-export.js +659 -180
  30. package/dist/stage.cjs +33026 -7554
  31. package/dist/stage.d.cts +7809 -286
  32. package/dist/stage.d.ts +7809 -286
  33. package/dist/stage.js +26066 -2599
  34. package/dist/{svg-import-C-RG1t7s.d.cts → svg-import-B5BGbC1t.d.cts} +455 -53
  35. package/dist/{svg-import-C-RG1t7s.d.ts → svg-import-B5BGbC1t.d.ts} +455 -53
  36. package/dist/{video-BSwNJZkn.d.cts → video-CiN1MDCS.d.cts} +27 -2
  37. package/dist/{video-BSwNJZkn.d.ts → video-CiN1MDCS.d.ts} +27 -2
  38. package/examples/README.md +1 -1
  39. package/examples/_teaching/layer-stack-connector.ts +36 -0
  40. package/examples/_teaching/layer-stack-recurrence.ts +29 -0
  41. package/examples/_teaching/layer-stack-tiny-gpt.ts +37 -0
  42. package/examples/_teaching/layer-stack-transformer.ts +44 -0
  43. package/examples/catalog-convolution-kernel.tsx +6 -7
  44. package/examples/{aurora-incident.tsx → checkout-incident.tsx} +1 -1
  45. package/examples/films/beam-search.ts +52 -0
  46. package/examples/films/cache-miss.ts +4 -3
  47. package/examples/films/catalog.json +30 -0
  48. package/examples/films/forecast.ts +354 -0
  49. package/examples/films/passage/chunking.ts +40 -0
  50. package/examples/films/passage/evidence.ts +44 -0
  51. package/examples/films/passage/prompt.ts +34 -0
  52. package/examples/films/paxos.ts +596 -0
  53. package/examples/films/taylor-series.ts +1 -1
  54. package/examples/narrated-cues/README.md +32 -0
  55. package/examples/narrated-cues/data/numbers.json +1 -0
  56. package/examples/narrated-cues/film.json +9 -0
  57. package/examples/narrated-cues/film.ts +78 -0
  58. package/examples/narrated-cues/package.json +1 -0
  59. package/examples/narrated-cues/script.json +57 -0
  60. package/examples/narrated-cues/timing.json +1 -0
  61. package/examples/narrated-cues/tsconfig.json +1 -0
  62. package/examples/proofs/decoding-bars.ts +67 -0
  63. package/examples/proofs/pipeline.ts +27 -0
  64. package/examples/proofs/table/evaluation.ts +41 -0
  65. package/examples/proofs/table/ledger.ts +47 -0
  66. package/examples/proofs/table/routing.ts +46 -0
  67. package/package.json +9 -4
  68. package/templates/narrated/README.md +61 -0
  69. package/templates/narrated/data/numbers.json +5 -0
  70. package/templates/narrated/film.json +12 -0
  71. package/templates/narrated/film.ts +14 -0
  72. package/templates/narrated/gitignore +8 -0
  73. package/templates/narrated/package.json +1 -0
  74. package/templates/narrated/scenes/answer.ts +25 -0
  75. package/templates/narrated/scenes/kit.ts +39 -0
  76. package/templates/narrated/scenes/question.ts +31 -0
  77. package/templates/narrated/script.json +26 -0
  78. package/templates/narrated/sources.md +22 -0
  79. package/templates/narrated/timing.json +1 -0
  80. package/templates/narrated/tsconfig.json +1 -0
  81. package/tools/narration/README.md +123 -0
  82. package/tools/narration/beats.py +43 -0
  83. package/tools/narration/checks.py +587 -0
  84. package/tools/narration/draft.py +73 -0
  85. package/tools/narration/film.py +341 -0
  86. package/tools/narration/lag.py +58 -0
  87. package/tools/narration/mix.py +265 -0
  88. package/tools/narration/probe.py +99 -0
  89. package/tools/narration/record.py +33 -0
  90. package/tools/narration/resound.py +170 -0
  91. package/tools/narration/soundbed.py +404 -0
  92. package/tools/narration/sync.py +93 -0
  93. package/tools/narration/transcribe.py +84 -0
  94. package/tools/narration/verify.py +59 -0
  95. package/tools/narration/voice.py +113 -0
  96. package/dist/chunk-6N6P2GJG.js +0 -88
  97. package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +0 -70
package/PROMPT.md CHANGED
@@ -15,10 +15,11 @@ For pnpm 11, allow esbuild's install script with `allowBuilds: { esbuild: true }
15
15
 
16
16
  ## Films
17
17
 
18
- Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
18
+ Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, `deck`, and `narrated`.
19
19
 
20
20
  ```bash
21
21
  npx vizmatic new intro --template explainer
22
+ npx vizmatic new lesson --template narrated
22
23
  ```
23
24
 
24
25
  ```ts
@@ -60,7 +61,7 @@ Rules of the engine:
60
61
 
61
62
  ### Check, look, and export
62
63
 
63
- An agent cannot watch a video, so judge a film from the check and from stills.
64
+ Use checks and stills to inspect the picture. Play the export at normal speed with sound to judge the rhythm and the way motion meets speech.
64
65
 
65
66
  ```bash
66
67
  npx vizmatic check intro.ts --json
@@ -68,11 +69,11 @@ npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
68
69
  npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
69
70
  ```
70
71
 
71
- `vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review. The [Studio](https://bvolpato.github.io/vizmatic/studio.html) is a visual film editor in the browser for a person who wants to edit by hand.
72
+ `vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_edge`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review. The [Studio](https://bvolpato.github.io/vizmatic/studio.html) is a visual film editor in the browser for a person who wants to edit by hand.
72
73
 
73
- The check does not look at motion, so a crossfade where two sentences overlap and a blank gap between two pictures both pass it. Add `--motion` to inspect every frame: `npx vizmatic check intro.ts --motion --json`. It reports a problem that appears only in motion as a warning, and 0.2 seconds or more with nothing visible as `film.blank`. Judge each warning, because the check cannot tell a collision from one picture that replaces another. `--content-top <px>` sets where the content starts, so that a heading that stays up does not hide a blank.
74
+ The check does not look at motion, so a crossfade where two sentences overlap and a blank gap between two pictures both pass it. Add `--motion` to inspect every frame: `npx vizmatic check intro.ts --motion --json`. It reports a problem that appears only in motion as a warning, 0.2 seconds or more with nothing visible as `film.blank`, and text that leaves before a viewer can read it as `film.text_brief`. Judge each warning, because the check cannot tell a collision from one picture that replaces another. `--content-top <px>` sets where the content starts, so that a heading that stays up does not hide a blank. `--text-gap 0.3` also reports `film.text_crowded`: text that is nearer to a line, a shape, or an image than 0.3 of its font size, such as a caption that touches its figure, and text that runs past the edge of the shape behind it. `--text-size 26` flags unreadable small labels, `--empty-space 0.5` flags persistent large unused canvas areas, and `--stepped` checks chapter-stepped decks.
74
75
 
75
- `--audio narration.wav` adds sound, padded or trimmed to the film's length, so hold until the voice ends. `s.caption(text, seconds)` writes a WebVTT file beside the video and draws nothing into the picture. MP4 output is H.264 with settings that QuickTime can play. To join a clip to a film without encoding it again, encode the clip with `filmEncoderSettings(quality)` from `vizmatic/stage/export`.
76
+ `--audio narration.wav` adds sound, padded or trimmed to the film's length, so hold until the voice ends. `s.caption(text, seconds)` writes a WebVTT sidecar and embeds a timed text track inside MP4 output while drawing nothing into the picture. For spoken lessons with `script.json`, `vizmatic narrated` (`build`, `voice`, `draft`, `mix`, `check`, `stills`, `sheet`, `beats`, `transcribe`, `sync`, `lag`, `probe`, `resound`) synthesizes per-beat takes, mixes background pads and cues (`vizmatic sounds list|export|bed`), checks every frame, and verifies voice-to-picture alignment. MP4 output is H.264 with settings that QuickTime can play. To join a clip to a film without encoding it again, encode the clip with `filmEncoderSettings(quality)` or `renderNarrationHold` from `vizmatic/stage/export`.
76
77
 
77
78
  Motion guidance:
78
79
 
@@ -86,11 +87,11 @@ Motion guidance:
86
87
  When a film must teach a topic, [lessons.md](https://bvolpato.github.io/vizmatic/references/lessons.md) has the full method. In short:
87
88
 
88
89
  - Put accuracy first, then completeness, clarity, and brevity. There is no target length, so keep every passage that teaches.
89
- - Finish the script before the film. Teach the problem, then the mechanism, then the limits. Keep one worked example throughout.
90
- - Compute every number in the film, and check it with `assert`. The voice and the screen use the same values and the same rounding.
90
+ - Finish the script before the film. Teach the problem, then the mechanism, then the limits. Carry a small example across a change when continuity helps. Switch examples when a fresh picture makes the next idea easier to see.
91
+ - Compute every number in the film, and check it with `assertEqual` from `'vizmatic/stage'` (never Node's `assert`, which breaks browser preview). The voice and the screen use the same values and the same rounding.
91
92
  - Keep each title true for as long as it is visible. List every text block with its visible times, and read each one against the picture and the voice.
92
93
  - Change pictures cleanly. Old text drops under about 25% opacity before new text reaches it, and something stays on screen through the change.
93
- - A person must watch the film at full speed with sound before it is published. You cannot do this, so say that it has not happened.
94
+ - Before publication, a person must watch the film at full speed with sound. Report which passages were played with sound and whether this full viewing has happened.
94
95
  - Use the computed states from `vizmatic` where they fit: `weightedVectorState`, `categoricalSampling`, `planTeachingRoutedTransfer`, `byteDifferenceState`, and `tokenHistoryState`. Show the limits of each. `check` and `film` accept this import, and `preview` refuses it because it runs in the browser. A project with a checked canvas host can use the same constructions through `createTeachingCanvas(painter)`.
95
96
 
96
97
  Read a finished film before you write a similar one. `examples/films/` in the package holds them with full source, and the [Films](https://bvolpato.github.io/vizmatic/films.html) page plays them.
@@ -157,4 +158,4 @@ After creating a visual, report:
157
158
  - whether `vizmatic check` passed
158
159
  - any overflow or layout fixes made
159
160
  - for a film, which stills you opened, and whether you scanned the motion
160
- - anything you could not verify, including that nobody has watched the film with sound
161
+ - what you checked in stills, what you checked in playback, and any remaining review
package/README.md CHANGED
@@ -3,31 +3,35 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- <strong>Explain things in motion, from code.</strong><br/>
7
- Vector films that play live in a browser and export frame-exact to MP4. Dense technical figures from TSX.
6
+ <strong>Explain mechanisms in motion and in print, from TypeScript.</strong><br/>
7
+ Vector films with relational layout, TeX, and local narration that play live in the browser and export frame-exact to MP4.<br/>
8
+ Dense dark and light technical figures from TSX.
8
9
  </p>
9
10
 
10
11
  <p align="center">
11
12
  <a href="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml"><img src="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
12
13
  <a href="https://www.npmjs.com/package/vizmatic"><img src="https://img.shields.io/npm/v/vizmatic?color=%2334d058" alt="npm version" /></a>
14
+ <img src="https://img.shields.io/badge/node-%3E%3D20-43853d" alt="Node >= 20" />
13
15
  <a href="https://github.com/bvolpato/vizmatic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
14
16
  </p>
15
17
 
16
18
  <p align="center">
17
- <a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/fourier-epicycles.png" alt="A still from a Vizmatic film: rotating circles trace a curve" width="820" /></a>
19
+ <a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/fourier-epicycles.png" alt="A still from a Vizmatic film: rotating Fourier epicycles trace a curve" width="840" /></a>
18
20
  </p>
19
21
 
20
22
  <p align="center">
21
23
  <a href="https://bvolpato.github.io/vizmatic/films.html">Films</a> ·
22
24
  <a href="https://bvolpato.github.io/vizmatic/docs/">Docs</a> ·
23
25
  <a href="https://bvolpato.github.io/vizmatic/studio.html">Studio</a> ·
26
+ <a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
24
27
  <a href="https://bvolpato.github.io/vizmatic/components.html">Components</a> ·
28
+ <a href="https://bvolpato.github.io/vizmatic/examples.html">Examples</a> ·
25
29
  <a href="https://bvolpato.github.io/vizmatic/agents.html">For agents</a>
26
30
  </p>
27
31
 
28
- ## A film in 15 lines
32
+ ## Quick start: a film in 19 lines
29
33
 
30
- Vizmatic needs Node.js 20 or newer. MP4 export also needs [FFmpeg](https://ffmpeg.org/download.html).
34
+ Vizmatic requires Node.js 20 or newer. MP4 and WebM export also require [FFmpeg](https://ffmpeg.org/download.html).
31
35
 
32
36
  ```bash
33
37
  npm install vizmatic
@@ -36,51 +40,117 @@ npm install vizmatic
36
40
  Create `intro.ts`:
37
41
 
38
42
  ```ts
39
- import { axes, draw, fadeIn, film, tex, write } from 'vizmatic/stage'
43
+ import { axes, column, draw, fadeIn, film, place, sceneKit, tex, write } from 'vizmatic/stage'
44
+
45
+ export default film({ title: 'A parabola and its equation', font: 'text-serif' }, (s) => {
46
+ const { area, heading, note } = sceneKit()
47
+ const [left, right] = area.columns([2, 1])
48
+
49
+ s.add(heading('A parabola and its equation'))
50
+ const plot = place(axes({ x: [-3, 3], y: [-1, 9], width: 1000, height: 640, grid: true, labelSize: 28 }), left)
51
+ const eq = tex('y = x^2', { size: 84 })
52
+ const caption = note('slope doubles with x')
53
+ place(column([eq, caption], { gap: 'normal' }), right)
40
54
 
41
- export default film({ title: 'My first film' }, (s) => {
42
- const plot = s.add(axes({ x: [-3, 3], y: [-1, 9], grid: true }).at(-240, 40))
43
55
  s.play(draw(plot.grid, { lag: 0.02 }), draw(plot.lines), fadeIn(plot.numbers))
44
- s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5 })))
45
- s.play(write(s.add(tex('y = x^2', { size: 72 }).at(600, -200))))
46
- s.wait(1)
56
+ s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5, glow: 6 })))
57
+ s.play(write(eq), fadeIn(caption))
58
+ s.wait(1.5)
47
59
  })
48
60
  ```
49
61
 
50
- Then watch it, check it, and export it:
62
+ Preview, check, inspect stills, and export:
51
63
 
52
64
  ```bash
53
- npx vizmatic preview intro.ts # live player with a timeline. Reloads when you save.
54
- npx vizmatic check intro.ts # finds clipped text, overlaps, and strokes through labels
55
- npx vizmatic film intro.ts --out dist # 1080p60 MP4
65
+ npx vizmatic preview intro.ts # live browser player with timeline, reloads on save
66
+ npx vizmatic check intro.ts --motion # static + per-frame collision, blank, and pacing scan
67
+ npx vizmatic film intro.ts --every 2 --sheet --out stills # timestamped contact sheet for visual review
68
+ npx vizmatic film intro.ts --look midnight,paper --quality high --out dist
56
69
  ```
57
70
 
58
- `npx vizmatic new intro --template architecture` starts from a working film. The templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
71
+ Scaffold a working project with `npx vizmatic new intro --template explainer`. Built-in templates are `explainer`, `equation`, `architecture`, `chart`, `deck`, and `narrated`.
72
+
73
+ <table>
74
+ <tr>
75
+ <td width="50%" align="center">
76
+ <a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/attention.png" alt="Attention weights computed from real token vectors" /></a><br/>
77
+ <sub><strong>Scaled dot-product attention</strong> · computed weights, TeX, and live readouts</sub>
78
+ </td>
79
+ <td width="50%" align="center">
80
+ <a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/cache-miss.png" alt="Cache hit and miss latency simulation" /></a><br/>
81
+ <sub><strong>Cache hit vs. database miss</strong> · queueing model, connectors, and system boxes</sub>
82
+ </td>
83
+ </tr>
84
+ </table>
85
+
86
+ ## Domain objects on stage
59
87
 
60
- ## What makes it different
88
+ Instead of assembling raw rectangles and coordinates for every explanation, `vizmatic/stage` includes relational layout and domain objects that measure their own labels, animate state transitions, and fail the build with actionable guidance when text does not fit. Run `npx vizmatic objects` to inspect the full catalog:
61
89
 
62
- **Everything on stage is real geometry.** Lines, glyphs, equations, and grids are all Bezier paths. Any shape can trace itself, morph into any other shape, or bend through a function. Equations use TeX glyphs, and `morphMatching` moves the shared terms from one line of a derivation to the next.
90
+ - **Layout and framing**: `sceneKit`, `sceneArea`, `row`, `column`, `grid`, `place`, `beside`, `between`, `fitted`, `boxOf`, `zone`, `card`, `steps`, `spotlight`, `tagTrack`.
91
+ - **Math, plots, and 3D**: `axes` (moving windows, `band`, `marker`), `plane` (`applyMatrix`), `numberLine`, `complexPlane`, `projectionMark`, `vectorField`, `streamLines`, `riemann`, `areaUnder`, `matrix`, `matrixProduct`, `fourier`, `epicycles`, `tex` (`morphMatching`), `scene3d` (`surface`, `parametricSurface`, `curve3d`, `point3d`, `trail3d`).
92
+ - **Systems, queues, and code**: `lanes` (actor timelines, child spans, deadlines, outages, boundary crossings), `pipeline` (stage gates, verdicts, counts, eject tray), `requestQueue`, `ringBuffer`, `boundary`, `stateGrid`, `bitField`, `eventLog`, `terminal`, `codeBlock` (including JSON, YAML, TLA+, Dafny, Lean, and SMT), `morphCode`, `connector` (`pulse`, `send`), `infoBox`, `pictogram` (57+ technical icons).
93
+ - **Models, data, and prose**: `layerStack`, `tokens`, `attentionMatrix`, `neuralNet`, `heatmap`, `barChart`, `histogram`, `scatter` (cells, hulls, k-NN), `dotChart` (linear or log), `segmentedBar`, `unitChart`, `lineChart`, `pie`, `donut`, `sparkline`, `table`, `passage` (claim marks, source links, diffs, chunking), `quote`, `quotePair`, `dateLine`.
63
94
 
64
- **A film is a pure function of time.** The build function runs once and writes a timeline. Any frame can then be sampled at any time, in any order. Scrubbing is instant, and identical input gives identical frames.
95
+ ## Narrated lessons and sound
65
96
 
66
- **One film, two destinations.** The same source paints live on a canvas with `<vz-film>`, and renders to MP4, WebM, GIF, PNG, or SVG in Node. Frames rasterize on worker threads, with real motion blur and bloom when you ask for them.
97
+ For lessons driven by a voiceover, `--template narrated` creates a self-contained folder with `script.json`, `film.json`, `film.ts`, and `scenes/`. One incremental command synthesizes speech locally, mixes audio, checks layout, and renders the movie:
98
+
99
+ ```bash
100
+ npx vizmatic new cache-lesson --template narrated
101
+ npx vizmatic narrated build cache-lesson --draft # local voice, sound mix, layout check, cache-lesson-draft.mp4
102
+ npx vizmatic narrated build cache-lesson # full delivery render with MP4 chapters and captions
103
+ ```
67
104
 
68
- **It looks right by default.** Five looks set the background, ink, pigments, and light. Authors write `color: 'yellow'`, so one film renders in `midnight`, `paper`, `blueprint`, `chalk`, and `neon`.
105
+ Scenes lock visual changes directly to spoken phrases through `SceneClock`. If the script changes and a phrase disappears or occurs twice, the build stops with the exact scene and phrase rather than drifting out of sync:
106
+
107
+ ```ts
108
+ import { assertEqual, narrated, place, type SceneClock, type Stage } from 'vizmatic/stage'
109
+ import timing from './timing.json'
110
+ import { claimTag, display, heading, kit, source } from './scenes/kit'
111
+
112
+ assertEqual(800 / 5, 160, 'speedup matches the spoken claim')
113
+
114
+ function answer(s: Stage, c: SceneClock) {
115
+ s.add(heading('With a cache in front'), source('Measured on warm hits'))
116
+ claimTag(c, { word: 'MEASURED', note: 'local benchmark' })
117
+ const speedup = place(display('160x faster'), kit.area)
118
+ c.show('one hundred and sixty times', speedup, { after: true })
119
+ }
120
+
121
+ export default narrated({ title: 'Why a cache matters', timing, scenes: { answer } })
122
+ ```
69
123
 
70
- **Figures pack information.** The TSX components default to the `dense` density: small type, hairlines, and tight gutters, like a figure in a good engineering paper. Set `density="presentation"` to use the same source on a slide.
124
+ Verify speech, cues, and sound from the CLI (`npx vizmatic narrated` lists every step):
71
125
 
72
- **Defects come back as data.** `vizmatic check --json` reports problems with their times and bounding boxes, so a coding agent can find and fix them without watching anything.
126
+ - `vizmatic narrated beats <folder> --words` prints beat windows and spoken words to pick cues.
127
+ - `vizmatic narrated stills <folder>` and `sheet <folder>` render per-beat full-resolution stills and contact sheets.
128
+ - `vizmatic narrated transcribe <folder>`, `sync <folder>`, `lag <folder>`, and `probe <folder>` verify TTS pronunciation against `script.json`, measure audio-to-video alignment, and inspect streams, chapters, captions, and file hashes.
129
+ - `vizmatic narrated resound <folder>` swaps an updated `narration.wav` into a rendered MP4 without re-rendering frames.
130
+ - `vizmatic sounds list`, `vizmatic sounds render <tap|slide|latch|resolve|bell> --out cue.wav`, and `vizmatic sounds bed --voice narration.wav --out bed.wav --palette warm --timing timing.json` generate subtle cues and ducked stereo beds.
73
131
 
74
- ## Figures
132
+ Read the [narrated films guide](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) for the full workflow.
75
133
 
76
- Render a TSX figure in each theme:
134
+ ## Dense figures from TSX
135
+
136
+ For documentation, papers, architecture reviews, and slides, write TSX with typed components from `vizmatic`. Figures default to the `dense` density (10 to 12 px detail type, hairlines, and tight gutters) and render dark and light PNG and SVG from one source.
137
+
138
+ <p align="center">
139
+ <a href="https://bvolpato.github.io/vizmatic/examples.html">
140
+ <picture>
141
+ <source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" />
142
+ <source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_light.png" />
143
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" alt="Data pipeline lineage figure rendered from TSX" width="840" />
144
+ </picture>
145
+ </a>
146
+ </p>
77
147
 
78
148
  ```tsx
79
- <Scene title="Checkout, read path">
149
+ <Scene title="Checkout read path" subtitle="Envoy -> Cart -> Orders replica">
80
150
  <Flow
81
151
  stages={[
82
152
  { title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
83
- { title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
153
+ { title: "Cart service", subtitle: "Go, 840 rps", tone: "purple" },
84
154
  { title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
85
155
  ]}
86
156
  />
@@ -88,63 +158,99 @@ Render a TSX figure in each theme:
88
158
  ```
89
159
 
90
160
  ```bash
91
- npx vizmatic ./frame.tsx --out ./figures --theme dark,light --format both
161
+ npx vizmatic check ./frame.tsx --theme dark,light --json
162
+ npx vizmatic render ./frame.tsx --out ./figures --theme dark,light --format both
92
163
  ```
93
164
 
94
- Read [Diagrams and density](https://bvolpato.github.io/vizmatic/docs/diagrams.html) and the [figures reference](https://bvolpato.github.io/vizmatic/docs/figures.html), or browse the [component catalog](https://bvolpato.github.io/vizmatic/components.html).
165
+ - Omit `width` and `height` while iterating: bare `.tsx` frames start at `960x540` and auto-grow to fit content.
166
+ - Outputs are alpha-transparent by default; pass `--background theme` (or `background={c.bg}`) for an opaque canvas, and `preset = "engineering";` with `--theme light` for flat technical paper figures.
167
+ - Switch to `density="presentation"` (or `--density presentation`) when placing the same scene on a slide.
168
+ - Convert existing Mermaid or D2 diagrams into `GraphDiagram` props with `importMermaid` and `importD2`, or animate existing TSX figures to GIF and MP4 with `defineAnimation` (`vizmatic gif` and `vizmatic video`).
95
169
 
96
- ## Teaching with a checked canvas
170
+ Browse the [component catalog](https://bvolpato.github.io/vizmatic/components.html), [examples gallery](https://bvolpato.github.io/vizmatic/examples.html), and [interactive playground](https://bvolpato.github.io/vizmatic/playground.html).
97
171
 
98
- `createTeachingCanvas(painter)` composes animated explanations through your host's checked drawing methods. Its components return computed state so labels and geometry follow the same calculation. Bind progress and answer reveals separately to the narration.
172
+ ## What makes Vizmatic different
99
173
 
100
- | Component | A worked example |
101
- |---|---|
102
- | `vectorAccumulation` | [Retain momentum, add an opposing gradient, then reveal the resultant](examples/_teaching/teaching-weighted-vector.ts) |
103
- | `categoricalSampling` | [Watch a rare category disappear from a supplied finite sample](examples/_teaching/categorical-tail-loss.ts) |
104
- | `routedTransfer` | [Carry a value around visible obstacles](examples/_teaching/teaching-routed-transfer.ts) |
105
- | `byteDifference` | [Locate a changed byte while retaining offsets and escaped control characters](examples/_teaching/teaching-byte-diff.ts) |
106
- | `tokenHistory` | [Drop and rebuild KV while preserving accepted and emitted tokens](examples/_teaching/teaching-token-history.ts) |
174
+ - **Real geometry on stage.** Lines, glyphs, TeX equations, and grids are Bezier paths. Any path can draw itself, morph into another shape, or bend through a function, and `morphMatching` carries shared terms cleanly across steps of a derivation.
175
+ - **Pure function of time.** A film compiles once into a deterministic timeline that can be sampled at any timestamp in any order. Scrubbing is instant, identical frames share buffers automatically, and worker threads rasterize in parallel with optional motion blur and dithered bloom.
176
+ - **Five looks and two figure themes.** Films author against semantic tokens (`blue`, `teal`, `yellow`, `ink`, `dim`) and render across `midnight`, `paper`, `blueprint`, `chalk`, and `neon`. TSX figures render coordinated `dark` and `light` palettes.
177
+ - **Defects reported as structured data.** `vizmatic check --json` and `vizmatic check --motion --json` return clipped text, edge crowding (`--text-gap`), phone-unreadable type (`--text-size`), empty regions (`--empty-space`), strokes crossing text, brief flashes, and blank gaps with exact timestamps and bounding boxes.
178
+ - **Live web playback, visual Studio, and QuickJS sandboxing.** Embed live, seekable films anywhere with `<vz-film>` (including `<vz-film stepped>` for chapter decks), edit visually in [Studio](https://bvolpato.github.io/vizmatic/studio.html), or evaluate untrusted bare TSX inside a deterministic offline QuickJS sandbox via `vizmatic/scene-runtime` and `vizmatic-scene`.
179
+
180
+ ## CLI at a glance
107
181
 
108
- Each example supplies its own data and timing. Inspect prediction frames, moving states, and settled results at the delivery resolution. The [canvas guide](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) describes the painter contract and component limits.
182
+ | Command | Purpose |
183
+ |---|---|
184
+ | `vizmatic new <name> [--template ...]` | Scaffold a film (`explainer`, `equation`, `architecture`, `chart`, `deck`, or `narrated`) |
185
+ | `vizmatic preview <file> [--port <n>] [--open]` | Live browser player with timeline scrubbing and hot reload |
186
+ | `vizmatic check <file-or-dir...> [--motion] [--json]` | Check films (`--motion`, `--text-gap`, `--text-size`, `--empty-space`, `--stepped`) or TSX frames (`--theme dark,light`) |
187
+ | `vizmatic film <file...> [--out <dir>]` | Export MP4, WebM, GIF, PNG stills (`--frame`, `--every`, `--sheet`), SVG, posters, captions, and chapters |
188
+ | `vizmatic narrated <step> <folder>` | Build, voice, mix, check, stills, sheet, beats, transcribe, sync, lag, probe, or resound narrated lessons |
189
+ | `vizmatic objects [--json]` / `vizmatic looks [--json]` | List stage domain objects and color looks |
190
+ | `vizmatic sounds <list\|render\|bed>` | List or synthesize sound effects and ducked stereo ambient beds |
191
+ | `vizmatic [render] <file-or-dir...>` | Render TSX figures to dark/light PNG and SVG (`--density`, `--background`, `--format png\|svg\|both`) |
192
+ | `vizmatic gif <file...>` / `vizmatic video <file...>` | Render animated TSX timelines (`createAnimation`) to GIF or MP4 |
193
+ | `vizmatic-scene --input req.json --output out.png\|out.mp4` | Render untrusted bare TSX inside the bounded QuickJS scene sandbox |
194
+
195
+ ## Checked teaching helpers
196
+
197
+ For custom hosts and verified mechanism animations, Vizmatic exports pure state calculators (`vizmatic`), audio hold tools (`vizmatic/stage/export`), and `createTeachingCanvas(painter)` methods so displayed numbers and geometry come from one checked calculation:
198
+
199
+ | Helper / canvas component | Purpose and worked example |
200
+ |---|---|
201
+ | `weightedVectorState` / `vectorAccumulation` | [Retain momentum, add an opposing gradient, then reveal the resultant](examples/_teaching/teaching-weighted-vector.ts) |
202
+ | `categoricalSampling` | [Map supplied uniform draws through a CDF and watch tail loss](examples/_teaching/categorical-tail-loss.ts) |
203
+ | `planTeachingRoutedTransfer` / `routedTransfer` | [Route orthogonal value transfers around declared obstacles](examples/_teaching/teaching-routed-transfer.ts) |
204
+ | `byteDifferenceState` / `byteDifference` | [Locate changed bytes with stable offsets and escaped control bytes](examples/_teaching/teaching-byte-diff.ts) |
205
+ | `tokenHistoryState` / `tokenHistory` | [Drop and rebuild KV cache while preserving accepted and emitted tokens](examples/_teaching/teaching-token-history.ts) |
206
+ | `pcmEnvelope` / `waveform`, `renderNarrationHold` | Time-synced PCM waveform envelopes with cursors, plus 48 kHz speech-and-demo audio holds |
207
+ | `layoutCellGrid` / `tileTransfer`, `rasterWipe`, `planSampleCopies` | Checked grid addressing, row-staggered tile transfers, raster wipes, and sample-copy trajectories |
208
+ | `softmaxTileMass`, `combineSoftmaxMass`, `traceCrossCorrelation2d` | Online/tiled softmax mass summaries and 2D kernel cross-correlation traces |
209
+ | `createCueTrack`, `assertCueReveal` | Hold discrete snapshots across cues and verify answers never appear before their spoken phrase |
210
+
211
+ See the [canvas and TSX animation guide](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) for the painter contract and scope rules.
109
212
 
110
213
  ## For coding agents
111
214
 
112
- Install the skill. It teaches the engine, the object catalog, and the check workflow.
215
+ Install the bundled skill for Codex, Claude Code, Gemini CLI, Cursor, or OpenCode. It teaches output selection, relational stage layout, narrated film workflows, TSX figure density, and check loops:
113
216
 
114
217
  ```bash
115
218
  npx skills add bvolpato/vizmatic --skill vizmatic -g -y
116
219
  ```
117
220
 
118
- Agents can also read [`llms.txt`](https://bvolpato.github.io/vizmatic/llms.txt), and `vizmatic objects --json` and `vizmatic looks --json` list what the installed version offers.
221
+ Agents can also read [`llms.txt`](https://bvolpato.github.io/vizmatic/llms.txt) and [`PROMPT.md`](PROMPT.md), or query `npx vizmatic objects --json` and `npx vizmatic looks --json` for the exact capabilities of the installed package.
119
222
 
120
223
  ## Documentation
121
224
 
122
- | Read this | For |
225
+ | Guide | What it covers |
123
226
  |---|---|
124
- | [Getting started](https://bvolpato.github.io/vizmatic/docs/) | Your first film, in two minutes |
125
- | [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) | The stage, the timeline, and why frames are pure |
126
- | [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html) | Axes, planes, charts, graphs, code, and 3D |
127
- | [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html) | Every command, format, and quality level |
128
- | [Embedding](https://bvolpato.github.io/vizmatic/docs/embedding.html) | A live, seekable film in any page |
129
- | [Editable scenes](https://bvolpato.github.io/vizmatic/docs/editable-scenes.html) | Running untrusted TSX in a bounded sandbox |
130
- | [TSX animation](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) | Animating an existing figure with typed timelines |
131
- | [Science guide](SCIENCE.md) | Accurate diagrams for math, physics, chemistry, and machine learning |
132
- | [Roadmap](ROADMAP.md) | What shipped and what comes next |
133
- | [Contributing](CONTRIBUTING.md) | Setup, checks, and the release process |
134
-
135
- ## Package installation
136
-
137
- Vizmatic 0.7.0 bundles its tested Satori renderer and uses patched `fflate` 0.7.5. Consumer dependency overrides are no longer required.
138
-
139
- For pnpm 11, allow esbuild's install script in the root `pnpm-workspace.yaml`. The CLI uses esbuild to compile films and frames:
227
+ | [Getting started](https://bvolpato.github.io/vizmatic/docs/) | First film, preview, check, and export in two minutes |
228
+ | [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) | Stage coordinates, pure timelines, and looks |
229
+ | [Layout](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/layout.md) | Relational placement with `sceneKit`, `row`, `column`, `grid`, `place`, `beside`, and `fitted` |
230
+ | [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html) | Math, plots, systems, queues, code, ML, prose, and 3D objects |
231
+ | [Narrated films](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) | Script format, local TTS, `SceneClock`, motion checks, and delivery review |
232
+ | [Looks](https://bvolpato.github.io/vizmatic/docs/looks.html) | Semantic pigments and rendering across `midnight`, `paper`, `blueprint`, `chalk`, and `neon` |
233
+ | [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html) | Every command, format, quality preset, sheet, and manifest |
234
+ | [Embedding](https://bvolpato.github.io/vizmatic/docs/embedding.html) and [Presentations](https://bvolpato.github.io/vizmatic/docs/presentations.html) | Live `<vz-film>` web player and chapter-stepped slide decks |
235
+ | [Diagrams and density](https://bvolpato.github.io/vizmatic/docs/diagrams.html) and [Figures](https://bvolpato.github.io/vizmatic/docs/figures.html) | Typed TSX components, themes, and engineering paper figures |
236
+ | [Editable scenes](https://bvolpato.github.io/vizmatic/docs/editable-scenes.html) | Evaluating untrusted TSX in a bounded QuickJS sandbox |
237
+ | [TSX animation](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) | Typed TSX timelines and checked teaching canvas hosts |
238
+ | [Science guide](SCIENCE.md) | Accurate math, physics, chemistry, and ML diagrams |
239
+ | [Roadmap](ROADMAP.md) and [Contributing](https://github.com/bvolpato/vizmatic/blob/main/CONTRIBUTING.md) | Shipped milestones, repository checks, and release workflow |
240
+
241
+ ## Requirements and installation
242
+
243
+ - **Node.js 20+** is required for all commands. Vizmatic bundles its tested Satori renderer, self-hosted fonts, and Twemoji vector subset with no dependency overrides required.
244
+ - **FFmpeg** (`libx264`, `libvpx-vp9`, `aac`) is required on `PATH` for MP4, WebM, and audio muxing. PNG, SVG, and GIF exports run without FFmpeg.
245
+ - **`uv`** is required on `PATH` only when running local speech synthesis, transcription, or sound-bed tools (`vizmatic narrated`, `vizmatic sounds`).
246
+
247
+ For **pnpm 11**, allow esbuild's install script in the root `pnpm-workspace.yaml` so the CLI can compile films and frames:
140
248
 
141
249
  ```yaml
142
250
  allowBuilds:
143
251
  esbuild: true
144
252
  ```
145
253
 
146
- Then add Vizmatic with your package manager.
147
-
148
254
  ## License
149
255
 
150
- MIT. Bundled fonts and other third-party assets keep their own licenses. See [`assets/THIRD_PARTY_LICENSES.md`](assets/THIRD_PARTY_LICENSES.md).
256
+ MIT. Bundled fonts and third-party assets retain their own licenses; see [`assets/THIRD_PARTY_LICENSES.md`](assets/THIRD_PARTY_LICENSES.md).
package/ROADMAP.md CHANGED
@@ -13,9 +13,10 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
13
13
  - Five looks, gradient strokes, glow, and bloom.
14
14
  - `<vz-film>`, a live, seekable player for any page, with chapters and a stepped presentation mode.
15
15
  - `fromSvg` and `fromComponent`, which turn any SVG or TSX figure into shapes that films can animate.
16
- - Export to MP4 and WebM with BT.709 color, GIF with a shared palette, PNG, and SVG. Frames rasterize on worker threads with a memory limit, with optional motion blur.
17
- - `vizmatic new`, `preview`, `check`, `film`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
18
- - `vizmatic check` for films: off-canvas marks, overlapping text, and strokes through text, with times and bounding boxes as JSON. `--motion` inspects every frame for collisions and blank gaps between pictures.
16
+ - Export to MP4 and WebM with BT.709 color, GIF with a shared palette, PNG, and SVG. Frames rasterize on worker threads with a memory limit, with optional motion blur, embedded MP4 chapter and caption tracks, and WebVTT sidecars.
17
+ - `vizmatic new`, `preview`, `check`, `film`, `narrated`, `sounds`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
18
+ - Narrated teaching films with `vizmatic narrated`: spoken beat takes, `timing.json` synchronization, background pads and cue sound effects (`vizmatic sounds`), transcript verification, and audio lag checks.
19
+ - `vizmatic check` for films: off-canvas marks, overlapping text, strokes through text, crowded text, small labels, and empty canvas space, with times and bounding boxes as JSON. `--motion` inspects every frame for collisions and blank gaps between pictures.
19
20
  - The Studio, which builds and exports a film in the browser.
20
21
 
21
22
  ### Figures
@@ -34,7 +35,7 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
34
35
 
35
36
  ### Films
36
37
 
37
- - Burned-in captions and audio-synchronized timing from a narration script. Today captions export as a VTT sidecar.
38
+ - Optional burned-in open captions rendered onto video frames. Synchronized narration timing, embedded MP4 caption tracks, and WebVTT sidecars are available now.
38
39
  - ProRes and 4:4:4 masters for video editors. MP4 and WebM use 4:2:0 today for browser compatibility.
39
40
  - Frame caching for faster incremental renders.
40
41
  - Parity tests between the canvas and SVG backends, which today share one display list but use separate painters.
package/SCIENCE.md CHANGED
@@ -84,8 +84,7 @@ rejects embedded ICC profiles. Raster operations also cap dimensions at
84
84
  accepts σ ≥ 0 and integer radius 0–64, and defaults the radius to `ceil(3σ)`.
85
85
  An explicit radius at σ = 0 keeps the matching valid crop while leaving its
86
86
  pixels unchanged. These helpers are not part of the bare QuickJS author-code
87
- environment. The helpers are in this source checkout; consumers need a
88
- Vizmatic release that includes them.
87
+ environment.
89
88
 
90
89
  See [PyTorch Conv2d](https://docs.pytorch.org/docs/stable/generated/torch.nn.Conv2d.html)
91
90
  for learned spatial filters and [OpenCV image filtering](https://docs.opencv.org/4.x/d4/d86/group__imgproc__filter.html)
@@ -35,7 +35,7 @@ both pinned hashes before updating the photo block.
35
35
 
36
36
  ## RGB PNG codec dependencies
37
37
 
38
- The raster helpers use `fast-png` 8.0.0, `iobuffer` 6.0.1, and `fflate` 0.7.5,
38
+ The raster helpers use `fast-png` 8.0.0, `iobuffer` 6.0.1, and `fflate` 0.8.3,
39
39
  each under the MIT License. Their full notices are in
40
40
  [`licenses/raster-codecs-MIT.txt`](licenses/raster-codecs-MIT.txt).
41
41
 
@@ -46,7 +46,7 @@ The unmodified source is available at
46
46
  https://github.com/vercel/satori/tree/a7e9338e15fec771b7e2cfb90df737789104edeb.
47
47
  Its bundled dependencies retain their MIT and ISC licenses. Full licenses and
48
48
  upstream notices are in [`licenses/satori-NOTICES.txt`](licenses/satori-NOTICES.txt).
49
- Satori uses the package's patched `fflate` 0.7.5 dependency.
49
+ Satori uses the package's `fflate` 0.8.3 dependency.
50
50
 
51
51
  ## Fonts
52
52
 
@@ -62,7 +62,7 @@ Satori uses the package's patched `fflate` 0.7.5 dependency.
62
62
  - Source Serif 4: SIL Open Font License 1.1.
63
63
  Copyright 2014 The Source Serif 4 Project Authors.
64
64
  Source: https://github.com/adobe-fonts/source-serif
65
- `SourceSerif4-24pt-Regular.ttf` and `SourceSerif4-24pt-Italic.ttf` are static cuts of the variable fonts at optical size 24. `scripts/build-stage-fonts.py` makes them.
65
+ `SourceSerif4-24pt-Regular.ttf`, `SourceSerif4-24pt-SemiBold.ttf` and `SourceSerif4-24pt-Italic.ttf` are static cuts of the variable fonts at optical size 24. `scripts/build-stage-fonts.py` makes them.
66
66
  - Noto Sans: SIL Open Font License 1.1.
67
67
  Copyright Google Inc.
68
68
  Source: https://github.com/notofonts/noto-fonts
@@ -53,7 +53,7 @@ fflate
53
53
 
54
54
  MIT License
55
55
 
56
- Copyright (c) 2020 Arjun Barrett
56
+ Copyright (c) 2026 Arjun Barrett
57
57
 
58
58
  Permission is hereby granted, free of charge, to any person obtaining a copy
59
59
  of this software and associated documentation files (the "Software"), to deal
@@ -71,4 +71,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
71
71
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
72
72
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
73
73
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
74
- SOFTWARE.
74
+ SOFTWARE.