textmode.js 0.3.2-beta.1 → 0.3.2-beta.3

package/dist/types/textmode/plugins/PluginManager.d.ts

@@ -0,0 +1,45 @@
+import type { Textmodifier } from '../Textmodifier';
+import type { GLRenderer } from '../../rendering/webgl/Renderer';
+import type { GLFramebuffer } from '../../rendering';
+import type { TextmodeFont } from '../font';
+import type { TextmodeGrid } from '../Grid';
+import type { TextmodeCanvas } from '../Canvas';
+export type TextmodePluginHook = () => void;
+export interface TextmodePluginContext {
+    readonly renderer: GLRenderer;
+    readonly font: TextmodeFont;
+    readonly grid: TextmodeGrid;
+    readonly canvas: TextmodeCanvas;
+    readonly drawFramebuffer: GLFramebuffer;
+    readonly asciiFramebuffer: GLFramebuffer;
+    flushDrawCommands(): void;
+}
+export interface TextmodePluginAPI extends TextmodePluginContext {
+    registerPreDrawHook(callback: TextmodePluginHook): () => void;
+    registerPostDrawHook(callback: TextmodePluginHook): () => void;
+}
+export interface TextmodePlugin {
+    name: string;
+    version?: string;
+    install(textmodifier: Textmodifier, api: TextmodePluginAPI): void | Promise<void>;
+    uninstall?(textmodifier: Textmodifier, api: TextmodePluginAPI): void | Promise<void>;
+}
+export declare class PluginManager {
+    private readonly _textmodifier;
+    private readonly _plugins;
+    private readonly _installationOrder;
+    private readonly _preDrawHooks;
+    private readonly _postDrawHooks;
+    constructor(textmodifier: Textmodifier);
+    installMany(plugins: TextmodePlugin[]): Promise<void>;
+    use(plugin: TextmodePlugin): Promise<void>;
+    unuse(pluginName: string): Promise<void>;
+    has(pluginName: string): boolean;
+    runPreDrawHooks(): void;
+    runPostDrawHooks(): void;
+    disposeAll(): Promise<void>;
+    private _createAPI;
+    private _registerHook;
+    private _removePluginHooks;
+    private _runHooks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.3.2-beta.1",
+  "version": "0.3.2-beta.3",
   "description": "textmode.js is a lightweight creative coding library for creating real-time ASCII art on the web.",
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -23,8 +23,8 @@
     "build": "vite build && vite build --mode min && tsc",
     "build:full": "vite build && tsc",
     "build:min": "vite build --mode min && tsc",
-    "build-docs": "typedoc",
-    "dev-docs": "typedoc --watch",
+    "build:docs": "typedoc",
+    "dev:docs": "typedoc --watch",
     "preview": "vite preview",
     "test": "vitest",
     "test:ui": "vitest --ui",

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

@@ -1,27 +0,0 @@
-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

@@ -1,16 +0,0 @@
-import type { TextmodeCanvas } from '../../index';
-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 canvas The canvas data containing the rendered textmode graphics
-     * @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(canvas: TextmodeCanvas, scale?: number, backgroundColor?: string): HTMLCanvasElement;
-}

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

@@ -1,38 +0,0 @@
-import type { ImageExportOptions, ImageGenerationOptions } from './types';
-import type { TextmodeCanvas } from '../../index';
-/**
- * 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 blob from textmode rendering without saving to file
-     * @param canvasData The canvas data containing the rendered textmode graphics
-     * @param options Export options
-     * @returns Promise that resolves to a Blob containing the image data
-     */
-    $generateImageBlob(canvas: TextmodeCanvas, options: ImageGenerationOptions): Promise<Blob>;
-    /**
-     * Exports image to a downloadable file
-     * @param canvas The canvas data containing the rendered textmode graphics
-     * @param options Export options
-     */
-    $saveImage(canvas: TextmodeCanvas, options?: ImageExportOptions): Promise<void>;
-}

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

@@ -1,27 +0,0 @@
-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: Blob, filename: string, format: ImageFormat): void;
-    /**
-     * Saves image from blob
-     * @param blob The blob containing image data
-     * @param filename The complete filename with extension
-     */
-    private _saveImageFromBlob;
-    /**
-     * 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;
-}

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

@@ -1,6 +0,0 @@
-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

@@ -1,62 +0,0 @@
-/**
- * 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).
-     */
-    filename?: string;
-    /**
-     * The image format to export (`'png'`, `'jpg'`, or `'webp'`).
-     */
-    format?: 'png' | 'jpg' | 'webp';
-    /**
-     * 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.
-     *
-     * Default is `'black'`.
-     */
-    backgroundColor?: string;
-};
-/**
- * Internal options used by image generation (with all defaults applied).
- */
-export interface ImageGenerationOptions {
-    filename: string;
-    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/txt/TXTContentGenerator.d.ts

@@ -1,14 +0,0 @@
-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

@@ -1,19 +0,0 @@
-import type { FramebufferData } from './types';
-import { DataExtractor } from '../base';
-import type { TextmodeGrid } from '../../textmode/Grid';
-import type { TextmodeFont } from '../../textmode/font';
-/**
- * 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

@@ -1,31 +0,0 @@
-import type { TXTExportOptions, TextmodeRenderingData } 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 renderingData The textmode rendering data containing pipeline, grid, and font
-     * @param options Export options (excluding filename)
-     * @returns TXT content as string
-     */
-    $generateTXT(renderingData: TextmodeRenderingData, options?: TXTExportOptions): string;
-    /**
-     * Exports TXT content to a downloadable file
-     * @param renderingData The textmode rendering data containing pipeline, grid, and font
-     * @param options Export options including filename
-     */
-    $saveTXT(renderingData: TextmodeRenderingData, options?: TXTExportOptions): void;
-}

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

@@ -1,19 +0,0 @@
-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;
-    /**
-     * 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

@@ -1,5 +0,0 @@
-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

@@ -1,55 +0,0 @@
-/**
- * TXT-specific type definitions for the textmode.js library.
- */
-import type { TextmodeFont, TextmodeGrid } from '../..';
-/**
- * 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;
-    filename: string;
-}
-/**
- * Data required for textmode rendering export
- */
-export interface TextmodeRenderingData {
-    pipeline: any;
-    grid: TextmodeGrid;
-    font: TextmodeFont;
-}
-/**
- * Re-export shared types from SVG module that are also used by TXT exporter
- */
-export type { FramebufferData } from '../svg/types';

package/dist/types/textmode/mixins/ExportMixin.d.ts

@@ -1,128 +0,0 @@
-import type { Mixin } from './TextmodifierMixin';
-import { type SVGExportOptions } from '../../export/svg';
-import { type TXTExportOptions } from '../../export/txt';
-import { type ImageExportOptions } from '../../export/image';
-/**
- * Interface for export capabilities that will be mixed into Textmodifier
- */
-export interface ExportCapabilities {
-    /**
-     * Generate the current textmode rendering as a text string.
-     * @param options Options for text generation *(excluding filename)*
-     * @returns Textmode grid content as a string.
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
-     *
-     * // Get the current rendering as a text string
-     * const textString = textmodifier.toString({
-     *   preserveTrailingSpaces: false,
-     *   lineEnding: 'lf'
-     * });
-     *
-     * // Print to console or use otherwise
-     * console.log(textString);
-     * ```
-     */
-    toString(options?: TXTExportOptions): string;
-    /**
-     * Export the current textmode rendering to a TXT file.
-     * @param options Options for TXT export
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
-     *
-     * // Export the current rendering to a TXT file
-     * textmodifier.saveStrings({
-     *   filename: 'my_textmode_rendering',
-     *   preserveTrailingSpaces: false
-     * });
-     * ```
-     */
-    saveStrings(options?: TXTExportOptions): void;
-    /**
-     * Generate the current textmode rendering as an SVG string.
-     * @param options Options for SVG generation *(excluding filename)*
-     * @returns SVG content as a string.
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
-     *
-     * // Get the current rendering as an SVG string
-     * const svgString = textmodifier.toSVG({
-     *   includeBackgroundRectangles: true,
-     *   drawMode: 'fill'
-     * });
-     *
-     * // Print to console or use otherwise
-     * console.log(svgString);
-     * ```
-     */
-    toSVG(options?: SVGExportOptions): string;
-    /**
-     * Export the current textmode rendering to an SVG file.
-     * @param options Options for SVG export
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
-     *
-     * // Export the current rendering to an SVG file
-     * textmodifier.saveSVG({
-     *   filename: 'my_textmode_rendering',
-     * });
-     * ```
-     */
-    saveSVG(options?: SVGExportOptions): void;
-    /**
-     * Export the current textmode rendering to an image file.
-     * @param options Options for image export
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create(canvas, {renderMode: 'manual'});
-     *
-     * // Export the current rendering to a PNG file *(default)*
-     * textmodifier.saveCanvas();
-     *
-     * // Export with custom options
-     * textmodifier.saveCanvas({
-     *   filename: 'my_textmode_rendering',
-     *   format: 'jpg',
-     *   quality: 0.8,
-     *   scale: 2.0,
-     *   backgroundColor: 'white'
-     * });
-     * ```
-     */
-    saveCanvas(options?: ImageExportOptions): Promise<void>;
-}
-/**
- * Mixin that adds export capabilities to a class
- * @param Base The base class to extend
- * @returns Extended class with export capabilities
- */
-export declare const ExportMixin: Mixin<ExportCapabilities>;