textmode.export.js 1.7.2 → 1.8.0-beta.2

package/dist/types/augmentations/textmode.d.ts

@@ -2,7 +2,7 @@
  * TypeScript augmentation for `textmode.export.js`.
  */
 import type { TextmodeExportAPI } from '../types';
-declare module 'textmode.js' {
-    interface Textmodifier extends TextmodeExportAPI {
+declare module 'textmode.js/addon' {
+    interface TextmodifierExtensions extends TextmodeExportAPI {
     }
 }

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

@@ -0,0 +1,20 @@
+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;
+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,30 +1,27 @@
 import type { Textmodifier } from 'textmode.js';
 import { type PostDrawSubscription } from './VideoFrameDriver';
 import type { VideoExportOptions } from './types';
-/**
- * Main video exporter for the textmode.js library.
- */
+/** Main video exporter for the textmode.js library. */
 export declare class VideoExporter {
     private readonly _recorder;
     private readonly _textmodifier;
     private readonly _registerPostDrawHook;
     constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription);
-    /**
-     * Captures deterministic frames and saves them as a video file.
-     *
-     * @param options Export options
-     */
+    /** Captures deterministic frames and saves them as a video file. */
     $saveVideo(options?: VideoExportOptions): Promise<void>;
     /** Generates a deterministic video without initiating a download. */
     $generateVideoBlob(options?: VideoExportOptions): Promise<Blob>;
+    private _record;
     private _applyDefaultOptions;
     private _positiveInteger;
     private _positiveNumber;
     private _bitrate;
     private _bitrateMode;
+    private _contentHint;
     private _latencyMode;
     private _hardwareAcceleration;
     private _keyFrameInterval;
     private _currentPixelDensity;
+    private _filePicker;
     private _withExtension;
 }

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

@@ -1,16 +1,19 @@
+import { type StreamTargetChunk } from 'mediabunny';
 import type { VideoExportProgress, VideoFrameDriverLike, VideoGenerationOptions } from './types';
-/**
- * Records deterministic textmode frames through WebCodecs and muxes them with Mediabunny.
- */
+export type VideoOutputDestination = {
+    kind: 'blob';
+    allowLargeInMemory: boolean;
+} | {
+    kind: 'stream';
+    writable: WritableStream<StreamTargetChunk>;
+};
+/** Records deterministic textmode frames through WebCodecs and muxes them with Mediabunny. */
 export declare class VideoRecorder {
-    $record(options: VideoGenerationOptions, frameDriver: VideoFrameDriverLike, onProgress?: (progress: VideoExportProgress) => void): Promise<Blob>;
-    private _drainIfNeeded;
-    private _drainEncodes;
-    private _shouldYieldAfterCaptureFrame;
-    private _yieldToBrowser;
+    $record(options: VideoGenerationOptions, frameDriver: VideoFrameDriverLike, onProgress?: (progress: VideoExportProgress) => void, destination?: VideoOutputDestination): Promise<Blob | undefined>;
     private _createEncodingPlan;
+    private _createQuality;
     private _assertWebCodecsAvailable;
-    private _resolveBitrate;
+    private _awaitWithAbort;
     private _throwIfAborted;
     private _emitProgress;
     private _normalizeError;

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

@@ -5,5 +5,6 @@ export declare class VideoExportError extends Error {
     constructor(code: VideoExportErrorCode, message: string, cause?: unknown);
 }
 export declare function createAbortError(): VideoExportError;
+export declare function normalizeFilePickerError(error: unknown): VideoExportError | undefined;
 export declare function createTimeoutError(message: string, cause?: unknown): VideoExportError;
 export declare function isAbortError(error: unknown): boolean;

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

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

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

@@ -16,20 +16,26 @@ export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportPhase | VideoExportPhase API reference}
  */
-export type VideoExportPhase = 'probing' | 'rendering' | 'capturing' | 'encoding' | 'draining' | 'finalizing';
+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.
  *
- * Higher presets produce larger files with more detail. Each preset maps to a fixed bits-per-pixel budget
- * (bits per pixel per second), so a given preset resolves to the same bitrate regardless of the export
- * frame rate. For exact control, pass a numeric `bitrate` value in bits per second instead.
+ * 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.
  *
  * @category Animation export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitratePreset | VideoBitratePreset API reference}
  */
-export type VideoBitratePreset = 'low' | 'medium' | 'high';
+export type VideoBitratePreset = 'low' | 'medium' | 'high' | 'ultra';
+/**
+ * Hint for the encoder's content-aware rate control.
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoContentHint | VideoContentHint API reference}
+ */
+export type VideoContentHint = '' | 'motion' | 'detail' | 'text';
 /**
  * Video container format written by `saveVideo`.
  *
@@ -77,7 +83,7 @@ export type VideoLatencyMode = 'quality' | 'realtime';
  * @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';
+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';
 /**
  * Progress information emitted during the video export process.
  *
@@ -128,6 +134,18 @@ export type VideoExportProgress = {
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#message | VideoExportProgress.message API reference}
      */
     message?: string;
+    /**
+     * The rate-control path selected by the browser, when known.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#ratecontrol | VideoExportProgress.rateControl API reference}
+     */
+    rateControl?: 'quantizer' | 'bitrate-fallback' | 'bitrate';
+    /**
+     * Conservative output-size estimate in bytes, when available.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#estimatedbytes | VideoExportProgress.estimatedBytes API reference}
+     */
+    estimatedBytes?: number;
 };
 /**
  * Options for exporting the textmode content to video format.
@@ -164,16 +182,15 @@ export type VideoExportOptions = {
     /**
      * Target bitrate in bits per second or a quality preset. Defaults to `'medium'`.
      *
-     * Bitrate controls how much encoded data is available per second of video. Higher values can preserve more detail
-     * in noisy or fast-changing sketches, but create larger files. Presets resolve to a fixed bits-per-pixel budget
-     * from the export dimensions only, so a given preset targets the same bitrate regardless of the frame rate.
-     * Numeric values are passed directly to the encoder.
+     * 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`.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitrate | VideoExportOptions.bitrate API reference}
      */
     bitrate?: number | VideoBitratePreset;
     /**
-     * Encoder bitrate allocation mode. Defaults to `'variable'`.
+     * 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.
@@ -181,6 +198,12 @@ export type VideoExportOptions = {
      * @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'`.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#contenthint | VideoExportOptions.contentHint API reference}
+     */
+    contentHint?: VideoContentHint;
     /**
      * Encoder latency mode. Defaults to `'quality'`.
      *
@@ -210,7 +233,7 @@ export type VideoExportOptions = {
      */
     keyFrameInterval?: number;
     /**
-     * Pixel density used during export. Defaults to `1` so video dimensions match the live canvas.
+     * Pixel density used during export. Defaults to `1` so video dimensions match the logical canvas size.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#pixeldensity | VideoExportOptions.pixelDensity API reference}
      */
@@ -245,6 +268,12 @@ 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;
@@ -253,6 +282,7 @@ export interface VideoGenerationOptions {
     frameCount: number;
     bitrate: number | VideoBitratePreset;
     bitrateMode: VideoBitrateMode;
+    contentHint?: VideoContentHint;
     latencyMode: VideoLatencyMode;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;
@@ -261,6 +291,7 @@ export interface VideoGenerationOptions {
     height: number;
     transparent: boolean;
     debugLogging: boolean;
+    allowLargeInMemory?: boolean;
     signal?: AbortSignal;
     prepareFrame?: PrepareExportFrame;
 }
@@ -271,6 +302,11 @@ export interface VideoEncodingPlan {
     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;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;

package/dist/types/index.d.ts

@@ -24,7 +24,7 @@ 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, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, VideoRecordingState, } from './exporters/video';
+export type { VideoBitrateMode, VideoBitratePreset, VideoContentHint, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, 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/Blade.d.ts

@@ -16,6 +16,11 @@ export interface BladeConfig<TOptions> {
     format: ExportFormat;
     defaultOptions: TOptions;
     layerTargetProvider?: LayerTargetProvider;
+    videoDimensionsProvider?: () => {
+        width: number;
+        height: number;
+    };
+    videoDimensionsTarget?: Element;
 }
 export declare abstract class Blade<TOptions> extends Component<void> {
     readonly capabilities: BladeCapabilities;

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

@@ -12,7 +12,9 @@ export declare class VideoBlade extends Blade<VideoExportOptions> {
     private keyFrameIntervalInput;
     private transparencyInput;
     private status;
+    private estimate;
     private recordingState;
+    private resizeObserver?;
     constructor(config: BladeConfig<VideoExportOptions>);
     render(): HTMLElement;
     getOptions(): VideoExportOptions;
@@ -26,6 +28,12 @@ export declare class VideoBlade extends Blade<VideoExportOptions> {
     private resolvePlannedFrameCount;
     private applyDefaults;
     private resolveBitratePreset;
+    private readonly handleBitrateChange;
+    private readonly handleEstimateChange;
+    private syncReadyStatus;
     private readonly handleFormatChange;
+    private syncOutputEstimate;
+    private formatBytes;
+    protected _onUnmount(): void;
     private syncTransparencyAvailability;
 }

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

@@ -3,4 +3,7 @@ import type { FormatDefinition } from './models/FormatDefinition';
 import type { LayerTargetProvider } from '../exporters/base';
 import type { ExportDefaults } from './types';
 export type ExportDefaultsProvider = <TFormat extends ExportFormat>(format: TFormat) => ExportDefaults[TFormat];
-export declare function getExportFormatDefinitions(layerTargetProvider?: LayerTargetProvider, getDefaults?: ExportDefaultsProvider): ReadonlyArray<FormatDefinition<ExportFormat>>;
+export declare function getExportFormatDefinitions(layerTargetProvider?: LayerTargetProvider, getDefaults?: ExportDefaultsProvider, videoDimensionsProvider?: () => {
+    width: number;
+    height: number;
+}, videoDimensionsTarget?: Element): ReadonlyArray<FormatDefinition<ExportFormat>>;

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

@@ -0,0 +1,24 @@
+import type { Textmodifier } from 'textmode.js';
+import type { TextmodeExportAPI } from '../types';
+export declare const EXPORT_API_METHOD_KEYS: ReadonlyArray<Exclude<keyof TextmodeExportAPI, 'exportOverlay'>>;
+type PostDrawSubscription = (callback: () => void) => () => void;
+/**
+ * Deep export implementation for one installed plugin instance.
+ *
+ * The host adapter registers this controller's API as extensions. The controller owns
+ * DOM resources, post-draw subscriptions, and abort controllers for asynchronous capture.
+ */
+export declare class TextmodeExportController {
+    readonly api: TextmodeExportAPI;
+    private readonly _registerPostDrawHook;
+    private readonly _activeOperations;
+    private readonly _overlayController;
+    private readonly _stopOverlayRefresh;
+    private _disposed;
+    constructor(textmodifier: Textmodifier, registerPostDrawHook: PostDrawSubscription);
+    dispose(): void;
+    private _createOverlayAPI;
+    private _runOperation;
+    private _assertLive;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "textmode.export.js",
-	"version": "1.7.2",
+	"version": "1.8.0-beta.2",
 	"description": "Export plugin for textmode.js - Save your creations as images, GIFs, videos, SVG, JSON, and plain text.",
 	"type": "module",
 	"devEngines": {
@@ -33,6 +33,8 @@
 		"dist"
 	],
 	"scripts": {
+		"prebuild": "npm run clean",
+		"clean": "rm -rf dist",
 		"dev": "textmode-build dev --port 5174 --host",
 		"build:bundle": "textmode-build build",
 		"build:types": "textmode-types build",
@@ -58,20 +60,20 @@
 		"release": "textmode-release release"
 	},
 	"peerDependencies": {
-		"textmode.js": "^0.17.2"
+		"textmode.js": "^0.18.0-beta.3"
 	},
 	"dependencies": {
 		"gifenc": "^1.0.1",
-		"mediabunny": "^1.45.4"
+		"mediabunny": "^1.52.3"
 	},
 	"devDependencies": {
 		"@textmode/build": "^0.1.0",
 		"@textmode/docs": "^0.3.0",
 		"@textmode/lint": "^0.1.0",
 		"@textmode/release": "^0.2.0",
-		"@textmode/tsconfig": "^0.2.0",
+		"@textmode/tsconfig": "^0.2.1",
 		"@types/node": "^24.0.0",
-		"textmode.js": "^0.17.2",
+		"textmode.js": "^0.18.0-beta.3",
 		"typescript": "^6.0.3",
 		"vite-plugin-css-injected-by-js": "^5.0.2",
 		"vitest": "^4.1.10"