textmode.export.js 1.6.0 → 1.7.0

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,14 @@
-import type { Textmodifier } from 'textmode.js';
-import type { TextmodePluginContext } from 'textmode.js';
+import type { Textmodifier, TextmodePluginContext } from 'textmode.js';
 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: TextmodePluginContext['registerPostDrawHook']);
     $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

@@ -21,4 +21,3 @@ export declare class GIFRecorder {
      */
     $record(canvas: HTMLCanvasElement, options: GIFGenerationOptions, registerPostDrawHook: TextmodePluginContext['registerPostDrawHook'], 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

@@ -15,7 +15,8 @@ export declare class VideoExporter {
      * @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

@@ -29,4 +29,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';
@@ -19,12 +24,16 @@ export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
  * Higher presets produce larger files with more detail. 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}
  */
 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 +45,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 +57,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 +71,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 +80,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 +131,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 = {
@@ -200,6 +219,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 +260,7 @@ export interface VideoGenerationOptions {
     transparent: boolean;
     debugLogging: boolean;
     signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
 }
 export interface VideoEncodingPlan {
     format: VideoExportFormat;
@@ -256,6 +282,7 @@ export interface VideoRenderFrameOptions {
     frameCount: number;
     frameRate: number;
     signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
     onFrame(frame: {
         frameIndex: number;
         canvas: HTMLCanvasElement;
@@ -265,4 +292,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

package/dist/types/index.d.ts

@@ -1,50 +1,35 @@
 /**
  * @packageDocumentation
  *
- * Export plugin for textmode.js - save artworks as images, videos, SVG, JSON, and text.
+ * Export finished textmode.js artworks without leaving the sketch.
  *
- * This plugin adds comprehensive export capabilities to textmode.js instances,
- * allowing you to save your generative artworks in multiple formats with a
- * convenient overlay UI for quick access to all export options.
+ * ## Choose an output
  *
- * ## Available export formats
+ * Use **canvas capture** for the exact image on screen: PNG, JPEG, WebP, GIF,
+ * or video preserve compositing, filters, shaders, and post-processing. Use
+ * **layer data export** when the artwork should stay editable or machine
+ * readable: TXT, SVG, and JSON read from the selected layer, while JSON can
+ * also describe the full layer stack.
  *
- * ### Image formats
- * - {@link ImageExportOptions | PNG/JPEG/WebP} - Save canvas as raster image
- *
- * ### Vector formats
- * - {@link SVGExportOptions | SVG} - Save as scalable vector graphics
- *
- * ### Text formats
- * - {@link TXTExportOptions | TXT} - Save text content as plain text
- * - {@link JSONExportOptions | JSON} - Save document data as structured JSON
- *
- * ### Animation formats
- * - {@link GIFExportOptions | GIF} - Save as animated GIF
- * - {@link VideoExportOptions | Video} - Save as WebM or MP4 video
- *
- * @module textmode.export.js
+ * Start with {@link ExportPlugin}, then call the helpers added to your sketch
+ * or use the built-in export overlay. For recipes and format trade-offs, read
+ * the [Exporting guide](/docs/exporting).
  */
 import type { TextmodePlugin } from 'textmode.js';
 import './augmentations';
-export type { ExportDefaults, ExportDefaultsPatch, ExportOverlayPosition, ExportOverlayPositionInput } from './types';
+export type { ExportDefaults, ExportDefaultsPatch, ExportOverlayPosition, ExportOverlayPositionInput, GIFOverlayDefaults, ImageOverlayDefaults, JSONOverlayDefaults, SVGOverlayDefaults, TXTOverlayDefaults, VideoOverlayDefaults, } from './types';
 export type { TextmodeExportAPI, ExportOverlayController } from './types';
 export type { ImageExportOptions } from './exporters/image';
 export type { SVGExportOptions } from './exporters/svg';
 export type { TXTExportOptions } from './exporters/txt';
-export type { JSONCellCollection, JSONCellTransform, JSONColorValue, JSONDocumentFormat, JSONDocumentVersion, JSONExportColorMode, JSONExportMetadata, JSONExportOptions, JSONExportTarget, JSONLayerGrid, JSONObjectRowCell, JSONObjectRowsCellCollection, JSONRGBAColor, TextmodeAllDocumentJSON, TextmodeDocumentJSON, TextmodeDocumentLayer, TextmodeSelectedDocumentJSON, TextmodeSelectedDocumentLayer, } from './exporters/json';
+export type { JSONExportColorMode, JSONExportOptions, JSONExportTarget, TextmodeDocumentJSON } from './exporters/json';
 export type { GIFExportOptions, GIFExportProgress } from './exporters/gif';
-export type { VideoBitrateMode, VideoBitratePreset, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, VideoRecordingState, } from './exporters/video';
+export type { VideoBitrateMode, VideoBitratePreset, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, VideoRecordingState, } from './exporters/video';
 export type { LayerExportOptions } from './exporters/base';
 /**
- * Export plugin for textmode.js.
- *
- * Add this plugin to your textmode.js instance to enable exporting artworks
- * as images, videos, SVG, JSON, and text files. Includes an overlay UI for quick
- * access to all export options, which can be controlled at runtime.
+ * Default export plugin instance for the standard textmode.js workflow.
  *
- * @example
- * {@includeCode ../examples/ExportPlugin/init/sketch.js}
+ * @category Workflow
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/variables/ExportPlugin | ExportPlugin API reference}
  */
@@ -54,4 +39,3 @@ declare global {
         ExportPlugin?: TextmodePlugin;
     }
 }
-//# sourceMappingURL=index.d.ts.map

package/dist/types/overlay/blades/Blade.d.ts

@@ -31,4 +31,3 @@ export declare abstract class Blade<TOptions> extends Component<void> {
     protected _onDestroy(): void;
 }
 export {};
-//# sourceMappingURL=Blade.d.ts.map

package/dist/types/overlay/blades/GIFBlade.d.ts

@@ -21,4 +21,3 @@ export declare class GIFBlade extends Blade<GIFExportOptions> {
     private safeParseInt;
     private safeParseFloat;
 }
-//# sourceMappingURL=GIFBlade.d.ts.map

package/dist/types/overlay/blades/ImageBlade.d.ts

@@ -12,4 +12,3 @@ export declare class ImageBlade extends Blade<ImageExportOptions> {
     validate(): boolean;
     private applyDefaults;
 }
-//# sourceMappingURL=ImageBlade.d.ts.map

package/dist/types/overlay/blades/JSONBlade.d.ts

@@ -18,4 +18,3 @@ export declare class JSONBlade extends Blade<JSONExportOptions> {
     private applyDefaults;
     private updateLayerTargetVisibility;
 }
-//# sourceMappingURL=JSONBlade.d.ts.map

package/dist/types/overlay/blades/RecordingBlade.d.ts

@@ -5,4 +5,3 @@ export interface RecordingBladeLike {
     handleProgress(progress: unknown): void;
 }
 export declare function isRecordingBlade(blade: Blade<unknown>): blade is Blade<unknown> & RecordingBladeLike;
-//# sourceMappingURL=RecordingBlade.d.ts.map

package/dist/types/overlay/blades/SVGBlade.d.ts

@@ -16,4 +16,3 @@ export declare class SVGBlade extends Blade<SVGExportOptions> {
     private updateStrokeControls;
     private applyDefaults;
 }
-//# sourceMappingURL=SVGBlade.d.ts.map