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.
- package/PROMPT.md +10 -9
- package/README.md +167 -61
- package/ROADMAP.md +5 -4
- package/SCIENCE.md +1 -2
- package/assets/THIRD_PARTY_LICENSES.md +3 -3
- package/assets/fonts/SourceSerif4-24pt-SemiBold.ttf +0 -0
- package/assets/licenses/raster-codecs-MIT.txt +2 -2
- package/dist/{chunk-ZB3HK7RM.js → chunk-4MXGLMBG.js} +274 -24
- package/dist/chunk-GGFDBJ25.js +88 -0
- package/dist/{chunk-6H2KTNJ7.js → chunk-I745F4QK.js} +2322 -357
- package/dist/{chunk-DZHX76RS.js → chunk-JZPMGVBP.js} +32 -3
- package/dist/cli.js +443 -126
- package/dist/index.cjs +1055 -98
- package/dist/index.d.cts +216 -4
- package/dist/index.d.ts +216 -4
- package/dist/index.js +734 -63
- package/dist/scene-browser-chunks/chunk-RQNLYYJN.js +70 -0
- package/dist/scene-browser-chunks/{scene-browser-layout-M3XSXMV4.js → scene-browser-layout-RC3ECYRK.js} +1 -1
- package/dist/scene-browser.js +16 -16
- package/dist/scene-cli.js +1 -1
- package/dist/scene-runtime.cjs +24 -3
- package/dist/scene-runtime.js +1 -1
- package/dist/{server-2FYHZ4UO.js → server-Q4COUZHV.js} +3 -3
- package/dist/stage-browser/browser.d.ts +8240 -315
- package/dist/stage-browser/stage.js +22 -5
- package/dist/stage-export.cjs +3620 -329
- package/dist/stage-export.d.cts +56 -3
- package/dist/stage-export.d.ts +56 -3
- package/dist/stage-export.js +659 -180
- package/dist/stage.cjs +33026 -7554
- package/dist/stage.d.cts +7809 -286
- package/dist/stage.d.ts +7809 -286
- package/dist/stage.js +26066 -2599
- package/dist/{svg-import-C-RG1t7s.d.cts → svg-import-B5BGbC1t.d.cts} +455 -53
- package/dist/{svg-import-C-RG1t7s.d.ts → svg-import-B5BGbC1t.d.ts} +455 -53
- package/dist/{video-BSwNJZkn.d.cts → video-CiN1MDCS.d.cts} +27 -2
- package/dist/{video-BSwNJZkn.d.ts → video-CiN1MDCS.d.ts} +27 -2
- package/examples/README.md +1 -1
- package/examples/_teaching/layer-stack-connector.ts +36 -0
- package/examples/_teaching/layer-stack-recurrence.ts +29 -0
- package/examples/_teaching/layer-stack-tiny-gpt.ts +37 -0
- package/examples/_teaching/layer-stack-transformer.ts +44 -0
- package/examples/catalog-convolution-kernel.tsx +6 -7
- package/examples/{aurora-incident.tsx → checkout-incident.tsx} +1 -1
- package/examples/films/beam-search.ts +52 -0
- package/examples/films/cache-miss.ts +4 -3
- package/examples/films/catalog.json +30 -0
- package/examples/films/forecast.ts +354 -0
- package/examples/films/passage/chunking.ts +40 -0
- package/examples/films/passage/evidence.ts +44 -0
- package/examples/films/passage/prompt.ts +34 -0
- package/examples/films/paxos.ts +596 -0
- package/examples/films/taylor-series.ts +1 -1
- package/examples/narrated-cues/README.md +32 -0
- package/examples/narrated-cues/data/numbers.json +1 -0
- package/examples/narrated-cues/film.json +9 -0
- package/examples/narrated-cues/film.ts +78 -0
- package/examples/narrated-cues/package.json +1 -0
- package/examples/narrated-cues/script.json +57 -0
- package/examples/narrated-cues/timing.json +1 -0
- package/examples/narrated-cues/tsconfig.json +1 -0
- package/examples/proofs/decoding-bars.ts +67 -0
- package/examples/proofs/pipeline.ts +27 -0
- package/examples/proofs/table/evaluation.ts +41 -0
- package/examples/proofs/table/ledger.ts +47 -0
- package/examples/proofs/table/routing.ts +46 -0
- package/package.json +9 -4
- package/templates/narrated/README.md +61 -0
- package/templates/narrated/data/numbers.json +5 -0
- package/templates/narrated/film.json +12 -0
- package/templates/narrated/film.ts +14 -0
- package/templates/narrated/gitignore +8 -0
- package/templates/narrated/package.json +1 -0
- package/templates/narrated/scenes/answer.ts +25 -0
- package/templates/narrated/scenes/kit.ts +39 -0
- package/templates/narrated/scenes/question.ts +31 -0
- package/templates/narrated/script.json +26 -0
- package/templates/narrated/sources.md +22 -0
- package/templates/narrated/timing.json +1 -0
- package/templates/narrated/tsconfig.json +1 -0
- package/tools/narration/README.md +123 -0
- package/tools/narration/beats.py +43 -0
- package/tools/narration/checks.py +587 -0
- package/tools/narration/draft.py +73 -0
- package/tools/narration/film.py +341 -0
- package/tools/narration/lag.py +58 -0
- package/tools/narration/mix.py +265 -0
- package/tools/narration/probe.py +99 -0
- package/tools/narration/record.py +33 -0
- package/tools/narration/resound.py +170 -0
- package/tools/narration/soundbed.py +404 -0
- package/tools/narration/sync.py +93 -0
- package/tools/narration/transcribe.py +84 -0
- package/tools/narration/verify.py +59 -0
- package/tools/narration/voice.py +113 -0
- package/dist/chunk-6N6P2GJG.js +0 -88
- 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 `
|
|
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
|
-
|
|
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,
|
|
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
|
|
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.
|
|
90
|
-
- Compute every number in the film, and check it with `assert
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
7
|
-
Vector films that play live in
|
|
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
|
|
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
|
-
##
|
|
32
|
+
## Quick start: a film in 19 lines
|
|
29
33
|
|
|
30
|
-
Vizmatic
|
|
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(
|
|
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
|
-
|
|
62
|
+
Preview, check, inspect stills, and export:
|
|
51
63
|
|
|
52
64
|
```bash
|
|
53
|
-
npx vizmatic preview intro.ts
|
|
54
|
-
npx vizmatic check intro.ts
|
|
55
|
-
npx vizmatic film intro.ts --out
|
|
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
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
95
|
+
## Narrated lessons and sound
|
|
65
96
|
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
+
Verify speech, cues, and sound from the CLI (`npx vizmatic narrated` lists every step):
|
|
71
125
|
|
|
72
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 --
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
172
|
+
## What makes Vizmatic different
|
|
99
173
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
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
|
|
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)
|
|
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
|
-
|
|
|
225
|
+
| Guide | What it covers |
|
|
123
226
|
|---|---|
|
|
124
|
-
| [Getting started](https://bvolpato.github.io/vizmatic/docs/) |
|
|
125
|
-
| [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) |
|
|
126
|
-
| [
|
|
127
|
-
| [
|
|
128
|
-
| [
|
|
129
|
-
| [
|
|
130
|
-
| [
|
|
131
|
-
| [
|
|
132
|
-
| [
|
|
133
|
-
| [
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
Binary file
|
|
@@ -53,7 +53,7 @@ fflate
|
|
|
53
53
|
|
|
54
54
|
MIT License
|
|
55
55
|
|
|
56
|
-
Copyright (c)
|
|
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.
|