textmode.export.js 1.8.0 → 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/FramePreparation.d.ts

@@ -2,6 +2,13 @@
 export interface ExportFrameContext {
     frameIndex: number;
     frameCount: number;
+    /** Left edge of the output-frame interval. Alias of `timeSeconds`. */
+    startSeconds: number;
+    /** Center of the output-frame interval; use this to sample external media. */
+    centerSeconds: number;
+    /** Exclusive right edge of the output-frame interval. */
+    endSeconds: number;
+    /** @deprecated Use `startSeconds`. */
     timeSeconds: number;
     frameRate: number;
     signal?: AbortSignal;

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/base/frame-sequence/FrameSchedule.d.ts

@@ -0,0 +1,8 @@
+export interface FrameTiming {
+    startSeconds: number;
+    centerSeconds: number;
+    endSeconds: number;
+    durationSeconds: number;
+}
+/** Produces one stable microsecond-rounded interval for an output frame. */
+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

@@ -1,21 +1,21 @@
 import type { PrepareExportFrame } from '../base';
 export type GIFRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
 /**
- * Progress information emitted during the GIF export process.
+ * Progress information emitted while deterministic frames are captured and encoded as an animated GIF.
  *
- * @category Animation export
+ * @category GIF export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress | GIFExportProgress API reference}
  */
 export type GIFExportProgress = {
     /**
-     * Current state of the recording process.
+     * Current GIF capture or encoding state.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress#state | GIFExportProgress.state API reference}
      */
     state: 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
     /**
-     * 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/GIFExportProgress#frameindex | GIFExportProgress.frameIndex API reference}
      */
@@ -34,9 +34,9 @@ export type GIFExportProgress = {
     message?: string;
 };
 /**
- * Options for exporting the textmode content to GIF format.
+ * Options for capturing deterministic textmode frames as an animated GIF.
  *
- * @category Animation export
+ * @category GIF export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions | GIFExportOptions API reference}
  */
@@ -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/VideoEncodingPolicy.d.ts

@@ -1,20 +1,3 @@
-import type { VideoBitrateMode, VideoCodec, VideoContentHint, VideoEncodingPlan, VideoGenerationOptions } from './types';
-export declare const MAX_SAFE_IN_MEMORY_VIDEO_BYTES = 100000000;
-export declare const ULTRA_FALLBACK_BITS_PER_PIXEL_PER_FRAME = 0.5;
-export type VideoQualityDescriptor = {
-    kind: 'named';
-    level: 'medium' | 'high' | 'very-high';
-} | {
-    kind: 'bitrate';
-    bitrate: number;
-    bitrateMode: VideoBitrateMode;
-} | {
-    kind: 'ultra';
-    bitrate: number;
-};
-export declare function resolveUltraFallbackBitrate(width: number, height: number, frameRate: number): number;
-export declare function estimateVideoOutputBytes(bitrate: number, frameCount: number, frameRate: number): number;
-export declare function getVideoQualityDescriptor(plan: VideoEncodingPlan): VideoQualityDescriptor;
-export declare function normalizeVideoContentHint(value: VideoContentHint | undefined): VideoContentHint;
+import type { VideoCodec, VideoEncodingPlan, VideoGenerationOptions } from './types';
+/** Resolves product-level format constraints independently of encoder probing. */
 export declare function createVideoEncodingPlan(options: VideoGenerationOptions, codec?: VideoCodec): VideoEncodingPlan;
-export declare function assertVideoOutputFitsMemory(plan: VideoEncodingPlan, allowLargeInMemory: boolean): void;

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 {
@@ -15,12 +15,10 @@ export declare class VideoExporter {
     private _applyDefaultOptions;
     private _positiveInteger;
     private _positiveNumber;
-    private _bitrate;
-    private _bitrateMode;
-    private _contentHint;
-    private _latencyMode;
+    private _quality;
+    private _isBitrateMode;
     private _hardwareAcceleration;
     private _keyFrameInterval;
     private _currentPixelDensity;
-    private _withExtension;
+    private _createFileSystemDestination;
 }

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

@@ -2,10 +2,11 @@ import { type StreamTargetChunk } from 'mediabunny';
 import type { VideoExportProgress, VideoFrameDriverLike, VideoGenerationOptions } from './types';
 export type VideoOutputDestination = {
     kind: 'blob';
-    allowLargeInMemory: boolean;
 } | {
     kind: 'stream';
     writable: WritableStream<StreamTargetChunk>;
+    /** Releases a destination selected before encoder probing starts. */
+    abort?: (reason?: unknown) => Promise<void>;
 };
 /** Records deterministic textmode frames through WebCodecs and muxes them with Mediabunny. */
 export declare class VideoRecorder {

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/index.d.ts

@@ -1,2 +1,2 @@
 export { VideoExportError } from './errors';
-export type { VideoBitrateMode, VideoBitratePreset, VideoContentHint, VideoEncodingPlan, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoFrameDriverLike, VideoHardwareAcceleration, VideoLatencyMode, VideoExportProgress, VideoGenerationOptions, VideoRecordingState, VideoRenderFrameOptions, } from './types';
+export type { VideoBitrateMode, VideoEncodingPlan, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoFrameDriverLike, VideoHardwareAcceleration, VideoQuality, VideoQualityLevel, VideoSaveDestination, VideoExportProgress, VideoGenerationOptions, VideoRecordingState, VideoRenderFrameOptions, } from './types';