vizmatic 0.4.0 → 0.6.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 (149) hide show
  1. package/PROMPT.md +75 -531
  2. package/README.md +85 -1052
  3. package/ROADMAP.md +49 -67
  4. package/SCIENCE.md +250 -0
  5. package/assets/THIRD_PARTY_LICENSES.md +44 -1
  6. package/assets/fonts/InstrumentSerif-Italic.ttf +0 -0
  7. package/assets/fonts/InstrumentSerif-Regular.ttf +0 -0
  8. package/assets/fonts/SourceSerif4-24pt-Italic.ttf +0 -0
  9. package/assets/fonts/SourceSerif4-24pt-Regular.ttf +0 -0
  10. package/assets/licenses/raster-codecs-MIT.txt +74 -0
  11. package/dist/chunk-3F2VQ7NW.js +1 -0
  12. package/dist/{chunk-FEIPTPBZ.js → chunk-4XE64I2U.js} +53 -463
  13. package/dist/chunk-5ZAFH2JC.js +4231 -0
  14. package/dist/chunk-JHHPLALU.js +79 -0
  15. package/dist/chunk-LTX44BAE.js +112 -0
  16. package/dist/chunk-MLKGABMK.js +9 -0
  17. package/dist/chunk-PSBF4TEK.js +1 -0
  18. package/dist/chunk-RPAHMKAR.js +605 -0
  19. package/dist/chunk-RWF4VBUL.js +3617 -0
  20. package/dist/cli.js +369 -12
  21. package/dist/index.cjs +7413 -1810
  22. package/dist/index.d.cts +900 -599
  23. package/dist/index.d.ts +900 -599
  24. package/dist/index.js +5019 -3278
  25. package/dist/math-LXB4FH4E.js +7 -0
  26. package/dist/math-QVCETQDQ.js +1 -0
  27. package/dist/scene-browser-assets.d.ts +38 -0
  28. package/dist/scene-browser-assets.js +53 -0
  29. package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +70 -0
  30. package/dist/scene-browser-chunks/chunk-ASXKN3NU.js +1 -0
  31. package/dist/scene-browser-chunks/chunk-CM5Y5LZP.js +1 -0
  32. package/dist/scene-browser-chunks/chunk-DP7NB4EW.js +6 -0
  33. package/dist/scene-browser-chunks/emscripten-module.browser-M5AEKJGE.js +1 -0
  34. package/dist/scene-browser-chunks/ffi-FL6ORJU3.js +1 -0
  35. package/dist/scene-browser-chunks/module-ES6BEMUI-JD5S5VKR.js +1 -0
  36. package/dist/scene-browser-chunks/module-asyncify-2EFITU5U-HWPFJFJC.js +1 -0
  37. package/dist/scene-browser-chunks/scene-browser-layout-M3XSXMV4.js +27 -0
  38. package/dist/scene-browser.d.ts +117 -0
  39. package/dist/scene-browser.js +220 -0
  40. package/dist/scene-cli.js +1 -1
  41. package/dist/scene-runtime.cjs +168 -103
  42. package/dist/scene-runtime.d.cts +3 -2
  43. package/dist/scene-runtime.d.ts +3 -2
  44. package/dist/scene-runtime.js +3 -1
  45. package/dist/server-2FYHZ4UO.js +331 -0
  46. package/dist/stage-browser/browser.d.ts +2483 -0
  47. package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
  48. package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
  49. package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
  50. package/dist/stage-browser/math-4WFNHVV2.js +18 -0
  51. package/dist/stage-browser/stage.js +19 -0
  52. package/dist/stage-export.cjs +4980 -0
  53. package/dist/stage-export.d.cts +112 -0
  54. package/dist/stage-export.d.ts +112 -0
  55. package/dist/stage-export.js +544 -0
  56. package/dist/stage.cjs +9789 -0
  57. package/dist/stage.d.cts +1679 -0
  58. package/dist/stage.d.ts +1679 -0
  59. package/dist/stage.js +5418 -0
  60. package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
  61. package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
  62. package/dist/video-CcHW1qhV.d.cts +532 -0
  63. package/dist/video-CcHW1qhV.d.ts +532 -0
  64. package/examples/README.md +18 -0
  65. package/examples/agent-pipeline.tsx +4 -4
  66. package/examples/animated-pipeline.tsx +1 -5
  67. package/examples/attention-head.tsx +12 -12
  68. package/examples/aurora-incident.tsx +4 -3
  69. package/examples/building-blocks.tsx +8 -9
  70. package/examples/catalog-charts.tsx +4 -4
  71. package/examples/catalog-content.tsx +7 -9
  72. package/examples/catalog-convolution-kernel.tsx +116 -0
  73. package/examples/catalog-data.tsx +2 -8
  74. package/examples/catalog-dataflow.tsx +5 -9
  75. package/examples/catalog-dense.tsx +80 -0
  76. package/examples/catalog-deployment.tsx +5 -11
  77. package/examples/catalog-diagrams.tsx +13 -16
  78. package/examples/catalog-drawing.tsx +7 -7
  79. package/examples/catalog-flows.tsx +4 -4
  80. package/examples/catalog-foundations.tsx +11 -11
  81. package/examples/catalog-gaussian-blur.tsx +146 -0
  82. package/examples/catalog-image-tensors.tsx +115 -0
  83. package/examples/catalog-ml.tsx +36 -31
  84. package/examples/catalog-numeric-matrices.tsx +93 -0
  85. package/examples/catalog-photo-blur.tsx +209 -0
  86. package/examples/catalog-science-ai.tsx +130 -0
  87. package/examples/catalog-science-chemistry.tsx +103 -0
  88. package/examples/catalog-science-math.tsx +93 -0
  89. package/examples/catalog-science-physics.tsx +84 -0
  90. package/examples/catalog-sequence.tsx +59 -38
  91. package/examples/data-pipeline-lineage-presentation.tsx +5 -0
  92. package/examples/data-pipeline-lineage.tsx +85 -0
  93. package/examples/daybreak-launch.tsx +1 -0
  94. package/examples/desired-quadrant.tsx +7 -8
  95. package/examples/engineering-dashboard-presentation.tsx +13 -0
  96. package/examples/engineering-dashboard.tsx +160 -0
  97. package/examples/engineering-flow.tsx +2 -4
  98. package/examples/eval-dashboard.tsx +6 -6
  99. package/examples/films/attention.ts +278 -0
  100. package/examples/films/cache-miss.ts +431 -0
  101. package/examples/films/catalog.json +132 -0
  102. package/examples/films/central-limit.ts +269 -0
  103. package/examples/films/complex-maps.ts +273 -0
  104. package/examples/films/deck-example.ts +224 -0
  105. package/examples/films/euler-circle.ts +179 -0
  106. package/examples/films/fourier-epicycles.ts +265 -0
  107. package/examples/films/gradient-descent.ts +345 -0
  108. package/examples/films/linear-maps.ts +175 -0
  109. package/examples/films/lorenz.ts +207 -0
  110. package/examples/films/pythagoras.ts +185 -0
  111. package/examples/films/taylor-series.ts +159 -0
  112. package/examples/films/vizmatic-title.ts +117 -0
  113. package/examples/llm-serving-stack-presentation.tsx +5 -0
  114. package/examples/llm-serving-stack.tsx +94 -0
  115. package/examples/model-garden.tsx +1 -0
  116. package/examples/model-router.tsx +6 -6
  117. package/examples/nccl-all-gather.tsx +3 -3
  118. package/examples/nccl-all-reduce.tsx +3 -3
  119. package/examples/nccl-all-to-all.tsx +1 -1
  120. package/examples/nccl-broadcast.tsx +1 -1
  121. package/examples/nccl-reduce-scatter.tsx +5 -5
  122. package/examples/orthogonal-routing.tsx +4 -4
  123. package/examples/pareto-frontier.tsx +9 -10
  124. package/examples/presentation-frame.tsx +6 -6
  125. package/examples/production-system-map-presentation.tsx +5 -0
  126. package/examples/production-system-map.tsx +130 -0
  127. package/examples/rag-graph.tsx +7 -7
  128. package/examples/release-card.tsx +5 -5
  129. package/examples/spec-anatomy.tsx +5 -5
  130. package/examples/system-architecture.tsx +19 -32
  131. package/examples/theme-system.tsx +1 -1
  132. package/examples/token-matrix.tsx +4 -2
  133. package/examples/transparent-badge.tsx +1 -2
  134. package/examples/videos/README.md +36 -2
  135. package/examples/videos/calculus-tangent.tsx +101 -0
  136. package/examples/videos/catalyst-pathway.tsx +56 -0
  137. package/examples/videos/causal-attention.tsx +91 -0
  138. package/examples/videos/convolution-kernel.tsx +34 -0
  139. package/examples/videos/gaussian-blur.tsx +32 -0
  140. package/examples/videos/image-to-matrix.tsx +22 -0
  141. package/examples/videos/matrix-multiplication.tsx +128 -0
  142. package/examples/videos/photo-gaussian-blur.tsx +39 -0
  143. package/examples/videos/wave-interference.tsx +80 -0
  144. package/examples/vizmatic-bare.d.ts +1 -0
  145. package/examples/vizmatic-hero.tsx +9 -18
  146. package/examples/website-workflow.tsx +7 -7
  147. package/examples/weekend-field-notes.tsx +3 -2
  148. package/package.json +65 -11
  149. package/dist/chunk-TH3F4SDB.js +0 -79
@@ -0,0 +1,742 @@
1
+ /** Rate functions map animation progress in [0, 1] to eased progress. */
2
+ type Ease = (t: number) => number;
3
+ declare const linear: Ease;
4
+ /** The house default. A sigmoid with a calm start and a calm landing. */
5
+ declare function smoothBy(inflection: number): Ease;
6
+ declare const smooth: Ease;
7
+ /** Fifth-order smoothstep, for long camera moves. */
8
+ declare const smoother: Ease;
9
+ declare const easeInQuad: Ease;
10
+ declare const easeOutQuad: Ease;
11
+ declare const easeInCubic: Ease;
12
+ declare const easeOutCubic: Ease;
13
+ declare const easeInOutCubic: Ease;
14
+ declare const easeOutQuint: Ease;
15
+ declare const easeInOutQuint: Ease;
16
+ declare const easeOutExpo: Ease;
17
+ declare const easeInExpo: Ease;
18
+ declare const rushInto: Ease;
19
+ declare const rushFrom: Ease;
20
+ declare const slowInto: Ease;
21
+ /** Overshoot the target once, then settle. */
22
+ declare function overshoot(amount?: number): Ease;
23
+ /** Physically based settle. Exactly 1 at t=1 so holds never drift. */
24
+ declare function spring(options?: {
25
+ bounce?: number;
26
+ frequency?: number;
27
+ }): Ease;
28
+ declare const bounce: Ease;
29
+ /** Goes to 1 and returns to 0. Ends where it started, for emphasis. */
30
+ declare const thereAndBack: Ease;
31
+ declare function thereAndBackWithPause(pause?: number): Ease;
32
+ /** Oscillates around 0 and ends at 0. */
33
+ declare function wiggle(cycles?: number): Ease;
34
+ /** Stops short of the target, for an unfinished gesture. */
35
+ declare function notQuiteThere(amount?: number, inner?: Ease): Ease;
36
+ /** Holds at 1 for the last part of the time. */
37
+ declare function lingering(hold?: number, inner?: Ease): Ease;
38
+ /** Backs up briefly, then runs through to the target. */
39
+ declare function runningStart(pull?: number): Ease;
40
+ /** Restrict an ease to a window of the animation. */
41
+ declare function during(from: number, to: number, inner?: Ease): Ease;
42
+ /** CSS-style cubic-bezier timing function. */
43
+ declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Ease;
44
+
45
+ /**
46
+ * Vector geometry for the stage engine.
47
+ *
48
+ * Every shape is a list of rings. A ring is a run of cubic Bezier segments in a
49
+ * flat array: [x0, y0, c1x, c1y, c2x, c2y, x1, y1, c1x, ...]. One representation
50
+ * for lines, arcs, glyphs, and imported SVG makes any shape morph into any other.
51
+ *
52
+ * Rings and paths are immutable by convention. Length tables and bounds are
53
+ * cached per ring, so sampling the same geometry on many frames stays cheap.
54
+ */
55
+ type Vec = readonly [number, number];
56
+ /** 2x3 affine matrix: x' = a*x + c*y + e, y' = b*x + d*y + f. */
57
+ type Mat = readonly [number, number, number, number, number, number];
58
+ interface Ring {
59
+ readonly p: Float64Array;
60
+ readonly closed: boolean;
61
+ /** Every segment is a straight line, so painters can use cheap line commands. */
62
+ readonly straight?: boolean;
63
+ }
64
+ type Path = readonly Ring[];
65
+ interface Bounds {
66
+ readonly x: number;
67
+ readonly y: number;
68
+ readonly width: number;
69
+ readonly height: number;
70
+ }
71
+ declare const IDENTITY: Mat;
72
+ declare const EMPTY_BOUNDS: Bounds;
73
+ declare function mul(m: Mat, n: Mat): Mat;
74
+ declare function invert(m: Mat): Mat;
75
+ declare function apply(m: Mat, x: number, y: number): [number, number];
76
+ /** Translate * Rotate * Scale * Translate(-pivot). */
77
+ declare function compose(x: number, y: number, rotation: number, sx: number, sy: number, px: number, py: number): Mat;
78
+ /** Mean scale of a matrix, used to scale stroke widths with the geometry. */
79
+ declare function matScale(m: Mat): number;
80
+ declare function ring(points: ArrayLike<number>, closed?: boolean): Ring;
81
+ declare function segmentCount(r: Ring): number;
82
+ declare function linePath(a: Vec, b: Vec): Path;
83
+ declare function polyPath(points: readonly Vec[], closed?: boolean): Path;
84
+ /** A smooth cubic spline through every point (Catmull-Rom, centripetal-ish tension). */
85
+ declare function smoothPath(points: readonly Vec[], closed?: boolean, tension?: number): Path;
86
+ /** Elliptical or circular arc, with one cubic per 45 degrees at most. */
87
+ declare function arcPath(cx: number, cy: number, rx: number, ry: number, from: number, to: number): Path;
88
+ declare function circlePath(cx: number, cy: number, r: number): Path;
89
+ declare function rectPath(x: number, y: number, width: number, height: number, radius?: number): Path;
90
+ /** Smooth open curve through samples of a parametric function. */
91
+ declare function parametricPath(f: (t: number) => Vec, from: number, to: number, samples?: number): Path;
92
+ /**
93
+ * Hermite fit through samples. Non-finite samples split the curve into separate
94
+ * rings, so poles such as tan(x) leave gaps instead of drawing vertical strokes.
95
+ */
96
+ declare function curveThrough(points: readonly Vec[]): Path;
97
+ declare function concat(...paths: readonly Path[]): Path;
98
+ declare function transformPath(path: Path, m: Mat): Path;
99
+ /** Deform a path through any point function. Segments split first, so curved maps stay smooth. */
100
+ declare function warpPath(path: Path, f: (x: number, y: number) => Vec, subdivisions?: number): Path;
101
+ /** Split every segment of a ring into n equal parameter pieces. Geometry is unchanged. */
102
+ declare function subdivideEach(r: Ring, n: number): Ring;
103
+ declare function ringLength(r: Ring): number;
104
+ declare function pathLength(path: Path): number;
105
+ /** Keep the part of a ring between two arc-length fractions. */
106
+ declare function trimRing(r: Ring, from: number, to: number): Ring | null;
107
+ /**
108
+ * Keep a fraction of a path. With `each`, every ring draws at once, which suits
109
+ * glyphs. Without it, rings draw one after another along the total length.
110
+ */
111
+ declare function trimPath(path: Path, from: number, to: number, each?: boolean): Path;
112
+ /** Point at an arc-length fraction of a path, in the path's own coordinates. */
113
+ declare function pointAt(path: Path, fraction: number): [number, number];
114
+ /** Unit tangent at an arc-length fraction, in the path's own coordinates. */
115
+ declare function tangentAt(path: Path, fraction: number): [number, number];
116
+ declare function pathBounds(path: Path): Bounds | null;
117
+ declare function unionBounds(a: Bounds | null, b: Bounds | null): Bounds | null;
118
+ /** Shoelace area over the anchors. The sign gives the winding direction. */
119
+ declare function signedArea(r: Ring): number;
120
+ declare function ringCenter(r: Ring): [number, number];
121
+ declare function reverseRing(r: Ring): Ring;
122
+ /** Parse SVG path data, including arcs and relative commands, into cubic rings. */
123
+ declare function parseSvgPath(d: string): Path;
124
+ /** Serialize a path to compact SVG path data. */
125
+ declare function pathToD(path: Path): string;
126
+
127
+ /** r, g, b from 0 to 255 and alpha from 0 to 1. */
128
+ type Rgba = readonly [number, number, number, number];
129
+ interface LinearGradient {
130
+ readonly type: 'linear';
131
+ readonly from: readonly [number, number];
132
+ readonly to: readonly [number, number];
133
+ readonly stops: readonly (readonly [number, Rgba])[];
134
+ }
135
+ interface RadialGradient {
136
+ readonly type: 'radial';
137
+ readonly center: readonly [number, number];
138
+ readonly radius: number;
139
+ readonly stops: readonly (readonly [number, Rgba])[];
140
+ }
141
+ /** Stroke whose color changes along its arc length. */
142
+ interface AlongGradient {
143
+ readonly type: 'along';
144
+ readonly stops: readonly (readonly [number, Rgba])[];
145
+ }
146
+ type Gradient = LinearGradient | RadialGradient | AlongGradient;
147
+ type Paint = Rgba | Gradient;
148
+ type ColorInput = string | Rgba | Gradient;
149
+ declare function parseColor(input: string): Rgba;
150
+ declare function toPaint(input: ColorInput): Paint;
151
+ declare function css(color: Rgba, alpha?: number): string;
152
+ /** Mix two colors in OKLab, which keeps blends bright and even in tone. */
153
+ declare function mixColor(a: Rgba, b: Rgba, t: number): Rgba;
154
+ declare function linearGradient(from: readonly [number, number], to: readonly [number, number], colors: readonly ColorInput[] | readonly (readonly [number, ColorInput])[]): LinearGradient;
155
+ declare function radialGradient(center: readonly [number, number], radius: number, colors: readonly ColorInput[]): RadialGradient;
156
+ /** Color that travels along a stroke, such as a graph that warms from left to right. */
157
+ declare function along$1(...colors: readonly ColorInput[]): AlongGradient;
158
+ /** Evenly spaced colors between stops, for coloring a list of items. */
159
+ declare function ramp(count: number, ...colors: readonly ColorInput[]): Rgba[];
160
+
161
+ interface Key<T> {
162
+ t0: number;
163
+ t1: number;
164
+ ease: Ease | null;
165
+ to: T;
166
+ /** Value at eased progress. Absent for a step key. */
167
+ at: ((alpha: number) => T) | null;
168
+ }
169
+ /** One property over time. Keys sort by start time, and a later key wins from its start. */
170
+ declare class Track<T> {
171
+ initial: T;
172
+ readonly keys: Key<T>[];
173
+ constructor(initial: T);
174
+ sample(t: number): T;
175
+ add(key: Key<T>): void;
176
+ step(t: number, value: T): void;
177
+ /** Last time this track changes. */
178
+ get end(): number;
179
+ }
180
+
181
+ type BlendMode = 'normal' | 'screen' | 'multiply' | 'overlay';
182
+ type Edge = 'left' | 'right' | 'top' | 'bottom';
183
+ type Side = Edge | 'up' | 'down' | Vec;
184
+ interface NodeProps {
185
+ x: number;
186
+ y: number;
187
+ rotation: number;
188
+ sx: number;
189
+ sy: number;
190
+ px: number;
191
+ py: number;
192
+ opacity: number;
193
+ visible: boolean;
194
+ z: number;
195
+ path: Path | null;
196
+ fill: Paint | null;
197
+ fillOpacity: number;
198
+ stroke: Paint | null;
199
+ strokeOpacity: number;
200
+ strokeWidth: number;
201
+ cap: 'round' | 'butt' | 'square';
202
+ join: 'round' | 'miter' | 'bevel';
203
+ dash: readonly number[] | null;
204
+ dashOffset: number;
205
+ trimFrom: number;
206
+ trimTo: number;
207
+ trimEach: boolean;
208
+ glow: number;
209
+ glowColor: Rgba | null;
210
+ blend: BlendMode;
211
+ /** Ignore the camera. Use it for titles, captions, and other screen-space marks. */
212
+ fixed: boolean;
213
+ image: StageImage | null;
214
+ }
215
+ interface StageImage {
216
+ /** Browser-usable URL or data URL. */
217
+ readonly src: string;
218
+ readonly width: number;
219
+ readonly height: number;
220
+ }
221
+ type PropName = keyof NodeProps;
222
+ /**
223
+ * Every visible thing on stage. A node with a path draws. A node with children
224
+ * groups. Both can carry a transform, and every property can change over time.
225
+ *
226
+ * Setter methods chain and apply at the current point on the timeline, so the
227
+ * same calls set up a node before it appears and change it afterwards.
228
+ */
229
+ declare class Node {
230
+ readonly id: number;
231
+ parent: Node | null;
232
+ children: Node[];
233
+ /** Free-form metadata, such as the source character of a glyph. */
234
+ data: Record<string, unknown>;
235
+ /** Label shown in timelines and diagnostics. */
236
+ label: string;
237
+ base: NodeProps;
238
+ tracks: Map<PropName, Track<unknown>> | null;
239
+ overlay: Map<string, unknown> | null;
240
+ overlayFrame: number;
241
+ /** On stage: writes become timeline keys instead of initial state. */
242
+ mounted: boolean;
243
+ /** Rebuilt on every frame from timeline values. */
244
+ draw: ((time: number) => Node | readonly Node[] | null) | null;
245
+ /** Emits draw operations directly, for objects with thousands of marks such as 3D meshes. */
246
+ rawOps: ((matrix: Mat, alpha: number, ops: DrawOp[]) => void) | null;
247
+ constructor(path?: Path | null);
248
+ get<K extends PropName>(prop: K): NodeProps[K];
249
+ set<K extends PropName>(prop: K, value: NodeProps[K]): this;
250
+ track<K extends PropName>(prop: K): Track<NodeProps[K]>;
251
+ /** Record a change from the current value to `to` over [t0, t1]. */
252
+ tween<K extends PropName>(prop: K, to: NodeProps[K], t0: number, t1: number, ease: Ease | null): void;
253
+ add(...nodes: Node[]): this;
254
+ drop(child: Node): this;
255
+ /** Self and all descendants, parents first. */
256
+ all(): Node[];
257
+ /** Descendants that draw something. A leaf group returns itself if it draws. */
258
+ leaves(): Node[];
259
+ /** A static copy of the current state, off stage. */
260
+ clone(): this;
261
+ localMatrix(): Mat;
262
+ worldMatrix(): Mat;
263
+ toWorld(x: number, y: number): [number, number];
264
+ /** Stage-space bounds of this node and its descendants. */
265
+ bounds(): Bounds;
266
+ private boundsFrom;
267
+ get center(): [number, number];
268
+ get top(): [number, number];
269
+ get bottom(): [number, number];
270
+ get left(): [number, number];
271
+ get right(): [number, number];
272
+ get width(): number;
273
+ get height(): number;
274
+ /** Set the local position of the origin. */
275
+ at(x: number | Vec, y?: number): this;
276
+ shift(dx: number | Vec, dy?: number): this;
277
+ /** Move so the center of the bounds lands on a stage point or on another node's center. */
278
+ moveTo(target: Vec | Node): this;
279
+ /** Move the origin to a stage point without changing how anything looks. */
280
+ pivotAt(point: Vec): this;
281
+ /** Scale around the center, or around a given stage point. */
282
+ scale(factor: number | Vec, about?: Vec): this;
283
+ /** Rotate around the center, or around a given stage point. */
284
+ rotate(radians: number, about?: Vec): this;
285
+ /** Scale to an exact on-screen width or height, keeping proportions. */
286
+ fitTo(size: {
287
+ width?: number;
288
+ height?: number;
289
+ }): this;
290
+ /** Place beside another node or stage point, with a gap measured between bounds. */
291
+ nextTo(target: Node | Vec, side?: Side, gap?: number): this;
292
+ /** Line up one edge with another node's same edge. */
293
+ alignTo(target: Node | Vec, edge: Edge): this;
294
+ /** Lay out children in a row or column, keeping the group's center. */
295
+ arrange(side?: Side, gap?: number): this;
296
+ fill(color: ColorInput | null, opacity?: number): this;
297
+ stroke(color: ColorInput | null, width?: number, opacity?: number): this;
298
+ /** Recolor this node and its descendants, keeping whichever paints exist. */
299
+ color(color: ColorInput): this;
300
+ opacity(value: number): this;
301
+ /** Soft light around the shape. The radius is in stage pixels. */
302
+ glow(radius: number, color?: ColorInput): this;
303
+ dash(pattern: readonly number[] | null, offset?: number): this;
304
+ zIndex(value: number): this;
305
+ /** Pin to the screen so the camera does not move this node. */
306
+ pin(): this;
307
+ hide(): this;
308
+ show(): this;
309
+ named(label: string): this;
310
+ }
311
+ /** A group. Children keep their own transforms inside it. */
312
+ declare function group(...children: Node[]): Node;
313
+ /** A node that rebuilds its contents on every frame from timeline values. */
314
+ declare function dynamic(build: (time: number) => Node | readonly Node[] | null): Node;
315
+
316
+ interface PathOp {
317
+ readonly kind: 'path';
318
+ readonly path: Path;
319
+ /** Stroke geometry when it differs from the fill, such as during a partial draw. */
320
+ readonly strokePath: Path;
321
+ readonly fill: Paint | null;
322
+ readonly fillAlpha: number;
323
+ readonly stroke: Paint | null;
324
+ readonly strokeAlpha: number;
325
+ readonly strokeWidth: number;
326
+ readonly cap: 'round' | 'butt' | 'square';
327
+ readonly join: 'round' | 'miter' | 'bevel';
328
+ readonly dash: readonly number[] | null;
329
+ readonly dashOffset: number;
330
+ readonly glow: number;
331
+ readonly glowColor: Rgba | null;
332
+ readonly blend: BlendMode;
333
+ /** The node that produced this mark, for checks and tools. */
334
+ readonly node?: Node;
335
+ }
336
+ interface ImageOp {
337
+ readonly kind: 'image';
338
+ readonly image: StageImage;
339
+ readonly matrix: Mat;
340
+ readonly alpha: number;
341
+ }
342
+ type DrawOp = PathOp | ImageOp;
343
+ interface Frame {
344
+ readonly width: number;
345
+ readonly height: number;
346
+ readonly background: string | null;
347
+ readonly bloom: number;
348
+ readonly ops: readonly DrawOp[];
349
+ readonly dark: boolean;
350
+ }
351
+ interface CameraState {
352
+ readonly x: number;
353
+ readonly y: number;
354
+ readonly zoom: number;
355
+ readonly rotation: number;
356
+ }
357
+ declare function buildOps(root: Node, camera: CameraState, width: number, height: number): DrawOp[];
358
+ /** Serialize a frame to standalone SVG. Text is already outlines, so no fonts are needed. */
359
+ declare function frameToSvg(frame: Frame, options?: {
360
+ scale?: number;
361
+ transparent?: boolean;
362
+ }): string;
363
+ type Canvas2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
364
+ interface ImageLookup {
365
+ (image: StageImage): CanvasImageSource | null;
366
+ }
367
+ /** Paint a frame to a 2D context at a device scale. Same result as the SVG backend. */
368
+ declare function paintFrame(ctx: Canvas2D, frame: Frame, scale?: number, images?: ImageLookup): void;
369
+ /** Pixel-space bounds of a frame's ink, used by checks for off-canvas marks. */
370
+ declare function frameInkBounds(frame: Frame): {
371
+ x: number;
372
+ y: number;
373
+ width: number;
374
+ height: number;
375
+ } | null;
376
+
377
+ /**
378
+ * A look is a complete art direction for a film: background, ink, a small set
379
+ * of named pigments, and how much light the image gives off. Authors write
380
+ * `color: 'yellow'`, so one film renders correctly in every look.
381
+ */
382
+ interface Look {
383
+ readonly name: string;
384
+ readonly dark: boolean;
385
+ readonly background: string;
386
+ /** Full-frame bloom in the light-emitting looks. 0 turns it off. */
387
+ readonly bloom: number;
388
+ readonly colors: Readonly<Record<LookToken, string>>;
389
+ }
390
+ type LookToken = 'bg' | 'surface' | 'ink' | 'dim' | 'faint' | 'grid' | 'gridStrong' | 'blue' | 'teal' | 'green' | 'yellow' | 'gold' | 'orange' | 'red' | 'pink' | 'purple';
391
+ /** Deep neutral black with luminous pigments. The default. */
392
+ declare const midnight: Look;
393
+ /** Warm paper and printed ink, for articles and print. */
394
+ declare const paper: Look;
395
+ /** Drafting-table navy with cool cyan linework. */
396
+ declare const blueprint: Look;
397
+ /** Near-black green with warm chalk, for classroom-style lessons. */
398
+ declare const chalk: Look;
399
+ /** Saturated light on pure black, for trailers and hero loops. */
400
+ declare const neon: Look;
401
+ declare const LOOKS: {
402
+ readonly midnight: Look;
403
+ readonly paper: Look;
404
+ readonly blueprint: Look;
405
+ readonly chalk: Look;
406
+ readonly neon: Look;
407
+ };
408
+ type LookName = keyof typeof LOOKS;
409
+ declare function resolveLook(look: LookName | Look | undefined): Look;
410
+
411
+ interface AnimContext {
412
+ t0: number;
413
+ t1: number;
414
+ ease: Ease;
415
+ stage: Stage;
416
+ }
417
+ /** A piece of motion. `schedule` writes timeline keys for a window of time. */
418
+ interface Anim {
419
+ label: string;
420
+ duration: number;
421
+ ease?: Ease;
422
+ schedule(ctx: AnimContext): void;
423
+ }
424
+ interface AnimOptions {
425
+ duration?: number;
426
+ ease?: Ease;
427
+ /** Fraction of one item's time between the starts of consecutive items. */
428
+ lag?: number;
429
+ }
430
+ type Target = Node | readonly Node[];
431
+ /** Run together. Each piece keeps its own length unless the whole is rescaled. */
432
+ declare function par(...anims: readonly Anim[]): Anim;
433
+ /** Run one after another. */
434
+ declare function seq(...anims: readonly Anim[]): Anim;
435
+ /** Start each piece after a fraction of the previous one has played. */
436
+ declare function lagged(anims: readonly Anim[], options?: {
437
+ lag?: number;
438
+ duration?: number;
439
+ }): Anim;
440
+ declare function delay(anim: Anim, seconds: number): Anim;
441
+ /** Change an animation's length or easing without changing what it does. */
442
+ declare function retime(anim: Anim, options: AnimOptions): Anim;
443
+ /** Run a plain function at a moment on the timeline. */
444
+ declare function call(fn: () => void): Anim;
445
+ /** Trace strokes in order. Filled shapes outline first, then fill. */
446
+ declare function draw(target: Target, options?: AnimOptions): Anim;
447
+ /** Handwrite text and equations: each glyph is outlined, then filled. */
448
+ declare function write(target: Target, options?: AnimOptions): Anim;
449
+ /** The reverse of draw. */
450
+ declare function erase(target: Target, options?: AnimOptions): Anim;
451
+ interface FadeOptions extends AnimOptions {
452
+ /** Start offset for fades in, or travel for fades out. */
453
+ shift?: Vec;
454
+ /** Start scale for fades in, or end scale for fades out. */
455
+ scale?: number;
456
+ }
457
+ declare function fadeIn(target: Target, options?: FadeOptions): Anim;
458
+ declare function fadeOut(target: Target, options?: FadeOptions): Anim;
459
+ /** Scale up from nothing. Pass a stage point to grow from it, such as an arrow's tail. */
460
+ declare function grow(target: Target, options?: AnimOptions & {
461
+ from?: Vec;
462
+ }): Anim;
463
+ /** Show at this moment, with no transition. */
464
+ declare function appear(target: Target): Anim;
465
+ /** Hide at this moment, with no transition. */
466
+ declare function vanish(target: Target): Anim;
467
+ /**
468
+ * Animate any change. Make the change on the node inside the callback, and the
469
+ * engine interpolates from the old state to the new one, including geometry.
470
+ *
471
+ * s.play(to(dot, (d) => d.moveTo(axes.p(2, 4)).color('yellow').scale(1.5)))
472
+ */
473
+ declare function to<T extends Node>(node: T, change: (node: T) => unknown, options?: AnimOptions & {
474
+ restore?: boolean;
475
+ }): Anim;
476
+ declare function moveTo(node: Node, target: Vec | Node, options?: AnimOptions): Anim;
477
+ declare function shift(node: Node, dx: number, dy: number, options?: AnimOptions): Anim;
478
+ declare function scaleBy(node: Node, factor: number | Vec, options?: AnimOptions & {
479
+ about?: Vec;
480
+ }): Anim;
481
+ declare function rotate(node: Node, radians: number, options?: AnimOptions & {
482
+ about?: Vec;
483
+ }): Anim;
484
+ declare function recolor(node: Node, color: ColorInput, options?: AnimOptions): Anim;
485
+ declare function fade(node: Node, opacity: number, options?: AnimOptions): Anim;
486
+ /** Follow a path, or the shape of a node, from start to end. */
487
+ declare function along(node: Node, track: Path | Node, options?: AnimOptions & {
488
+ orient?: boolean;
489
+ }): Anim;
490
+ /**
491
+ * Deform every shape under a node through a function of stage position.
492
+ * This is how a grid bends under a matrix or a complex map.
493
+ */
494
+ declare function warp(target: Target, f: (x: number, y: number) => Vec, options?: AnimOptions & {
495
+ subdivisions?: number;
496
+ }): Anim;
497
+ /** Multiply a node's geometry by a 2x2 matrix around a stage point. */
498
+ declare function applyMatrix(target: Target, matrix: readonly [readonly [number, number], readonly [number, number]], options?: AnimOptions & {
499
+ origin?: Vec;
500
+ yUp?: boolean;
501
+ }): Anim;
502
+ /**
503
+ * Turn `from` into `to`, whatever their shapes. Afterwards `to` is on stage and
504
+ * `from` is hidden, so later code always refers to the node it can see.
505
+ */
506
+ declare function morph(from: Target, to: Target, options?: AnimOptions & {
507
+ lag?: number;
508
+ }): Anim;
509
+ /**
510
+ * Morph equations and labels by meaning. Glyphs that exist on both sides travel
511
+ * to their new places. The rest fade out or in where they stand.
512
+ */
513
+ declare function morphMatching(from: Node, to: Node, options?: AnimOptions & {
514
+ key?: (leaf: Node) => unknown;
515
+ fadeShift?: Vec;
516
+ }): Anim;
517
+ /** Swell and tint for a moment, then return. */
518
+ declare function indicate(target: Target, options?: AnimOptions & {
519
+ color?: ColorInput;
520
+ scale?: number;
521
+ }): Anim;
522
+ /** Shake gently to draw the eye. */
523
+ declare function shake(node: Node, options?: AnimOptions & {
524
+ angle?: number;
525
+ cycles?: number;
526
+ }): Anim;
527
+ /** Trace a line around a node for emphasis, then let it run off. */
528
+ declare function circumscribe(target: Node, options?: AnimOptions & {
529
+ color?: ColorInput;
530
+ pad?: number;
531
+ radius?: number;
532
+ width?: number;
533
+ }): Anim;
534
+ /** Radial burst at a point, for a moment of arrival. */
535
+ declare function flash(point: Vec | Node, options?: AnimOptions & {
536
+ color?: ColorInput;
537
+ radius?: number;
538
+ rays?: number;
539
+ }): Anim;
540
+ /** Expanding ring that fades out, for a pulse from a point. */
541
+ declare function ripple(point: Vec | Node, options?: AnimOptions & {
542
+ color?: ColorInput;
543
+ radius?: number;
544
+ width?: number;
545
+ }): Anim;
546
+ /**
547
+ * A short lit segment that travels along a line: a packet on an edge, a signal
548
+ * on a wire. The source line stays in place underneath.
549
+ */
550
+ declare function pulse(line: Node, options?: AnimOptions & {
551
+ color?: ColorInput;
552
+ length?: number;
553
+ width?: number;
554
+ glow?: number;
555
+ }): Anim;
556
+ /** A number on the timeline. Read `.value` inside `dynamic` and `update` to drive anything. */
557
+ declare class Value {
558
+ readonly track: Track<number>;
559
+ constructor(initial: number);
560
+ get value(): number;
561
+ /** Set at the current point on the timeline. */
562
+ set(value: number): this;
563
+ to(value: number, options?: AnimOptions): Anim;
564
+ }
565
+
566
+ type Aspect = '16:9' | '9:16' | '1:1' | '4:3' | '21:9';
567
+ interface FilmOptions {
568
+ /** Lines and shapes run past the frame edges on purpose, as a warped grid does. Text is still checked. */
569
+ bleed?: boolean;
570
+ title?: string;
571
+ description?: string;
572
+ /** Logical stage size. 16:9 is 1920x1080. Everything is authored in these units. */
573
+ aspect?: Aspect;
574
+ width?: number;
575
+ height?: number;
576
+ fps?: number;
577
+ look?: LookName | Look;
578
+ background?: string | null;
579
+ /** Light that spills from bright marks. Defaults to the look's value. */
580
+ bloom?: number;
581
+ /** Time in seconds of the frame to use as a poster. Defaults to the richest frame. */
582
+ poster?: number;
583
+ }
584
+ interface Chapter {
585
+ title: string;
586
+ time: number;
587
+ }
588
+ interface Clip {
589
+ t0: number;
590
+ t1: number;
591
+ labels: string[];
592
+ }
593
+ interface Caption {
594
+ t0: number;
595
+ t1: number;
596
+ text: string;
597
+ }
598
+ interface PlayOptions {
599
+ duration?: number;
600
+ ease?: Ease;
601
+ /** Name shown in timelines. */
602
+ label?: string;
603
+ }
604
+ interface Updater {
605
+ node: Node;
606
+ fn: (node: Node, time: number) => void;
607
+ from: number;
608
+ to: number;
609
+ }
610
+ /** The timeline a film is authored on. All coordinates are centered: (0, 0) is mid-frame and y points down. */
611
+ declare class Stage {
612
+ readonly root: Node;
613
+ /** Move, zoom, and rotate the view with to(s.camera, ...). `sx` is the zoom. */
614
+ readonly camera: Node;
615
+ readonly width: number;
616
+ readonly height: number;
617
+ readonly fps: number;
618
+ readonly look: Look;
619
+ readonly chapters: Chapter[];
620
+ readonly clips: Clip[];
621
+ readonly captions: Caption[];
622
+ readonly updaters: Updater[];
623
+ time: number;
624
+ private ending;
625
+ constructor(options: FilmOptions);
626
+ /** Half of the frame in each direction. */
627
+ get right(): number;
628
+ get left(): number;
629
+ get top(): number;
630
+ get bottom(): number;
631
+ /** Put nodes on stage now. Returns the first, so setup reads as one line. */
632
+ add<T extends Node>(first: T, ...rest: Node[]): T;
633
+ /** Put a node on stage so it first shows at `time`, which may differ from the cursor. */
634
+ mountAt(node: Node, time: number): void;
635
+ remove(...nodes: Node[]): void;
636
+ /** Run animations together and advance the timeline past them. */
637
+ play(...items: (Anim | PlayOptions)[]): this;
638
+ /** Hold on the current picture. */
639
+ wait(seconds?: number): this;
640
+ /** Author something at another time, then return to where you were. */
641
+ at(time: number, build: () => void): this;
642
+ /** Mark a chapter for the player, presentation steps, and the timeline. */
643
+ chapter(title: string): this;
644
+ /** Show a caption for a span of time. Captions also export as a VTT sidecar. */
645
+ caption(text: string, duration?: number): this;
646
+ /** A number that animates, for driving dynamic drawings. */
647
+ value(initial?: number): Value;
648
+ /** Re-run a function each frame while the node shows. It can set any property on the node. */
649
+ update<T extends Node>(node: T, fn: (node: T, time: number) => void, window?: {
650
+ from?: number;
651
+ to?: number;
652
+ }): T;
653
+ get duration(): number;
654
+ }
655
+ interface FilmDefinition {
656
+ readonly kind: 'vizmatic.film';
657
+ readonly options: FilmOptions;
658
+ readonly build: (stage: Stage) => void | Promise<void>;
659
+ /**
660
+ * Compile with the engine that authored this film. The clock is module state,
661
+ * so a tool with its own bundled engine must call this and not its own compileFilm.
662
+ */
663
+ readonly compile: (overrides?: CompileOverrides) => Promise<CompiledFilm>;
664
+ }
665
+ /** Define a film: a function that authors a timeline on a stage. */
666
+ declare function film(build: (stage: Stage) => void | Promise<void>): FilmDefinition;
667
+ declare function film(options: FilmOptions, build: (stage: Stage) => void | Promise<void>): FilmDefinition;
668
+ declare function isFilm(value: unknown): value is FilmDefinition;
669
+ /** Thrown while an asset loads. The compiler waits and runs the build function again. */
670
+ declare class Suspend {
671
+ readonly promise: Promise<unknown>;
672
+ /** Lets a second copy of the engine recognize this without instanceof. */
673
+ readonly isVizmaticSuspend = true;
674
+ constructor(promise: Promise<unknown>);
675
+ }
676
+ /** True for a Suspend thrown by any copy of the engine. */
677
+ declare function isSuspend(error: unknown): error is Suspend;
678
+ interface CompileOverrides {
679
+ look?: LookName | Look;
680
+ fps?: number;
681
+ bloom?: number;
682
+ background?: string | null;
683
+ }
684
+ /** A film ready to sample. `frame(t)` is pure: seek to any time, in any order. */
685
+ declare class CompiledFilm {
686
+ readonly width: number;
687
+ readonly height: number;
688
+ readonly fps: number;
689
+ readonly duration: number;
690
+ readonly title: string;
691
+ readonly description: string;
692
+ readonly look: Look;
693
+ readonly bloom: number;
694
+ readonly background: string | null;
695
+ /** The author's chosen poster time, when set. */
696
+ readonly posterTime: number | undefined;
697
+ readonly bleed: boolean;
698
+ readonly chapters: readonly Chapter[];
699
+ readonly clips: readonly Clip[];
700
+ readonly captions: readonly Caption[];
701
+ readonly stage: Stage;
702
+ constructor(stage: Stage, options: FilmOptions, overrides: CompileOverrides);
703
+ get frameCount(): number;
704
+ /** The draw list at a time in seconds. May throw Suspend if a drawing needs a new asset. */
705
+ frame(time: number): Frame;
706
+ /** Standalone SVG for a time. */
707
+ svg(time: number, options?: {
708
+ transparent?: boolean;
709
+ scale?: number;
710
+ }): string;
711
+ }
712
+ /** Run the build function, waiting for fonts and math when it asks for them, and return a seekable film. */
713
+ declare function compileFilm(definition: FilmDefinition, overrides?: CompileOverrides): Promise<CompiledFilm>;
714
+
715
+ interface FromSvgOptions {
716
+ /** Fit into this box, keeping proportions. Defaults to the SVG's own size. */
717
+ width?: number;
718
+ height?: number;
719
+ /** Center the picture on the node's origin. On by default. */
720
+ center?: boolean;
721
+ /** Keep a full-canvas background rectangle. Films have their own, so it is dropped by default. */
722
+ background?: boolean;
723
+ /** Split filled multi-glyph outlines into one node per glyph, so text writes letter by letter. */
724
+ splitGlyphs?: boolean;
725
+ }
726
+ /** An imported picture. It is a regular node tree, so every verb works on it. */
727
+ declare class SvgNode extends Node {
728
+ readonly byId: Map<string, Node>;
729
+ pictureWidth: number;
730
+ pictureHeight: number;
731
+ /** Find an element by its SVG id. */
732
+ find(id: string): Node;
733
+ }
734
+ /**
735
+ * Turn SVG markup into stage nodes. Each shape becomes a leaf whose origin is its
736
+ * center, so it can be drawn, faded, scaled, and morphed like anything else.
737
+ * Filters and masks are skipped, because shapes draw without them.
738
+ */
739
+ declare function fromSvg(source: string, options?: FromSvgOptions): SvgNode;
740
+
741
+ export { bounce as $, IDENTITY as I, Stage as K, LOOKS as L, Node as N, Suspend as Q, SvgNode as S, along as U, appear as W, apply as X, applyMatrix as Y, arcPath as Z, blueprint as _, CompiledFilm as a, pathToD as a$, buildOps as a0, call as a1, chalk as a2, circlePath as a3, circumscribe as a4, along$1 as a5, compileFilm as a6, compose as a7, concat as a8, css as a9, indicate as aA, invert as aB, isFilm as aC, isSuspend as aD, lagged as aE, linePath as aF, linear as aG, linearGradient as aH, lingering as aI, matScale as aJ, midnight as aK, mixColor as aL, morph as aM, morphMatching as aN, moveTo as aO, mul as aP, neon as aQ, notQuiteThere as aR, overshoot as aS, paintFrame as aT, paper as aU, par as aV, parametricPath as aW, parseColor as aX, parseSvgPath as aY, pathBounds as aZ, pathLength as a_, cubicBezier as aa, curveThrough as ab, delay as ac, draw as ad, during as ae, dynamic as af, easeInCubic as ag, easeInExpo as ah, easeInOutCubic as ai, easeInOutQuint as aj, easeInQuad as ak, easeOutCubic as al, easeOutExpo as am, easeOutQuad as an, easeOutQuint as ao, erase as ap, fade as aq, fadeIn as ar, fadeOut as as, film as at, flash as au, frameInkBounds as av, frameToSvg as aw, fromSvg as ax, group as ay, grow as az, pointAt as b0, polyPath as b1, pulse as b2, radialGradient as b3, ramp as b4, recolor as b5, rectPath as b6, resolveLook as b7, retime as b8, reverseRing as b9, transformPath as bA, trimPath as bB, trimRing as bC, unionBounds as bD, vanish as bE, warp as bF, warpPath as bG, wiggle as bH, write as bI, ring as ba, ringCenter as bb, ringLength as bc, ripple as bd, rotate as be, runningStart as bf, rushFrom as bg, rushInto as bh, scaleBy as bi, segmentCount as bj, seq as bk, shake as bl, shift as bm, signedArea as bn, slowInto as bo, smooth as bp, smoothBy as bq, smoothPath as br, smoother as bs, spring as bt, subdivideEach as bu, tangentAt as bv, thereAndBack as bw, thereAndBackWithPause as bx, to as by, toPaint as bz, Value as f, EMPTY_BOUNDS as o };
742
+ export type { AnimOptions as A, Bounds as B, CompileOverrides as C, DrawOp as D, Edge as E, FromSvgOptions as F, Gradient as G, PropName as H, Ring as J, Mat as M, StageImage as O, Path as P, Rgba as R, Target as T, Vec as V, FilmDefinition as b, ColorInput as c, Side as d, Anim as e, PathOp as g, AnimContext as h, Aspect as i, BlendMode as j, Canvas2D as k, Caption as l, Chapter as m, Clip as n, Ease as p, FadeOptions as q, FilmOptions as r, Frame as s, ImageOp as t, Look as u, LookName as v, LookToken as w, NodeProps as x, Paint as y, PlayOptions as z };