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
@@ -1,5 +1,3 @@
1
- import React, { ReactNode } from 'react';
2
-
3
1
  /**
4
2
  * Density: how much information a diagram packs into its space.
5
3
  *
@@ -178,6 +176,8 @@ declare const gradients: {
178
176
  readonly warm: string;
179
177
  readonly cyan: string;
180
178
  readonly pink: string;
179
+ readonly red: "linear-gradient(135deg, #b83232, #8f2626)";
180
+ readonly critical: "linear-gradient(135deg, #b83232, #8f2626)";
181
181
  readonly sunset: string;
182
182
  readonly ocean: string;
183
183
  readonly dark: string;
@@ -344,238 +344,5 @@ declare function getGradient(name: ColorName): string;
344
344
  */
345
345
  declare function heatColor(value: number): string;
346
346
 
347
- /**
348
- * Vizmatic — Brand
349
- *
350
- * Adds a small theme-aware watermark to rendered artifacts.
351
- */
352
-
353
- type WatermarkPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
354
- interface WatermarkImageOptions {
355
- src: string;
356
- width?: number;
357
- height?: number;
358
- alt?: string;
359
- }
360
- interface WatermarkOptions {
361
- text?: string | false;
362
- image?: string | WatermarkImageOptions;
363
- icon?: ReactNode | string | false;
364
- element?: ReactNode;
365
- position?: WatermarkPosition;
366
- opacity?: number;
367
- color?: string;
368
- }
369
- interface WatermarkElementProps extends WatermarkOptions {
370
- children?: ReactNode;
371
- }
372
- type WatermarkInput = boolean | string | WatermarkOptions | React.ReactElement<WatermarkElementProps>;
373
- declare function normalizeWatermark(watermark: WatermarkInput | undefined): WatermarkOptions | undefined;
374
- declare function Watermark(_props: WatermarkElementProps): null;
375
- /**
376
- * Wrap an illustration element with a watermark overlay.
377
- */
378
- declare function wrapWithWatermark(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', watermark?: WatermarkInput): React.ReactElement;
379
- declare function wrapWithBrand(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', label?: string): React.ReactElement;
380
-
381
- type RenderBackground = 'transparent' | 'theme' | (string & {});
382
-
383
- type AnimationEasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
384
- type AnimationEasing = AnimationEasingName | ((progress: number) => number);
385
- type AnimationInterpolator<T> = {
386
- bivarianceHack(from: T, to: T, progress: number): T;
387
- }['bivarianceHack'];
388
- interface AnimationHoldStep {
389
- type: 'hold';
390
- duration: number;
391
- label?: string;
392
- }
393
- interface AnimationKeyframeStep<T> {
394
- type: 'keyframe';
395
- value: T;
396
- label?: string;
397
- }
398
- interface AnimationTweenStep<T> {
399
- type: 'tween';
400
- to: T;
401
- duration: number;
402
- easing?: AnimationEasing;
403
- interpolate?: AnimationInterpolator<T>;
404
- label?: string;
405
- }
406
- type AnimationPropertyStep<T> = AnimationHoldStep | AnimationKeyframeStep<T> | AnimationTweenStep<T>;
407
- type AnimationParallelTracks<S extends object> = {
408
- [K in keyof S]?: readonly AnimationPropertyStep<S[K]>[];
409
- };
410
- interface AnimationParallelStep<S extends object> {
411
- type: 'parallel';
412
- tracks: AnimationParallelTracks<S>;
413
- label?: string;
414
- }
415
- type AnimationTimelineStep<S extends object> = AnimationHoldStep | AnimationKeyframeStep<Partial<S>> | AnimationTweenStep<Partial<S>> | AnimationParallelStep<S>;
416
- interface AnimationFrameContext {
417
- index: number;
418
- count: number;
419
- time: number;
420
- duration: number;
421
- delay: number;
422
- progress: number;
423
- step: number;
424
- stepProgress: number;
425
- label?: string;
426
- fps: number;
427
- }
428
- interface AnimationDefinition<S extends object> {
429
- initial: S;
430
- timeline: readonly AnimationTimelineStep<S>[];
431
- render: (state: Readonly<S>, frame: Readonly<AnimationFrameContext>) => ReactNode;
432
- fps?: number;
433
- }
434
- interface DefinedAnimation<S extends object> extends AnimationDefinition<S> {
435
- readonly kind: 'vizmatic.animation';
436
- readonly duration: number;
437
- readonly fps: number;
438
- }
439
- interface SampleAnimationOptions {
440
- fps?: number;
441
- }
442
- interface SampledAnimationFrame<S extends object> {
443
- state: Readonly<S>;
444
- frame: Readonly<AnimationFrameContext>;
445
- }
446
- interface AnimationCadenceAnalysis {
447
- fps: number;
448
- duration: number;
449
- frameCount: number;
450
- encodedDuration: number;
451
- targetInterval: number;
452
- minDelay: number;
453
- maxDelay: number;
454
- }
455
- declare function hold(duration: number, label?: string): AnimationHoldStep;
456
- declare function keyframe<T>(value: T, label?: string): AnimationKeyframeStep<T>;
457
- declare function tween<T>(to: T, options: Omit<AnimationTweenStep<T>, 'type' | 'to'>): AnimationTweenStep<T>;
458
- declare function parallel<S extends object>(tracks: AnimationParallelTracks<S>, label?: string): AnimationParallelStep<S>;
459
- declare function defineAnimation<S extends object>(definition: AnimationDefinition<S>): DefinedAnimation<S>;
460
- declare function sampleAnimation<S extends object>(animation: DefinedAnimation<S>, time: number): Readonly<S>;
461
- /** Samples an exact timestamp with caller-provided frame timing, without GIF cadence rounding. */
462
- declare function sampleAnimationFrame<S extends object>(animation: DefinedAnimation<S>, requestedTime: number, timing: Pick<AnimationFrameContext, 'index' | 'count' | 'delay' | 'fps'>): SampledAnimationFrame<S>;
463
- declare function analyzeAnimationCadence<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): AnimationCadenceAnalysis;
464
- declare function sampleAnimationFrames<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): readonly SampledAnimationFrame<S>[];
465
-
466
- interface VideoFrameInfo {
467
- /** Zero-based frame index. The final frame is always before the video endpoint. */
468
- index: number;
469
- count: number;
470
- /** Frame presentation time in milliseconds. */
471
- time: number;
472
- /** Duration rounded to the nearest whole frame, in milliseconds. */
473
- duration: number;
474
- /** Fraction of the video represented by this frame, from 0 to 1. */
475
- progress: number;
476
- fps: number;
477
- }
478
- type VideoCodec = 'h264' | 'vp9';
479
- type H264Encoder = 'libx264' | 'videotoolbox';
480
- interface RgbaVideoOptions {
481
- width: number;
482
- height: number;
483
- /** Requested duration before rounding to a whole number of frames. */
484
- duration: number;
485
- outputPath: string;
486
- /** After drawing, return true only if the RGBA bytes equal the preceding frame.
487
- * Return 'compare' to check consecutive RGBA snapshots byte for byte.
488
- * Sends timestamped RGBA packets and expands holds after color conversion. */
489
- frameIsRepeat?: (frame: VideoFrameInfo) => boolean | 'compare';
490
- fps?: number;
491
- audioPath?: string;
492
- /** Seconds to skip in the audio file, for a render that starts partway through a timeline. */
493
- audioOffset?: number;
494
- ffmpegPath?: string;
495
- /** H.264 writes MP4. VP9 writes WebM. */
496
- codec?: VideoCodec;
497
- /** Prefer Apple's hardware encoder for standard-quality H.264. The default is libx264. */
498
- h264Encoder?: H264Encoder;
499
- /** Fail before painting if the requested encoder cannot encode this format. */
500
- requireH264Encoder?: boolean;
501
- preset?: string;
502
- /** Encoder tuning for H.264, such as "animation" for flat color and line art. */
503
- tune?: string;
504
- /**
505
- * More settings for the H.264 encoder, as x264 writes them: `name=value` pairs with a colon between them,
506
- * such as "aq-strength=1.0:trellis=0". They come after the preset and the tune, so they replace a value of those.
507
- */
508
- x264Params?: string;
509
- crf?: number;
510
- threads?: number;
511
- /** Title in the file's metadata. MP4 only. */
512
- title?: string;
513
- /** Chapter markers, in seconds from the start of the video. MP4 only. Players show them on the timeline. */
514
- chapters?: readonly {
515
- title: string;
516
- time: number;
517
- }[];
518
- /** A caption track that the viewer can switch on, in seconds from the start of the video. MP4 only. */
519
- captions?: readonly {
520
- t0: number;
521
- t1: number;
522
- text: string;
523
- }[];
524
- signal?: AbortSignal;
525
- onProgress?: (frame: VideoFrameInfo) => void | Promise<void>;
526
- }
527
- /** FFmpeg metadata with a title and chapters. Each chapter ends where the next one starts. */
528
- declare function chapterMetadata(title: string | undefined, chapters: readonly {
529
- title: string;
530
- time: number;
531
- }[], duration: number): string;
532
- /** Captions as SubRip text, clipped to the video. */
533
- declare function captionsToSrt(captions: readonly {
534
- t0: number;
535
- t1: number;
536
- text: string;
537
- }[], duration: number): string;
538
- interface RgbaVideoOutput {
539
- width: number;
540
- height: number;
541
- frameCount: number;
542
- duration: number;
543
- fps: number;
544
- bytes: number;
545
- outputPath: string;
546
- audioIncluded: boolean;
547
- /** Full RGBA packets written when frameIsRepeat is supplied. */
548
- rgbaPackets?: number;
549
- /** The encoder that produced the H.264 stream. Absent for other codecs. */
550
- h264Encoder?: H264Encoder;
551
- }
552
- interface AnimationVideoOptions extends Omit<RgbaVideoOptions, 'duration'> {
553
- /** Physical output pixels per logical scene pixel. Defaults to 1. Scaled dimensions must be even integers. */
554
- scale?: number;
555
- theme?: ThemeMode;
556
- /** MP4 has no alpha channel. Defaults to the opaque theme background. */
557
- background?: RenderBackground;
558
- watermark?: WatermarkInput;
559
- brand?: boolean | string;
560
- }
561
- type RgbaVideoFrameRenderer = (frame: VideoFrameInfo) => Uint8Array | Promise<Uint8Array>;
562
- /** Lazily yields every frame timestamp; it never emits a duplicate endpoint frame. */
563
- declare function videoFrameSchedule(duration: number, fps?: number): Generator<VideoFrameInfo>;
564
- /** Streams a typed TSX animation to H.264 MP4 with BT.709 color at exact video frame times (30 fps by default). */
565
- declare function renderAnimationVideo<S extends object>(animation: DefinedAnimation<S>, options: AnimationVideoOptions): Promise<RgbaVideoOutput>;
566
- type H264Format = {
567
- width: number;
568
- height: number;
569
- fps: number;
570
- };
571
- /** Check that FFmpeg can encode a frame with the requested hardware and format. */
572
- declare function resolveH264Encoder(requested?: H264Encoder, ffmpegPath?: string, format?: H264Format): Promise<H264Encoder>;
573
- /**
574
- * Encodes caller-rendered RGBA frames as H.264 MP4 or VP9 WebM, tagged BT.709.
575
- * Frames are requested and written one at a time, so the caller controls
576
- * rendering and memory use.
577
- */
578
- declare function renderRgbaVideo(renderFrame: RgbaVideoFrameRenderer, options: RgbaVideoOptions): Promise<RgbaVideoOutput>;
579
-
580
- export { compositeColor as $, Watermark as L, analyzeAnimationCadence as Q, assertDensity as U, canvas as X, captionsToSrt as Y, chapterMetadata as Z, colors as _, defineAnimation as a0, densityOf as a1, densityTokens as a2, getColor as a3, getGradient as a4, getReadableColor as a5, getReadableTextColor as a6, getReadableToneColor as a7, getStyles as a8, getThemeColors as a9, wrapWithBrand as aA, wrapWithWatermark as aB, getToneColor as aa, getToneFill as ab, getToneGradient as ac, gradients as ad, hasShadow as ae, heatColor as af, hold as ag, keyframe as ah, normalizeWatermark as ai, parallel as aj, parseDensity as ak, renderAnimationVideo as al, renderRgbaVideo as am, resolveH264Encoder as an, sampleAnimation as ao, sampleAnimationFrame as ap, sampleAnimationFrames as aq, setDefaultDensity as ar, setDensityResolver as as, styles as at, toneGradients as au, tween as av, typeOf as aw, videoFrameSchedule as ax, withColorAlpha as ay, withDensity as az, DEFAULT_DENSITY as q, DENSITY_NAMES as r, typography as t };
581
- export type { AnimationCadenceAnalysis as A, RgbaVideoOptions as B, ColorName as C, Density as D, RgbaVideoOutput as E, SampledAnimationFrame as F, ThemeOptions as G, H264Encoder as H, ThemePreset as I, TypographyVariant as J, VideoFrameInfo as K, WatermarkElementProps as M, WatermarkImageOptions as N, WatermarkOptions as O, WatermarkPosition as P, RenderBackground as R, SampleAnimationOptions as S, ThemeColors as T, VideoCodec as V, WatermarkInput as W, ToneName as a, ThemeMode as b, DefinedAnimation as c, AnimationDefinition as d, AnimationEasing as e, AnimationEasingName as f, AnimationFrameContext as g, AnimationHoldStep as h, AnimationInterpolator as i, AnimationKeyframeStep as j, AnimationParallelStep as k, AnimationParallelTracks as l, AnimationPropertyStep as m, AnimationTimelineStep as n, AnimationTweenStep as o, AnimationVideoOptions as p, DensityName as s, DensityRadiusScale as u, DensitySpaceScale as v, DensityStrokeScale as w, DensityTokens as x, DensityTypeScale as y, RgbaVideoFrameRenderer as z };
347
+ export { getThemeColors as A, getToneColor as B, getToneFill as E, getToneGradient as F, gradients as G, hasShadow as H, heatColor as I, parseDensity as J, setDefaultDensity as K, setDensityResolver as L, styles as M, toneGradients as N, typeOf as O, withColorAlpha as P, withDensity as Q, DEFAULT_DENSITY as c, DENSITY_NAMES as d, assertDensity as n, canvas as o, colors as p, compositeColor as q, densityOf as r, densityTokens as s, typography as t, getColor as u, getGradient as v, getReadableColor as w, getReadableTextColor as x, getReadableToneColor as y, getStyles as z };
348
+ export type { ColorName as C, Density as D, ThemeColors as T, ToneName as a, ThemeMode as b, DensityName as e, DensityRadiusScale as f, DensitySpaceScale as g, DensityStrokeScale as h, DensityTokens as i, DensityTypeScale as j, ThemeOptions as k, ThemePreset as l, TypographyVariant as m };
@@ -0,0 +1,259 @@
1
+ import React, { ReactNode } from 'react';
2
+ import { b as ThemeMode } from './theme-DhVdDQKO.js';
3
+
4
+ /**
5
+ * Vizmatic — Brand
6
+ *
7
+ * Adds a small theme-aware watermark to rendered artifacts.
8
+ */
9
+
10
+ type WatermarkPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
11
+ interface WatermarkImageOptions {
12
+ src: string;
13
+ width?: number;
14
+ height?: number;
15
+ alt?: string;
16
+ }
17
+ interface WatermarkOptions {
18
+ text?: string | false;
19
+ image?: string | WatermarkImageOptions;
20
+ icon?: ReactNode | string | false;
21
+ element?: ReactNode;
22
+ position?: WatermarkPosition;
23
+ opacity?: number;
24
+ color?: string;
25
+ }
26
+ interface WatermarkElementProps extends WatermarkOptions {
27
+ children?: ReactNode;
28
+ }
29
+ type WatermarkInput = boolean | string | WatermarkOptions | React.ReactElement<WatermarkElementProps>;
30
+ declare function normalizeWatermark(watermark: WatermarkInput | undefined): WatermarkOptions | undefined;
31
+ declare function Watermark(_props: WatermarkElementProps): null;
32
+ /**
33
+ * Wrap an illustration element with a watermark overlay.
34
+ */
35
+ declare function wrapWithWatermark(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', watermark?: WatermarkInput): React.ReactElement;
36
+ declare function wrapWithBrand(element: React.ReactNode, width: number, height: number, theme?: 'dark' | 'light', label?: string): React.ReactElement;
37
+
38
+ type RenderBackground = 'transparent' | 'theme' | (string & {});
39
+
40
+ type AnimationEasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
41
+ type AnimationEasing = AnimationEasingName | ((progress: number) => number);
42
+ type AnimationInterpolator<T> = {
43
+ bivarianceHack(from: T, to: T, progress: number): T;
44
+ }['bivarianceHack'];
45
+ interface AnimationHoldStep {
46
+ type: 'hold';
47
+ duration: number;
48
+ label?: string;
49
+ }
50
+ interface AnimationKeyframeStep<T> {
51
+ type: 'keyframe';
52
+ value: T;
53
+ label?: string;
54
+ }
55
+ interface AnimationTweenStep<T> {
56
+ type: 'tween';
57
+ to: T;
58
+ duration: number;
59
+ easing?: AnimationEasing;
60
+ interpolate?: AnimationInterpolator<T>;
61
+ label?: string;
62
+ }
63
+ type AnimationPropertyStep<T> = AnimationHoldStep | AnimationKeyframeStep<T> | AnimationTweenStep<T>;
64
+ type AnimationParallelTracks<S extends object> = {
65
+ [K in keyof S]?: readonly AnimationPropertyStep<S[K]>[];
66
+ };
67
+ interface AnimationParallelStep<S extends object> {
68
+ type: 'parallel';
69
+ tracks: AnimationParallelTracks<S>;
70
+ label?: string;
71
+ }
72
+ type AnimationTimelineStep<S extends object> = AnimationHoldStep | AnimationKeyframeStep<Partial<S>> | AnimationTweenStep<Partial<S>> | AnimationParallelStep<S>;
73
+ interface AnimationFrameContext {
74
+ index: number;
75
+ count: number;
76
+ time: number;
77
+ duration: number;
78
+ delay: number;
79
+ progress: number;
80
+ step: number;
81
+ stepProgress: number;
82
+ label?: string;
83
+ fps: number;
84
+ }
85
+ interface AnimationDefinition<S extends object> {
86
+ initial: S;
87
+ timeline: readonly AnimationTimelineStep<S>[];
88
+ render: (state: Readonly<S>, frame: Readonly<AnimationFrameContext>) => ReactNode;
89
+ fps?: number;
90
+ }
91
+ interface DefinedAnimation<S extends object> extends AnimationDefinition<S> {
92
+ readonly kind: 'vizmatic.animation';
93
+ readonly duration: number;
94
+ readonly fps: number;
95
+ }
96
+ interface SampleAnimationOptions {
97
+ fps?: number;
98
+ }
99
+ interface SampledAnimationFrame<S extends object> {
100
+ state: Readonly<S>;
101
+ frame: Readonly<AnimationFrameContext>;
102
+ }
103
+ interface AnimationCadenceAnalysis {
104
+ fps: number;
105
+ duration: number;
106
+ frameCount: number;
107
+ encodedDuration: number;
108
+ targetInterval: number;
109
+ minDelay: number;
110
+ maxDelay: number;
111
+ }
112
+ declare function hold(duration: number, label?: string): AnimationHoldStep;
113
+ declare function keyframe<T>(value: T, label?: string): AnimationKeyframeStep<T>;
114
+ declare function tween<T>(to: T, options: Omit<AnimationTweenStep<T>, 'type' | 'to'>): AnimationTweenStep<T>;
115
+ declare function parallel<S extends object>(tracks: AnimationParallelTracks<S>, label?: string): AnimationParallelStep<S>;
116
+ declare function defineAnimation<S extends object>(definition: AnimationDefinition<S>): DefinedAnimation<S>;
117
+ declare function sampleAnimation<S extends object>(animation: DefinedAnimation<S>, time: number): Readonly<S>;
118
+ /** Samples an exact timestamp with caller-provided frame timing, without GIF cadence rounding. */
119
+ declare function sampleAnimationFrame<S extends object>(animation: DefinedAnimation<S>, requestedTime: number, timing: Pick<AnimationFrameContext, 'index' | 'count' | 'delay' | 'fps'>): SampledAnimationFrame<S>;
120
+ declare function analyzeAnimationCadence<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): AnimationCadenceAnalysis;
121
+ declare function sampleAnimationFrames<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): readonly SampledAnimationFrame<S>[];
122
+
123
+ interface VideoFrameInfo {
124
+ /** Zero-based frame index. The final frame is always before the video endpoint. */
125
+ index: number;
126
+ count: number;
127
+ /** Frame presentation time in milliseconds. */
128
+ time: number;
129
+ /** Duration rounded to the nearest whole frame, in milliseconds. */
130
+ duration: number;
131
+ /** Fraction of the video represented by this frame, from 0 to 1. */
132
+ progress: number;
133
+ fps: number;
134
+ }
135
+ type VideoCodec = 'h264' | 'vp9';
136
+ type H264Encoder = 'libx264' | 'videotoolbox' | 'nvenc';
137
+ type H264EncoderRequest = H264Encoder | 'auto';
138
+ interface RgbaVideoOptions {
139
+ width: number;
140
+ height: number;
141
+ /** Requested duration before rounding to a whole number of frames. */
142
+ duration: number;
143
+ outputPath: string;
144
+ /** After drawing, return true only if the RGBA bytes equal the preceding frame.
145
+ * Return 'compare' to check consecutive RGBA snapshots byte for byte.
146
+ * Sends timestamped RGBA packets and expands holds after color conversion. */
147
+ frameIsRepeat?: (frame: VideoFrameInfo) => boolean | 'compare';
148
+ fps?: number;
149
+ audioPath?: string;
150
+ /** Seconds to skip in the audio file, for a render that starts partway through a timeline. */
151
+ audioOffset?: number;
152
+ ffmpegPath?: string;
153
+ /** H.264 writes MP4. VP9 writes WebM. */
154
+ codec?: VideoCodec;
155
+ /**
156
+ * The default is libx264. Auto probes local hardware for standard-quality output, except in CI.
157
+ * Auto preserves custom CRF, x264 parameters and tuning by selecting software.
158
+ * NVENC uses NVIDIA's dedicated video encoder; RGBA drawing and color conversion are unchanged.
159
+ */
160
+ h264Encoder?: H264EncoderRequest;
161
+ /** Fail before painting if an explicit encoder cannot encode these settings. Auto permits software. */
162
+ requireH264Encoder?: boolean;
163
+ /**
164
+ * x264 speed preset, default fast. NVENC maps ultrafast/superfast/veryfast/faster/fast/medium
165
+ * to p1/p2/p3/p4/p5/p6, and slow/slower/veryslow/placebo to p7, with high-quality tuning.
166
+ * These preserve the speed/quality preference, not identical compression or image quality.
167
+ */
168
+ preset?: string;
169
+ /** x264 tuning, such as "animation" or "grain". NVENC falls back to software to preserve it. */
170
+ tune?: string;
171
+ /**
172
+ * More settings for the H.264 encoder, as x264 writes them: `name=value` pairs with a colon between them,
173
+ * such as "aq-strength=1.0:trellis=0". They come after the preset and the tune, so they replace a value of those.
174
+ */
175
+ x264Params?: string;
176
+ /**
177
+ * Default 18 for H.264, 30 for VP9. Explicit NVENC maps 1..51 to VBR CQ of the same number,
178
+ * without a bitrate cap. CQ and CRF are not equivalent quality scales. CRF 0 keeps software
179
+ * lossless encoding, since NVENC CQ 0 means automatic quality, not lossless.
180
+ */
181
+ crf?: number;
182
+ threads?: number;
183
+ /** Title in the file's metadata. MP4 only. */
184
+ title?: string;
185
+ /** Chapter markers, in seconds from the start of the video. MP4 only. Players show them on the timeline. */
186
+ chapters?: readonly {
187
+ title: string;
188
+ time: number;
189
+ }[];
190
+ /** A caption track that the viewer can switch on, in seconds from the start of the video. MP4 only. */
191
+ captions?: readonly {
192
+ t0: number;
193
+ t1: number;
194
+ text: string;
195
+ }[];
196
+ signal?: AbortSignal;
197
+ onProgress?: (frame: VideoFrameInfo) => void | Promise<void>;
198
+ }
199
+ /** FFmpeg metadata with a title and chapters. Each chapter ends where the next one starts. */
200
+ declare function chapterMetadata(title: string | undefined, chapters: readonly {
201
+ title: string;
202
+ time: number;
203
+ }[], duration: number): string;
204
+ /** Captions as SubRip text, clipped to the video. */
205
+ declare function captionsToSrt(captions: readonly {
206
+ t0: number;
207
+ t1: number;
208
+ text: string;
209
+ }[], duration: number): string;
210
+ interface RgbaVideoOutput {
211
+ width: number;
212
+ height: number;
213
+ frameCount: number;
214
+ duration: number;
215
+ fps: number;
216
+ bytes: number;
217
+ outputPath: string;
218
+ audioIncluded: boolean;
219
+ /** Full RGBA packets written when frameIsRepeat is supplied. */
220
+ rgbaPackets?: number;
221
+ /** The encoder that produced the H.264 stream. Absent for other codecs. */
222
+ h264Encoder?: H264Encoder;
223
+ }
224
+ interface AnimationVideoOptions extends Omit<RgbaVideoOptions, 'duration'> {
225
+ /** Physical output pixels per logical scene pixel. Defaults to 1. Scaled dimensions must be even integers. */
226
+ scale?: number;
227
+ theme?: ThemeMode;
228
+ /** MP4 has no alpha channel. Defaults to the opaque theme background. */
229
+ background?: RenderBackground;
230
+ watermark?: WatermarkInput;
231
+ brand?: boolean | string;
232
+ }
233
+ type RgbaVideoFrameRenderer = (frame: VideoFrameInfo) => Uint8Array | Promise<Uint8Array>;
234
+ /** Lazily yields every frame timestamp; it never emits a duplicate endpoint frame. */
235
+ declare function videoFrameSchedule(duration: number, fps?: number): Generator<VideoFrameInfo>;
236
+ /** Streams a typed TSX animation to H.264 MP4 with BT.709 color at exact video frame times (30 fps by default). */
237
+ declare function renderAnimationVideo<S extends object>(animation: DefinedAnimation<S>, options: AnimationVideoOptions): Promise<RgbaVideoOutput>;
238
+ type H264Format = {
239
+ width: number;
240
+ height: number;
241
+ fps: number;
242
+ };
243
+ type H264SelectionOptions = Pick<RgbaVideoOptions, 'preset' | 'crf' | 'tune' | 'x264Params' | 'signal' | 'requireH264Encoder'>;
244
+ /**
245
+ * Resolve to an actual encoder after encoding one frame with the output format and settings.
246
+ * Auto prefers VideoToolbox on macOS and NVENC elsewhere, with a software fallback. Any nonempty
247
+ * CI or GITHUB_ACTIONS environment variable disables automatic hardware selection. Explicit requests
248
+ * still probe in CI. Custom x264 tuning/parameters and nondefault CRF keep auto on software.
249
+ */
250
+ declare function resolveH264Encoder(requested?: H264EncoderRequest, ffmpegPath?: string, format?: H264Format, options?: H264SelectionOptions): Promise<H264Encoder>;
251
+ /**
252
+ * Encodes caller-rendered RGBA frames as H.264 MP4 or VP9 WebM, tagged BT.709.
253
+ * Frames are requested and written one at a time, so the caller controls
254
+ * rendering and memory use.
255
+ */
256
+ declare function renderRgbaVideo(renderFrame: RgbaVideoFrameRenderer, options: RgbaVideoOptions): Promise<RgbaVideoOutput>;
257
+
258
+ export { chapterMetadata as B, defineAnimation as C, hold as E, keyframe as F, normalizeWatermark as G, parallel as I, renderAnimationVideo as J, renderRgbaVideo as K, resolveH264Encoder as L, sampleAnimation as M, sampleAnimationFrame as N, sampleAnimationFrames as O, tween as P, videoFrameSchedule as Q, wrapWithBrand as T, wrapWithWatermark as U, Watermark as t, analyzeAnimationCadence as y, captionsToSrt as z };
259
+ export type { AnimationCadenceAnalysis as A, DefinedAnimation as D, H264Encoder as H, RenderBackground as R, SampleAnimationOptions as S, VideoCodec as V, WatermarkInput as W, AnimationDefinition as a, AnimationEasing as b, AnimationEasingName as c, AnimationFrameContext as d, AnimationHoldStep as e, AnimationInterpolator as f, AnimationKeyframeStep as g, AnimationParallelStep as h, AnimationParallelTracks as i, AnimationPropertyStep as j, AnimationTimelineStep as k, AnimationTweenStep as l, AnimationVideoOptions as m, H264EncoderRequest as n, RgbaVideoFrameRenderer as o, RgbaVideoOptions as p, RgbaVideoOutput as q, SampledAnimationFrame as r, VideoFrameInfo as s, WatermarkElementProps as u, WatermarkImageOptions as v, WatermarkOptions as w, WatermarkPosition as x };