vizmatic 0.8.3 → 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 (99) hide show
  1. package/PROMPT.md +32 -0
  2. package/README.md +8 -3
  3. package/ROADMAP.md +4 -2
  4. package/SCIENCE.md +69 -3
  5. package/dist/chunk-6JI55YX4.js +604 -0
  6. package/dist/{chunk-LTX44BAE.js → chunk-BYKXNUX7.js} +25 -4
  7. package/dist/{chunk-4MXGLMBG.js → chunk-EPZLNABN.js} +107 -37
  8. package/dist/chunk-EWCO6ZT6.js +696 -0
  9. package/dist/{chunk-JZPMGVBP.js → chunk-G7HRSKHV.js} +1 -1
  10. package/dist/{chunk-RPAHMKAR.js → chunk-JTWC2OPN.js} +7 -5
  11. package/dist/chunk-LJZO36IR.js +124 -0
  12. package/dist/chunk-REL2BZ2B.js +88 -0
  13. package/dist/chunk-RLPEOWST.js +1 -0
  14. package/dist/chunk-VMHOWCDL.js +296 -0
  15. package/dist/chunk-YDD63HHD.js +1 -0
  16. package/dist/{chunk-I745F4QK.js → chunk-YNGDEARY.js} +1134 -643
  17. package/dist/cli.js +80 -543
  18. package/dist/gpu-selection-CDWCZH27.js +1 -0
  19. package/dist/gpu-selection-MX6NHMNA.js +635 -0
  20. package/dist/index.cjs +473 -155
  21. package/dist/index.d.cts +30 -239
  22. package/dist/index.d.ts +30 -239
  23. package/dist/index.js +410 -457
  24. package/dist/math-E7W5LFWO.js +1 -0
  25. package/dist/{math-LXB4FH4E.js → math-NEFQUPRV.js} +3 -1
  26. package/dist/scene-browser.js +17 -17
  27. package/dist/scene-cli.js +1 -1
  28. package/dist/scene-runtime.cjs +4 -2
  29. package/dist/scene-runtime.js +2 -2
  30. package/dist/stage-browser/browser.d.ts +1206 -854
  31. package/dist/stage-browser/gpu-renderer.js +138 -0
  32. package/dist/stage-browser/{math-4WFNHVV2.js → math-KYHUOK7A.js} +46 -10
  33. package/dist/stage-browser/stage.js +107 -19
  34. package/dist/stage-export.cjs +8221 -6784
  35. package/dist/stage-export.d.cts +13 -5
  36. package/dist/stage-export.d.ts +13 -5
  37. package/dist/stage-export.js +111 -601
  38. package/dist/stage.cjs +6243 -3474
  39. package/dist/stage.d.cts +1064 -765
  40. package/dist/stage.d.ts +1064 -765
  41. package/dist/stage.js +3571 -2405
  42. package/dist/{svg-import-B5BGbC1t.d.cts → svg-import-CSCFWYaB.d.cts} +21 -12
  43. package/dist/{svg-import-B5BGbC1t.d.ts → svg-import-CSCFWYaB.d.ts} +21 -12
  44. package/dist/teaching-math-DTKc0XsB.d.cts +243 -0
  45. package/dist/teaching-math-ydDBhJ2M.d.ts +243 -0
  46. package/dist/{video-CiN1MDCS.d.cts → theme-DhVdDQKO.d.cts} +4 -237
  47. package/dist/{video-CiN1MDCS.d.ts → theme-DhVdDQKO.d.ts} +4 -237
  48. package/dist/video-BYCeOz8F.d.ts +259 -0
  49. package/dist/video-CGLxJXqu.d.cts +259 -0
  50. package/examples/catalog-science-physics.tsx +6 -6
  51. package/examples/films/_boltzmann-entropy/model.ts +63 -0
  52. package/examples/films/_catalysis/model.ts +49 -0
  53. package/examples/films/_gravitational-waves/model.ts +32 -0
  54. package/examples/films/_heat-equation/model.ts +54 -0
  55. package/examples/films/_hydrogen-orbitals/model.ts +31 -0
  56. package/examples/films/_maxwell/model.ts +84 -0
  57. package/examples/films/_planetary-orbits/appearance.ts +71 -0
  58. package/examples/films/_planetary-orbits/model.ts +152 -0
  59. package/examples/films/_planetary-orbits/saturn.ts +142 -0
  60. package/examples/films/_quantum-tunneling/model.ts +58 -0
  61. package/examples/films/_reaction-diffusion/model.ts +61 -0
  62. package/examples/films/_stationary-action/model.ts +38 -0
  63. package/examples/films/attention.ts +309 -253
  64. package/examples/films/beam-search.ts +321 -49
  65. package/examples/films/boltzmann-entropy.ts +104 -0
  66. package/examples/films/cache-miss.ts +387 -394
  67. package/examples/films/catalog.json +238 -77
  68. package/examples/films/catalysis.ts +128 -0
  69. package/examples/films/central-limit.ts +27 -22
  70. package/examples/films/complex-maps.ts +70 -56
  71. package/examples/films/deck-example.ts +261 -200
  72. package/examples/films/euler-circle.ts +72 -28
  73. package/examples/films/flash-attention.ts +549 -0
  74. package/examples/films/forecast.ts +2 -2
  75. package/examples/films/fourier-epicycles.ts +21 -20
  76. package/examples/films/gradient-descent.ts +23 -49
  77. package/examples/films/gravitational-waves.ts +179 -0
  78. package/examples/films/heat-equation.ts +124 -0
  79. package/examples/films/hydrogen-orbitals.ts +135 -0
  80. package/examples/films/io-uring.ts +635 -0
  81. package/examples/films/linear-maps.ts +42 -31
  82. package/examples/films/lorenz.ts +42 -79
  83. package/examples/films/maxwell.ts +197 -0
  84. package/examples/films/pathlines.ts +85 -0
  85. package/examples/films/planetary-orbits.ts +146 -0
  86. package/examples/films/pythagoras.ts +18 -10
  87. package/examples/films/quantum-tunneling.ts +116 -0
  88. package/examples/films/rag-citations.ts +423 -0
  89. package/examples/films/reaction-diffusion.ts +70 -0
  90. package/examples/films/ring-allreduce.ts +531 -0
  91. package/examples/films/stationary-action.ts +170 -0
  92. package/examples/films/svd-3d.ts +605 -0
  93. package/examples/films/taylor-series.ts +9 -9
  94. package/examples/films/vizmatic-title.ts +1 -0
  95. package/examples/vizmatic-hero.tsx +102 -32
  96. package/package.json +3 -1
  97. package/dist/chunk-3F2VQ7NW.js +0 -1
  98. package/dist/chunk-GGFDBJ25.js +0 -88
  99. package/dist/math-QVCETQDQ.js +0 -1
package/PROMPT.md CHANGED
@@ -69,6 +69,8 @@ npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
69
69
  npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
70
70
  ```
71
71
 
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.
73
+
72
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.
73
75
 
74
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.
@@ -96,6 +98,36 @@ When a film must teach a topic, [lessons.md](https://bvolpato.github.io/vizmatic
96
98
 
97
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.
98
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
+
99
131
  ## Figures
100
132
 
101
133
  Create `frame.tsx`. `Scene` title and subtitle are optional.
package/README.md CHANGED
@@ -70,6 +70,10 @@ npx vizmatic film intro.ts --look midnight,paper --quality high --out dist
70
70
 
71
71
  Scaffold a working project with `npx vizmatic new intro --template explainer`. Built-in templates are `explainer`, `equation`, `architecture`, `chart`, `deck`, and `narrated`.
72
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
+
73
77
  <table>
74
78
  <tr>
75
79
  <td width="50%" align="center">
@@ -87,9 +91,10 @@ Scaffold a working project with `npx vizmatic new intro --template explainer`. B
87
91
 
88
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:
89
93
 
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).
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).
93
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`.
94
99
 
95
100
  ## Narrated lessons and sound
package/ROADMAP.md CHANGED
@@ -6,10 +6,12 @@ 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.
@@ -38,7 +40,7 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
38
40
  - Optional burned-in open captions rendered onto video frames. Synchronized narration timing, embedded MP4 caption tracks, and WebVTT sidecars are available now.
39
41
  - ProRes and 4:4:4 masters for video editors. MP4 and WebM use 4:2:0 today for browser compatibility.
40
42
  - Frame caching for faster incremental renders.
41
- - 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.
42
44
 
43
45
  ### Figures
44
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
  |---|---|---|
@@ -127,13 +179,27 @@ The worked lessons use these contracts:
127
179
  `MoleculeDiagram` renders supplied 2D atom positions and bond orders. It checks
128
180
  elements, identifiers, endpoints, and finite geometry. Supply the molecular
129
181
  structure deliberately: the renderer does not infer bonds, valence, a 3D
130
- 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.
131
196
 
132
197
  `ReactionEquation` displays supplied formulas, coefficients, and phase labels.
133
198
  For conservation checks, supply an explicit `composition` map and optional
134
199
  integer `charge` for each term. `reactionBalance` compares coefficient-weighted
135
200
  element counts and charge. Missing composition means balance is unavailable;
136
- 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.
137
203
 
138
204
  `ReactionEnergyDiagram` accepts absolute energy levels in one explicitly named
139
205
  unit. The barrier is the peak energy, not activation energy itself. Activation