vizmatic 0.3.2 → 0.4.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.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import React, { ReactNode } from 'react';
2
2
  import { SatoriNode, Font } from 'satori';
3
3
  export { SatoriNode } from 'satori';
4
+ import { SceneFrameRequest, SceneRequest } from './scene-runtime.js';
5
+ export { EvaluatedSceneFrame, PreparedScene, SCENE_LIMITS, SCENE_RUNTIME_VERSION, evaluateSceneSource, prepareScene } from './scene-runtime.js';
4
6
 
5
7
  /**
6
8
  * Vizmatic — Theme
@@ -2037,6 +2039,8 @@ declare function tween<T>(to: T, options: Omit<AnimationTweenStep<T>, 'type' | '
2037
2039
  declare function parallel<S extends object>(tracks: AnimationParallelTracks<S>, label?: string): AnimationParallelStep<S>;
2038
2040
  declare function defineAnimation<S extends object>(definition: AnimationDefinition<S>): DefinedAnimation<S>;
2039
2041
  declare function sampleAnimation<S extends object>(animation: DefinedAnimation<S>, time: number): Readonly<S>;
2042
+ /** Samples an exact timestamp with caller-provided frame timing, without GIF cadence rounding. */
2043
+ declare function sampleAnimationFrame<S extends object>(animation: DefinedAnimation<S>, requestedTime: number, timing: Pick<AnimationFrameContext, 'index' | 'count' | 'delay' | 'fps'>): SampledAnimationFrame<S>;
2040
2044
  declare function analyzeAnimationCadence<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): AnimationCadenceAnalysis;
2041
2045
  declare function sampleAnimationFrames<S extends object>(animation: DefinedAnimation<S>, options?: SampleAnimationOptions): readonly SampledAnimationFrame<S>[];
2042
2046
 
@@ -2076,6 +2080,557 @@ declare function renderAnimatedGifWithOutput(scenes: AnimatedScene[], options: A
2076
2080
  declare function renderAnimationGif<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<void>;
2077
2081
  declare function renderAnimationGifWithOutput<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<AnimationOutput>;
2078
2082
 
2083
+ interface RenderMathSvgOptions {
2084
+ fontSize?: number;
2085
+ color?: string;
2086
+ display?: boolean;
2087
+ }
2088
+ interface RenderMathSvgResult {
2089
+ svg: string;
2090
+ width: number;
2091
+ height: number;
2092
+ /** Baseline from the SVG top, possibly outside the ink bounds for isolated symbols. */
2093
+ baseline: number;
2094
+ }
2095
+ /** Typeset TeX as a standalone SVG with pixel dimensions and baseline metrics. */
2096
+ declare function renderMathSvg(tex: string, options?: RenderMathSvgOptions): RenderMathSvgResult;
2097
+
2098
+ interface MotionPoint {
2099
+ x: number;
2100
+ y: number;
2101
+ }
2102
+ type MotionEasing = (progress: number) => number;
2103
+ interface ArcSwapOptions {
2104
+ /** Maximum perpendicular distance each point travels from the direct path. */
2105
+ lift?: number;
2106
+ easing?: MotionEasing;
2107
+ }
2108
+ /** Cubic ease-in-out with progress clamped to the unit interval. */
2109
+ declare function smoothstep(progress: number): number;
2110
+ /** Move two points to each other's positions along mirrored quadratic arcs. */
2111
+ declare function arcSwap(from: MotionPoint, to: MotionPoint, progress: number, options?: ArcSwapOptions): readonly [MotionPoint, MotionPoint];
2112
+ /** Return the visible prefix of a polyline at a fraction of its arc length. */
2113
+ declare function tracePolyline(points: readonly MotionPoint[], progress: number): MotionPoint[];
2114
+ /** Return the point at a fraction of a polyline's actual arc length. */
2115
+ declare function pointAlongPath(points: readonly MotionPoint[], progress: number): MotionPoint;
2116
+
2117
+ interface CanvasPoint {
2118
+ x: number;
2119
+ y: number;
2120
+ }
2121
+ interface CanvasBounds extends CanvasPoint {
2122
+ width: number;
2123
+ height: number;
2124
+ radius?: number;
2125
+ }
2126
+ interface CanvasScopeOptions {
2127
+ padding?: number;
2128
+ id?: string;
2129
+ }
2130
+ /** Inject checked drawing methods to retain the host renderer's audit metadata. */
2131
+ interface CanvasPainter<Shape = unknown> {
2132
+ rect(x: number, y: number, width: number, height: number, fill?: string, stroke?: string, radius?: number): Shape;
2133
+ text(value: string, x: number, y: number, size: number, color?: string, align?: 'left' | 'center' | 'right', font?: string): unknown;
2134
+ container(bounds: CanvasBounds, draw: () => void, options?: CanvasScopeOptions): unknown;
2135
+ labelScope(bounds: CanvasBounds, draw: () => void, options?: CanvasScopeOptions): unknown;
2136
+ opacity(alpha: number, draw: () => void): unknown;
2137
+ circle(x: number, y: number, radius: number, fill?: string, stroke?: string, width?: number): unknown;
2138
+ }
2139
+ interface CanvasPanelStyle {
2140
+ fill?: string;
2141
+ stroke?: string;
2142
+ radius?: number;
2143
+ padding?: number;
2144
+ id?: string;
2145
+ scope?: 'container' | 'label';
2146
+ opacity?: number;
2147
+ }
2148
+ interface CanvasPanelOptions extends CanvasBounds, CanvasPanelStyle {
2149
+ }
2150
+ interface CanvasCardStyle extends CanvasPanelStyle {
2151
+ fontSize?: number;
2152
+ font?: string;
2153
+ textColor?: string;
2154
+ baselineOffset?: number;
2155
+ labelOpacity?: number;
2156
+ }
2157
+ interface CanvasCardOptions extends CanvasBounds, CanvasCardStyle {
2158
+ label: string | number;
2159
+ }
2160
+ interface CanvasMatrixOptions<Value = string | number> {
2161
+ values: readonly (readonly Value[])[];
2162
+ x: number;
2163
+ y: number;
2164
+ cellSize?: number;
2165
+ gap?: number;
2166
+ inset?: number;
2167
+ format?: (value: Value, row: number, column: number) => string | number;
2168
+ style?: CanvasCardStyle;
2169
+ cellStyle?: (value: Value, row: number, column: number) => CanvasCardStyle | undefined;
2170
+ }
2171
+ interface TokenRowLayoutOptions {
2172
+ centerX?: number;
2173
+ x?: number;
2174
+ advance?: number;
2175
+ gap?: number;
2176
+ minWidth?: number;
2177
+ paddingX?: number;
2178
+ width?: number;
2179
+ }
2180
+ interface TokenRowItem {
2181
+ text: string;
2182
+ x: number;
2183
+ width: number;
2184
+ }
2185
+ interface CanvasTokenRowOptions extends TokenRowLayoutOptions, CanvasCardStyle {
2186
+ values: readonly (string | number)[];
2187
+ y: number;
2188
+ height?: number;
2189
+ reveal?: number;
2190
+ }
2191
+ interface CanvasParticleOptions {
2192
+ points: readonly CanvasPoint[];
2193
+ progress: number;
2194
+ radius?: number;
2195
+ fill: string;
2196
+ stroke?: string;
2197
+ strokeWidth?: number;
2198
+ }
2199
+ /** Lay out token cards using literal text length, or an explicit fixed width. */
2200
+ declare function layoutTokenRow(values: readonly (string | number)[], options?: TokenRowLayoutOptions): TokenRowItem[];
2201
+ /** Compose reusable Canvas geometry exclusively through an injected painter. */
2202
+ declare function createCanvasComponents<Shape>(painter: CanvasPainter<Shape>): {
2203
+ panel: (options: CanvasPanelOptions, draw?: () => void) => Shape;
2204
+ card: (options: CanvasCardOptions) => Shape;
2205
+ matrix: <Value>(options: CanvasMatrixOptions<Value>) => Shape[];
2206
+ tokenRow: (options: CanvasTokenRowOptions) => Shape[];
2207
+ particle: (options: CanvasParticleOptions) => CanvasPoint | null;
2208
+ fade: (alpha: number, draw: () => void) => void;
2209
+ };
2210
+
2211
+ interface AllocationPart {
2212
+ id: string;
2213
+ label: string;
2214
+ value: number;
2215
+ color?: string;
2216
+ }
2217
+ interface AllocationLayoutOptions extends CanvasBounds {
2218
+ capacity: number;
2219
+ parts: readonly AllocationPart[];
2220
+ }
2221
+ interface AllocationLayout {
2222
+ bounds: CanvasBounds;
2223
+ used: number;
2224
+ remaining: number;
2225
+ parts: {
2226
+ id: string;
2227
+ value: number;
2228
+ bounds: CanvasBounds;
2229
+ }[];
2230
+ freeBounds: CanvasBounds;
2231
+ }
2232
+ interface TeachingAllocationOptions extends AllocationLayoutOptions {
2233
+ fontSize?: number;
2234
+ unit?: string;
2235
+ format?: (value: number) => string;
2236
+ color?: string;
2237
+ trackColor?: string;
2238
+ }
2239
+ /** Capacity-scaled partitions; unused capacity is preserved rather than normalized away. */
2240
+ declare function layoutAllocation(options: AllocationLayoutOptions): AllocationLayout;
2241
+
2242
+ interface TeachingTimeLane {
2243
+ id: string;
2244
+ label: string;
2245
+ }
2246
+ interface TeachingTimeInterval {
2247
+ id: string;
2248
+ lane: string;
2249
+ start: number;
2250
+ end: number;
2251
+ label?: string;
2252
+ color?: string;
2253
+ opacity?: number;
2254
+ }
2255
+ interface TeachingTimelineOptions extends CanvasBounds {
2256
+ domain: readonly [number, number];
2257
+ lanes: readonly TeachingTimeLane[];
2258
+ intervals: readonly TeachingTimeInterval[];
2259
+ time?: number;
2260
+ ticks?: readonly number[];
2261
+ formatTime?: (value: number) => string;
2262
+ labelWidth?: number;
2263
+ laneGap?: number;
2264
+ fontSize?: number;
2265
+ color?: string;
2266
+ trackColor?: string;
2267
+ cursorColor?: string;
2268
+ }
2269
+ interface TeachingTimelineInterval<Shape> {
2270
+ id: string;
2271
+ shape: Shape | null;
2272
+ bounds: CanvasBounds;
2273
+ elapsed: number;
2274
+ opacity: number;
2275
+ complete: boolean;
2276
+ }
2277
+ interface TeachingTimelineResult<Shape> {
2278
+ bounds: CanvasBounds;
2279
+ time: number;
2280
+ point(time: number): number;
2281
+ lanes: Record<string, {
2282
+ shape: Shape;
2283
+ bounds: CanvasBounds;
2284
+ }>;
2285
+ intervals: Record<string, TeachingTimelineInterval<Shape>>;
2286
+ }
2287
+
2288
+ interface CellGridOptions extends CanvasBounds {
2289
+ rows: number;
2290
+ columns: number;
2291
+ }
2292
+ interface CellGridLayout {
2293
+ bounds: CanvasBounds;
2294
+ cells: CanvasBounds[][];
2295
+ cell(row: number, column: number): CanvasBounds;
2296
+ }
2297
+ interface TeachingGridHighlight {
2298
+ row: number;
2299
+ column: number;
2300
+ fill: string;
2301
+ stroke?: string;
2302
+ opacity?: number;
2303
+ }
2304
+ interface TeachingGridOptions extends CellGridOptions {
2305
+ fill?: string;
2306
+ stroke?: string;
2307
+ lineWidth?: number;
2308
+ labels?: readonly (readonly (string | number)[])[];
2309
+ highlights?: readonly TeachingGridHighlight[];
2310
+ fontSize?: number;
2311
+ textColor?: string;
2312
+ padding?: number;
2313
+ }
2314
+ /** Shared cell geometry for dense diagrams, without creating one panel per cell. */
2315
+ declare function layoutCellGrid(options: CellGridOptions): CellGridLayout;
2316
+
2317
+ interface TeachingTransferEndpoint {
2318
+ shape: CanvasBounds;
2319
+ /** Use the same local opacity supplied when painting this endpoint. */
2320
+ opacity: number;
2321
+ }
2322
+ interface TeachingTransferOptions extends TeachingConnectionOptions {
2323
+ source: TeachingTransferEndpoint;
2324
+ target: TeachingTransferEndpoint;
2325
+ opacity?: number;
2326
+ progress?: number;
2327
+ margin?: number;
2328
+ particle?: {
2329
+ radius?: number;
2330
+ fill?: string;
2331
+ stroke?: string;
2332
+ strokeWidth?: number;
2333
+ };
2334
+ }
2335
+
2336
+ interface TeachingPathOptions {
2337
+ color?: string;
2338
+ width?: number;
2339
+ clip?: CanvasBounds;
2340
+ closed?: boolean;
2341
+ fill?: string;
2342
+ }
2343
+ interface TeachingConnectionOptions {
2344
+ color?: string;
2345
+ width?: number;
2346
+ gap?: number;
2347
+ fromGap?: number;
2348
+ toGap?: number;
2349
+ }
2350
+ interface TeachingRoute {
2351
+ from: CanvasPoint;
2352
+ to: CanvasPoint;
2353
+ }
2354
+ /** Inject host methods so every mark retains checked geometry and label metadata. */
2355
+ interface TeachingPainter<Shape extends CanvasBounds = CanvasBounds> extends CanvasPainter<Shape> {
2356
+ math(value: string, x: number, y: number, size: number, color?: string, align?: 'left' | 'center' | 'right'): unknown;
2357
+ line(x1: number, y1: number, x2: number, y2: number, color?: string, width?: number): unknown;
2358
+ arrow(x1: number, y1: number, x2: number, y2: number, color?: string, width?: number): unknown;
2359
+ path(points: readonly CanvasPoint[], options?: TeachingPathOptions): unknown;
2360
+ connect(source: CanvasBounds, target: CanvasBounds, options?: TeachingConnectionOptions): TeachingRoute;
2361
+ }
2362
+ interface TeachingPlot {
2363
+ point(x: number, y: number): CanvasPoint;
2364
+ bounds: CanvasBounds;
2365
+ xDomain: readonly [number, number];
2366
+ yDomain: readonly [number, number];
2367
+ }
2368
+ interface TeachingAxesOptions extends CanvasBounds {
2369
+ xDomain: readonly [number, number];
2370
+ yDomain: readonly [number, number];
2371
+ equalUnits?: boolean;
2372
+ xLabel?: string;
2373
+ yLabel?: string;
2374
+ color?: string;
2375
+ gridColor?: string;
2376
+ fontSize?: number;
2377
+ xTicks?: readonly number[];
2378
+ yTicks?: readonly number[];
2379
+ formatX?: (value: number) => string;
2380
+ formatY?: (value: number) => string;
2381
+ }
2382
+ interface TeachingCurveOptions {
2383
+ plot: TeachingPlot;
2384
+ points: readonly CanvasPoint[];
2385
+ color: string;
2386
+ width?: number;
2387
+ progress?: number;
2388
+ }
2389
+ interface TeachingScatterPoint extends CanvasPoint {
2390
+ color?: string;
2391
+ radius?: number;
2392
+ }
2393
+ interface TeachingScatterOptions {
2394
+ plot: TeachingPlot;
2395
+ points: readonly TeachingScatterPoint[];
2396
+ color?: string;
2397
+ radius?: number;
2398
+ opacity?: number;
2399
+ }
2400
+ interface TeachingBarsOptions extends CanvasBounds {
2401
+ values: readonly number[];
2402
+ labels?: readonly string[];
2403
+ colors?: readonly string[];
2404
+ color?: string;
2405
+ max?: number;
2406
+ progress?: number;
2407
+ showValues?: boolean;
2408
+ format?: (value: number) => string;
2409
+ fontSize?: number;
2410
+ gap?: number;
2411
+ }
2412
+ interface TeachingBarsResult<Shape> {
2413
+ bars: (Shape | null)[];
2414
+ slots: CanvasBounds[];
2415
+ bounds: CanvasBounds;
2416
+ }
2417
+ interface TeachingFlowNode extends CanvasBounds {
2418
+ id: string;
2419
+ label: string;
2420
+ color?: string;
2421
+ fill?: string;
2422
+ fontSize?: number;
2423
+ }
2424
+ interface TeachingFlowEdge extends TeachingConnectionOptions {
2425
+ from: string;
2426
+ to: string;
2427
+ progress?: number;
2428
+ }
2429
+ interface TeachingFlowGraphOptions {
2430
+ nodes: readonly TeachingFlowNode[];
2431
+ edges: readonly TeachingFlowEdge[];
2432
+ stroke?: string;
2433
+ fill?: string;
2434
+ textColor?: string;
2435
+ padding?: number;
2436
+ }
2437
+ /** Chart and graph compositions built entirely from the host's checked primitives. */
2438
+ declare function createTeachingCanvas<Shape extends CanvasBounds>(painter: TeachingPainter<Shape>): {
2439
+ axes: (options: TeachingAxesOptions) => TeachingPlot;
2440
+ curve: (options: TeachingCurveOptions) => CanvasPoint[];
2441
+ scatter: (options: TeachingScatterOptions) => unknown[];
2442
+ bars: (options: TeachingBarsOptions) => TeachingBarsResult<Shape>;
2443
+ flowGraph: (options: TeachingFlowGraphOptions) => {
2444
+ nodes: Record<string, Shape>;
2445
+ routes: TeachingRoute[];
2446
+ };
2447
+ transfer: (options: TeachingTransferOptions) => TeachingRoute | null;
2448
+ grid: (options: TeachingGridOptions) => CellGridLayout & {
2449
+ shape: Shape;
2450
+ };
2451
+ timeline: (options: TeachingTimelineOptions) => TeachingTimelineResult<Shape>;
2452
+ allocation: (options: TeachingAllocationOptions) => AllocationLayout & {
2453
+ shapes: (Shape | null)[];
2454
+ shape: Shape;
2455
+ };
2456
+ };
2457
+
2458
+ /** A reproducible Mulberry32 stream returning values in [0, 1). */
2459
+ declare function seededRandom(seed: number): () => number;
2460
+ /** Interpolate vectors without mutating either input. Progress may extrapolate. */
2461
+ declare function lerpArray(from: readonly number[], to: readonly number[], progress: number): number[];
2462
+ declare function dotProduct(left: readonly number[], right: readonly number[]): number;
2463
+ declare function multiplyMatrices(left: readonly (readonly number[])[], right: readonly (readonly number[])[]): number[][];
2464
+ /** Subtract the largest logit before exponentiation, including at small temperatures. */
2465
+ declare function stableSoftmax(values: readonly number[], temperature?: number): number[];
2466
+ /** Shannon entropy of a normalized probability distribution. Zero terms contribute zero. */
2467
+ declare function entropy(probabilities: readonly number[], base?: number): number;
2468
+ /** Unit-length vector; the zero vector stays zero. Scaling avoids intermediate overflow. */
2469
+ declare function normalizeVector(values: readonly number[]): number[];
2470
+ /** Sample both endpoints of a finite domain into a polyline. */
2471
+ declare function sampleFunction(fn: (x: number) => number, low: number, high: number, count?: number): CanvasPoint[];
2472
+ /** Normal probability density at x. */
2473
+ declare function gaussian(mean: number, sigma: number, x: number): number;
2474
+ /** One standard normal sample using two draws from a supplied [0, 1) random stream. */
2475
+ declare function sampleGaussian(random: () => number): number;
2476
+
2477
+ interface CuePosition {
2478
+ beat: number;
2479
+ beatP: number;
2480
+ }
2481
+ interface CueSnapshot<Snapshot> {
2482
+ id: string;
2483
+ snapshot: Snapshot;
2484
+ }
2485
+ interface DiscreteCue<Snapshot> extends CueSnapshot<Snapshot> {
2486
+ beat: number;
2487
+ at: number;
2488
+ }
2489
+ interface CueTrackOptions<Snapshot> {
2490
+ initial: CueSnapshot<Snapshot>;
2491
+ cues: readonly DiscreteCue<Snapshot>[];
2492
+ }
2493
+ /** Hold one authored simulation snapshot until the next explicit semantic cue. */
2494
+ declare function createCueTrack<Snapshot>(options: CueTrackOptions<Snapshot>): Readonly<{
2495
+ sample(current: CuePosition): Readonly<CueSnapshot<Snapshot>>;
2496
+ }>;
2497
+
2498
+ /** Camera center in world coordinates and the scale applied to that world. */
2499
+ interface Camera2D {
2500
+ x: number;
2501
+ y: number;
2502
+ zoom: number;
2503
+ }
2504
+ /** Size of the SVG viewport in pixels. */
2505
+ interface CameraViewport {
2506
+ width: number;
2507
+ height: number;
2508
+ }
2509
+ interface CameraMotionOptions {
2510
+ easing?: MotionEasing;
2511
+ minZoom?: number;
2512
+ maxZoom?: number;
2513
+ }
2514
+ /**
2515
+ * Interpolate a camera at any normalized time. Position is linear, zoom is
2516
+ * logarithmic, and progress outside [0, 1] holds the nearest endpoint.
2517
+ */
2518
+ declare function interpolateCamera(from: Camera2D, to: Camera2D, progress: number, options?: CameraMotionOptions): Camera2D;
2519
+ /** Return the SVG transform that centers the camera on its world position. */
2520
+ declare function cameraSvgTransform(camera: Camera2D, viewport: CameraViewport): string;
2521
+ /** Project one world point to pixels using the same center-pivot camera rule. */
2522
+ declare function projectWorldPoint(point: MotionPoint, camera: Camera2D, viewport: CameraViewport): MotionPoint;
2523
+
2524
+ interface PathMorphOptions {
2525
+ /** Number of evenly spaced arc-length samples in the returned polyline. */
2526
+ samples?: number;
2527
+ easing?: MotionEasing;
2528
+ }
2529
+ /** Prepare arc-length correspondence once, then sample fresh points at any progress. */
2530
+ declare function createPolylineMorph(from: readonly MotionPoint[], to: readonly MotionPoint[], options?: PathMorphOptions): (progress: number) => MotionPoint[];
2531
+ /** Morph two polylines by matching points at equal fractions of their arc length. */
2532
+ declare function morphPolyline(from: readonly MotionPoint[], to: readonly MotionPoint[], progress: number, options?: PathMorphOptions): MotionPoint[];
2533
+
2534
+ interface VideoFrameInfo {
2535
+ /** Zero-based frame index. The final frame is always before the video endpoint. */
2536
+ index: number;
2537
+ count: number;
2538
+ /** Frame presentation time in milliseconds. */
2539
+ time: number;
2540
+ /** Duration rounded to the nearest whole frame, in milliseconds. */
2541
+ duration: number;
2542
+ /** Fraction of the video represented by this frame, from 0 to 1. */
2543
+ progress: number;
2544
+ fps: number;
2545
+ }
2546
+ interface RgbaVideoOptions {
2547
+ width: number;
2548
+ height: number;
2549
+ /** Requested duration before rounding to a whole number of frames. */
2550
+ duration: number;
2551
+ outputPath: string;
2552
+ fps?: number;
2553
+ audioPath?: string;
2554
+ ffmpegPath?: string;
2555
+ preset?: string;
2556
+ crf?: number;
2557
+ threads?: number;
2558
+ signal?: AbortSignal;
2559
+ onProgress?: (frame: VideoFrameInfo) => void | Promise<void>;
2560
+ }
2561
+ interface RgbaVideoOutput {
2562
+ width: number;
2563
+ height: number;
2564
+ frameCount: number;
2565
+ duration: number;
2566
+ fps: number;
2567
+ bytes: number;
2568
+ outputPath: string;
2569
+ audioIncluded: boolean;
2570
+ }
2571
+ interface AnimationVideoOptions extends Omit<RgbaVideoOptions, 'duration'> {
2572
+ /** Physical output pixels per logical scene pixel. Defaults to 1. Scaled dimensions must be even integers. */
2573
+ scale?: number;
2574
+ theme?: ThemeMode;
2575
+ /** MP4 has no alpha channel. Defaults to the opaque theme background. */
2576
+ background?: RenderBackground;
2577
+ watermark?: WatermarkInput;
2578
+ brand?: boolean | string;
2579
+ }
2580
+ type RgbaVideoFrameRenderer = (frame: VideoFrameInfo) => Uint8Array | Promise<Uint8Array>;
2581
+ /** Lazily yields every frame timestamp; it never emits a duplicate endpoint frame. */
2582
+ declare function videoFrameSchedule(duration: number, fps?: number): Generator<VideoFrameInfo>;
2583
+ /** Streams a typed TSX animation to H.264 MP4 at exact video frame times (30 fps by default). */
2584
+ declare function renderAnimationVideo<S extends object>(animation: DefinedAnimation<S>, options: AnimationVideoOptions): Promise<RgbaVideoOutput>;
2585
+ /**
2586
+ * Encodes caller-rendered RGBA frames as H.264 MP4. Frames are requested and
2587
+ * written one at a time, so the caller controls rendering and memory use.
2588
+ */
2589
+ declare function renderRgbaVideo(renderFrame: RgbaVideoFrameRenderer, options: RgbaVideoOptions): Promise<RgbaVideoOutput>;
2590
+
2591
+ interface SceneRasterOptions {
2592
+ /** Physical pixels per logical scene pixel, from 0.25 to 1. Scaled dimensions must be even integers. */
2593
+ outputScale?: number;
2594
+ }
2595
+ interface RenderSceneFrameOptions extends SceneFrameRequest, SceneRasterOptions {
2596
+ outputPath: string;
2597
+ }
2598
+ interface RenderSceneVideoOptions extends SceneRequest, SceneRasterOptions {
2599
+ outputPath: string;
2600
+ signal?: AbortSignal;
2601
+ /** Sample fewer output frames without changing the scene's logical fps or frame globals. */
2602
+ previewFps?: number;
2603
+ }
2604
+ interface SceneRenderOutput {
2605
+ runtimeVersion: string;
2606
+ sourceSha256: string;
2607
+ /** Includes the complete render request and bundled font/emoji fingerprint. */
2608
+ inputSha256: string;
2609
+ /** SHA-256 of the actual PNG or MP4 bytes. */
2610
+ assetSha256: string;
2611
+ fontAssetsSha256: string;
2612
+ width: number;
2613
+ height: number;
2614
+ /** Requested narration duration, in seconds. */
2615
+ duration: number;
2616
+ fps: number;
2617
+ frameCount: number;
2618
+ bytes: number;
2619
+ outputPath: string;
2620
+ time?: number;
2621
+ /** MP4 duration after rounding to a whole number of frames, in seconds. */
2622
+ encodedDuration?: number;
2623
+ /** Present for a reduced-resolution or reduced-frame-rate preview. */
2624
+ outputScale?: number;
2625
+ previewFps?: number;
2626
+ logicalWidth?: number;
2627
+ logicalHeight?: number;
2628
+ logicalFps?: number;
2629
+ logicalFrameCount?: number;
2630
+ }
2631
+ declare function renderSceneFrame(options: RenderSceneFrameOptions): Promise<SceneRenderOutput>;
2632
+ declare function renderSceneVideo(options: RenderSceneVideoOptions): Promise<SceneRenderOutput>;
2633
+
2079
2634
  type GraphImportSource = 'mermaid' | 'd2';
2080
2635
  type GraphImportDirection = 'LR' | 'RL' | 'TB' | 'BT';
2081
2636
  type GraphImportDiagnosticCode = 'import.empty' | 'import.lossy_semantics' | 'import.parse_error' | 'import.unsupported_semantics' | 'import.unsupported_syntax';
@@ -2216,4 +2771,4 @@ interface CheckFrameReport {
2216
2771
  */
2217
2772
  declare function checkFrame(input: CheckFrameInput, options?: CheckOptions): Promise<CheckFrameReport>;
2218
2773
 
2219
- export { type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Board, type BoardProps, Box, CANVAS_ITEM_COMPONENT, CHECK_DIAGNOSTIC_CODES, CalloutCard, Canvas, CanvasItem, type CanvasItemProps, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, type CheckAutoSize, type CheckAutoSizeAxes, type CheckDiagnostic, type CheckDiagnosticCode, type CheckDiagnosticCounts, type CheckDiagnosticLocation, type CheckFailurePolicy, type CheckFrameInput, type CheckFrameReport, type CheckOptions, type CheckThemeReport, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagnosticSeverity, type DiagramIconDefinition, type DiagramIconRenderProps, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramPort, type GraphDiagramProps, type GraphImportDiagnostic, type GraphImportDiagnosticCode, type GraphImportDirection, type GraphImportGraph, type GraphImportResult, type GraphImportSource, type GraphPortSide, type GraphRouting, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, ParetoBarChart, type ParetoBarChartProps, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, PieChart, type PieChartProps, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, canvas, checkFrame, colors, createPlotArea, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, formatTensorShape, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, importD2Graph, importMermaidGraph, keyframe, loadAdditionalAsset, normalizeWatermark, parallel, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrames, styles, toneGradients, tween, typography, withColorAlpha, wrapWithBrand, wrapWithWatermark };
2774
+ export { type AllocationLayout, type AllocationLayoutOptions, type AllocationPart, type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, type AnimationVideoOptions, type ArcSwapOptions, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Board, type BoardProps, Box, CANVAS_ITEM_COMPONENT, CHECK_DIAGNOSTIC_CODES, CalloutCard, type Camera2D, type CameraMotionOptions, type CameraViewport, Canvas, type CanvasBounds, type CanvasCardOptions, type CanvasCardStyle, CanvasItem, type CanvasItemProps, type CanvasMatrixOptions, CanvasOverflowError, type CanvasPainter, type CanvasPanelOptions, type CanvasPanelStyle, type CanvasParticleOptions, type CanvasPoint, type CanvasScopeOptions, type CanvasTokenRowOptions, Card, type CellGridLayout, type CellGridOptions, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, type CheckAutoSize, type CheckAutoSizeAxes, type CheckDiagnostic, type CheckDiagnosticCode, type CheckDiagnosticCounts, type CheckDiagnosticLocation, type CheckFailurePolicy, type CheckFrameInput, type CheckFrameReport, type CheckOptions, type CheckThemeReport, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, type CuePosition, type CueSnapshot, type CueTrackOptions, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagnosticSeverity, type DiagramIconDefinition, type DiagramIconRenderProps, type DiscreteCue, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramPort, type GraphDiagramProps, type GraphImportDiagnostic, type GraphImportDiagnosticCode, type GraphImportDirection, type GraphImportGraph, type GraphImportResult, type GraphImportSource, type GraphPortSide, type GraphRouting, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type MotionEasing, type MotionPoint, type OverflowResult, Panel, ParetoBarChart, type ParetoBarChartProps, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, type PathMorphOptions, PieChart, type PieChartProps, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderMathSvgOptions, type RenderMathSvgResult, type RenderOptions, type RenderOutput, type RenderSceneFrameOptions, type RenderSceneVideoOptions, type RgbaVideoFrameRenderer, type RgbaVideoOptions, type RgbaVideoOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, SceneFrameRequest, type SceneRenderOutput, SceneRequest, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TeachingAllocationOptions, type TeachingAxesOptions, type TeachingBarsOptions, type TeachingBarsResult, type TeachingConnectionOptions, type TeachingCurveOptions, type TeachingFlowEdge, type TeachingFlowGraphOptions, type TeachingFlowNode, type TeachingGridHighlight, type TeachingGridOptions, type TeachingPainter, type TeachingPathOptions, type TeachingPlot, type TeachingRoute, type TeachingScatterOptions, type TeachingScatterPoint, type TeachingTimeInterval, type TeachingTimeLane, type TeachingTimelineInterval, type TeachingTimelineOptions, type TeachingTimelineResult, type TeachingTransferEndpoint, type TeachingTransferOptions, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type TokenRowItem, type TokenRowLayoutOptions, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, type VideoFrameInfo, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, arcSwap, cameraSvgTransform, canvas, checkFrame, colors, createCanvasComponents, createCueTrack, createPlotArea, createPolylineMorph, createTeachingCanvas, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, dotProduct, entropy, formatMathText, formatTensorShape, gaussian, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, importD2Graph, importMermaidGraph, interpolateCamera, keyframe, layoutAllocation, layoutCellGrid, layoutTokenRow, lerpArray, loadAdditionalAsset, morphPolyline, multiplyMatrices, normalizeVector, normalizeWatermark, parallel, pointAlongPath, projectWorldPoint, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderAnimationVideo, renderMathSvg, renderRgbaVideo, renderSceneFrame, renderSceneVideo, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrame, sampleAnimationFrames, sampleFunction, sampleGaussian, seededRandom, smoothstep, stableSoftmax, styles, toneGradients, tracePolyline, tween, typography, videoFrameSchedule, withColorAlpha, wrapWithBrand, wrapWithWatermark };