vizmatic 0.8.1 → 0.9.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 (159) hide show
  1. package/PROMPT.md +42 -9
  2. package/README.md +172 -61
  3. package/ROADMAP.md +9 -6
  4. package/SCIENCE.md +70 -5
  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-6JI55YX4.js +604 -0
  9. package/dist/{chunk-LTX44BAE.js → chunk-BYKXNUX7.js} +25 -4
  10. package/dist/{chunk-ZB3HK7RM.js → chunk-EPZLNABN.js} +345 -25
  11. package/dist/chunk-EWCO6ZT6.js +696 -0
  12. package/dist/{chunk-DZHX76RS.js → chunk-G7HRSKHV.js} +33 -4
  13. package/dist/{chunk-RPAHMKAR.js → chunk-JTWC2OPN.js} +7 -5
  14. package/dist/chunk-LJZO36IR.js +124 -0
  15. package/dist/chunk-REL2BZ2B.js +88 -0
  16. package/dist/chunk-RLPEOWST.js +1 -0
  17. package/dist/chunk-VMHOWCDL.js +296 -0
  18. package/dist/chunk-YDD63HHD.js +1 -0
  19. package/dist/chunk-YNGDEARY.js +7230 -0
  20. package/dist/cli.js +124 -270
  21. package/dist/gpu-selection-CDWCZH27.js +1 -0
  22. package/dist/gpu-selection-MX6NHMNA.js +635 -0
  23. package/dist/index.cjs +1492 -217
  24. package/dist/index.d.cts +233 -230
  25. package/dist/index.d.ts +233 -230
  26. package/dist/index.js +1103 -479
  27. package/dist/math-E7W5LFWO.js +1 -0
  28. package/dist/{math-LXB4FH4E.js → math-NEFQUPRV.js} +3 -1
  29. package/dist/scene-browser-chunks/chunk-RQNLYYJN.js +70 -0
  30. package/dist/scene-browser-chunks/{scene-browser-layout-M3XSXMV4.js → scene-browser-layout-RC3ECYRK.js} +1 -1
  31. package/dist/scene-browser.js +18 -18
  32. package/dist/scene-cli.js +1 -1
  33. package/dist/scene-runtime.cjs +28 -5
  34. package/dist/scene-runtime.js +2 -2
  35. package/dist/{server-2FYHZ4UO.js → server-Q4COUZHV.js} +3 -3
  36. package/dist/stage-browser/browser.d.ts +8962 -685
  37. package/dist/stage-browser/gpu-renderer.js +138 -0
  38. package/dist/stage-browser/{math-4WFNHVV2.js → math-KYHUOK7A.js} +46 -10
  39. package/dist/stage-browser/stage.js +110 -5
  40. package/dist/stage-export.cjs +8616 -3888
  41. package/dist/stage-export.d.cts +65 -4
  42. package/dist/stage-export.d.ts +65 -4
  43. package/dist/stage-export.js +314 -325
  44. package/dist/stage.cjs +36997 -8756
  45. package/dist/stage.d.cts +8456 -634
  46. package/dist/stage.d.ts +8456 -634
  47. package/dist/stage.js +28135 -3502
  48. package/dist/{svg-import-C-RG1t7s.d.cts → svg-import-CSCFWYaB.d.cts} +473 -62
  49. package/dist/{svg-import-C-RG1t7s.d.ts → svg-import-CSCFWYaB.d.ts} +473 -62
  50. package/dist/teaching-math-DTKc0XsB.d.cts +243 -0
  51. package/dist/teaching-math-ydDBhJ2M.d.ts +243 -0
  52. package/dist/{video-BSwNJZkn.d.cts → theme-DhVdDQKO.d.cts} +4 -212
  53. package/dist/{video-BSwNJZkn.d.ts → theme-DhVdDQKO.d.ts} +4 -212
  54. package/dist/video-BYCeOz8F.d.ts +259 -0
  55. package/dist/video-CGLxJXqu.d.cts +259 -0
  56. package/examples/README.md +1 -1
  57. package/examples/_teaching/layer-stack-connector.ts +36 -0
  58. package/examples/_teaching/layer-stack-recurrence.ts +29 -0
  59. package/examples/_teaching/layer-stack-tiny-gpt.ts +37 -0
  60. package/examples/_teaching/layer-stack-transformer.ts +44 -0
  61. package/examples/catalog-convolution-kernel.tsx +6 -7
  62. package/examples/catalog-science-physics.tsx +6 -6
  63. package/examples/{aurora-incident.tsx → checkout-incident.tsx} +1 -1
  64. package/examples/films/_boltzmann-entropy/model.ts +63 -0
  65. package/examples/films/_catalysis/model.ts +49 -0
  66. package/examples/films/_gravitational-waves/model.ts +32 -0
  67. package/examples/films/_heat-equation/model.ts +54 -0
  68. package/examples/films/_hydrogen-orbitals/model.ts +31 -0
  69. package/examples/films/_maxwell/model.ts +84 -0
  70. package/examples/films/_planetary-orbits/appearance.ts +71 -0
  71. package/examples/films/_planetary-orbits/model.ts +152 -0
  72. package/examples/films/_planetary-orbits/saturn.ts +142 -0
  73. package/examples/films/_quantum-tunneling/model.ts +58 -0
  74. package/examples/films/_reaction-diffusion/model.ts +61 -0
  75. package/examples/films/_stationary-action/model.ts +38 -0
  76. package/examples/films/attention.ts +309 -253
  77. package/examples/films/beam-search.ts +324 -0
  78. package/examples/films/boltzmann-entropy.ts +104 -0
  79. package/examples/films/cache-miss.ts +387 -393
  80. package/examples/films/catalog.json +251 -60
  81. package/examples/films/catalysis.ts +128 -0
  82. package/examples/films/central-limit.ts +27 -22
  83. package/examples/films/complex-maps.ts +70 -56
  84. package/examples/films/deck-example.ts +261 -200
  85. package/examples/films/euler-circle.ts +72 -28
  86. package/examples/films/flash-attention.ts +549 -0
  87. package/examples/films/forecast.ts +354 -0
  88. package/examples/films/fourier-epicycles.ts +21 -20
  89. package/examples/films/gradient-descent.ts +23 -49
  90. package/examples/films/gravitational-waves.ts +179 -0
  91. package/examples/films/heat-equation.ts +124 -0
  92. package/examples/films/hydrogen-orbitals.ts +135 -0
  93. package/examples/films/io-uring.ts +635 -0
  94. package/examples/films/linear-maps.ts +42 -31
  95. package/examples/films/lorenz.ts +42 -79
  96. package/examples/films/maxwell.ts +197 -0
  97. package/examples/films/passage/chunking.ts +40 -0
  98. package/examples/films/passage/evidence.ts +44 -0
  99. package/examples/films/passage/prompt.ts +34 -0
  100. package/examples/films/pathlines.ts +85 -0
  101. package/examples/films/paxos.ts +596 -0
  102. package/examples/films/planetary-orbits.ts +146 -0
  103. package/examples/films/pythagoras.ts +18 -10
  104. package/examples/films/quantum-tunneling.ts +116 -0
  105. package/examples/films/rag-citations.ts +423 -0
  106. package/examples/films/reaction-diffusion.ts +70 -0
  107. package/examples/films/ring-allreduce.ts +531 -0
  108. package/examples/films/stationary-action.ts +170 -0
  109. package/examples/films/svd-3d.ts +605 -0
  110. package/examples/films/taylor-series.ts +10 -10
  111. package/examples/films/vizmatic-title.ts +1 -0
  112. package/examples/narrated-cues/README.md +32 -0
  113. package/examples/narrated-cues/data/numbers.json +1 -0
  114. package/examples/narrated-cues/film.json +9 -0
  115. package/examples/narrated-cues/film.ts +78 -0
  116. package/examples/narrated-cues/package.json +1 -0
  117. package/examples/narrated-cues/script.json +57 -0
  118. package/examples/narrated-cues/timing.json +1 -0
  119. package/examples/narrated-cues/tsconfig.json +1 -0
  120. package/examples/proofs/decoding-bars.ts +67 -0
  121. package/examples/proofs/pipeline.ts +27 -0
  122. package/examples/proofs/table/evaluation.ts +41 -0
  123. package/examples/proofs/table/ledger.ts +47 -0
  124. package/examples/proofs/table/routing.ts +46 -0
  125. package/examples/vizmatic-hero.tsx +102 -32
  126. package/package.json +11 -4
  127. package/templates/narrated/README.md +61 -0
  128. package/templates/narrated/data/numbers.json +5 -0
  129. package/templates/narrated/film.json +12 -0
  130. package/templates/narrated/film.ts +14 -0
  131. package/templates/narrated/gitignore +8 -0
  132. package/templates/narrated/package.json +1 -0
  133. package/templates/narrated/scenes/answer.ts +25 -0
  134. package/templates/narrated/scenes/kit.ts +39 -0
  135. package/templates/narrated/scenes/question.ts +31 -0
  136. package/templates/narrated/script.json +26 -0
  137. package/templates/narrated/sources.md +22 -0
  138. package/templates/narrated/timing.json +1 -0
  139. package/templates/narrated/tsconfig.json +1 -0
  140. package/tools/narration/README.md +123 -0
  141. package/tools/narration/beats.py +43 -0
  142. package/tools/narration/checks.py +587 -0
  143. package/tools/narration/draft.py +73 -0
  144. package/tools/narration/film.py +341 -0
  145. package/tools/narration/lag.py +58 -0
  146. package/tools/narration/mix.py +265 -0
  147. package/tools/narration/probe.py +99 -0
  148. package/tools/narration/record.py +33 -0
  149. package/tools/narration/resound.py +170 -0
  150. package/tools/narration/soundbed.py +404 -0
  151. package/tools/narration/sync.py +93 -0
  152. package/tools/narration/transcribe.py +84 -0
  153. package/tools/narration/verify.py +59 -0
  154. package/tools/narration/voice.py +113 -0
  155. package/dist/chunk-3F2VQ7NW.js +0 -1
  156. package/dist/chunk-6H2KTNJ7.js +0 -4774
  157. package/dist/chunk-6N6P2GJG.js +0 -88
  158. package/dist/math-QVCETQDQ.js +0 -1
  159. 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,13 @@ 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
+ Movie exports default to `--backend auto`: longer, demanding HD exports compare local CPU/GPU speed and sampled image quality. GPU rendering needs an installed Chrome, Edge, or Chromium; CI uses the CPU. `--backend cpu` forces software rendering, and `--backend gpu` requires a working GPU. `--encoder nvenc` requests NVIDIA H.264 encoding and fails if unavailable. Automatic film encoding retains `libx264` animation/grain settings. Hardware CQ and software CRF are different quality scales; inspect the resulting gradients and fine lines. `--json` records the selected backend, encoder, and selection reason.
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
+ `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.
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
+ 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.
77
+
78
+ `--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
79
 
77
80
  Motion guidance:
78
81
 
@@ -86,15 +89,45 @@ Motion guidance:
86
89
  When a film must teach a topic, [lessons.md](https://bvolpato.github.io/vizmatic/references/lessons.md) has the full method. In short:
87
90
 
88
91
  - 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.
92
+ - 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.
93
+ - 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
94
  - 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
95
  - 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.
96
+ - 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
97
  - 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
98
 
96
99
  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.
97
100
 
101
+ ### Scientific films
102
+
103
+ Use the same model values for the picture, equation, labels, and captions.
104
+ `tex.part()` and `.parts()` match formula structure, including scripts and local
105
+ macros; fragments without visible glyphs return no targets. `morphMatching`
106
+ preserves reordered symbols, pairing repeated symbols in reading order. `row`
107
+ aligns text and TeX baselines. Chemical notation uses bundled `mhchem`:
108
+
109
+ ```ts
110
+ tex(String.raw`\ce{2 H2 + O2 -> 2 H2O}`)
111
+ ```
112
+
113
+ Use `axes` with `xScale` / `yScale` for linear, log, or symlog coordinates.
114
+ Opt into `plot(f, { adaptive: true, discontinuities: [[0, 0]] })` when uniform sampling
115
+ misses detail or bridges a known singularity. Use `scalarField` for concentrations
116
+ and probability slices, `contourPaths` for level curves, and `colorBar` with the
117
+ same fixed `domain`, `colors`, and `scale`. Label units and sampling limits.
118
+ `parametric` accepts the same adaptive options and parameter exclusions, with
119
+ tolerance measured in local pixels before later transforms.
120
+
121
+ `integrateTrajectory((t, state) => derivative, { initial, to, step })` precomputes
122
+ seekable RK4 trajectories. Check convergence; it is not a stiff solver.
123
+ `isosurface` renders an explicit scalar level inside `scene3d`. `molecule3d`
124
+ renders supplied coordinates or one supported V2000 MOL/SDF record, without
125
+ inferring bonds or conformations. Keep subject-specific physics in the film;
126
+ extract a public component only when it serves more than one model.
127
+
128
+ See `SCIENCE.md` and the Maxwell, hydrogen, reaction–diffusion, and catalysis films
129
+ for worked examples. Inspect full-size stills and browser playback in both looks.
130
+
98
131
  ## Figures
99
132
 
100
133
  Create `frame.tsx`. `Scene` title and subtitle are optional.
@@ -157,4 +190,4 @@ After creating a visual, report:
157
190
  - whether `vizmatic check` passed
158
191
  - any overflow or layout fixes made
159
192
  - 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
193
+ - 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,122 @@ 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
+ MP4 and WebM exports automatically compare CPU and GPU rendering for longer, demanding HD films when Chrome, Edge, or Chromium is installed locally. The comparison includes frame transfer and startup cost, and checks sampled pixels against the CPU renderer. Short exports and CI use the CPU. Use `--backend cpu` for reproducible software rendering or `--backend gpu` to require hardware rendering. Set `VIZMATIC_BROWSER_EXECUTABLE_PATH` if the browser is outside the usual locations.
74
+
75
+ For NVIDIA hardware encoding, use `--encoder nvenc`; FFmpeg must provide `h264_nvenc` and a working NVIDIA driver. A CUDA toolkit installation is not required. Drawing uses the browser's graphics backend, while NVENC encodes the video. Automatic film exports retain `libx264` animation and grain settings; hardware encoders have different quality scales, so inspect fine lines and dark gradients before delivery. `--json` reports the selected renderer, encoder, GPU, and selection reason.
76
+
77
+ <table>
78
+ <tr>
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/attention.png" alt="Attention weights computed from real token vectors" /></a><br/>
81
+ <sub><strong>Scaled dot-product attention</strong> · computed weights, TeX, and live readouts</sub>
82
+ </td>
83
+ <td width="50%" align="center">
84
+ <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/>
85
+ <sub><strong>Cache hit vs. database miss</strong> · queueing model, connectors, and system boxes</sub>
86
+ </td>
87
+ </tr>
88
+ </table>
89
+
90
+ ## Domain objects on stage
91
+
92
+ 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:
59
93
 
60
- ## What makes it different
94
+ - **Layout and framing**: `sceneKit`, `sceneArea`, `row`, `column`, `grid`, `place`, `beside`, `between`, `fitted`, `boxOf`, `zone`, `card`, `steps`, `spotlight`, `focusOn`, `resetCamera`, `tagTrack`.
95
+ - **Math and scientific plots**: `tex` with structural term selection, matching morphs, and chemical notation; `axes` with linear/log/symlog scales and adaptive sampling; `contourPaths`, `scalarField`, `colorBar`, `integrateTrajectory`, `vectorField`, `streamLines`, `riemann`, `matrix`, `fourier`, and `epicycles`.
96
+ - **3D and chemistry**: `scene3d`, `surface`, `parametricSurface`, `isosurface`, `curve3d`, `point3d`, and `trail3d`; `molecule3d` renders supplied coordinates or a supported V2000 MOL/SDF record. See [the scientific guide](SCIENCE.md) for examples and model limits.
97
+ - **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` (`avoid`, `pulse`, `send`), `infoBox`, `pictogram` (57+ technical icons).
98
+ - **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`.
61
99
 
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.
100
+ ## Narrated lessons and sound
63
101
 
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.
102
+ 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:
65
103
 
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.
104
+ ```bash
105
+ npx vizmatic new cache-lesson --template narrated
106
+ npx vizmatic narrated build cache-lesson --draft # local voice, sound mix, layout check, cache-lesson-draft.mp4
107
+ npx vizmatic narrated build cache-lesson # full delivery render with MP4 chapters and captions
108
+ ```
67
109
 
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`.
110
+ 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:
111
+
112
+ ```ts
113
+ import { assertEqual, narrated, place, type SceneClock, type Stage } from 'vizmatic/stage'
114
+ import timing from './timing.json'
115
+ import { claimTag, display, heading, kit, source } from './scenes/kit'
69
116
 
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.
117
+ assertEqual(800 / 5, 160, 'speedup matches the spoken claim')
118
+
119
+ function answer(s: Stage, c: SceneClock) {
120
+ s.add(heading('With a cache in front'), source('Measured on warm hits'))
121
+ claimTag(c, { word: 'MEASURED', note: 'local benchmark' })
122
+ const speedup = place(display('160x faster'), kit.area)
123
+ c.show('one hundred and sixty times', speedup, { after: true })
124
+ }
125
+
126
+ export default narrated({ title: 'Why a cache matters', timing, scenes: { answer } })
127
+ ```
71
128
 
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.
129
+ Verify speech, cues, and sound from the CLI (`npx vizmatic narrated` lists every step):
73
130
 
74
- ## Figures
131
+ - `vizmatic narrated beats <folder> --words` prints beat windows and spoken words to pick cues.
132
+ - `vizmatic narrated stills <folder>` and `sheet <folder>` render per-beat full-resolution stills and contact sheets.
133
+ - `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.
134
+ - `vizmatic narrated resound <folder>` swaps an updated `narration.wav` into a rendered MP4 without re-rendering frames.
135
+ - `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.
75
136
 
76
- Render a TSX figure in each theme:
137
+ Read the [narrated films guide](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) for the full workflow.
138
+
139
+ ## Dense figures from TSX
140
+
141
+ 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.
142
+
143
+ <p align="center">
144
+ <a href="https://bvolpato.github.io/vizmatic/examples.html">
145
+ <picture>
146
+ <source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" />
147
+ <source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_light.png" />
148
+ <img src="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" alt="Data pipeline lineage figure rendered from TSX" width="840" />
149
+ </picture>
150
+ </a>
151
+ </p>
77
152
 
78
153
  ```tsx
79
- <Scene title="Checkout, read path">
154
+ <Scene title="Checkout read path" subtitle="Envoy -> Cart -> Orders replica">
80
155
  <Flow
81
156
  stages={[
82
157
  { title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
83
- { title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
158
+ { title: "Cart service", subtitle: "Go, 840 rps", tone: "purple" },
84
159
  { title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
85
160
  ]}
86
161
  />
@@ -88,63 +163,99 @@ Render a TSX figure in each theme:
88
163
  ```
89
164
 
90
165
  ```bash
91
- npx vizmatic ./frame.tsx --out ./figures --theme dark,light --format both
166
+ npx vizmatic check ./frame.tsx --theme dark,light --json
167
+ npx vizmatic render ./frame.tsx --out ./figures --theme dark,light --format both
92
168
  ```
93
169
 
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).
170
+ - Omit `width` and `height` while iterating: bare `.tsx` frames start at `960x540` and auto-grow to fit content.
171
+ - 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.
172
+ - Switch to `density="presentation"` (or `--density presentation`) when placing the same scene on a slide.
173
+ - 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
174
 
96
- ## Teaching with a checked canvas
175
+ 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
176
 
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.
177
+ ## What makes Vizmatic different
99
178
 
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) |
179
+ - **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.
180
+ - **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.
181
+ - **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.
182
+ - **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.
183
+ - **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`.
107
184
 
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.
185
+ ## CLI at a glance
186
+
187
+ | Command | Purpose |
188
+ |---|---|
189
+ | `vizmatic new <name> [--template ...]` | Scaffold a film (`explainer`, `equation`, `architecture`, `chart`, `deck`, or `narrated`) |
190
+ | `vizmatic preview <file> [--port <n>] [--open]` | Live browser player with timeline scrubbing and hot reload |
191
+ | `vizmatic check <file-or-dir...> [--motion] [--json]` | Check films (`--motion`, `--text-gap`, `--text-size`, `--empty-space`, `--stepped`) or TSX frames (`--theme dark,light`) |
192
+ | `vizmatic film <file...> [--out <dir>]` | Export MP4, WebM, GIF, PNG stills (`--frame`, `--every`, `--sheet`), SVG, posters, captions, and chapters |
193
+ | `vizmatic narrated <step> <folder>` | Build, voice, mix, check, stills, sheet, beats, transcribe, sync, lag, probe, or resound narrated lessons |
194
+ | `vizmatic objects [--json]` / `vizmatic looks [--json]` | List stage domain objects and color looks |
195
+ | `vizmatic sounds <list\|render\|bed>` | List or synthesize sound effects and ducked stereo ambient beds |
196
+ | `vizmatic [render] <file-or-dir...>` | Render TSX figures to dark/light PNG and SVG (`--density`, `--background`, `--format png\|svg\|both`) |
197
+ | `vizmatic gif <file...>` / `vizmatic video <file...>` | Render animated TSX timelines (`createAnimation`) to GIF or MP4 |
198
+ | `vizmatic-scene --input req.json --output out.png\|out.mp4` | Render untrusted bare TSX inside the bounded QuickJS scene sandbox |
199
+
200
+ ## Checked teaching helpers
201
+
202
+ 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:
203
+
204
+ | Helper / canvas component | Purpose and worked example |
205
+ |---|---|
206
+ | `weightedVectorState` / `vectorAccumulation` | [Retain momentum, add an opposing gradient, then reveal the resultant](examples/_teaching/teaching-weighted-vector.ts) |
207
+ | `categoricalSampling` | [Map supplied uniform draws through a CDF and watch tail loss](examples/_teaching/categorical-tail-loss.ts) |
208
+ | `planTeachingRoutedTransfer` / `routedTransfer` | [Route orthogonal value transfers around declared obstacles](examples/_teaching/teaching-routed-transfer.ts) |
209
+ | `byteDifferenceState` / `byteDifference` | [Locate changed bytes with stable offsets and escaped control bytes](examples/_teaching/teaching-byte-diff.ts) |
210
+ | `tokenHistoryState` / `tokenHistory` | [Drop and rebuild KV cache while preserving accepted and emitted tokens](examples/_teaching/teaching-token-history.ts) |
211
+ | `pcmEnvelope` / `waveform`, `renderNarrationHold` | Time-synced PCM waveform envelopes with cursors, plus 48 kHz speech-and-demo audio holds |
212
+ | `layoutCellGrid` / `tileTransfer`, `rasterWipe`, `planSampleCopies` | Checked grid addressing, row-staggered tile transfers, raster wipes, and sample-copy trajectories |
213
+ | `softmaxTileMass`, `combineSoftmaxMass`, `traceCrossCorrelation2d` | Online/tiled softmax mass summaries and 2D kernel cross-correlation traces |
214
+ | `createCueTrack`, `assertCueReveal` | Hold discrete snapshots across cues and verify answers never appear before their spoken phrase |
215
+
216
+ See the [canvas and TSX animation guide](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) for the painter contract and scope rules.
109
217
 
110
218
  ## For coding agents
111
219
 
112
- Install the skill. It teaches the engine, the object catalog, and the check workflow.
220
+ 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
221
 
114
222
  ```bash
115
223
  npx skills add bvolpato/vizmatic --skill vizmatic -g -y
116
224
  ```
117
225
 
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.
226
+ 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
227
 
120
228
  ## Documentation
121
229
 
122
- | Read this | For |
230
+ | Guide | What it covers |
123
231
  |---|---|
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:
232
+ | [Getting started](https://bvolpato.github.io/vizmatic/docs/) | First film, preview, check, and export in two minutes |
233
+ | [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) | Stage coordinates, pure timelines, and looks |
234
+ | [Layout](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/layout.md) | Relational placement with `sceneKit`, `row`, `column`, `grid`, `place`, `beside`, and `fitted` |
235
+ | [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html) | Math, plots, systems, queues, code, ML, prose, and 3D objects |
236
+ | [Narrated films](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) | Script format, local TTS, `SceneClock`, motion checks, and delivery review |
237
+ | [Looks](https://bvolpato.github.io/vizmatic/docs/looks.html) | Semantic pigments and rendering across `midnight`, `paper`, `blueprint`, `chalk`, and `neon` |
238
+ | [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 |
239
+ | [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 |
240
+ | [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 |
241
+ | [Editable scenes](https://bvolpato.github.io/vizmatic/docs/editable-scenes.html) | Evaluating untrusted TSX in a bounded QuickJS sandbox |
242
+ | [TSX animation](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) | Typed TSX timelines and checked teaching canvas hosts |
243
+ | [Science guide](SCIENCE.md) | Accurate math, physics, chemistry, and ML diagrams |
244
+ | [Roadmap](ROADMAP.md) and [Contributing](https://github.com/bvolpato/vizmatic/blob/main/CONTRIBUTING.md) | Shipped milestones, repository checks, and release workflow |
245
+
246
+ ## Requirements and installation
247
+
248
+ - **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.
249
+ - **FFmpeg** (`libx264`, `libvpx-vp9`, `aac`) is required on `PATH` for MP4, WebM, and audio muxing. PNG, SVG, and GIF exports run without FFmpeg.
250
+ - **`uv`** is required on `PATH` only when running local speech synthesis, transcription, or sound-bed tools (`vizmatic narrated`, `vizmatic sounds`).
251
+
252
+ For **pnpm 11**, allow esbuild's install script in the root `pnpm-workspace.yaml` so the CLI can compile films and frames:
140
253
 
141
254
  ```yaml
142
255
  allowBuilds:
143
256
  esbuild: true
144
257
  ```
145
258
 
146
- Then add Vizmatic with your package manager.
147
-
148
259
  ## License
149
260
 
150
- MIT. Bundled fonts and other third-party assets keep their own licenses. See [`assets/THIRD_PARTY_LICENSES.md`](assets/THIRD_PARTY_LICENSES.md).
261
+ 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
@@ -6,16 +6,19 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
6
6
 
7
7
  ### Films
8
8
 
9
- - A vector animation engine in `vizmatic/stage`. Every object is Bezier geometry, so any shape can trace itself, morph, or bend through a function.
9
+ - A deterministic animation engine in `vizmatic/stage`. Vector shapes can trace, morph, and bend; sampled fields and imported images share their transforms and export path.
10
10
  - A timeline that is a pure function of time. Any frame can be sampled in any order, so scrubbing is instant and output is reproducible.
11
11
  - TeX glyphs for equations, with `morphMatching` to carry shared terms between lines.
12
12
  - Objects for math, charts, computer science, and systems, plus 3D scenes with surfaces, curves, and an orbiting camera.
13
+ - Scientific plots with log/symlog axes, adaptive sampling, contours, sampled scalar fields, numeric color bars, RK4 trajectories, and implicit 3D surfaces.
14
+ - Structural equation targeting, reordered symbol morphs, chemical typesetting, and supplied 3D molecules with a bounded V2000 MOL/SDF importer.
13
15
  - Five looks, gradient strokes, glow, and bloom.
14
16
  - `<vz-film>`, a live, seekable player for any page, with chapters and a stepped presentation mode.
15
17
  - `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.
18
+ - 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.
19
+ - `vizmatic new`, `preview`, `check`, `film`, `narrated`, `sounds`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
20
+ - 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.
21
+ - `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
22
  - The Studio, which builds and exports a film in the browser.
20
23
 
21
24
  ### Figures
@@ -34,10 +37,10 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
34
37
 
35
38
  ### Films
36
39
 
37
- - Burned-in captions and audio-synchronized timing from a narration script. Today captions export as a VTT sidecar.
40
+ - Optional burned-in open captions rendered onto video frames. Synchronized narration timing, embedded MP4 caption tracks, and WebVTT sidecars are available now.
38
41
  - ProRes and 4:4:4 masters for video editors. MP4 and WebM use 4:2:0 today for browser compatibility.
39
42
  - Frame caching for faster incremental renders.
40
- - Parity tests between the canvas and SVG backends, which today share one display list but use separate painters.
43
+ - Broader Canvas/SVG parity coverage beyond the current image, equation, scalar-field, bloom, and export regressions.
41
44
 
42
45
  ### Figures
43
46
 
package/SCIENCE.md CHANGED
@@ -5,7 +5,59 @@ deterministic animation. Scientific components use the same public API and scene
5
5
  registry in native rendering and the in-browser editor. They require no network
6
6
  requests or scientific drawing service.
7
7
 
8
- ## Choose a foundation
8
+ ## Scientific films
9
+
10
+ Use `vizmatic/stage` for new animations. A film supplies its equations and model;
11
+ the engine supplies typesetting, geometry, scales, layout, and deterministic
12
+ playback. The same source runs in browser previews and video exports.
13
+
14
+ | Capability | Reusable tools | Film |
15
+ |---|---|---|
16
+ | Equations and derivations | `tex`, structural `.part()` / `.parts()`, `morphMatching`, baseline-aligned `row` | [Euler's circle](examples/films/euler-circle.ts) |
17
+ | Scalar fields and concentrations | `scalarField`, `colorBar`, `contourPaths` | [Reaction and diffusion](examples/films/reaction-diffusion.ts) |
18
+ | Scales and differential equations | `axes` with `xScale` / `yScale`, `integrateTrajectory` | [Lorenz](examples/films/lorenz.ts) |
19
+ | Waves and polarization | `scene3d`, `curve3d`, `vector3d`, `parametricSurface` | [Maxwell](examples/films/maxwell.ts) |
20
+ | Orbital motion and shaded geometry | `scene3d`, `curve3d`, `parametricSurface`, `scalarField` | [Eight worlds, one gravity](examples/films/planetary-orbits.ts) |
21
+ | Implicit surfaces and probability | `isosurface`, `scalarField`, `colorBar` | [Hydrogen orbitals](examples/films/hydrogen-orbitals.ts) |
22
+ | Molecular geometry and reaction paths | `molecule3d`, `tex` with `\ce`, `axes` | [Catalysis](examples/films/catalysis.ts) |
23
+
24
+ `axes({ x: [1, 100], xScale: 'log', yScale: 'symlog' })` applies the same transform to
25
+ coordinates, inverse coordinates, ticks, and plots. Log domains must be positive.
26
+ `plot(f, { adaptive: { tolerance: 0.5 }, discontinuities: [[0, 0]] })` refines sampled
27
+ geometry in stage pixels and leaves specified discontinuities open. Adaptive
28
+ sampling is bounded and cannot discover every narrow feature of an arbitrary
29
+ function. Series retain their original points; uniform sampling remains the
30
+ default.
31
+ Zero-baseline areas and Riemann rectangles cannot use a logarithmic y axis.
32
+ Use a positive `over` curve or `band` to fill a region on that scale.
33
+
34
+ `parametric(f, from, to, { adaptive: true })` uses the same bounded sampler for
35
+ curves such as particle trajectories. Its tolerance is in local pixels at
36
+ construction time, before later node or parent transforms. It accepts the same
37
+ parameter-interval exclusions; the default uniform spline remains unchanged.
38
+
39
+ `scalarField((x, y, t) => value, { x, y, domain, colors, scale })` draws a sampled
40
+ image, with positive y upward. Keep `domain`, `colors`, and `scale` identical in
41
+ its `colorBar`; do not renormalize each frame. Missing samples become transparent
42
+ holes. Spatial resolution is explicit, from 2 to 512 samples per axis. A field
43
+ supports the same placement, clipping, opacity, and blending as other nodes.
44
+ `contourPaths(f, { x, y, levels, resolution })` returns connected polylines in
45
+ data coordinates, for either 2D plots or projected 3D geometry.
46
+
47
+ `integrateTrajectory((t, state) => derivative, { initial, to, step })` precomputes
48
+ fixed-step RK4 with cubic interpolation. Sampling is independent of seek order.
49
+ Use it for time-dependent particle paths as well as autonomous systems. It is
50
+ not a stiff or adaptive solver; compare smaller steps and check the model's
51
+ invariants. `streamLines` depicts the geometry of a steady field, not the particle
52
+ paths of a changing field.
53
+
54
+ `isosurface(f, { x, y, z, level, resolution })` creates a cached, bounded
55
+ marching-tetrahedra mesh inside `scene3d`. The grid approximates the level set;
56
+ surfaces that touch the sampling box remain open. For density lobes, use
57
+ `normals: 'decreasing'`. A displayed probability isosurface is a chosen density
58
+ threshold, not an electron boundary or orbit.
59
+
60
+ ## Still figures
9
61
 
10
62
  | Subject | Components and helpers | Worked examples |
11
63
  |---|---|---|
@@ -84,8 +136,7 @@ rejects embedded ICC profiles. Raster operations also cap dimensions at
84
136
  accepts σ ≥ 0 and integer radius 0–64, and defaults the radius to `ceil(3σ)`.
85
137
  An explicit radius at σ = 0 keeps the matching valid crop while leaving its
86
138
  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.
139
+ environment.
89
140
 
90
141
  See [PyTorch Conv2d](https://docs.pytorch.org/docs/stable/generated/torch.nn.Conv2d.html)
91
142
  for learned spatial filters and [OpenCV image filtering](https://docs.opencv.org/4.x/d4/d86/group__imgproc__filter.html)
@@ -128,13 +179,27 @@ The worked lessons use these contracts:
128
179
  `MoleculeDiagram` renders supplied 2D atom positions and bond orders. It checks
129
180
  elements, identifiers, endpoints, and finite geometry. Supply the molecular
130
181
  structure deliberately: the renderer does not infer bonds, valence, a 3D
131
- conformation, stereochemistry, or chemical validity from a formula.
182
+ conformation, stereochemistry, or chemical validity from a formula. Single bonds
183
+ accept `stereo: 'wedge' | 'hashed'`; the narrow end is `from`, so atom order matters.
184
+
185
+ For films, `molecule3d({ atoms, bonds }, options)` places explicit 3D coordinates
186
+ in a `Scene3D`. `atom(id)` and `bond(from, to)` expose parts for animation. Display
187
+ radii are illustrative, not measured atomic radii. The same function accepts one
188
+ V2000 MOL/SDF string containing plain element atoms and explicit bonds. Unsupported
189
+ stereochemistry, charges, isotopes, query atoms, and property blocks are rejected;
190
+ V3000 and multiple SDF records are not supported. A planar input remains planar.
191
+ Vizmatic does not generate conformers or add missing hydrogens.
192
+
193
+ `tex` bundles MathJax's `mhchem` extension, including `\ce` and `\pu`, for formulas,
194
+ reaction arrows, charges, and units. This typesets the author's chemistry; it does
195
+ not infer its meaning or balance a reaction.
132
196
 
133
197
  `ReactionEquation` displays supplied formulas, coefficients, and phase labels.
134
198
  For conservation checks, supply an explicit `composition` map and optional
135
199
  integer `charge` for each term. `reactionBalance` compares coefficient-weighted
136
200
  element counts and charge. Missing composition means balance is unavailable;
137
- the rendered formula is not parsed or automatically balanced.
201
+ the rendered formula is not parsed or automatically balanced. An electron term
202
+ uses `composition: {}` and `charge: -1`; it contributes charge without an element.
138
203
 
139
204
  `ReactionEnergyDiagram` accepts absolute energy levels in one explicitly named
140
205
  unit. The barrier is the peak energy, not activation energy itself. Activation