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

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

@@ -9,18 +9,5 @@ export declare class FileHandler {
      * @param blob The content to download
      * @param filename The filename to use for the downloaded file
      */
-    $downloadFile(blob: Blob, filename: string | undefined): void;
-    /**
-     * Validates and sanitizes filename for safety and compatibility
-     *
-     * @param filename The filename to validate
-     * @returns Sanitized filename
-     */
-    private _sanitizeFilename;
-    /**
-     * Generates a default filename with timestamp
-     *
-     * @returns Generated filename
-     */
-    private _generateDefaultFilename;
+    $downloadFile(blob: Blob, filename: string | undefined, extension?: `.${string}`): void;
 }

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

@@ -0,0 +1,6 @@
+/** Central filename normalization and canonical-extension policy. */
+export declare class FilenamePolicy {
+    $resolve(filename: string | undefined, extension: `.${string}`, createdAt?: Date): string;
+    $sanitizeStem(filename: string | undefined, createdAt?: Date, maximumBytes?: number): string;
+    $defaultStem(createdAt?: Date): string;
+}

package/dist/types/exporters/base/frame-sequence/ExclusiveCaptureGate.d.ts

@@ -0,0 +1,7 @@
+/** Rejects overlapping deterministic captures for one installed plugin instance. */
+export declare class ExclusiveCaptureGate {
+    private _active;
+    private _disposed;
+    acquire(): () => void;
+    dispose(): void;
+}

package/dist/types/exporters/{video/VideoFrameSchedule.d.ts → base/frame-sequence/FrameSchedule.d.ts}

@@ -1,8 +1,8 @@
-export interface VideoFrameTiming {
+export interface FrameTiming {
     startSeconds: number;
     centerSeconds: number;
     endSeconds: number;
     durationSeconds: number;
 }
 /** Produces one stable microsecond-rounded interval for an output frame. */
-export declare function videoFrameTiming(frameIndex: number, frameRate: number): VideoFrameTiming;
+export declare function frameTiming(frameIndex: number, frameRate: number): FrameTiming;

package/dist/types/exporters/{video/VideoFrameDriver.d.ts → base/frame-sequence/FrameSequenceDriver.d.ts}

@@ -1,13 +1,7 @@
 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.
- *
- * The visible textmode canvas remains untouched. Each presented frame is copied
- * into a staging canvas sized for the requested video output.
- */
-export declare class VideoFrameDriver {
+import type { FrameSequenceRenderOptions, FrameSequenceStagingSurface, PostDrawSubscription } from './types';
+/** Drives deterministic export frames through public textmode.js lifecycle APIs. */
+export declare class FrameSequenceDriver {
     readonly canvas: HTMLCanvasElement;
     private readonly _textmodifier;
     private readonly _registerPostDrawHook;
@@ -16,8 +10,8 @@ export declare class VideoFrameDriver {
     private _pendingFrame;
     private _syntheticFrameCount;
     private _syntheticMillis;
-    constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription, width: number, height: number);
-    $render(options: VideoRenderFrameOptions): Promise<void>;
+    constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription, stagingSurface?: FrameSequenceStagingSurface);
+    $render(options: FrameSequenceRenderOptions): Promise<void>;
     private _renderOneFrame;
     private _capturePendingFrame;
     private _createStagingCanvas;

package/dist/types/exporters/base/frame-sequence/errors.d.ts

@@ -0,0 +1,12 @@
+export type FrameSequenceErrorCode = 'FRAME_SEQUENCE_ABORTED' | 'FRAME_SEQUENCE_TIMEOUT' | 'FRAME_SEQUENCE_BUSY' | 'FRAME_SEQUENCE_DISPOSED';
+/** Internal error used by deterministic capture infrastructure. */
+export declare class FrameSequenceError extends Error {
+    readonly code: FrameSequenceErrorCode;
+    readonly cause?: unknown;
+    constructor(code: FrameSequenceErrorCode, message: string, cause?: unknown);
+}
+export declare function createFrameSequenceAbortError(): FrameSequenceError;
+export declare function createFrameSequenceTimeoutError(message: string, cause?: unknown): FrameSequenceError;
+export declare function createFrameSequenceBusyError(): FrameSequenceError;
+export declare function createFrameSequenceDisposedError(): FrameSequenceError;
+export declare function isFrameSequenceAbortError(error: unknown): boolean;

package/dist/types/exporters/base/frame-sequence/index.d.ts

@@ -0,0 +1,5 @@
+export { ExclusiveCaptureGate } from './ExclusiveCaptureGate';
+export { FrameSequenceDriver } from './FrameSequenceDriver';
+export { frameTiming } from './FrameSchedule';
+export { FrameSequenceError, createFrameSequenceAbortError, isFrameSequenceAbortError } from './errors';
+export type { FrameSequenceDriverLike, FrameSequenceRenderOptions, FrameSequenceStagingSurface, PostDrawSubscription, } from './types';

package/dist/types/exporters/base/frame-sequence/types.d.ts

@@ -0,0 +1,20 @@
+import type { PrepareExportFrame } from '../FramePreparation';
+export type PostDrawSubscription = (callback: () => void) => () => void;
+export interface FrameSequenceStagingSurface {
+    width: number;
+    height: number;
+}
+export interface FrameSequenceRenderOptions {
+    frameCount: number;
+    frameRate: number;
+    signal?: AbortSignal;
+    prepareFrame?: PrepareExportFrame;
+    onFrame(frame: {
+        frameIndex: number;
+        canvas: HTMLCanvasElement;
+    }): Promise<void> | void;
+}
+export interface FrameSequenceDriverLike {
+    readonly canvas: HTMLCanvasElement;
+    $render(options: FrameSequenceRenderOptions): Promise<void>;
+}

package/dist/types/exporters/base/frame-sequence/withAbortableTimeout.d.ts

@@ -0,0 +1 @@
+export declare function withAbortableFrameTimeout<T>(promise: Promise<T>, message: string, signal: AbortSignal | undefined, timeoutMs: number): Promise<T>;

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

@@ -1,6 +1,9 @@
 export { DataExtractor } from './DataExtractor';
 export { FileHandler } from './FileHandler';
+export { FilenamePolicy } from './FilenamePolicy';
 export { getEncodedGlyphValueFromColor, resolveGlyphByEncodedValue } from './CharacterResolver';
 export { createLayerTargetProvider, getLayerTargetId, getLayerTargetOptions, resolveLayerExportTarget, resolveLayerStackExportTargets, } from './LayerTarget';
 export type { LayerExportOptions, LayerTargetOption, LayerTargetProvider, ResolvedLayerExportTarget, ResolvedLayerStackExportTarget, } from './LayerTarget';
 export type { ExportFrameContext, PrepareExportFrame } from './FramePreparation';
+export { ExclusiveCaptureGate, FrameSequenceDriver, FrameSequenceError, createFrameSequenceAbortError, frameTiming, isFrameSequenceAbortError, } from './frame-sequence';
+export type { FrameSequenceDriverLike, FrameSequenceRenderOptions, FrameSequenceStagingSurface, PostDrawSubscription, } from './frame-sequence';

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

@@ -1,5 +1,5 @@
 import type { Textmodifier } from 'textmode.js';
-import { type PostDrawSubscription } from '../video/VideoFrameDriver';
+import { type PostDrawSubscription } from '../base';
 import type { GIFExportOptions } from './types';
 /** Deterministic, bounded-memory GIF exporter. */
 export declare class GIFExporter {

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

@@ -1,3 +1,2 @@
 export { GIFExporter } from './GIFExporter';
-export { GIFRecorder } from './GIFRecorder';
 export type { GIFExportOptions, GIFExportProgress, GIFGenerationOptions, GIFRecordingState } from './types';

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

@@ -103,9 +103,3 @@ export interface GIFGenerationOptions {
     signal?: AbortSignal;
     prepareFrame?: PrepareExportFrame;
 }
-export interface GIFFrame {
-    imageData: ImageData;
-    width: number;
-    height: number;
-    delayMs?: number;
-}

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

@@ -41,7 +41,7 @@ export declare class JSONExporter {
      * @param options Export options
      * @returns Structured JSON document for the selected layer or layer stack
      */
-    $generateJSONData(textmodifier: Textmodifier, options?: JSONExportOptions): TextmodeDocumentJSON;
+    $generateJSONData(textmodifier: Textmodifier, options?: JSONExportOptions, createdAt?: Date): TextmodeDocumentJSON;
     /**
      * Generates the serialized JSON string for the selected layer or layer stack.
      *
@@ -49,7 +49,7 @@ export declare class JSONExporter {
      * @param options Export options
      * @returns Serialized JSON string
      */
-    $generateJSONString(textmodifier: Textmodifier, options?: JSONExportOptions): string;
+    $generateJSONString(textmodifier: Textmodifier, options?: JSONExportOptions, createdAt?: Date): string;
     /**
      * Exports the generated JSON to a downloadable file.
      *

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,4 +1,4 @@
-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.
  *
@@ -325,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;
+}

package/dist/types/index.d.ts

@@ -27,6 +27,9 @@
  * @categoryDescription Video export
  * Capture deterministic frames and encode MP4 or WebM video with Mediabunny.
  *
+ * @categoryDescription ZIP frame-sequence export
+ * Capture deterministic PNG, JPEG, WebP, SVG, JSON, or TXT frames in a code-only ZIP archive.
+ *
  * @categoryDescription Layer data export
  * Export selected-layer text or vector data as TXT or SVG.
  *
@@ -47,6 +50,8 @@ export type { SVGExportOptions } from './exporters/svg';
 export type { TXTExportOptions } from './exporters/txt';
 export type { JSONExportColorMode, JSONExportOptions, JSONExportTarget, TextmodeDocumentJSON } from './exporters/json';
 export type { GIFExportOptions, GIFExportProgress } from './exporters/gif';
+export { ZIPExportError } from './exporters/zip';
+export type { ZIPCaptureOptions, ZIPExportErrorCode, ZIPExportOptions, ZIPExportProgress, ZIPExportState, ZIPFrameFormat, ZIPFrameOptionsMap, } from './exporters/zip';
 export type { VideoBitrateMode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoQuality, VideoQualityLevel, VideoSaveDestination, VideoRecordingState, } from './exporters/video';
 export type { LayerExportOptions } from './exporters/base';
 /**

package/dist/types/runtime/TextmodeExportController.d.ts

@@ -12,6 +12,7 @@ export declare class TextmodeExportController {
     readonly api: TextmodeExportAPI;
     private readonly _registerPostDrawHook;
     private readonly _activeOperations;
+    private readonly _captureGate;
     private readonly _overlayController;
     private readonly _stopOverlayRefresh;
     private _disposed;
@@ -19,6 +20,8 @@ export declare class TextmodeExportController {
     dispose(): void;
     private _createOverlayAPI;
     private _runOperation;
+    private _runCaptureOperation;
+    private _emitZIPGateError;
     private _assertLive;
 }
 export {};

package/dist/types/types.d.ts

@@ -4,6 +4,7 @@ import type { SVGExportOptions } from './exporters/svg';
 import type { GIFExportOptions } from './exporters/gif';
 import type { VideoExportOptions } from './exporters/video';
 import type { JSONExportOptions, TextmodeDocumentJSON } from './exporters/json';
+import type { ZIPExportOptions } from './exporters/zip';
 /**
  * Default TXT export fields controlled by the export overlay.
  *
@@ -503,4 +504,50 @@ export interface TextmodeExportAPI {
      * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeExportAPI#tovideoblob | TextmodeExportAPI.toVideoBlob API reference}
      */
     toVideoBlob(options?: VideoExportOptions): Promise<Blob>;
+    /**
+     * Captures and downloads a deterministic frame sequence as a ZIP archive.
+     *
+     * The archive contains a versioned manifest followed by one-based, zero-padded frame files. ZIP export is available
+     * through code only and does not appear in the export overlay.
+     *
+     * @param options Required archive format, deterministic capture controls, and per-frame exporter options.
+     * @returns A promise that resolves after the archive download is initiated.
+     * @throws {Error} When validation, capture, serialization, archive writing, or download fails.
+     *
+     * @category ZIP frame-sequence export
+     *
+     * @example
+     * ```ts
+     * await t.saveZip({
+     *     format: 'png',
+     *     filename: 'orbit-frames',
+     *     frameCount: 120,
+     *     frameRate: 30,
+     *     frameOptions: { scale: 2 },
+     * });
+     * ```
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeExportAPI#savezip | TextmodeExportAPI.saveZip API reference}
+     */
+    saveZip(options: ZIPExportOptions): Promise<void>;
+    /**
+     * Captures a deterministic frame sequence as an in-memory ZIP archive without downloading it.
+     *
+     * Peak memory includes the completed ZIP because this method returns a `Blob`; individual uncompressed frame
+     * payloads are serialized and released sequentially.
+     *
+     * @param options Required archive format, deterministic capture controls, and per-frame exporter options.
+     * @returns The completed `application/zip` blob.
+     * @throws {Error} When validation, capture, serialization, archive writing, or cancellation fails.
+     *
+     * @category ZIP frame-sequence export
+     *
+     * @example
+     * ```ts
+     * const archive = await t.toZipBlob({ format: 'svg', frameCount: 60, frameRate: 24 });
+     * ```
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeExportAPI#tozipblob | TextmodeExportAPI.toZipBlob API reference}
+     */
+    toZipBlob(options: ZIPExportOptions): Promise<Blob>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "textmode.export.js",
-	"version": "1.8.1",
-	"description": "Export plugin for textmode.js - Save your creations as images, GIFs, videos, SVG, JSON, and plain text.",
+	"version": "1.9.0-beta.1",
+	"description": "Export plugin for textmode.js - Save images, GIFs, videos, SVG, JSON, text, and ZIP frame sequences.",
 	"type": "module",
 	"devEngines": {
 		"runtime": {
@@ -63,6 +63,7 @@
 		"textmode.js": "^0.18.0"
 	},
 	"dependencies": {
+		"fflate": "0.8.3",
 		"gifenc": "^1.0.1",
 		"mediabunny": "1.55.2"
 	},
@@ -94,6 +95,8 @@
 		"png",
 		"jpg",
 		"webp",
+		"zip",
+		"frame-sequence",
 		"creative-coding",
 		"canvas"
 	],

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

@@ -1,23 +0,0 @@
-import type { PostDrawSubscription } from '../video/VideoFrameDriver';
-import type { GIFExportProgress, GIFFrame, GIFGenerationOptions } from './types';
-/**
- * Records frames from a canvas for GIF generation.
- * Captures frames at specified intervals using textmode.js post-draw hooks.
- */
-export declare class GIFRecorder {
-    /** Reusable canvas for frame scaling */
-    private _canvas?;
-    /** Reusable 2D context for frame scaling */
-    private _ctx?;
-    /**
-     * Records a sequence of frames from the provided canvas.
-     *
-     * @param canvas - Source canvas to capture frames from
-     * @param options - Frame generation options (rate, count, scale)
-     * @param registerPostDrawHook - Hook registration function from textmode.js API
-     * @param onProgress - Optional callback for recording progress updates
-     * @returns Promise resolving to array of captured frames
-     * @throws {Error} If frame capture fails
-     */
-    $record(canvas: HTMLCanvasElement, options: GIFGenerationOptions, registerPostDrawHook: PostDrawSubscription, onProgress?: (progress: GIFExportProgress) => void): Promise<GIFFrame[]>;
-}