textmode.export.js 1.8.0 → 1.9.0-beta.1

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

@@ -1,45 +1,83 @@
-import type { PrepareExportFrame } from '../base';
+import type { FrameSequenceDriverLike, FrameSequenceRenderOptions, PrepareExportFrame } from '../base';
 /**
- * Lifecycle state reported while a video export is being prepared, recorded, encoded, or completed.
+ * High-level lifecycle state reported while a video export is captured, encoded, or completed.
  *
- * @category Animation export
+ * @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';
 /**
- * More granular phase information for progress UIs that need to distinguish setup, rendering, and finalization.
+ * Detailed phase information for progress UIs that distinguish capability probing, frame capture, and output.
  *
- * `rendering` is retained for 1.5.x compatibility. Current deterministic video capture emits `capturing`.
+ * Current exports emit `probing`, `capturing`, and either `writing` for streamed file-system output or `finalizing`
+ * for buffered output. `rendering`, `encoding`, and `draining` remain available for compatibility with older progress
+ * producers.
  *
- * @category Animation export
+ * @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';
 export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
 /**
- * Subjective bitrate preset used when an exact bits-per-second value is not supplied.
+ * Qualitative video quality level matching Mediabunny's five native levels.
  *
- * Higher presets request higher constant perceptual quality from Mediabunny. The `ultra` preset requests quantizer
- * zero with a frame-rate-aware bitrate fallback and should be described as near-lossless, never mathematically
- * lossless. For exact bitrate control, pass a numeric `bitrate` value in bits per second instead.
+ * 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 Animation export
+ * @category Video export
  *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitratePreset | VideoBitratePreset API reference}
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQualityLevel | VideoQualityLevel API reference}
  */
-export type VideoBitratePreset = 'low' | 'medium' | 'high' | 'ultra';
+export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
 /**
- * Hint for the encoder's content-aware rate control.
+ * Video compression policy passed to Mediabunny.
  *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoContentHint | VideoContentHint API reference}
+ * Use a named {@link VideoQualityLevel} for content-dependent qualitative encoding. Use the object form to request a
+ * positive target bitrate in bits per second and, optionally, constant or variable allocation. When `bitrateMode` is
+ * omitted, Mediabunny defaults bitrate-based encoding to `'variable'`. A target bitrate guides the encoder but does
+ * not guarantee an exact final file size.
+ *
+ * @example Named qualitative quality
+ * ```ts
+ * await t.saveVideo({ quality: 'very-high' });
+ * ```
+ *
+ * @example Target bitrate with constant allocation
+ * ```ts
+ * 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 VideoContentHint = '' | 'motion' | 'detail' | 'text';
+export type VideoQuality = VideoQualityLevel | {
+    bitrate: number;
+    bitrateMode?: VideoBitrateMode;
+};
 /**
- * Video container format written by `saveVideo`.
+ * Destination policy used by `saveVideo()`.
+ *
+ * - `'download'` is the default. The complete video is buffered in memory before a browser download begins.
+ * - `'file-system'` opens the browser's save picker and streams encoded chunks directly to the selected file. It
+ *   requires the File System Access API and rejects with `VIDEO_EXPORT_UNSUPPORTED` when that API is unavailable.
+ *
+ * This setting does not affect `toVideoBlob()`, which always returns an in-memory `Blob`.
  *
- * @category Animation export
+ * @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';
+/**
+ * Video container format produced by `saveVideo()` and `toVideoBlob()`.
+ *
+ * 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}
  */
@@ -52,23 +90,13 @@ 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
+ * 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';
-/**
- * Encoder scheduling mode.
- *
- * - `'quality'`: prioritizes complete, stable export output. Mediabunny notes that this mode prevents dropped frames.
- * - `'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';
 /**
  * WebCodecs hardware acceleration preference.
  *
@@ -78,34 +106,34 @@ 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
+ * @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';
-export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNSUPPORTED' | 'VIDEO_EXPORT_ABORTED' | 'VIDEO_EXPORT_TIMEOUT' | 'VIDEO_EXPORT_FAILED' | 'VIDEO_TRANSPARENCY_UNSUPPORTED' | 'VIDEO_DIMENSIONS_UNSUPPORTED' | 'VIDEO_OUTPUT_TOO_LARGE';
+export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNSUPPORTED' | 'VIDEO_EXPORT_ABORTED' | 'VIDEO_EXPORT_TIMEOUT' | 'VIDEO_EXPORT_FAILED' | 'VIDEO_TRANSPARENCY_UNSUPPORTED' | 'VIDEO_DIMENSIONS_UNSUPPORTED';
 /**
- * Progress information emitted during the video export process.
+ * Progress information emitted while a deterministic video is probed, captured, and written.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
     /**
-     * Current state of the recording process.
+     * Current high-level export state.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#state | VideoExportProgress.state API reference}
      */
     state: VideoRecordingState;
     /**
-     * Current export phase for newer progress UIs.
+     * Current detailed phase. See {@link VideoExportPhase} for current and compatibility-only values.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#phase | VideoExportProgress.phase API reference}
      */
     phase?: VideoExportPhase;
     /**
-     * Number of frames that have been recorded so far.
+     * Number of frames captured so far.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#frameindex | VideoExportProgress.frameIndex API reference}
      */
@@ -123,7 +151,9 @@ export type VideoExportProgress = {
      */
     totalFrames?: number;
     /**
-     * Export completion ratio between `0` and `1`.
+     * Normalized frame-capture completion ratio between `0` and `1`.
+     *
+     * Final writing or muxing may still be in progress when this value reaches `1`.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#progress | VideoExportProgress.progress API reference}
      */
@@ -135,22 +165,34 @@ export type VideoExportProgress = {
      */
     message?: string;
     /**
-     * The rate-control path selected by the browser, when known.
+     * Effective codec family selected after capability probing (`avc`, `vp9`, or `vp8`).
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codec | VideoExportProgress.codec API reference}
+     */
+    codec?: VideoCodec;
+    /**
+     * Effective coded width in pixels.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codedwidth | VideoExportProgress.codedWidth API reference}
+     */
+    codedWidth?: number;
+    /**
+     * Effective coded height in pixels.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#ratecontrol | VideoExportProgress.rateControl API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codedheight | VideoExportProgress.codedHeight API reference}
      */
-    rateControl?: 'quantizer' | 'bitrate-fallback' | 'bitrate';
+    codedHeight?: number;
     /**
-     * Conservative output-size estimate in bytes, when available.
+     * Exact output frame rate passed to the muxer.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#estimatedbytes | VideoExportProgress.estimatedBytes API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#framerate | VideoExportProgress.frameRate API reference}
      */
-    estimatedBytes?: number;
+    frameRate?: number;
 };
 /**
- * Options for exporting the textmode content to video format.
+ * Options for capturing deterministic textmode frames as MP4 or WebM video.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
@@ -180,39 +222,23 @@ export type VideoExportOptions = {
      */
     frameRate?: number;
     /**
-     * Target bitrate in bits per second or a quality preset. Defaults to `'medium'`.
+     * Video quality policy. Defaults to `'medium'`.
      *
-     * String values request constant-quality encoding through Mediabunny. `low`, `medium`, and `high` map to the
-     * upstream `medium`, `high`, and `very-high` quality levels; `ultra` requests quantizer zero and may create very
-     * large files. Numeric values remain exact bits-per-second targets and are wrapped in Mediabunny `Quality`.
+     * Named levels map one-to-one to Mediabunny's qualitative levels and produce content-dependent file sizes. Use the
+     * object form to request a positive target bitrate in bits per second and an optional bitrate mode.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitrate | VideoExportOptions.bitrate API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#quality | VideoExportOptions.quality API reference}
      */
-    bitrate?: number | VideoBitratePreset;
+    quality?: VideoQuality;
     /**
-     * Bitrate allocation mode for numeric bitrates and quality fallback paths. Defaults to `'variable'`.
-     *
-     * Use `'variable'` for most exports so simple frames can compress efficiently and complex frames can receive more
-     * bits. Use `'constant'` only when a steadier data rate is more important than compression efficiency.
+     * Save destination used by `saveVideo()`. Defaults to `'download'`.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitratemode | VideoExportOptions.bitrateMode API reference}
-     */
-    bitrateMode?: VideoBitrateMode;
-    /**
-     * Content hint passed to the native video encoder. Defaults to `'text'`.
+     * `'file-system'` opens a save picker and streams directly to the selected file when the File System Access API is
+     * available. `toVideoBlob()` always returns an in-memory blob and does not use this setting.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#contenthint | VideoExportOptions.contentHint API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#destination | VideoExportOptions.destination API reference}
      */
-    contentHint?: VideoContentHint;
-    /**
-     * Encoder latency mode. Defaults to `'quality'`.
-     *
-     * Use `'quality'` for deterministic exports; it prioritizes completed output and avoids dropped frames. Use
-     * `'realtime'` only for low-latency use cases where dropped frames are acceptable.
-     *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#latencymode | VideoExportOptions.latencyMode API reference}
-     */
-    latencyMode?: VideoLatencyMode;
+    destination?: VideoSaveDestination;
     /**
      * WebCodecs hardware acceleration hint. Defaults to `'no-preference'`.
      *
@@ -251,7 +277,7 @@ export type VideoExportOptions = {
      */
     prepareFrame?: PrepareExportFrame;
     /**
-     * When true, attempts to preserve alpha data in WebM recordings. MP4 exports reject this option.
+     * When `true`, attempts to preserve alpha data in WebM recordings. MP4 exports reject this option.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#transparent | VideoExportOptions.transparent API reference}
      */
@@ -268,22 +294,13 @@ export type VideoExportOptions = {
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#debuglogging | VideoExportOptions.debugLogging API reference}
      */
     debugLogging?: boolean;
-    /**
-     * Allows `toVideoBlob()` to retain its in-memory contract above the safe 100 MB default.
-     *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#allowlargeinmemory | VideoExportOptions.allowLargeInMemory API reference}
-     */
-    allowLargeInMemory?: boolean;
 };
 export interface VideoGenerationOptions {
     filename?: string;
     format: VideoExportFormat;
     frameRate: number;
     frameCount: number;
-    bitrate: number | VideoBitratePreset;
-    bitrateMode: VideoBitrateMode;
-    contentHint?: VideoContentHint;
-    latencyMode: VideoLatencyMode;
+    quality: VideoQuality;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;
     pixelDensity: number;
@@ -291,7 +308,6 @@ export interface VideoGenerationOptions {
     height: number;
     transparent: boolean;
     debugLogging: boolean;
-    allowLargeInMemory?: boolean;
     signal?: AbortSignal;
     prepareFrame?: PrepareExportFrame;
 }
@@ -300,14 +316,7 @@ export interface VideoEncodingPlan {
     extension: '.webm' | '.mp4';
     mimeType: string;
     codec: VideoCodec;
-    bitrate: number;
-    bitrateMode: VideoBitrateMode;
-    qualityPreset: VideoBitratePreset | null;
-    rateControlIntent: 'bitrate' | 'constant-quality' | 'ultra';
-    qualityLevel?: 'medium' | 'high' | 'very-high';
-    contentHint: VideoContentHint;
-    estimatedBytes: number;
-    latencyMode: VideoLatencyMode;
+    quality: VideoQuality;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;
     frameRate: number;
@@ -316,17 +325,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,14 @@
+import type { ZIPExportErrorCode } from './types';
+/**
+ * Error raised by ZIP frame-sequence validation, capture, or archive creation.
+ *
+ * @category ZIP frame-sequence export
+ * @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,177 @@
+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.
+ *
+ * @category 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.
+ *
+ * @category 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.
+ *
+ * @category ZIP frame-sequence export
+ * @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.
+ *
+ * @category ZIP frame-sequence export
+ * @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.
+ *
+ * @category ZIP frame-sequence export
+ * @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.
+ *
+ * @category ZIP frame-sequence export
+ * @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.
+ *
+ * @category 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;
+}