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

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

@@ -4,8 +4,6 @@ import type { TextmodeLayer } from 'textmode.js';
 /**
  * Shared option for exporters that read layer framebuffer data.
  *
- * @category Layer data export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/LayerExportOptions | LayerExportOptions API reference}
  */
 export interface LayerExportOptions {
@@ -48,4 +46,4 @@ export declare function getLayerTargetOptions(textmodifier: Textmodifier): Layer
 export declare function createLayerTargetProvider(textmodifier: Textmodifier): LayerTargetProvider;
 export declare function getLayerTargetId(textmodifier: Textmodifier, layer: TextmodeLayer): string;
 export declare function resolveLayerExportTarget(textmodifier: Textmodifier, layer?: TextmodeLayer): ResolvedLayerExportTarget;
-export declare function resolveLayerStackExportTargets(textmodifier: Textmodifier): ResolvedLayerStackExportTarget[];
+export declare function resolveLayerStackExportTargets(textmodifier: Textmodifier, selectedLayers?: readonly TextmodeLayer[]): ResolvedLayerStackExportTarget[];

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

@@ -3,8 +3,6 @@ export type GIFRecordingState = 'idle' | 'recording' | 'encoding' | 'completed'
 /**
  * Progress information emitted while deterministic frames are captured and encoded as an animated GIF.
  *
- * @category GIF export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress | GIFExportProgress API reference}
  */
 export type GIFExportProgress = {
@@ -36,8 +34,6 @@ export type GIFExportProgress = {
 /**
  * Options for capturing deterministic textmode frames as an animated GIF.
  *
- * @category GIF export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions | GIFExportOptions API reference}
  */
 export type GIFExportOptions = {

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

@@ -8,8 +8,6 @@ export type ImageFormat = 'png' | 'jpg' | 'webp';
 /**
  * Options for exporting the textmode content to image format.
  *
- * @category Canvas capture
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ImageExportOptions | ImageExportOptions API reference}
  */
 export type ImageExportOptions = {

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

@@ -1,5 +1,6 @@
 import type { Textmodifier } from 'textmode.js';
-import type { JSONExportOptions, TextmodeDocumentJSON } from './types';
+import type { JSONExportOptions } from './types';
+import type { TextmodeDocumentJSON } from '@textmode/document';
 /**
  * Main JSON exporter for the textmode.js library.
  * Orchestrates structured selected-layer or layer-stack export and file download.

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

@@ -1,3 +1,2 @@
 export { JSONExporter } from './JSONExporter';
-export { JSONDataExtractor } from './JSONDataExtractor';
-export type { JSONDocumentFormat, JSONDocumentVersion, JSONCellCollection, JSONCellData, JSONCellTransform, JSONColorValue, JSONExportColorMode, JSONExportMetadata, JSONExportOptions, JSONExportTarget, JSONGenerationOptions, JSONLayerGrid, JSONObjectRowCell, JSONObjectRowsCellCollection, JSONRGBAColor, TextmodeAllDocumentJSON, TextmodeDocumentJSON, TextmodeDocumentLayer, TextmodeSelectedDocumentJSON, TextmodeSelectedDocumentLayer, } from './types';
+export type { JSONExportTarget, JSONExportColorMode, JSONExportOptions } from './types';

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

@@ -1,225 +1,42 @@
 import type { LayerExportOptions } from '../base';
+import type { TextmodeDocumentCellTransform, TextmodeDocumentRGBAColor } from '@textmode/document';
 /**
- * Target scope for JSON export.
- *
- * @category JSON document data
+ * Layer selection for export; never serialized into the document.
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportTarget | JSONExportTarget API reference}
  */
 export type JSONExportTarget = 'selected' | 'all';
 /**
- * Canonical JSON document format identifier.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONDocumentFormat | JSONDocumentFormat API reference}
- */
-export type JSONDocumentFormat = 'textmode.document';
-/**
- * Canonical JSON document format version.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONDocumentVersion | JSONDocumentVersion API reference}
- */
-export type JSONDocumentVersion = '2.0.0';
-/**
- * Supported JSON color output modes.
- *
- * @category JSON document data
+ * Color representation written by the JSON exporter: hexadecimal strings or
+ * RGBA channel objects.
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportColorMode | JSONExportColorMode API reference}
  */
 export type JSONExportColorMode = 'hex' | 'rgba';
 /**
- * RGBA color representation used in JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONRGBAColor | JSONRGBAColor API reference}
- */
-export interface JSONRGBAColor {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-}
-/**
- * Color value used in the exported JSON document.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONColorValue | JSONColorValue API reference}
- */
-export type JSONColorValue = string | JSONRGBAColor;
-/**
- * Cell transform data for JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONCellTransform | JSONCellTransform API reference}
- */
-export interface JSONCellTransform {
-    invert: boolean;
-    flipX: boolean;
-    flipY: boolean;
-    rotation: number;
-}
-/**
- * Rich per-cell representation for readable JSON exports.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONObjectRowCell | JSONObjectRowCell API reference}
- */
-export interface JSONObjectRowCell {
-    x: number;
-    y: number;
-    character: string;
-    foreground: JSONColorValue;
-    background: JSONColorValue;
-    transform: JSONCellTransform;
-}
-/**
- * Row-based cell encoding.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONObjectRowsCellCollection | JSONObjectRowsCellCollection API reference}
- */
-export interface JSONObjectRowsCellCollection {
-    encoding: 'object-rows-v1';
-    rows: JSONObjectRowCell[][];
-}
-/**
- * Supported JSON cell collection variants.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONCellCollection | JSONCellCollection API reference}
- */
-export type JSONCellCollection = JSONObjectRowsCellCollection;
-/**
- * Grid dimensions exported for a layer.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONLayerGrid | JSONLayerGrid API reference}
- */
-export interface JSONLayerGrid {
-    cols: number;
-    rows: number;
-    cellWidth: number;
-    cellHeight: number;
-}
-/**
- * Optional export metadata.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/JSONExportMetadata | JSONExportMetadata API reference}
- */
-export interface JSONExportMetadata {
-    createdAt: string;
-    generator: {
-        name: 'textmode.export.js';
-        version: string;
-    };
-}
-/**
- * Selected-layer entry in a JSON document export.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeSelectedDocumentLayer | TextmodeSelectedDocumentLayer API reference}
- */
-export interface TextmodeSelectedDocumentLayer {
-    id: string;
-    cells: JSONCellCollection;
-}
-/**
- * Selected-layer document exported by the JSON exporter.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeSelectedDocumentJSON | TextmodeSelectedDocumentJSON API reference}
- */
-export interface TextmodeSelectedDocumentJSON {
-    format: JSONDocumentFormat;
-    formatVersion: JSONDocumentVersion;
-    target: 'selected';
-    metadata?: JSONExportMetadata;
-    canvas: {
-        width: number;
-        height: number;
-    };
-    grid: JSONLayerGrid;
-    layer: TextmodeSelectedDocumentLayer;
-}
-/**
- * Single layer entry in an all-layers JSON export.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeDocumentLayer | TextmodeDocumentLayer API reference}
- */
-export interface TextmodeDocumentLayer {
-    id: string;
-    visible: boolean;
-    opacity: number;
-    blendMode: string;
-    offsetX: number;
-    offsetY: number;
-    rotationZ: number;
-    grid: JSONLayerGrid;
-    cells: JSONCellCollection;
-}
-/**
- * Layer stack document exported by the JSON exporter.
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/TextmodeAllDocumentJSON | TextmodeAllDocumentJSON API reference}
- */
-export interface TextmodeAllDocumentJSON {
-    format: JSONDocumentFormat;
-    formatVersion: JSONDocumentVersion;
-    target: 'all';
-    metadata?: JSONExportMetadata;
-    canvas: {
-        width: number;
-        height: number;
-    };
-    layers: TextmodeDocumentLayer[];
-}
-/**
- * JSON document exported by the JSON exporter.
- *
- * @category JSON document data
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/TextmodeDocumentJSON | TextmodeDocumentJSON API reference}
- */
-export type TextmodeDocumentJSON = TextmodeSelectedDocumentJSON | TextmodeAllDocumentJSON;
-/**
- * Options for exporting the textmode content to JSON format.
- *
- * @category JSON document data
+ * Options for exporting textmode content to JSON.
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONExportOptions | JSONExportOptions API reference}
  */
 export type JSONExportOptions = LayerExportOptions & {
     /**
-     * Scope of the JSON export.
-     *
-     * Use `'selected'` to export one layer, or `'all'` to export the base layer and every user-created layer.
-     *
-     * Defaults to `'selected'`.
+     * Export one selected layer or the complete layer stack.
+     * Defaults to `selected`.
      */
     target?: JSONExportTarget;
-    /**
-     * The filename to save the JSON file as.
-     *
-     * If not provided, a default filename is used.
-     */
+    /** Filename used by the download helper. A default name is used when omitted. */
     filename?: string;
     /**
-     * Pretty-print the generated JSON.
-     *
-     * When set to `true`, output uses two-space indentation.
-     * When set to a number, that value is used as indentation width.
-     * When `false`, the output is minified.
-     *
-     * Defaults to `true`.
+     * Pretty-print with two spaces when `true`, use the given indentation width
+     * when numeric, or produce compact JSON when `false`. Defaults to `true`.
      */
     pretty?: boolean | number;
-    /**
-     * Color representation used for foreground and background values.
-     *
-     * Defaults to `'hex'`.
-     */
+    /** Foreground and background color representation. Defaults to `hex`. */
     colorMode?: JSONExportColorMode;
-    /**
-     * Whether to include export metadata such as timestamp and generator details.
-     *
-     * Defaults to `true`.
-     */
+    /** Include the creation timestamp and generator metadata. Defaults to `true`. */
     includeMetadata?: boolean;
 };
-/**
- * Internal options used by JSON generation (with all defaults applied).
- */
+/** Internal JSON generation options after defaults have been applied. */
 export interface JSONGenerationOptions {
     target: JSONExportTarget;
     pretty: boolean | number;
@@ -228,14 +45,12 @@ export interface JSONGenerationOptions {
     filename?: string;
     layer?: LayerExportOptions['layer'];
 }
-/**
- * Internal extracted cell data used while building the JSON document.
- */
+/** Internal framebuffer cell data used while building a document. */
 export interface JSONCellData {
     x: number;
     y: number;
     character: string;
-    foreground: JSONRGBAColor;
-    background: JSONRGBAColor;
-    transform: JSONCellTransform;
+    foreground: TextmodeDocumentRGBAColor;
+    background: TextmodeDocumentRGBAColor;
+    transform: TextmodeDocumentCellTransform;
 }

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

@@ -1,4 +1,4 @@
-import type { LayerExportOptions } from '../base';
+import type { LayerExportOptions } from '../base/LayerTarget';
 /**
  * RGBA color representation.
  */
@@ -54,8 +54,6 @@ export interface FramebufferData {
 /**
  * Options for exporting the textmode content to SVG format.
  *
- * @category Layer data export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/SVGExportOptions | SVGExportOptions API reference}
  */
 export type SVGExportOptions = LayerExportOptions & {

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

@@ -2,8 +2,6 @@ import type { LayerExportOptions } from '../base';
 /**
  * Options for exporting the textmode content to TXT format.
  *
- * @category Layer data export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/TXTExportOptions | TXTExportOptions API reference}
  */
 export type TXTExportOptions = LayerExportOptions & {

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

@@ -2,8 +2,6 @@ import type { FrameSequenceDriverLike, FrameSequenceRenderOptions, PrepareExport
 /**
  * High-level lifecycle state reported while a video export is captured, encoded, or completed.
  *
- * @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';
@@ -14,8 +12,6 @@ export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed
  * for buffered output. `rendering`, `encoding`, and `draining` remain available for compatibility with older progress
  * producers.
  *
- * @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';
@@ -26,8 +22,6 @@ export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
  * 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 Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQualityLevel | VideoQualityLevel API reference}
  */
 export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
@@ -49,8 +43,6 @@ export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-h
  * 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 VideoQuality = VideoQualityLevel | {
@@ -66,8 +58,6 @@ export type VideoQuality = VideoQualityLevel | {
  *
  * This setting does not affect `toVideoBlob()`, which always returns an in-memory `Blob`.
  *
- * @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';
@@ -77,8 +67,6 @@ export type VideoSaveDestination = 'download' | 'file-system';
  * 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}
  */
 export type VideoExportFormat = 'webm' | 'mp4';
@@ -92,8 +80,6 @@ export type VideoExportFormat = 'webm' | 'mp4';
  *
  * 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';
@@ -106,8 +92,6 @@ export type VideoBitrateMode = 'variable' | 'constant';
  *   availability and output characteristics vary by device.
  * - `'prefer-software'`: prefer CPU encoding, often more consistent across machines, but usually slower.
  *
- * @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';
@@ -115,8 +99,6 @@ export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNS
 /**
  * Progress information emitted while a deterministic video is probed, captured, and written.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
@@ -192,8 +174,6 @@ export type VideoExportProgress = {
 /**
  * Options for capturing deterministic textmode frames as MP4 or WebM video.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
 export type VideoExportOptions = {

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

@@ -2,7 +2,6 @@ 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 {

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

@@ -6,28 +6,24 @@ 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 {
@@ -65,7 +61,6 @@ export interface ZIPExportProgress {
 /**
  * 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 {
@@ -109,7 +104,6 @@ export interface ZIPCaptureOptions {
 /**
  * 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 {
@@ -123,7 +117,6 @@ export interface ZIPFrameOptionsMap {
 /**
  * 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 = {

package/dist/types/index.d.ts

@@ -15,30 +15,6 @@
  * 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';
@@ -48,7 +24,7 @@ export type { TextmodeExportAPI, ExportOverlayController } from './types';
 export type { ImageExportOptions } from './exporters/image';
 export type { SVGExportOptions } from './exporters/svg';
 export type { TXTExportOptions } from './exporters/txt';
-export type { JSONExportColorMode, JSONExportOptions, JSONExportTarget, TextmodeDocumentJSON } from './exporters/json';
+export type { JSONExportTarget, JSONExportColorMode, JSONExportOptions } 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';
@@ -57,8 +33,6 @@ export type { LayerExportOptions } from './exporters/base';
 /**
  * Default export plugin instance for the standard textmode.js workflow.
  *
- * @category Workflow
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/variables/ExportPlugin | ExportPlugin API reference}
  */
 export declare const ExportPlugin: TextmodePlugin;