textmode.js 0.1.0 → 0.1.1

package/dist/types/export/base/DataExtractor.d.ts

@@ -0,0 +1,33 @@
+import type { FramebufferData } from '../svg/types';
+/**
+ * Base class for data extraction from textmode framebuffers.
+ * Provides common functionality shared between different export formats.
+ */
+export declare abstract class DataExtractor {
+    /**
+     * Extracts pixel data from all framebuffers needed for export
+     * @param pipeline The conversion pipeline containing framebuffers
+     * @returns Object containing all pixel data arrays
+     */
+    extractFramebufferData(pipeline: any): FramebufferData;
+    /**
+     * Gets character index from character framebuffer pixels
+     * @param characterPixels Character framebuffer pixel data
+     * @param pixelIndex Index in the pixel array (already multiplied by 4 for RGBA)
+     * @param charactersLength Total number of available characters
+     * @returns Character index
+     */
+    protected getCharacterIndex(characterPixels: Uint8Array, pixelIndex: number): number;
+    /**
+     * Converts raw pixel data to RGBA color object
+     * @param pixels Pixel data array
+     * @param index Pixel index (already multiplied by 4 for RGBA)
+     * @returns RGBA color object with r, g, b, a properties
+     */
+    protected pixelsToRGBA(pixels: Uint8Array, index: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Base class for file handling operations.
+ * Provides common functionality for downloading files in the browser.
+ */
+export declare abstract class FileHandler {
+    /**
+     * Creates a downloadable blob from content
+     * @param content The content to include in the blob
+     * @param mimeType The MIME type for the blob
+     * @returns Blob object containing the content
+     */
+    protected createBlob(content: string, mimeType: string): Blob;
+    /**
+     * Creates a data URL from content
+     * @param content The content to convert
+     * @param mimeType The MIME type for the blob
+     * @returns Data URL string
+     */
+    protected createDataURL(content: string, mimeType: string): string;
+    /**
+     * Downloads content as a file
+     * @param content The content to download
+     * @param filename The filename (with extension)
+     * @param mimeType The MIME type for the content
+     */
+    protected downloadFile(content: string, filename: string, mimeType: string): void;
+    /**
+     * Generates a timestamp string for filenames
+     * @returns Formatted timestamp string
+     */
+    protected generateTimestamp(): string;
+    /**
+     * Generates a date-time string for filenames (alternative format)
+     * @returns Formatted date and time string
+     */
+    protected generateDateTimeString(): {
+        date: string;
+        time: string;
+    };
+    /**
+     * Validates and sanitizes filename for safety and compatibility
+     * @param filename The filename to validate
+     * @returns Sanitized filename
+     */
+    protected sanitizeFilename(filename: string): string;
+    /**
+     * Ensures filename has the correct extension
+     * @param filename The filename to check
+     * @param expectedExtension The expected file extension (with dot)
+     * @returns Filename with correct extension
+     */
+    protected ensureFileExtension(filename: string, expectedExtension: string): string;
+    /**
+     * Generates a default filename with prefix and timestamp
+     * @param prefix The prefix for the filename
+     * @param extension The file extension (with dot)
+     * @returns Generated filename
+     */
+    protected generateDefaultFilename(prefix: string, extension: string): string;
+}

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

@@ -0,0 +1,2 @@
+export { DataExtractor } from './DataExtractor';
+export { FileHandler } from './FileHandler';

package/dist/types/export/image/ImageContentGenerator.d.ts

@@ -0,0 +1,27 @@
+import type { ImageGenerationOptions } from './types';
+/**
+ * Content generator for image export.
+ * Handles the conversion of canvas data to different image formats.
+ */
+export declare class ImageContentGenerator {
+    /**
+     * Generates image data from canvas
+     * @param canvas The canvas containing the image data
+     * @param options Generation options with format, quality, etc.
+     * @returns Data URL string containing the image data
+     */
+    generateImageData(canvas: HTMLCanvasElement, options: ImageGenerationOptions): string;
+    /**
+     * Generates image blob from canvas
+     * @param canvas The canvas containing the image data
+     * @param options Generation options with format, quality, etc.
+     * @returns Promise that resolves to a Blob containing the image data
+     */
+    generateImageBlob(canvas: HTMLCanvasElement, options: ImageGenerationOptions): Promise<Blob>;
+    /**
+     * Gets the MIME type for a given image format
+     * @param format The image format
+     * @returns The corresponding MIME type
+     */
+    private getMimeType;
+}

package/dist/types/export/image/ImageDataExtractor.d.ts

@@ -0,0 +1,15 @@
+import { DataExtractor } from '../base/DataExtractor';
+/**
+ * Data extractor for image export.
+ * Captures the current visual state of the textmode canvas for image generation.
+ */
+export declare class ImageDataExtractor extends DataExtractor {
+    /**
+     * Captures the current state of the textmode canvas as image data
+     * @param textmodeCanvas The TextmodeCanvas instance to capture from
+     * @param scale Scale factor for the output image
+     * @param backgroundColor Background color for formats that don't support transparency
+     * @returns Canvas element containing the captured image data
+     */
+    captureCanvasData(textmodeCanvas: any, scale?: number, backgroundColor?: string): HTMLCanvasElement;
+}

package/dist/types/export/image/ImageExporter.d.ts

@@ -0,0 +1,44 @@
+import type { ImageExportOptions } from './types';
+/**
+ * Main image exporter for the textmode.js library.
+ * Orchestrates the image export process by coordinating canvas capture,
+ * format conversion, and file handling.
+ */
+export declare class ImageExporter {
+    private dataExtractor;
+    private contentGenerator;
+    private fileHandler;
+    constructor();
+    /**
+     * Applies default values to image export options
+     * @param options User-provided options
+     * @returns Complete options with defaults applied
+     */
+    private applyDefaultOptions;
+    /**
+     * Validates export options and browser support
+     * @param options The options to validate
+     * @throws Error if options are invalid or format is not supported
+     */
+    private validateOptions;
+    /**
+     * Generates image data from textmode rendering without saving to file
+     * @param textmodifier The textmodifier instance containing the canvas
+     * @param options Export options (excluding filename)
+     * @returns Data URL string containing the image data
+     */
+    generateImage(textmodifier: any, options?: Omit<ImageExportOptions, 'filename'>): string;
+    /**
+     * Generates image blob from textmode rendering without saving to file
+     * @param textmodifier The textmodifier instance containing the canvas
+     * @param options Export options (excluding filename)
+     * @returns Promise that resolves to a Blob containing the image data
+     */
+    generateImageBlob(textmodifier: any, options?: Omit<ImageExportOptions, 'filename'>): Promise<Blob>;
+    /**
+     * Exports image to a downloadable file
+     * @param textmodifier The textmodifier instance containing the canvas
+     * @param options Export options including filename
+     */
+    saveImage(textmodifier: any, options?: ImageExportOptions): Promise<void>;
+}

package/dist/types/export/image/ImageFileHandler.d.ts

@@ -0,0 +1,51 @@
+import { FileHandler } from '../base/FileHandler';
+import type { ImageFormat } from './types';
+/**
+ * File handler for image export operations.
+ * Manages saving image files to disk with proper MIME types and extensions.
+ */
+export declare class ImageFileHandler extends FileHandler {
+    /**
+     * Saves image content as a downloadable file
+     * @param content The image content (data URL or blob)
+     * @param filename The filename (without extension)
+     * @param format The image format
+     */
+    saveImage(content: string | Blob, filename: string, format: ImageFormat): void;
+    /**
+     * Saves image from data URL
+     * @param dataURL The data URL containing image data
+     * @param filename The complete filename with extension
+     */
+    private saveImageFromDataURL;
+    /**
+     * Saves image from blob
+     * @param blob The blob containing image data
+     * @param filename The complete filename with extension
+     */
+    private saveImageFromBlob;
+    /**
+     * Generates a default filename for image export
+     * @param format The image format for the file extension
+     * @returns Generated filename with timestamp
+     */
+    generateDefaultImageFilename(format?: ImageFormat): string;
+    /**
+     * Validates if the browser supports saving files in the specified format
+     * @param format The image format to validate
+     * @returns True if the format is supported for saving
+     */
+    validateSaveSupport(format: ImageFormat): boolean;
+    /**
+     * Gets the MIME type for the specified image format
+     * @param format The image format
+     * @returns The MIME type string
+     */
+    getMimeType(format: ImageFormat): string;
+    /**
+     * Gets the file extension for the specified image format
+     * @param format The image format
+     * @returns The file extension (including the dot)
+     */
+    getFileExtension(format: ImageFormat): string;
+}

package/dist/types/export/image/index.d.ts

@@ -0,0 +1,6 @@
+export { ImageExporter } from './ImageExporter';
+export { ImageDataExtractor } from './ImageDataExtractor';
+export { ImageContentGenerator } from './ImageContentGenerator';
+export { ImageFileHandler } from './ImageFileHandler';
+export type { ImageExportOptions, ImageGenerationOptions, ImageFormat } from './types';
+export { IMAGE_MIME_TYPES, IMAGE_EXTENSIONS } from './types';

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

@@ -0,0 +1,57 @@
+/**
+ * Image-specific type definitions for the textmode.js library.
+ */
+/**
+ * Supported image formats for export.
+ */
+export type ImageFormat = 'png' | 'jpg' | 'webp';
+/**
+ * Options for exporting the textmode content to image format.
+ */
+export type ImageExportOptions = {
+    /**
+     * The filename to save the image file as (without extension).
+     * If not provided, a default filename is used.
+     */
+    filename?: string;
+    /**
+     * The image format to export ('png', 'jpg', or 'webp').
+     * Default is 'png'.
+     */
+    format?: ImageFormat;
+    /**
+     * Image quality for lossy formats (jpg, webp).
+     * Range: 0.0 to 1.0, where 1.0 is highest quality.
+     * Default is 1.0. Ignored for PNG format.
+     */
+    quality?: number;
+    /**
+     * Scale factor for the output image.
+     * 1.0 = original size, 2.0 = double size, 0.5 = half size.
+     * Default is 1.0.
+     */
+    scale?: number;
+    /**
+     * Background color for formats that don't support transparency (jpg).
+     * Format: CSS color string or 'transparent' for PNG/WebP.
+     * Default is 'black'.
+     */
+    backgroundColor?: string;
+};
+/**
+ * Internal options used by image generation (with all defaults applied).
+ */
+export interface ImageGenerationOptions {
+    format: ImageFormat;
+    quality: number;
+    scale: number;
+    backgroundColor: string;
+}
+/**
+ * MIME type mapping for image formats.
+ */
+export declare const IMAGE_MIME_TYPES: Record<ImageFormat, string>;
+/**
+ * File extension mapping for image formats.
+ */
+export declare const IMAGE_EXTENSIONS: Record<ImageFormat, string>;

package/dist/types/export/index.d.ts

@@ -0,0 +1,3 @@
+export type { SVGExportOptions } from './svg';
+export type { TXTExportOptions } from './txt';
+export type { ImageExportOptions } from './image/types';

package/dist/types/export/svg/SVGContentGenerator.d.ts

@@ -1,4 +1,5 @@
-import type { SVGCellData, GridInfo, FontInfo, SVGGenerationOptions } from './types';
+import type { SVGCellData, SVGGenerationOptions } from './types';
+import type { TextmodeFont, TextmodeGrid } from '../../Textmode';
 /**
  * Generates SVG content and markup from processed cell data.
  * This class handles the creation of SVG elements, groups, and styling.
@@ -11,7 +12,7 @@ export declare class SVGContentGenerator {
      * @param gridInfo Grid dimensions
      * @returns SVG header string
      */
-    generateSVGHeader(gridInfo: GridInfo): string;
+    generateSVGHeader(gridInfo: TextmodeGrid): string;
     /**
      * Generates the SVG footer
      * @returns SVG footer string
@@ -23,7 +24,7 @@ export declare class SVGContentGenerator {
      * @param options SVG generation options
      * @returns Background rectangle SVG string or empty string
      */
-    generateBackground(gridInfo: GridInfo, options: SVGGenerationOptions): string;
+    generateBackground(gridInfo: TextmodeGrid, options: SVGGenerationOptions): string;
     /**
      * Converts RGBA object to CSS color string
      * @param color RGBA color object
@@ -62,16 +63,16 @@ export declare class SVGContentGenerator {
      * @param options SVG generation options
      * @returns Complete cell SVG content
      */
-    generateCellContent(cellData: SVGCellData, gridInfo: GridInfo, fontInfo: FontInfo, options: SVGGenerationOptions): string;
+    generateCellContent(cellData: SVGCellData, gridInfo: TextmodeGrid, fontInfo: TextmodeFont, options: SVGGenerationOptions): string;
     /**
      * Generates the complete SVG content from cell data
      * @param cellDataArray Array of cell data
-     * @param gridInfo Grid information
+     * @param grid Grid information
      * @param fontInfo Font information
      * @param options SVG generation options
      * @returns Complete SVG string
      */
-    generateSVGContent(cellDataArray: SVGCellData[], gridInfo: GridInfo, fontInfo: FontInfo, options: SVGGenerationOptions): string;
+    generateSVGContent(cellDataArray: SVGCellData[], grid: TextmodeGrid, fontInfo: TextmodeFont, options: SVGGenerationOptions): string;
     /**
      * Optimizes SVG content by removing empty elements and unnecessary whitespace
      * @param svgContent Raw SVG content

package/dist/types/export/svg/SVGDataExtractor.d.ts

@@ -1,34 +1,11 @@
-import type { FramebufferData, SVGCellData, GridInfo, FontInfo } from './types';
+import type { FramebufferData, SVGCellData } from './types';
+import { DataExtractor } from '../base';
+import type { TextmodeGrid } from '../../Textmode';
 /**
  * Extracts and processes data from framebuffers for SVG generation.
  * This class handles the conversion of raw pixel data into structured data objects.
  */
-export declare class SVGDataExtractor {
-    /**
-     * Extracts pixel data from all framebuffers needed for SVG export
-     * @param pipeline The conversion pipeline containing framebuffers
-     * @returns Object containing all pixel data arrays
-     */
-    extractFramebufferData(pipeline: any): FramebufferData;
-    /**
-     * Extracts grid information from the grid object
-     * @param grid The textmode grid object
-     * @returns Grid information object
-     */
-    extractGridInfo(grid: any): GridInfo;
-    /**
-     * Extracts font information from the font object
-     * @param font The textmode font object
-     * @returns Font information object
-     */
-    extractFontInfo(font: any): FontInfo;
-    /**
-     * Converts raw pixel data to RGBA color object
-     * @param pixels Pixel data array
-     * @param index Pixel index (already multiplied by 4 for RGBA)
-     * @returns RGBA color object
-     */
-    private pixelsToRGBA;
+export declare class SVGDataExtractor extends DataExtractor {
     /**
      * Extracts transform data from transform pixels
      * @param transformPixels Transform framebuffer pixels
@@ -48,17 +25,9 @@ export declare class SVGDataExtractor {
     /**
      * Processes all grid cells and extracts SVG cell data
      * @param framebufferData Raw pixel data from framebuffers
-     * @param gridInfo Grid information
-     * @param fontInfo Font information
+     * @param grid Grid information
+     * @param font Font information
      * @returns Array of SVG cell data objects
      */
-    extractSVGCellData(framebufferData: FramebufferData, gridInfo: GridInfo, fontInfo: FontInfo): SVGCellData[];
-    /**
-     * Validates that all required data is present for SVG generation
-     * @param framebufferData Framebuffer data
-     * @param gridInfo Grid information
-     * @param fontInfo Font information
-     * @returns True if all data is valid, false otherwise
-     */
-    validateExportData(framebufferData: FramebufferData, gridInfo: GridInfo, fontInfo: FontInfo): boolean;
+    extractSVGCellData(framebufferData: FramebufferData, grid: TextmodeGrid): SVGCellData[];
 }

package/dist/types/export/svg/SVGFileHandler.d.ts

@@ -1,8 +1,9 @@
+import { FileHandler } from '../base/FileHandler.js';
 /**
  * Handles SVG file operations including download and save functionality.
  * This class manages the creation of downloadable SVG files and blob handling.
  */
-export declare class SVGFileHandler {
+export declare class SVGFileHandler extends FileHandler {
     /**
      * Generates a default filename for SVG export
      * @param prefix Optional prefix for the filename
@@ -39,22 +40,4 @@ export declare class SVGFileHandler {
      * @param filename Optional filename (will generate if not provided)
      */
     saveSVG(svgContent: string, filename?: string): void;
-    /**
-     * Gets the size of the SVG content in bytes
-     * @param svgContent The SVG content string
-     * @returns Size in bytes
-     */
-    getSVGSize(svgContent: string): number;
-    /**
-     * Formats file size in human-readable format
-     * @param bytes Size in bytes
-     * @returns Formatted size string
-     */
-    formatFileSize(bytes: number): string;
-    /**
-     * Validates SVG content before saving
-     * @param svgContent The SVG content to validate
-     * @returns True if valid, false otherwise
-     */
-    validateSVGContent(svgContent: string): boolean;
 }

package/dist/types/export/svg/index.d.ts

@@ -3,4 +3,4 @@ export { SVGDataExtractor } from './SVGDataExtractor';
 export { SVGContentGenerator } from './SVGContentGenerator';
 export { SVGPathGenerator } from './SVGPathGenerator';
 export { SVGFileHandler } from './SVGFileHandler';
-export type { SVGExportOptions, SVGGenerationOptions, SVGCellData, GridInfo, FontInfo, FramebufferData, RGBA, Position, CellPosition, CellTransform, GlyphPath } from './types';
+export type { SVGExportOptions, SVGGenerationOptions, SVGCellData, FramebufferData, RGBA, Position, CellPosition, CellTransform, GlyphPath } from './types';

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

@@ -45,25 +45,6 @@ export interface SVGCellData {
     transform: CellTransform;
     position: CellPosition;
 }
-/**
- * Grid dimensions and cell sizing information.
- */
-export interface GridInfo {
-    cols: number;
-    rows: number;
-    width: number;
-    height: number;
-    cellWidth: number;
-    cellHeight: number;
-}
-/**
- * Font information needed for SVG generation.
- */
-export interface FontInfo {
-    fontSize: number;
-    fontData: any;
-    characters: any[];
-}
 /**
  * Framebuffer data extracted for SVG generation.
  */

package/dist/types/export/txt/TXTContentGenerator.d.ts

@@ -0,0 +1,14 @@
+import type { TXTGenerationOptions } from './types';
+/**
+ * Generates TXT content from character grid data.
+ * This class handles the conversion of character arrays into formatted text strings.
+ */
+export declare class TXTContentGenerator {
+    /**
+     * Generates TXT content from a 2D character array
+     * @param characterGrid 2D array of characters (rows x columns)
+     * @param options Generation options
+     * @returns TXT content as string
+     */
+    generateTXTContent(characterGrid: string[][], options: TXTGenerationOptions): string;
+}

package/dist/types/export/txt/TXTDataExtractor.d.ts

@@ -0,0 +1,18 @@
+import type { FramebufferData } from './types';
+import { DataExtractor } from '../base';
+import type { TextmodeFont, TextmodeGrid } from '../../Textmode';
+/**
+ * Extracts and processes data from framebuffers for TXT generation.
+ * This class handles the conversion of raw pixel data into character arrays.
+ */
+export declare class TXTDataExtractor extends DataExtractor {
+    /**
+     * Extracts character data for TXT generation
+     * @param framebufferData Framebuffer pixel data
+     * @param grid Grid information
+     * @param font Font information
+     * @param emptyCharacter Character to use for empty cells
+     * @returns 2D array of characters (rows x columns)
+     */
+    extractCharacterGrid(framebufferData: FramebufferData, grid: TextmodeGrid, font: TextmodeFont, emptyCharacter?: string): string[][];
+}

package/dist/types/export/txt/TXTExporter.d.ts

@@ -0,0 +1,31 @@
+import type { TXTExportOptions } from './types';
+/**
+ * Main TXT exporter for the textmode.js library.
+ * Orchestrates the TXT export process by coordinating data extraction,
+ * content generation, and file handling.
+ */
+export declare class TXTExporter {
+    private dataExtractor;
+    private contentGenerator;
+    private fileHandler;
+    constructor();
+    /**
+     * Applies default values to TXT export options
+     * @param options User-provided options
+     * @returns Complete options with defaults applied
+     */
+    private applyDefaultOptions;
+    /**
+     * Generates TXT content from textmode rendering data without saving to file
+     * @param textmodifier The textmodifier instance containing rendering data
+     * @param options Export options (excluding filename)
+     * @returns TXT content as string
+     */
+    generateTXT(textmodifier: any, options?: Omit<TXTExportOptions, 'filename'>): string;
+    /**
+     * Exports TXT content to a downloadable file
+     * @param textmodifier The textmodifier instance containing rendering data
+     * @param options Export options including filename
+     */
+    saveTXT(textmodifier: any, options?: TXTExportOptions): void;
+}

package/dist/types/export/txt/TXTFileHandler.d.ts

@@ -0,0 +1,24 @@
+import { FileHandler } from '../base/FileHandler.js';
+/**
+ * Handles file operations for TXT export.
+ * This class manages the saving of TXT content to downloadable files.
+ */
+export declare class TXTFileHandler extends FileHandler {
+    /**
+     * Saves TXT content as a downloadable file
+     * @param content The TXT content to save
+     * @param filename The filename to use for the download
+     */
+    saveTXT(content: string, filename: string): void;
+    /**
+     * Generates a default filename for TXT export
+     * @returns Default filename with timestamp
+     */
+    generateDefaultFilename(): string;
+    /**
+     * Ensures filename has proper extension and is valid
+     * @param filename The filename to validate and fix
+     * @returns Valid filename with .txt extension
+     */
+    private ensureValidFilename;
+}

package/dist/types/export/txt/index.d.ts

@@ -0,0 +1,5 @@
+export { TXTExporter } from './TXTExporter';
+export { TXTDataExtractor } from './TXTDataExtractor';
+export { TXTContentGenerator } from './TXTContentGenerator';
+export { TXTFileHandler } from './TXTFileHandler';
+export type { TXTExportOptions, TXTGenerationOptions, FramebufferData } from './types';

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

@@ -0,0 +1,40 @@
+/**
+ * TXT-specific type definitions for the textmode.js library.
+ */
+/**
+ * Options for exporting the textmode content to TXT format.
+ */
+export type TXTExportOptions = {
+    /**
+     * The filename to save the TXT file as. If not provided, a default filename is used.
+     */
+    filename?: string;
+    /**
+     * Whether to preserve trailing spaces on each line.
+     * When false, trailing spaces are trimmed from each line.
+     * Default is `false`.
+     */
+    preserveTrailingSpaces?: boolean;
+    /**
+     * The line ending format to use (`'lf'` for Unix/Linux, `'crlf'` for Windows).
+     * Default is `'lf'`.
+     */
+    lineEnding?: 'lf' | 'crlf';
+    /**
+     * Character to use for empty cells (when no character is rendered).
+     * Default is a space `' '`.
+     */
+    emptyCharacter?: string;
+};
+/**
+ * Internal options used by TXT generation (with all defaults applied).
+ */
+export interface TXTGenerationOptions {
+    preserveTrailingSpaces: boolean;
+    lineEnding: 'lf' | 'crlf';
+    emptyCharacter: string;
+}
+/**
+ * Re-export shared types from SVG module that are also used by TXT exporter
+ */
+export type { FramebufferData } from '../svg/types';

package/dist/types/index.d.ts

@@ -5,7 +5,8 @@ export { TextmodeCanvas } from './textmode/Canvas';
 export { TextmodeGrid } from './textmode/Grid';
 export type { TextmodeOptions } from './textmode/Textmodifier';
 export type { TextmodeCharacter } from './textmode/font';
-export type { SVGExportOptions } from './export/svg';
+/** All types related to export options for different formats. */
+export * as ExportOptions from './export';
 export { TextmodeConversionPipeline } from './textmode/ConversionPipeline';
 export { TextmodeErrorLevel } from './errors/ErrorHandler';
 /** Contains all converters that can be added to a rendering pipeline to shape the textmode output. */

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

@@ -64,6 +64,7 @@ export declare class TextmodeConversionPipeline {
      * @ignore
      */
     resize(): void;
+    hasEnabledConverters(): boolean;
     /** Returns the character framebuffer containing the combined result of all converters. @ignore */
     get characterFramebuffer(): Framebuffer;
     /** Returns the primary color framebuffer containing the combined result of all converters. @ignore */