textmode.export.js 1.8.1 → 1.9.0-beta.2

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

@@ -1,225 +1,37 @@
 import type { LayerExportOptions } from '../base';
+import type { JSONCellTransform, JSONExportTarget, JSONRGBAColor } from '../../document';
 /**
- * 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';
-/**
- * Canonical JSON document format identifier.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONDocumentFormat | JSONDocumentFormat API reference}
- */
-export type JSONDocumentFormat = 'textmode.document';
-/**
- * Canonical JSON document format version.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONDocumentVersion | JSONDocumentVersion API reference}
- */
-export type JSONDocumentVersion = '2.0.0';
-/**
- * Supported JSON color output modes.
- *
- * @category JSON document data
+ * Color representation written by the JSON exporter: hexadecimal strings or
+ * RGBA channel objects.
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportColorMode | JSONExportColorMode API reference}
  */
 export type JSONExportColorMode = 'hex' | 'rgba';
+export type { JSONCellCollection, JSONCellTransform, JSONColorValue, JSONDocumentFormat, JSONDocumentVersion, JSONExportMetadata, JSONExportTarget, JSONLayerGrid, JSONObjectRowCell, JSONObjectRowsCellCollection, JSONRGBAColor, TextmodeAllDocumentJSON, TextmodeDocumentJSON, TextmodeDocumentLayer, TextmodeSelectedDocumentJSON, TextmodeSelectedDocumentLayer, } from '../../document';
 /**
- * RGBA color representation used in JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONRGBAColor | JSONRGBAColor API reference}
- */
-export interface JSONRGBAColor {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-}
-/**
- * Color value used in the exported JSON document.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONColorValue | JSONColorValue API reference}
- */
-export type JSONColorValue = string | JSONRGBAColor;
-/**
- * Cell transform data for JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONCellTransform | JSONCellTransform API reference}
- */
-export interface JSONCellTransform {
-    invert: boolean;
-    flipX: boolean;
-    flipY: boolean;
-    rotation: number;
-}
-/**
- * Rich per-cell representation for readable JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONObjectRowCell | JSONObjectRowCell API reference}
- */
-export interface JSONObjectRowCell {
-    x: number;
-    y: number;
-    character: string;
-    foreground: JSONColorValue;
-    background: JSONColorValue;
-    transform: JSONCellTransform;
-}
-/**
- * Row-based cell encoding.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONObjectRowsCellCollection | JSONObjectRowsCellCollection API reference}
- */
-export interface JSONObjectRowsCellCollection {
-    encoding: 'object-rows-v1';
-    rows: JSONObjectRowCell[][];
-}
-/**
- * Supported JSON cell collection variants.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONCellCollection | JSONCellCollection API reference}
- */
-export type JSONCellCollection = JSONObjectRowsCellCollection;
-/**
- * Grid dimensions exported for a layer.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONLayerGrid | JSONLayerGrid API reference}
- */
-export interface JSONLayerGrid {
-    cols: number;
-    rows: number;
-    cellWidth: number;
-    cellHeight: number;
-}
-/**
- * Optional export metadata.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONExportMetadata | JSONExportMetadata API reference}
- */
-export interface JSONExportMetadata {
-    createdAt: string;
-    generator: {
-        name: 'textmode.export.js';
-        version: string;
-    };
-}
-/**
- * Selected-layer entry in a JSON document export.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeSelectedDocumentLayer | TextmodeSelectedDocumentLayer API reference}
- */
-export interface TextmodeSelectedDocumentLayer {
-    id: string;
-    cells: JSONCellCollection;
-}
-/**
- * Selected-layer document exported by the JSON exporter.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeSelectedDocumentJSON | TextmodeSelectedDocumentJSON API reference}
- */
-export interface TextmodeSelectedDocumentJSON {
-    format: JSONDocumentFormat;
-    formatVersion: JSONDocumentVersion;
-    target: 'selected';
-    metadata?: JSONExportMetadata;
-    canvas: {
-        width: number;
-        height: number;
-    };
-    grid: JSONLayerGrid;
-    layer: TextmodeSelectedDocumentLayer;
-}
-/**
- * Single layer entry in an all-layers JSON export.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeDocumentLayer | TextmodeDocumentLayer API reference}
- */
-export interface TextmodeDocumentLayer {
-    id: string;
-    visible: boolean;
-    opacity: number;
-    blendMode: string;
-    offsetX: number;
-    offsetY: number;
-    rotationZ: number;
-    grid: JSONLayerGrid;
-    cells: JSONCellCollection;
-}
-/**
- * Layer stack document exported by the JSON exporter.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeAllDocumentJSON | TextmodeAllDocumentJSON API reference}
- */
-export interface TextmodeAllDocumentJSON {
-    format: JSONDocumentFormat;
-    formatVersion: JSONDocumentVersion;
-    target: 'all';
-    metadata?: JSONExportMetadata;
-    canvas: {
-        width: number;
-        height: number;
-    };
-    layers: TextmodeDocumentLayer[];
-}
-/**
- * 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
+ * Options for exporting textmode content to JSON.
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportOptions | JSONExportOptions API reference}
  */
 export type JSONExportOptions = LayerExportOptions & {
     /**
-     * Scope of the JSON export.
-     *
-     * Use `'selected'` to export one layer, or `'all'` to export the base layer and every user-created layer.
-     *
-     * Defaults to `'selected'`.
+     * Export one selected layer or the complete layer stack.
+     * Defaults to `selected`.
      */
     target?: JSONExportTarget;
-    /**
-     * The filename to save the JSON file as.
-     *
-     * If not provided, a default filename is used.
-     */
+    /** Filename used by the download helper. A default name is used when omitted. */
     filename?: string;
     /**
-     * Pretty-print the generated JSON.
-     *
-     * When set to `true`, output uses two-space indentation.
-     * When set to a number, that value is used as indentation width.
-     * When `false`, the output is minified.
-     *
-     * Defaults to `true`.
+     * Pretty-print with two spaces when `true`, use the given indentation width
+     * when numeric, or produce compact JSON when `false`. Defaults to `true`.
      */
     pretty?: boolean | number;
-    /**
-     * Color representation used for foreground and background values.
-     *
-     * Defaults to `'hex'`.
-     */
+    /** Foreground and background color representation. Defaults to `hex`. */
     colorMode?: JSONExportColorMode;
-    /**
-     * Whether to include export metadata such as timestamp and generator details.
-     *
-     * Defaults to `true`.
-     */
+    /** Include the creation timestamp and generator metadata. Defaults to `true`. */
     includeMetadata?: boolean;
 };
-/**
- * Internal options used by JSON generation (with all defaults applied).
- */
+/** Internal JSON generation options after defaults have been applied. */
 export interface JSONGenerationOptions {
     target: JSONExportTarget;
     pretty: boolean | number;
@@ -228,9 +40,7 @@ export interface JSONGenerationOptions {
     filename?: string;
     layer?: LayerExportOptions['layer'];
 }
-/**
- * Internal extracted cell data used while building the JSON document.
- */
+/** Internal framebuffer cell data used while building a document. */
 export interface JSONCellData {
     x: number;
     y: number;

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

@@ -1,4 +1,4 @@
-import type { LayerExportOptions } from '../base';
+import type { LayerExportOptions } from '../base/LayerTarget';
 /**
  * RGBA color representation.
  */
@@ -54,8 +54,6 @@ 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 & {

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

@@ -2,8 +2,6 @@ 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 & {

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

@@ -1,5 +1,5 @@
 import type { Textmodifier } from 'textmode.js';
-import { type PostDrawSubscription } from './VideoFrameDriver';
+import { type PostDrawSubscription } from '../base';
 import type { VideoExportOptions } from './types';
 /** Main video exporter for the textmode.js library. */
 export declare class VideoExporter {
@@ -20,6 +20,5 @@ export declare class VideoExporter {
     private _hardwareAcceleration;
     private _keyFrameInterval;
     private _currentPixelDensity;
-    private _withExtension;
     private _createFileSystemDestination;
 }

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

@@ -7,3 +7,4 @@ 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;
+export declare function normalizeVideoExportError(error: unknown): VideoExportError;

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

@@ -1,9 +1,7 @@
-import type { PrepareExportFrame } from '../base';
+import type { FrameSequenceDriverLike, FrameSequenceRenderOptions, PrepareExportFrame } from '../base';
 /**
  * High-level lifecycle state reported while a video export is captured, encoded, or completed.
  *
- * @category Video 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';
@@ -14,8 +12,6 @@ export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed
  * for buffered output. `rendering`, `encoding`, and `draining` remain available for compatibility with older progress
  * producers.
  *
- * @category Video 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' | 'writing' | 'finalizing';
@@ -26,8 +22,6 @@ export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
  * Higher levels generally preserve more detail and produce larger, content-dependent files. Mediabunny may use
  * quantizer-based encoding or a codec-adjusted bitrate, depending on codec and browser support.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQualityLevel | VideoQualityLevel API reference}
  */
 export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
@@ -49,8 +43,6 @@ export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-h
  * await t.saveVideo({ quality: { bitrate: 8_000_000, bitrateMode: 'constant' } });
  * ```
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQuality | VideoQuality API reference}
  */
 export type VideoQuality = VideoQualityLevel | {
@@ -66,8 +58,6 @@ export type VideoQuality = VideoQualityLevel | {
  *
  * This setting does not affect `toVideoBlob()`, which always returns an in-memory `Blob`.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoSaveDestination | VideoSaveDestination API reference}
  */
 export type VideoSaveDestination = 'download' | 'file-system';
@@ -77,8 +67,6 @@ export type VideoSaveDestination = 'download' | 'file-system';
  * MP4 uses AVC/H.264 and requires even coded dimensions. WebM selects VP9 when available and falls back to VP8; it
  * is the only format that can be requested with transparency.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportFormat | VideoExportFormat API reference}
  */
 export type VideoExportFormat = 'webm' | 'mp4';
@@ -92,8 +80,6 @@ export type VideoExportFormat = 'webm' | 'mp4';
  *
  * If omitted for an explicit target bitrate, Mediabunny uses `'variable'`.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitrateMode | VideoBitrateMode API reference}
  */
 export type VideoBitrateMode = 'variable' | 'constant';
@@ -106,8 +92,6 @@ export type VideoBitrateMode = 'variable' | 'constant';
  *   availability and output characteristics vary by device.
  * - `'prefer-software'`: prefer CPU encoding, often more consistent across machines, but usually slower.
  *
- * @category Video 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';
@@ -115,8 +99,6 @@ export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNS
 /**
  * Progress information emitted while a deterministic video is probed, captured, and written.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
@@ -192,8 +174,6 @@ export type VideoExportProgress = {
 /**
  * Options for capturing deterministic textmode frames as MP4 or WebM video.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
 export type VideoExportOptions = {
@@ -325,17 +305,5 @@ export interface VideoEncodingPlan {
     height: number;
     transparent: boolean;
 }
-export interface VideoRenderFrameOptions {
-    frameCount: number;
-    frameRate: number;
-    signal?: AbortSignal;
-    prepareFrame?: PrepareExportFrame;
-    onFrame(frame: {
-        frameIndex: number;
-        canvas: HTMLCanvasElement;
-    }): Promise<void> | void;
-}
-export interface VideoFrameDriverLike {
-    readonly canvas: HTMLCanvasElement;
-    $render(options: VideoRenderFrameOptions): Promise<void>;
-}
+export type VideoRenderFrameOptions = FrameSequenceRenderOptions;
+export type VideoFrameDriverLike = FrameSequenceDriverLike;

package/dist/types/exporters/zip/FrameSerializerRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { Textmodifier } from 'textmode.js';
+import type { ZIPFrameFormat, ZIPFrameSerializer } from './types';
+/** Resolves the thin adapter for one supported ZIP frame format. */
+export declare function createZIPFrameSerializerRegistry(textmodifier: Textmodifier): Record<ZIPFrameFormat, ZIPFrameSerializer>;

package/dist/types/exporters/zip/ZIPArchiveWriter.d.ts

@@ -0,0 +1,21 @@
+import type { ZIPEntryCompression } from './types';
+/** Streaming ZIP wrapper that retains only compressed archive output chunks. */
+export declare class ZIPArchiveWriter {
+    private readonly _archive;
+    private readonly _chunks;
+    private readonly _entryNames;
+    private readonly _modifiedAt;
+    private readonly _maxArchiveBytes;
+    private _state;
+    private _archiveBytes;
+    private _failure;
+    private _resolveFinal?;
+    private _rejectFinal?;
+    constructor(modifiedAt: Date, maxArchiveBytes?: number);
+    $addEntry(path: string, data: Uint8Array, compression: ZIPEntryCompression): Promise<void>;
+    $finalize(): Promise<Blob>;
+    $abort(reason?: unknown): void;
+    private _assertOpen;
+    private _validateEntryPath;
+    private _fail;
+}

package/dist/types/exporters/zip/ZIPExporter.d.ts

@@ -0,0 +1,32 @@
+import type { Textmodifier } from 'textmode.js';
+import { type FrameSequenceDriverLike, type PostDrawSubscription } from '../base';
+import type { ZIPExportOptions, ZIPFrameFormat, ZIPFrameSerializer } from './types';
+interface ZIPExporterDependencies {
+    createDriver?: () => FrameSequenceDriverLike;
+    createWriter?: (createdAt: Date) => ZIPArchiveWriterLike;
+    resolveSerializer?: (format: ZIPFrameFormat) => ZIPFrameSerializer;
+    now?: () => Date;
+}
+interface ZIPArchiveWriterLike {
+    $addEntry(path: string, data: Uint8Array, compression: 'store' | 'deflate'): Promise<void>;
+    $finalize(): Promise<Blob>;
+    $abort(reason?: unknown): void;
+}
+/** Captures deterministic frames and archives them in capture order. */
+export declare class ZIPExporter {
+    private readonly _textmodifier;
+    private readonly _registerPostDrawHook;
+    private readonly _dependencies;
+    constructor(_textmodifier: Textmodifier, _registerPostDrawHook: PostDrawSubscription, dependencies?: ZIPExporterDependencies);
+    $saveZIP(options: ZIPExportOptions): Promise<void>;
+    /** Generates a deterministic ZIP archive without initiating a download. */
+    $generateZIPBlob(options: ZIPExportOptions): Promise<Blob>;
+    private _export;
+    private _executeExport;
+    private _validateAndNormalize;
+    private _emitProgress;
+    private _progressFrameCount;
+    private _throwIfAborted;
+    private _yieldToBrowser;
+}
+export {};

package/dist/types/exporters/zip/ZIPManifest.d.ts

@@ -0,0 +1,12 @@
+import type { ZIPFrameFormat, ZIPFrameSequenceManifest } from './types';
+export declare function createZIPFramePath(rootStem: string, frameIndex: number, extension: string): string;
+export declare function createZIPManifest(options: {
+    createdAt: Date;
+    format: ZIPFrameFormat;
+    frameCount: number;
+    frameRate: number;
+    width: number;
+    height: number;
+    extension: string;
+}): ZIPFrameSequenceManifest;
+export declare function encodeZIPManifest(manifest: ZIPFrameSequenceManifest): Uint8Array;

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

@@ -0,0 +1,13 @@
+import type { ZIPExportErrorCode } from './types';
+/**
+ * Error raised by ZIP frame-sequence validation, capture, or archive creation.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/classes/ZIPExportError | ZIPExportError API reference}
+ */
+export declare class ZIPExportError extends Error {
+    readonly code: ZIPExportErrorCode;
+    readonly cause?: unknown;
+    constructor(code: ZIPExportErrorCode, message: string, cause?: unknown);
+}
+export declare function createZIPAbortError(cause?: unknown): ZIPExportError;
+export declare function normalizeZIPExportError(error: unknown): ZIPExportError;

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

@@ -0,0 +1,3 @@
+export { ZIPExporter } from './ZIPExporter';
+export { ZIPExportError } from './errors';
+export type { ZIPCaptureOptions, ZIPExportErrorCode, ZIPExportOptions, ZIPExportProgress, ZIPExportState, ZIPFrameFormat, ZIPFrameOptionsMap, } from './types';

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

@@ -0,0 +1,170 @@
+import type { PrepareExportFrame } from '../base';
+import type { ImageExportOptions } from '../image';
+import type { JSONExportOptions } from '../json';
+import type { SVGExportOptions } from '../svg';
+import type { TXTExportOptions } from '../txt';
+/**
+ * File format used for every frame in a ZIP frame-sequence export.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPFrameFormat | ZIPFrameFormat API reference}
+ */
+export type ZIPFrameFormat = 'png' | 'jpg' | 'webp' | 'svg' | 'json' | 'txt';
+/**
+ * Lifecycle state reported by a ZIP frame-sequence export.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportState | ZIPExportState API reference}
+ */
+export type ZIPExportState = 'capturing' | 'finalizing' | 'completed' | 'error';
+/**
+ * Machine-readable ZIP export failure category.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportErrorCode | ZIPExportErrorCode API reference}
+ */
+export type ZIPExportErrorCode = 'ZIP_EXPORT_INVALID_OPTIONS' | 'ZIP_EXPORT_ENCODING_UNSUPPORTED' | 'ZIP_EXPORT_TOO_LARGE' | 'ZIP_EXPORT_ABORTED' | 'ZIP_EXPORT_TIMEOUT' | 'ZIP_EXPORT_BUSY' | 'ZIP_EXPORT_DISPOSED' | 'ZIP_EXPORT_FAILED';
+/**
+ * Progress information emitted while ZIP frames are captured and archived.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress | ZIPExportProgress API reference}
+ */
+export interface ZIPExportProgress {
+    /**
+     * Current ZIP export state.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress#state | ZIPExportProgress.state API reference}
+     */
+    state: ZIPExportState;
+    /**
+     * Number of completed frame entries.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress#frameindex | ZIPExportProgress.frameIndex API reference}
+     */
+    frameIndex: number;
+    /**
+     * Total number of frame entries planned for the archive.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress#totalframes | ZIPExportProgress.totalFrames API reference}
+     */
+    totalFrames: number;
+    /**
+     * Normalized completed-frame ratio from `0` through `1`.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress#progress | ZIPExportProgress.progress API reference}
+     */
+    progress: number;
+    /**
+     * Optional failure message for an `error` event.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress#message | ZIPExportProgress.message API reference}
+     */
+    message?: string;
+}
+/**
+ * Options shared by all ZIP frame formats.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions | ZIPCaptureOptions API reference}
+ */
+export interface ZIPCaptureOptions {
+    /**
+     * Target archive filename, with or without `.zip`.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#filename | ZIPCaptureOptions.filename API reference}
+     */
+    filename?: string;
+    /**
+     * Number of frames to capture. Defaults to `300`.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#framecount | ZIPCaptureOptions.frameCount API reference}
+     */
+    frameCount?: number;
+    /**
+     * Deterministic sampling rate. Defaults to `60`.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#framerate | ZIPCaptureOptions.frameRate API reference}
+     */
+    frameRate?: number;
+    /**
+     * Prepares external state before each deterministic redraw.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#prepareframe | ZIPCaptureOptions.prepareFrame API reference}
+     */
+    prepareFrame?: PrepareExportFrame;
+    /**
+     * Cancels capture, serialization, or archive finalization.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#signal | ZIPCaptureOptions.signal API reference}
+     */
+    signal?: AbortSignal;
+    /**
+     * Receives capture and archive lifecycle updates.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions#onprogress | ZIPCaptureOptions.onProgress API reference}
+     */
+    onProgress?: (progress: ZIPExportProgress) => void;
+}
+/**
+ * Format-specific options forwarded to each existing still exporter.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPFrameOptionsMap | ZIPFrameOptionsMap API reference}
+ */
+export interface ZIPFrameOptionsMap {
+    png: Omit<ImageExportOptions, 'filename' | 'format'>;
+    jpg: Omit<ImageExportOptions, 'filename' | 'format'>;
+    webp: Omit<ImageExportOptions, 'filename' | 'format'>;
+    svg: Omit<SVGExportOptions, 'filename'>;
+    json: Omit<JSONExportOptions, 'filename'>;
+    txt: Omit<TXTExportOptions, 'filename'>;
+}
+/**
+ * Discriminated options for a deterministic ZIP frame-sequence export.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportOptions | ZIPExportOptions API reference}
+ */
+export type ZIPExportOptions = {
+    [F in ZIPFrameFormat]: ZIPCaptureOptions & {
+        format: F;
+        frameOptions?: ZIPFrameOptionsMap[F];
+    };
+}[ZIPFrameFormat];
+export interface ZIPGenerationOptions {
+    format: ZIPFrameFormat;
+    filename?: string;
+    frameCount: number;
+    frameRate: number;
+    frameOptions: unknown;
+    prepareFrame?: PrepareExportFrame;
+    signal?: AbortSignal;
+    onProgress?: (progress: ZIPExportProgress) => void;
+}
+export type ZIPEntryCompression = 'store' | 'deflate';
+export interface ZIPFrameSerializer {
+    readonly extension: `.${ZIPFrameFormat}`;
+    readonly compression: ZIPEntryCompression;
+    getDimensions(context: {
+        canvas: HTMLCanvasElement;
+        frameOptions: unknown;
+    }): {
+        width: number;
+        height: number;
+    };
+    serialize(context: {
+        canvas: HTMLCanvasElement;
+        frameOptions: unknown;
+        createdAt: Date;
+    }): Promise<Uint8Array>;
+}
+export interface ZIPFrameSequenceManifest {
+    schema: 'textmode.frame-sequence';
+    schemaVersion: '1.0.0';
+    generator: {
+        name: 'textmode.export.js';
+        version: string;
+    };
+    createdAt: string;
+    format: ZIPFrameFormat;
+    frameCount: number;
+    frameRate: number;
+    width: number;
+    height: number;
+    indexBase: 1;
+    filePattern: string;
+}