vizmatic 0.7.2 → 0.8.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.
@@ -178,6 +178,44 @@ declare class Track<T> {
178
178
  get end(): number;
179
179
  }
180
180
 
181
+ /** Encoded bytes and intrinsic dimensions, validated before a film uses them. */
182
+ interface ImageAsset {
183
+ readonly id?: string;
184
+ readonly src: string;
185
+ readonly mediaType: 'image/png' | 'image/jpeg' | 'image/gif';
186
+ readonly width: number;
187
+ readonly height: number;
188
+ readonly sha256: string;
189
+ }
190
+ interface ImageAssetOptions {
191
+ id?: string;
192
+ mediaType?: string;
193
+ sha256?: string;
194
+ /** Resolve a local filename relative to this directory in Node. */
195
+ baseDir?: string;
196
+ /** Expected intrinsic dimensions, such as those declared in an asset manifest. */
197
+ width?: number;
198
+ height?: number;
199
+ }
200
+ interface ImageCrop {
201
+ x: number;
202
+ y: number;
203
+ width: number;
204
+ height: number;
205
+ }
206
+ interface ImageFitOptions {
207
+ width?: number;
208
+ height?: number;
209
+ fit?: 'contain' | 'cover';
210
+ /** A region in intrinsic image pixels, before fitting the destination box. */
211
+ crop?: ImageCrop;
212
+ }
213
+ declare class ImageAssetError extends Error {
214
+ constructor(message: string);
215
+ }
216
+ /** Load once before authoring. No network request or file read occurs while painting. */
217
+ declare function resolveImageAsset(source: string | Uint8Array, options?: ImageAssetOptions): Promise<ImageAsset>;
218
+
181
219
  type BlendMode = 'normal' | 'screen' | 'multiply' | 'overlay';
182
220
  type Edge = 'left' | 'right' | 'top' | 'bottom';
183
221
  type Side = Edge | 'up' | 'down' | Vec;
@@ -213,10 +251,12 @@ interface NodeProps {
213
251
  image: StageImage | null;
214
252
  }
215
253
  interface StageImage {
216
- /** Browser-usable URL or data URL. */
254
+ /** Embedded raster, local filename or legacy URL, resolved before the film is rendered. */
217
255
  readonly src: string;
218
256
  readonly width: number;
219
257
  readonly height: number;
258
+ readonly crop?: Readonly<ImageCrop>;
259
+ readonly asset?: ImageAsset;
220
260
  }
221
261
  type PropName = keyof NodeProps;
222
262
  /**
@@ -338,6 +378,7 @@ interface ImageOp {
338
378
  readonly image: StageImage;
339
379
  readonly matrix: Mat;
340
380
  readonly alpha: number;
381
+ readonly node?: Node;
341
382
  }
342
383
  type DrawOp = PathOp | ImageOp;
343
384
  interface Frame {
@@ -565,6 +606,8 @@ declare class Value {
565
606
 
566
607
  type Aspect = '16:9' | '9:16' | '1:1' | '4:3' | '21:9';
567
608
  interface FilmOptions {
609
+ /** Legacy URL images are allowed by default. Prepared image assets never use the network. */
610
+ imageNetwork?: 'allow' | 'deny';
568
611
  /** Lines and shapes run past the frame edges on purpose, as a warped grid does. Text is still checked. */
569
612
  bleed?: boolean;
570
613
  title?: string;
@@ -676,6 +719,7 @@ declare class Suspend {
676
719
  /** True for a Suspend thrown by any copy of the engine. */
677
720
  declare function isSuspend(error: unknown): error is Suspend;
678
721
  interface CompileOverrides {
722
+ imageNetwork?: 'allow' | 'deny';
679
723
  look?: LookName | Look;
680
724
  fps?: number;
681
725
  bloom?: number;
@@ -683,6 +727,9 @@ interface CompileOverrides {
683
727
  }
684
728
  /** A film ready to sample. `frame(t)` is pure: seek to any time, in any order. */
685
729
  declare class CompiledFilm {
730
+ private readonly allowImageNetwork;
731
+ private readonly imageAssets;
732
+ private readonly imageLoads;
686
733
  readonly width: number;
687
734
  readonly height: number;
688
735
  readonly fps: number;
@@ -701,6 +748,9 @@ declare class CompiledFilm {
701
748
  readonly stage: Stage;
702
749
  constructor(stage: Stage, options: FilmOptions, overrides: CompileOverrides);
703
750
  get frameCount(): number;
751
+ private prepareImage;
752
+ /** Preload static and keyed images, including those not visible in the first frame. */
753
+ preloadImages(): Promise<void>;
704
754
  /** The draw list at a time in seconds. May throw Suspend if a drawing needs a new asset. */
705
755
  frame(time: number): Frame;
706
756
  /** Standalone SVG for a time. */
@@ -738,5 +788,5 @@ declare class SvgNode extends Node {
738
788
  */
739
789
  declare function fromSvg(source: string, options?: FromSvgOptions): SvgNode;
740
790
 
741
- export { bounce as $, IDENTITY as I, 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, Stage as g, EMPTY_BOUNDS as p };
742
- export type { AnimOptions as A, Bounds as B, CompileOverrides as C, DrawOp as D, Edge as E, FromSvgOptions as F, Gradient as G, PlayOptions as H, PropName as J, Ring as K, 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 h, AnimContext as i, Aspect as j, BlendMode as k, Canvas2D as l, Caption as m, Chapter as n, Clip as o, Ease as q, FadeOptions as r, FilmOptions as s, Frame as t, ImageOp as u, Look as v, LookName as w, LookToken as x, NodeProps as y, Paint as z };
791
+ export { appear as $, LOOKS as L, Node as N, SvgNode as S, Suspend as Z, along as _, CompiledFilm as a, parametricPath as a$, apply as a0, applyMatrix as a1, arcPath as a2, blueprint as a3, bounce as a4, buildOps as a5, call as a6, chalk as a7, circlePath as a8, circumscribe as a9, frameInkBounds as aA, frameToSvg as aB, fromSvg as aC, group as aD, grow as aE, indicate as aF, invert as aG, isFilm as aH, isSuspend as aI, lagged as aJ, linePath as aK, linear as aL, linearGradient as aM, lingering as aN, matScale as aO, midnight as aP, mixColor as aQ, morph as aR, morphMatching as aS, moveTo as aT, mul as aU, neon as aV, notQuiteThere as aW, overshoot as aX, paintFrame as aY, paper as aZ, par as a_, along$1 as aa, compileFilm as ab, compose as ac, concat as ad, css as ae, cubicBezier as af, curveThrough as ag, delay as ah, draw as ai, during as aj, dynamic as ak, easeInCubic as al, easeInExpo as am, easeInOutCubic as an, easeInOutQuint as ao, easeInQuad as ap, easeOutCubic as aq, easeOutExpo as ar, easeOutQuad as as, easeOutQuint as at, erase as au, fade as av, fadeIn as aw, fadeOut as ax, film as ay, flash as az, parseColor as b0, parseSvgPath as b1, pathBounds as b2, pathLength as b3, pathToD as b4, pointAt as b5, polyPath as b6, pulse as b7, radialGradient as b8, ramp as b9, subdivideEach as bA, tangentAt as bB, thereAndBack as bC, thereAndBackWithPause as bD, to as bE, toPaint as bF, transformPath as bG, trimPath as bH, trimRing as bI, unionBounds as bJ, vanish as bK, warp as bL, warpPath as bM, wiggle as bN, write as bO, recolor as ba, rectPath as bb, resolveImageAsset as bc, resolveLook as bd, retime as be, reverseRing as bf, ring as bg, ringCenter as bh, ringLength as bi, ripple as bj, rotate as bk, runningStart as bl, rushFrom as bm, rushInto as bn, scaleBy as bo, segmentCount as bp, seq as bq, shake as br, shift as bs, signedArea as bt, slowInto as bu, smooth as bv, smoothBy as bw, smoothPath as bx, smoother as by, spring as bz, Value as g, Stage as h, EMPTY_BOUNDS as q, IDENTITY as v, ImageAssetError as w };
792
+ export type { AnimOptions as A, Bounds as B, CompileOverrides as C, DrawOp as D, Edge as E, FromSvgOptions as F, Gradient as G, Look as H, ImageFitOptions as I, LookName as J, LookToken as K, Mat as M, NodeProps as O, Path as P, Paint as Q, Rgba as R, Target as T, PlayOptions as U, Vec as V, PropName as W, Ring as X, StageImage as Y, FilmDefinition as b, ColorInput as c, ImageAsset as d, Side as e, Anim as f, PathOp as i, AnimContext as j, Aspect as k, BlendMode as l, Canvas2D as m, Caption as n, Chapter as o, Clip as p, Ease as r, FadeOptions as s, FilmOptions as t, Frame as u, ImageAssetOptions as x, ImageCrop as y, ImageOp as z };
@@ -1,6 +1,6 @@
1
- import { createTeachingCategoricalSampling, categoricalSampling } from '../../src/teaching-categorical-sampling'
2
- import type { TeachingPainter } from '../../src/teaching-canvas'
3
- import type { CanvasBounds } from '../../src/canvas-components'
1
+ import { createTeachingCategoricalSampling, categoricalSampling } from 'vizmatic'
2
+ import type { TeachingPainter } from 'vizmatic'
3
+ import type { CanvasBounds } from 'vizmatic'
4
4
 
5
5
  /** Supplied deterministic draws illustrate one possible sample, not a randomly executed experiment. */
6
6
  export const tailLossFixture = {
@@ -1,13 +1,13 @@
1
1
  import { createHash } from 'node:crypto'
2
2
  import { pathToFileURL } from 'node:url'
3
- import { createTeachingByteDifference } from '../../src/teaching-byte-diff'
4
- import type { CanvasBounds, CanvasPainter } from '../../src/canvas-components'
3
+ import { createTeachingByteDifference } from 'vizmatic'
4
+ import type { CanvasBounds, CanvasPainter } from 'vizmatic'
5
5
 
6
6
  const xml = (value: string) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
7
7
  const bytes = (value: string) => new TextEncoder().encode(value)
8
8
  const digest = (value: Uint8Array) => createHash('sha256').update(value).digest('hex').slice(0, 12)
9
9
 
10
- /** Run: pnpm exec tsx examples/teaching-byte-diff.ts [--reveal] > /tmp/byte-diff.svg */
10
+ /** Run: npx tsx examples/_teaching/teaching-byte-diff.ts [--reveal] > /tmp/byte-diff.svg */
11
11
  export function renderByteDifferenceExample(revealVerdict = false, scanProgress = 1): string {
12
12
  const content: string[] = []
13
13
  const painter: CanvasPainter<CanvasBounds> = {
@@ -1,6 +1,6 @@
1
- import type { CanvasBounds } from '../../src/canvas-components'
2
- import type { TeachingPainter } from '../../src/teaching-canvas'
3
- import { createTeachingRoutedTransfer } from '../../src/teaching-routed-transfer'
1
+ import type { CanvasBounds } from 'vizmatic'
2
+ import type { TeachingPainter } from 'vizmatic'
3
+ import { createTeachingRoutedTransfer } from 'vizmatic'
4
4
 
5
5
  /** A new parameter copy passes around three completed rank replicas. */
6
6
  export function drawRoutedParameterBroadcast<Shape extends CanvasBounds>(painter: TeachingPainter<Shape>, progress: number) {
@@ -1,5 +1,5 @@
1
- import type { CanvasPainter } from '../../src/canvas-components'
2
- import { createTeachingTokenHistory, type TokenHistoryPhase } from '../../src/teaching-token-history'
1
+ import type { CanvasPainter } from 'vizmatic'
2
+ import { createTeachingTokenHistory, type TokenHistoryPhase } from 'vizmatic'
3
3
 
4
4
  // Vocabulary IDs can repeat; these IDs identify their immutable occurrences.
5
5
  const prompt = [101, 102, 103].map((token, i) => ({ id: `prompt-${i}`, token }))
@@ -1,6 +1,6 @@
1
- import { createTeachingCanvas, type TeachingPainter } from '../../src/teaching-canvas'
2
- import { createTeachingVectorAccumulation, type WeightedVectorTerm } from '../../src/teaching-vector'
3
- import type { CanvasBounds } from '../../src/canvas-components'
1
+ import { createTeachingCanvas, type TeachingPainter } from 'vizmatic'
2
+ import { createTeachingVectorAccumulation, type WeightedVectorTerm } from 'vizmatic'
3
+ import type { CanvasBounds } from 'vizmatic'
4
4
 
5
5
  // A supplied two-coordinate EMA example, with beta=0.75.
6
6
  const terms: readonly WeightedVectorTerm[] = [
@@ -4,7 +4,7 @@
4
4
  * Q K^T, scaling by sqrt(d), softmax per row, and the weighted sum of values.
5
5
  */
6
6
  import {
7
- Node, dynamic, fade, fadeIn, fadeOut, film, line, linear, morphMatching, parseColor, parseSvgPath, rect, smoother, text, tex, to, write, mixColor,
7
+ Node, dynamic, fade, fadeIn, fadeOut, film, line, linear, morphMatching, parseColor, parseSvgPath, rect, seq, smoother, text, tex, to, write, mixColor,
8
8
  type Rgba,
9
9
  } from 'vizmatic/stage'
10
10
 
@@ -256,12 +256,13 @@ export default film({
256
256
  s.wait(0.6)
257
257
 
258
258
  s.chapter('Scale')
259
- s.play(morphMatching(eq0, eq1), fadeOut(note0), fadeIn(note1), { duration: 1.3 })
259
+ // One note leaves before the next arrives, so two sentences never share the same lines.
260
+ s.play(morphMatching(eq0, eq1), seq(fadeOut(note0), fadeIn(note1)), { duration: 1.3 })
260
261
  s.play(scaled.to(1, { ease: smoother }), { duration: 1.8 })
261
262
  s.wait(0.8)
262
263
 
263
264
  s.chapter('Softmax')
264
- s.play(morphMatching(eq1, eq2), fadeOut(note1), fadeIn(note2), { duration: 1.3 })
265
+ s.play(morphMatching(eq1, eq2), seq(fadeOut(note1), fadeIn(note2)), { duration: 1.3 })
265
266
  s.add(sums, shares)
266
267
  s.play(soft.to(1, { ease: smoother }), fadeIn(shareLabel), focus.to(1), { duration: 2.6 })
267
268
  s.wait(0.6)
@@ -270,7 +271,7 @@ export default film({
270
271
  s.wait(1.2)
271
272
 
272
273
  s.chapter('Values')
273
- s.play(morphMatching(eq2, eq3), fadeOut(note2), fadeIn(note3), fadeIn(vStrips, { lag: 0.01 }), fadeIn(vTag), { duration: 1.5 })
274
+ s.play(morphMatching(eq2, eq3), seq(fadeOut(note2), fadeIn(note3)), fadeIn(vStrips, { lag: 0.01 }), fadeIn(vTag), { duration: 1.5 })
274
275
  s.add(output)
275
276
  s.play(flow.to(1, { ease: linear }), fadeIn(outTag), { duration: 3.2 })
276
277
  s.play(fadeIn(caveat), { duration: 0.8 })
@@ -267,9 +267,12 @@ export default film({
267
267
  camera.at((tx + 240 / z) * a, (ty) * a)
268
268
  camera.set('sx', z)
269
269
  })
270
- s.play(fade(title, 0), fade(target, 0), follow.to(1, { ease: smoother }), zoom.to(9, { ease: smoother }), phase.to(phase.value + 0.06, { ease: linear }), { duration: 3 })
270
+ // The title leaves before the zoom carries the curve through it, and returns when the curve is back in place.
271
+ s.at(s.time, () => s.play(fade(title, 0), { duration: 0.3 }))
272
+ s.play(fade(target, 0), follow.to(1, { ease: smoother }), zoom.to(9, { ease: smoother }), phase.to(phase.value + 0.06, { ease: linear }), { duration: 3 })
271
273
  s.play(phase.to(phase.value + 0.14, { ease: linear }), { duration: 6 })
272
- s.play(fade(title, 1), follow.to(0, { ease: smoother }), zoom.to(1, { ease: smoother }), phase.to(phase.value + 0.08, { ease: linear }), { duration: 3 })
274
+ s.at(s.time + 2.6, () => s.play(fade(title, 1), { duration: 0.4 }))
275
+ s.play(follow.to(0, { ease: smoother }), zoom.to(1, { ease: smoother }), phase.to(phase.value + 0.08, { ease: linear }), { duration: 3 })
273
276
 
274
277
  s.chapter('The whole curve')
275
278
  s.play(phase.to(phase.value + 1, { ease: linear }), { duration: 4.6 })
@@ -4,7 +4,7 @@
4
4
  * must have the same area both times, so c^2 = a^2 + b^2. Legs are 3 and 4 units.
5
5
  */
6
6
  import {
7
- Node, draw, fade, fadeIn, fadeOut, film, morph, polygon, polyPath, rect, shape, smoother, text, tex, to, write,
7
+ Node, delay, draw, fade, fadeIn, fadeOut, film, morph, polygon, polyPath, rect, shape, smoother, text, tex, to, write,
8
8
  type Vec,
9
9
  } from 'vizmatic/stage'
10
10
 
@@ -180,6 +180,6 @@ export default film({
180
180
  s.play(fadeIn([...equation.part('='), ...equation.part('+')]), { duration: 0.6 })
181
181
  s.wait(1)
182
182
  check.moveTo([430, 448])
183
- s.play(to(equation, (eq) => eq.shift(-300, 0)), fadeIn([tilesA, tilesB], { lag: 0.02 }), fadeIn(check, { shift: [-30, 0] }), fade(aSquared, 0), fade(bSquared, 0), { duration: 1.4 })
183
+ s.play(to(equation, (eq) => eq.shift(-300, 0)), fadeIn([tilesA, tilesB], { lag: 0.02 }), delay(fadeIn(check, { shift: [-30, 0] }), 0.5), fade(aSquared, 0), fade(bSquared, 0), { duration: 1.4 })
184
184
  s.wait(3)
185
185
  })
@@ -4,7 +4,7 @@
4
4
  * widest |x| where the partial sum stays within 0.01 of sin x.
5
5
  */
6
6
  import {
7
- Node, axes, curveThrough, draw, dynamic, fadeIn, film, line, morphMatching, parametricPath, rect, smoother, text, tex, write,
7
+ Node, axes, curveThrough, draw, dynamic, fadeIn, film, line, morphMatching, parametricPath, rect, seq, smoother, text, tex, write,
8
8
  type Vec,
9
9
  } from 'vizmatic/stage'
10
10
 
@@ -154,6 +154,7 @@ export default film({
154
154
  }
155
155
 
156
156
  s.chapter('The whole wave')
157
- s.play(fadeIn(closingPlate), fadeIn(closing, { shift: [0, 12] }), { duration: 1.2 })
157
+ // The plate covers the curve before the sentence arrives on it.
158
+ s.play(seq(fadeIn(closingPlate), fadeIn(closing, { shift: [0, 12] })), { duration: 1.2 })
158
159
  s.wait(3.2)
159
160
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vizmatic",
3
- "version": "0.7.2",
3
+ "version": "0.8.0",
4
4
  "description": "Code-driven animation, diagrams, and charts: vector films that play live in a browser and export to MP4, with typed components for dense technical figures.",
5
5
  "type": "module",
6
6
  "license": "MIT",