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

package/dist/types/index.d.ts

@@ -5,15 +5,41 @@
  *
  * ## Choose an output
  *
- * 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.
+ * Use **canvas capture** for the rendered image on screen: PNG, JPEG, WebP,
+ * GIF, and video preserve compositing, filters, shaders, and post-processing.
+ * Use **layer data export** when the artwork should stay editable or machine
+ * readable: TXT and SVG read from the selected layer, while JSON can describe
+ * either the selected layer or the full layer stack.
  *
  * 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).
+ *
+ * @categoryDescription Workflow
+ * Install the plugin and use the export helpers added to a textmode.js sketch.
+ *
+ * @categoryDescription Canvas capture
+ * Export a still image from the rendered canvas.
+ *
+ * @categoryDescription GIF export
+ * Capture deterministic frames and encode an animated GIF.
+ *
+ * @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.
+ *
+ * @categoryDescription JSON document data
+ * Export selected-layer or full-stack document data as JSON.
+ *
+ * @categoryDescription Overlay
+ * Configure and control the built-in export overlay.
+ *
+ * @showCategories
  */
 import type { TextmodePlugin } from 'textmode.js';
 import './augmentations';
@@ -24,7 +50,9 @@ 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 type { VideoBitrateMode, VideoBitratePreset, VideoContentHint, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, VideoRecordingState, } from './exporters/video';
+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';
 /**
  * Default export plugin instance for the standard textmode.js workflow.

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

@@ -3,11 +3,9 @@ import type { BladeConfig } from './Blade';
 import { Blade } from './Blade';
 export declare class VideoBlade extends Blade<VideoExportOptions> {
     private formatSelect;
-    private bitrateSelect;
+    private qualitySelect;
     private frameRateInput;
     private frameCountInput;
-    private bitrateModeSelect;
-    private latencyModeSelect;
     private hardwareAccelerationSelect;
     private keyFrameIntervalInput;
     private transparencyInput;
@@ -27,13 +25,12 @@ export declare class VideoBlade extends Blade<VideoExportOptions> {
     private syncStatus;
     private resolvePlannedFrameCount;
     private applyDefaults;
-    private resolveBitratePreset;
-    private readonly handleBitrateChange;
+    private resolveQuality;
+    private readonly handleQualityChange;
     private readonly handleEstimateChange;
     private syncReadyStatus;
     private readonly handleFormatChange;
     private syncOutputEstimate;
-    private formatBytes;
     protected _onUnmount(): void;
     private syncTransparencyAvailability;
 }

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

@@ -2,7 +2,7 @@ import type { ImageExportOptions } from '../exporters/image';
 import type { TXTExportOptions } from '../exporters/txt';
 import type { SVGExportOptions } from '../exporters/svg';
 import type { GIFExportOptions } from '../exporters/gif';
-import type { VideoBitratePreset, VideoExportOptions } from '../exporters/video';
+import type { VideoExportOptions } from '../exporters/video';
 import type { JSONExportOptions } from '../exporters/json';
 export type ExportFormat = 'txt' | 'json' | 'image' | 'gif' | 'video' | 'svg';
 export type ExportOptionsMap = {
@@ -18,9 +18,7 @@ export type JSONOverlayDefaults = Pick<JSONExportOptions, 'target' | 'pretty' |
 export type ImageOverlayDefaults = Pick<ImageExportOptions, 'format' | 'scale'>;
 export type SVGOverlayDefaults = Pick<SVGExportOptions, 'includeBackgroundRectangles' | 'drawMode' | 'strokeWidth'>;
 export type GIFOverlayDefaults = Pick<GIFExportOptions, 'frameCount' | 'frameRate' | 'scale' | 'repeat'>;
-export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'bitrateMode' | 'latencyMode' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'> & {
-    bitrate?: VideoBitratePreset;
-};
+export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'quality' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'>;
 /**
  * Curated default options for every export format.
  *

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

@@ -2,8 +2,9 @@ import type { ImageExportOptions } from './exporters/image';
 import type { TXTExportOptions } from './exporters/txt';
 import type { SVGExportOptions } from './exporters/svg';
 import type { GIFExportOptions } from './exporters/gif';
-import type { VideoBitratePreset, VideoExportOptions } from './exporters/video';
+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.
  *
@@ -51,9 +52,7 @@ export type GIFOverlayDefaults = Pick<GIFExportOptions, 'frameCount' | 'frameRat
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoOverlayDefaults | VideoOverlayDefaults API reference}
  */
-export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'bitrateMode' | 'latencyMode' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'> & {
-    bitrate?: VideoBitratePreset;
-};
+export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'quality' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'>;
 /**
  * Per-format default options used to seed the overlay UI inputs at mount time
  * and after a {@link ExportOverlayController.resetDefaults} call.
@@ -463,15 +462,29 @@ export interface TextmodeExportAPI {
      *
      * @example
      * ```ts
-     * await t.saveVideo({ frameCount: 240, frameRate: 60, filename: 'capture' });
+     * // Mediabunny's qualitative quality levels produce content-dependent file sizes.
      * await t.saveVideo({
      *     format: 'webm',
-     *     bitrate: 'high',
-     *     bitrateMode: 'variable',
-     *     latencyMode: 'quality',
-     *     keyFrameInterval: 2,
+     *     quality: 'very-high',
+     *     frameCount: 240,
+     *     frameRate: 60,
+     *     filename: 'high-quality-capture',
+     * });
+     *
+     * // Request a target bitrate and rate-control mode.
+     * await t.saveVideo({
+     *     quality: { bitrate: 8_000_000, bitrateMode: 'variable' },
+     *     frameCount: 240,
+     *     frameRate: 60,
+     *     filename: 'target-bitrate-capture',
+     * });
+     *
+     * // Stream directly to a user-selected file when the browser supports it.
+     * await t.saveVideo({
+     *     destination: 'file-system',
+     *     quality: 'high',
      *     frameCount: 240,
-     *     filename: 'capture',
+     *     frameRate: 60,
      * });
      * ```
      *
@@ -479,7 +492,9 @@ export interface TextmodeExportAPI {
      */
     saveVideo(options?: VideoExportOptions): Promise<void>;
     /**
-     * Generates a video blob without downloading it.
+     * Generates an in-memory video blob without downloading it.
+     *
+     * `destination` is only used by {@link saveVideo}; this method always buffers and returns a `Blob`.
      *
      * @example
      * ```ts
@@ -489,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.0",
-	"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,8 +63,9 @@
 		"textmode.js": "^0.18.0"
 	},
 	"dependencies": {
+		"fflate": "0.8.3",
 		"gifenc": "^1.0.1",
-		"mediabunny": "^1.52.3"
+		"mediabunny": "1.55.2"
 	},
 	"devDependencies": {
 		"@textmode/build": "^0.1.0",
@@ -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[]>;
-}