textmode.export.js 1.6.0 → 1.7.1

package/dist/types/augmentations/index.d.ts

@@ -2,4 +2,3 @@
  * Augmentation barrel.
  */
 import './textmode';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/augmentations/textmode.d.ts

@@ -6,4 +6,3 @@ declare module 'textmode.js' {
     interface Textmodifier extends TextmodeExportAPI {
     }
 }
-//# sourceMappingURL=textmode.d.ts.map

package/dist/types/exporters/base/CharacterResolver.d.ts

@@ -26,4 +26,3 @@ export declare function getEncodedGlyphValueFromColor(color: [number, number, nu
  */
 export declare function resolveGlyphByEncodedValue(font: ResolvableFont, encodedValue: number): ResolvableGlyph | undefined;
 export {};
-//# sourceMappingURL=CharacterResolver.d.ts.map

package/dist/types/exporters/base/DataExtractor.d.ts

@@ -42,4 +42,3 @@ export declare class DataExtractor {
         rotation: number;
     };
 }
-//# sourceMappingURL=DataExtractor.d.ts.map

package/dist/types/exporters/base/FileHandler.d.ts

@@ -24,4 +24,3 @@ export declare class FileHandler {
      */
     private _generateDefaultFilename;
 }
-//# sourceMappingURL=FileHandler.d.ts.map

package/dist/types/exporters/base/FramePreparation.d.ts

@@ -0,0 +1,10 @@
+/** Context supplied before a deterministic export frame is rendered. */
+export interface ExportFrameContext {
+    frameIndex: number;
+    frameCount: number;
+    timeSeconds: number;
+    frameRate: number;
+    signal?: AbortSignal;
+}
+/** Prepares external media or state before an export frame is redrawn. */
+export type PrepareExportFrame = (context: ExportFrameContext) => void | Promise<void>;

package/dist/types/exporters/base/LayerTarget.d.ts

@@ -1,9 +1,11 @@
-import type { Textmodifier, TextmodeFramebuffer, TextmodeGrid } from 'textmode.js';
+import { LayerBlendMode, type Textmodifier, type TextmodeFramebuffer, type TextmodeGrid } from 'textmode.js';
 import type { TextmodeFont, TextmodeTileset } from 'textmode.js';
 import type { TextmodeLayer } from 'textmode.js';
 /**
  * Shared option for exporters that read layer framebuffer data.
  *
+ * @category Layer data export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/LayerExportOptions | LayerExportOptions API reference}
  */
 export interface LayerExportOptions {
@@ -27,7 +29,7 @@ export interface ResolvedLayerExportTarget {
 export interface ResolvedLayerStackExportTarget extends ResolvedLayerExportTarget {
     visible: boolean;
     opacity: number;
-    blendMode: string;
+    blendMode: LayerBlendMode;
     offsetX: number;
     offsetY: number;
     rotationZ: number;
@@ -47,4 +49,3 @@ export declare function createLayerTargetProvider(textmodifier: Textmodifier): L
 export declare function getLayerTargetId(textmodifier: Textmodifier, layer: TextmodeLayer): string;
 export declare function resolveLayerExportTarget(textmodifier: Textmodifier, layer?: TextmodeLayer): ResolvedLayerExportTarget;
 export declare function resolveLayerStackExportTargets(textmodifier: Textmodifier): ResolvedLayerStackExportTarget[];
-//# sourceMappingURL=LayerTarget.d.ts.map

package/dist/types/exporters/base/index.d.ts

@@ -3,4 +3,4 @@ export { FileHandler } from './FileHandler';
 export { getEncodedGlyphValueFromColor, resolveGlyphByEncodedValue } from './CharacterResolver';
 export { createLayerTargetProvider, getLayerTargetId, getLayerTargetOptions, resolveLayerExportTarget, resolveLayerStackExportTargets, } from './LayerTarget';
 export type { LayerExportOptions, LayerTargetOption, LayerTargetProvider, ResolvedLayerExportTarget, ResolvedLayerStackExportTarget, } from './LayerTarget';
-//# sourceMappingURL=index.d.ts.map
+export type { ExportFrameContext, PrepareExportFrame } from './FramePreparation';

package/dist/types/exporters/gif/GIFEncoderWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/exporters/gif/GIFExporter.d.ts

@@ -1,34 +1,15 @@
 import type { Textmodifier } from 'textmode.js';
-import type { TextmodePluginContext } from 'textmode.js';
+import { type PostDrawSubscription } from '../video/VideoFrameDriver';
 import type { GIFExportOptions } from './types';
-/**
- * Main GIF exporter for the textmode.js library.
- * Orchestrates the GIF export process by coordinating canvas capture,
- * frame processing, and file handling.
- */
+/** Deterministic, bounded-memory GIF exporter. */
 export declare class GIFExporter {
-    private readonly _recorder;
     private readonly _textmodifier;
     private readonly _registerPostDrawHook;
-    /**
-     * Creates an instance of GIFExporter.
-     *
-     * @param textmodifier The Textmodifier instance to capture frames from
-     * @param registerPostDrawHook Function to register post-draw hooks
-     */
-    constructor(textmodifier: Textmodifier, registerPostDrawHook: TextmodePluginContext['registerPostDrawHook']);
-    /**
-     * Captures frames and saves them as a GIF file
-     *
-     * @param options Export options
-     */
+    constructor(_textmodifier: Textmodifier, _registerPostDrawHook: PostDrawSubscription);
     $saveGIF(options?: GIFExportOptions): Promise<void>;
-    /**
-     * Applies default values to the provided export options
-     *
-     * @param options User-provided options
-     * @returns Complete options with defaults applied
-     */
+    /** Generates a GIF blob without initiating a download. */
+    $generateGIFBlob(options?: GIFExportOptions): Promise<Blob>;
     private _applyDefaultOptions;
+    private _throwIfAborted;
+    private _yieldToBrowser;
 }
-//# sourceMappingURL=GIFExporter.d.ts.map

package/dist/types/exporters/gif/GIFRecorder.d.ts

@@ -1,4 +1,4 @@
-import type { TextmodePluginContext } from 'textmode.js';
+import type { PostDrawSubscription } from '../video/VideoFrameDriver';
 import type { GIFExportProgress, GIFFrame, GIFGenerationOptions } from './types';
 /**
  * Records frames from a canvas for GIF generation.
@@ -19,6 +19,5 @@ export declare class GIFRecorder {
      * @returns Promise resolving to array of captured frames
      * @throws {Error} If frame capture fails
      */
-    $record(canvas: HTMLCanvasElement, options: GIFGenerationOptions, registerPostDrawHook: TextmodePluginContext['registerPostDrawHook'], onProgress?: (progress: GIFExportProgress) => void): Promise<GIFFrame[]>;
+    $record(canvas: HTMLCanvasElement, options: GIFGenerationOptions, registerPostDrawHook: PostDrawSubscription, onProgress?: (progress: GIFExportProgress) => void): Promise<GIFFrame[]>;
 }
-//# sourceMappingURL=GIFRecorder.d.ts.map

package/dist/types/exporters/gif/GIFWorkerClient.d.ts

@@ -0,0 +1,15 @@
+/** One-at-a-time worker bridge that bounds captured GIF memory to one RGBA frame. */
+export declare class GIFWorkerClient {
+    private readonly _worker;
+    private readonly _pending;
+    private readonly _ready;
+    private _requestId;
+    private _disposed;
+    constructor(width: number, height: number, frameRate: number, repeat: number, signal?: AbortSignal);
+    encodeFrame(buffer: ArrayBuffer, frameIndex: number): Promise<void>;
+    finish(): Promise<ArrayBuffer>;
+    dispose: () => void;
+    private _request;
+    private _handleMessage;
+    private _handleError;
+}

package/dist/types/exporters/gif/index.d.ts

@@ -1,4 +1,3 @@
 export { GIFExporter } from './GIFExporter';
 export { GIFRecorder } from './GIFRecorder';
 export type { GIFExportOptions, GIFExportProgress, GIFGenerationOptions, GIFRecordingState } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/gif/types.d.ts

@@ -1,7 +1,10 @@
+import type { PrepareExportFrame } from '../base';
 export type GIFRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
 /**
  * Progress information emitted during the GIF export process.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress | GIFExportProgress API reference}
  */
 export type GIFExportProgress = {
@@ -33,6 +36,8 @@ export type GIFExportProgress = {
 /**
  * Options for exporting the textmode content to GIF format.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions | GIFExportOptions API reference}
  */
 export type GIFExportOptions = {
@@ -70,6 +75,18 @@ export type GIFExportOptions = {
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions#repeat | GIFExportOptions.repeat API reference}
      */
     repeat?: number;
+    /**
+     * Abort signal for cancelling capture or encoding.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions#signal | GIFExportOptions.signal API reference}
+     */
+    signal?: AbortSignal;
+    /**
+     * Prepares external media before each deterministic frame is redrawn.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions#prepareframe | GIFExportOptions.prepareFrame API reference}
+     */
+    prepareFrame?: PrepareExportFrame;
     /**
      * Progress callback invoked throughout the recording lifecycle.
      *
@@ -83,6 +100,8 @@ export interface GIFGenerationOptions {
     frameRate: number;
     scale: number;
     repeat: number;
+    signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
 }
 export interface GIFFrame {
     imageData: ImageData;
@@ -90,4 +109,3 @@ export interface GIFFrame {
     height: number;
     delayMs?: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/image/ImageExporter.d.ts

@@ -34,6 +34,8 @@ export declare class ImageExporter {
      * @param options Export options
      */
     $saveImage(canvas: HTMLCanvasElement, options?: ImageExportOptions): Promise<void>;
+    /** Generates an image blob using the public export options. */
+    $toImageBlob(canvas: HTMLCanvasElement, options?: ImageExportOptions): Promise<Blob>;
     /**
      * Copies the generated image to the clipboard using the modern Clipboard API
      *
@@ -42,4 +44,3 @@ export declare class ImageExporter {
      */
     $copyImageToClipboard(canvas: HTMLCanvasElement, options?: ImageExportOptions): Promise<void>;
 }
-//# sourceMappingURL=ImageExporter.d.ts.map

package/dist/types/exporters/image/index.d.ts

@@ -1,4 +1,3 @@
 export { ImageExporter } from './ImageExporter';
 export type { ImageExportOptions, ImageGenerationOptions, ImageFormat } from './types';
 export { IMAGE_MIME_TYPES, IMAGE_EXTENSIONS } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/image/types.d.ts

@@ -8,6 +8,8 @@ export type ImageFormat = 'png' | 'jpg' | 'webp';
 /**
  * Options for exporting the textmode content to image format.
  *
+ * @category Canvas capture
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ImageExportOptions | ImageExportOptions API reference}
  */
 export type ImageExportOptions = {
@@ -50,4 +52,3 @@ export declare const IMAGE_MIME_TYPES: Record<ImageFormat, string>;
  * File extension mapping for image formats.
  */
 export declare const IMAGE_EXTENSIONS: Record<ImageFormat, string>;
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/json/JSONDataExtractor.d.ts

@@ -12,4 +12,3 @@ export declare class JSONDataExtractor extends DataExtractor {
      */
     $extractCellData(target: ResolvedLayerExportTarget): JSONCellData[];
 }
-//# sourceMappingURL=JSONDataExtractor.d.ts.map

package/dist/types/exporters/json/JSONExporter.d.ts

@@ -58,4 +58,3 @@ export declare class JSONExporter {
      */
     $saveJSON(textmodifier: Textmodifier, options?: JSONExportOptions): void;
 }
-//# sourceMappingURL=JSONExporter.d.ts.map

package/dist/types/exporters/json/index.d.ts

@@ -1,4 +1,3 @@
 export { JSONExporter } from './JSONExporter';
 export { JSONDataExtractor } from './JSONDataExtractor';
 export type { JSONDocumentFormat, JSONDocumentVersion, JSONCellCollection, JSONCellData, JSONCellTransform, JSONColorValue, JSONExportColorMode, JSONExportMetadata, JSONExportOptions, JSONExportTarget, JSONGenerationOptions, JSONLayerGrid, JSONObjectRowCell, JSONObjectRowsCellCollection, JSONRGBAColor, TextmodeAllDocumentJSON, TextmodeDocumentJSON, TextmodeDocumentLayer, TextmodeSelectedDocumentJSON, TextmodeSelectedDocumentLayer, } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/json/types.d.ts

@@ -2,6 +2,8 @@ import type { LayerExportOptions } from '../base';
 /**
  * Target scope for JSON export.
  *
+ * @category JSON document data
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportTarget | JSONExportTarget API reference}
  */
 export type JSONExportTarget = 'selected' | 'all';
@@ -20,6 +22,8 @@ export type JSONDocumentVersion = '2.0.0';
 /**
  * Supported JSON color output modes.
  *
+ * @category JSON document data
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportColorMode | JSONExportColorMode API reference}
  */
 export type JSONExportColorMode = 'hex' | 'rgba';
@@ -163,12 +167,16 @@ export interface TextmodeAllDocumentJSON {
 /**
  * JSON document exported by the JSON exporter.
  *
+ * @category JSON document data
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/TextmodeDocumentJSON | TextmodeDocumentJSON API reference}
  */
 export type TextmodeDocumentJSON = TextmodeSelectedDocumentJSON | TextmodeAllDocumentJSON;
 /**
  * Options for exporting the textmode content to JSON format.
  *
+ * @category JSON document data
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportOptions | JSONExportOptions API reference}
  */
 export type JSONExportOptions = LayerExportOptions & {
@@ -231,4 +239,3 @@ export interface JSONCellData {
     background: JSONRGBAColor;
     transform: JSONCellTransform;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/svg/SVGContentGenerator.d.ts

@@ -76,4 +76,3 @@ export declare class SVGContentGenerator {
      */
     $optimizeSVGContent(svgContent: string): string;
 }
-//# sourceMappingURL=SVGContentGenerator.d.ts.map

package/dist/types/exporters/svg/SVGDataExtractor.d.ts

@@ -24,4 +24,3 @@ export declare class SVGDataExtractor extends DataExtractor {
      */
     $extractSVGCellData(framebufferData: FramebufferData, grid: TextmodeGrid): SVGCellData[];
 }
-//# sourceMappingURL=SVGDataExtractor.d.ts.map

package/dist/types/exporters/svg/SVGExporter.d.ts

@@ -29,4 +29,3 @@ export declare class SVGExporter {
      */
     $saveSVG(textmodifier: Textmodifier, options?: SVGExportOptions): void;
 }
-//# sourceMappingURL=SVGExporter.d.ts.map

package/dist/types/exporters/svg/SVGPathGenerator.d.ts

@@ -69,4 +69,3 @@ export declare class SVGPathGenerator {
     $generatePositionedCharacterPath(_character: string, font: TextmodeFont, cellX: number, cellY: number, cellWidth: number, _cellHeight: number, fontSize: number, glyphData: GlyphData | null): string | null;
 }
 export {};
-//# sourceMappingURL=SVGPathGenerator.d.ts.map

package/dist/types/exporters/svg/index.d.ts

@@ -3,4 +3,3 @@ export { SVGDataExtractor } from './SVGDataExtractor';
 export { SVGContentGenerator } from './SVGContentGenerator';
 export { SVGPathGenerator } from './SVGPathGenerator';
 export type { SVGExportOptions, SVGGenerationOptions, SVGCellData, FramebufferData, RGBA, Position, CellPosition, CellTransform, GlyphPath, } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/svg/types.d.ts

@@ -54,6 +54,8 @@ export interface FramebufferData {
 /**
  * Options for exporting the textmode content to SVG format.
  *
+ * @category Layer data export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/SVGExportOptions | SVGExportOptions API reference}
  */
 export type SVGExportOptions = LayerExportOptions & {
@@ -110,4 +112,3 @@ export interface SVGGenerationOptions {
     filename?: string;
     layer?: LayerExportOptions['layer'];
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/txt/TXTExporter.d.ts

@@ -37,4 +37,3 @@ export declare class TXTExporter {
      */
     $saveTXT(textmodifier: Textmodifier, options?: TXTExportOptions): void;
 }
-//# sourceMappingURL=TXTExporter.d.ts.map

package/dist/types/exporters/txt/index.d.ts

@@ -1,3 +1,2 @@
 export { TXTExporter } from './TXTExporter';
 export type { TXTExportOptions, TXTGenerationOptions, FramebufferData } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/txt/types.d.ts

@@ -2,6 +2,8 @@ import type { LayerExportOptions } from '../base';
 /**
  * Options for exporting the textmode content to TXT format.
  *
+ * @category Layer data export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/TXTExportOptions | TXTExportOptions API reference}
  */
 export type TXTExportOptions = LayerExportOptions & {
@@ -38,4 +40,3 @@ export interface TXTGenerationOptions {
  * Re-export shared types from SVG module that are also used by TXT exporter
  */
 export type { FramebufferData } from '../svg/types';
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/video/VideoExporter.d.ts

@@ -1,5 +1,5 @@
 import type { Textmodifier } from 'textmode.js';
-import type { TextmodePluginContext } from 'textmode.js';
+import { type PostDrawSubscription } from './VideoFrameDriver';
 import type { VideoExportOptions } from './types';
 /**
  * Main video exporter for the textmode.js library.
@@ -8,14 +8,15 @@ export declare class VideoExporter {
     private readonly _recorder;
     private readonly _textmodifier;
     private readonly _registerPostDrawHook;
-    constructor(textmodifier: Textmodifier, registerPostDrawHook: TextmodePluginContext['registerPostDrawHook']);
+    constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription);
     /**
      * Captures deterministic frames and saves them as a video file.
      *
      * @param options Export options
      */
     $saveVideo(options?: VideoExportOptions): Promise<void>;
-    private _saveVideo;
+    /** Generates a deterministic video without initiating a download. */
+    $generateVideoBlob(options?: VideoExportOptions): Promise<Blob>;
     private _applyDefaultOptions;
     private _positiveInteger;
     private _positiveNumber;
@@ -27,4 +28,3 @@ export declare class VideoExporter {
     private _currentPixelDensity;
     private _withExtension;
 }
-//# sourceMappingURL=VideoExporter.d.ts.map

package/dist/types/exporters/video/VideoFrameDriver.d.ts

@@ -1,5 +1,6 @@
-import type { Textmodifier, TextmodePluginContext } from 'textmode.js';
+import type { Textmodifier } from 'textmode.js';
 import type { VideoRenderFrameOptions } from './types';
+export type PostDrawSubscription = (callback: () => void) => () => void;
 /**
  * Drives deterministic video export frames through public textmode APIs.
  *
@@ -15,7 +16,7 @@ export declare class VideoFrameDriver {
     private _pendingFrame;
     private _syntheticFrameCount;
     private _syntheticMillis;
-    constructor(textmodifier: Textmodifier, registerPostDrawHook: TextmodePluginContext['registerPostDrawHook'], width: number, height: number);
+    constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription, width: number, height: number);
     $render(options: VideoRenderFrameOptions): Promise<void>;
     private _renderOneFrame;
     private _capturePendingFrame;
@@ -29,4 +30,3 @@ export declare class VideoFrameDriver {
     private _restoreProperties;
     private _throwIfAborted;
 }
-//# sourceMappingURL=VideoFrameDriver.d.ts.map

package/dist/types/exporters/video/VideoRecorder.d.ts

@@ -16,4 +16,3 @@ export declare class VideoRecorder {
     private _normalizeError;
     private _log;
 }
-//# sourceMappingURL=VideoRecorder.d.ts.map

package/dist/types/exporters/video/errors.d.ts

@@ -7,4 +7,3 @@ export declare class VideoExportError extends Error {
 export declare function createAbortError(): VideoExportError;
 export declare function createTimeoutError(message: string, cause?: unknown): VideoExportError;
 export declare function isAbortError(error: unknown): boolean;
-//# sourceMappingURL=errors.d.ts.map

package/dist/types/exporters/video/index.d.ts

@@ -3,4 +3,3 @@ export { VideoFrameDriver } from './VideoFrameDriver';
 export { VideoRecorder } from './VideoRecorder';
 export { VideoExportError } from './errors';
 export type { VideoBitrateMode, VideoBitratePreset, VideoEncodingPlan, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoFrameDriverLike, VideoHardwareAcceleration, VideoLatencyMode, VideoExportProgress, VideoGenerationOptions, VideoRecordingState, VideoRenderFrameOptions, } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/exporters/video/types.d.ts

@@ -1,6 +1,9 @@
+import type { PrepareExportFrame } from '../base';
 /**
  * Lifecycle state reported while a video export is being prepared, recorded, encoded, or completed.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoRecordingState | VideoRecordingState API reference}
  */
 export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
@@ -9,6 +12,8 @@ export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed
  *
  * `rendering` is retained for 1.5.x compatibility. Current deterministic video capture emits `capturing`.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportPhase | VideoExportPhase API reference}
  */
 export type VideoExportPhase = 'probing' | 'rendering' | 'capturing' | 'encoding' | 'draining' | 'finalizing';
@@ -16,8 +21,11 @@ export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
 /**
  * Subjective bitrate preset used when an exact bits-per-second value is not supplied.
  *
- * Higher presets produce larger files with more detail. For exact control, pass a numeric
- * `bitrate` value in bits per second instead.
+ * Higher presets produce larger files with more detail. Each preset maps to a fixed bits-per-pixel budget
+ * (bits per pixel per second), so a given preset resolves to the same bitrate regardless of the export
+ * frame rate. For exact control, pass a numeric `bitrate` value in bits per second instead.
+ *
+ * @category Animation export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitratePreset | VideoBitratePreset API reference}
  */
@@ -25,6 +33,8 @@ export type VideoBitratePreset = 'low' | 'medium' | 'high';
 /**
  * Video container format written by `saveVideo`.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportFormat | VideoExportFormat API reference}
  */
 export type VideoExportFormat = 'webm' | 'mp4';
@@ -36,6 +46,8 @@ export type VideoExportFormat = 'webm' | 'mp4';
  * - `'constant'`: asks the encoder to keep the bitrate steadier throughout the export. This can make file size
  *   more predictable, but may waste bits on simple frames or reduce detail on complex frames.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitrateMode | VideoBitrateMode API reference}
  */
 export type VideoBitrateMode = 'variable' | 'constant';
@@ -46,6 +58,8 @@ export type VideoBitrateMode = 'variable' | 'constant';
  * - `'realtime'`: prioritizes low-latency encoding. It is intended for live streams and may drop frames when overloaded,
  *   so it is usually not recommended for frame-perfect exports.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoLatencyMode | VideoLatencyMode API reference}
  */
 export type VideoLatencyMode = 'quality' | 'realtime';
@@ -58,6 +72,8 @@ export type VideoLatencyMode = 'quality' | 'realtime';
  *   availability and output characteristics vary by device.
  * - `'prefer-software'`: prefer CPU encoding, often more consistent across machines, but usually slower.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoHardwareAcceleration | VideoHardwareAcceleration API reference}
  */
 export type VideoHardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer-software';
@@ -65,6 +81,8 @@ export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNS
 /**
  * Progress information emitted during the video export process.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
@@ -114,6 +132,8 @@ export type VideoExportProgress = {
 /**
  * Options for exporting the textmode content to video format.
  *
+ * @category Animation export
+ *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
 export type VideoExportOptions = {
@@ -142,11 +162,12 @@ export type VideoExportOptions = {
      */
     frameRate?: number;
     /**
-     * Target bitrate in bits per second or a bitrate preset. Defaults to `'medium'`.
+     * Target bitrate in bits per second or a quality preset. Defaults to `'medium'`.
      *
      * Bitrate controls how much encoded data is available per second of video. Higher values can preserve more detail
-     * in noisy or fast-changing sketches, but create larger files. Presets are resolved from the export dimensions and
-     * frame rate; numeric values are passed directly to the encoder.
+     * in noisy or fast-changing sketches, but create larger files. Presets resolve to a fixed bits-per-pixel budget
+     * from the export dimensions only, so a given preset targets the same bitrate regardless of the frame rate.
+     * Numeric values are passed directly to the encoder.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitrate | VideoExportOptions.bitrate API reference}
      */
@@ -200,6 +221,12 @@ export type VideoExportOptions = {
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#signal | VideoExportOptions.signal API reference}
      */
     signal?: AbortSignal;
+    /**
+     * Prepares external media before each deterministic frame is redrawn.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#prepareframe | VideoExportOptions.prepareFrame API reference}
+     */
+    prepareFrame?: PrepareExportFrame;
     /**
      * When true, attempts to preserve alpha data in WebM recordings. MP4 exports reject this option.
      *
@@ -235,6 +262,7 @@ export interface VideoGenerationOptions {
     transparent: boolean;
     debugLogging: boolean;
     signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
 }
 export interface VideoEncodingPlan {
     format: VideoExportFormat;
@@ -256,6 +284,7 @@ export interface VideoRenderFrameOptions {
     frameCount: number;
     frameRate: number;
     signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
     onFrame(frame: {
         frameIndex: number;
         canvas: HTMLCanvasElement;
@@ -265,4 +294,3 @@ export interface VideoFrameDriverLike {
     readonly canvas: HTMLCanvasElement;
     $render(options: VideoRenderFrameOptions): Promise<void>;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types/exporters/video/withAbortableTimeout.d.ts

@@ -1,2 +1 @@
 export declare function withAbortableTimeout<T>(promise: Promise<T>, message: string, signal: AbortSignal | undefined, timeoutMs: number): Promise<T>;
-//# sourceMappingURL=withAbortableTimeout.d.ts.map