textmode.js 0.3.2-beta.2 → 0.4.0

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

@@ -0,0 +1,76 @@
+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 {
+    /** The WebGL renderer used by the Textmodifier instance. */
+    renderer: GLRenderer;
+    /** The font used by the Textmodifier instance. */
+    font: TextmodeFont;
+    /** The grid used by the Textmodifier instance. */
+    grid: TextmodeGrid;
+    /** The canvas used by the Textmodifier instance. */
+    canvas: TextmodeCanvas;
+    /** The framebuffer the user draws to. */
+    drawFramebuffer: GLFramebuffer;
+    /** The framebuffer containing the ASCII representation. */
+    asciiFramebuffer: GLFramebuffer;
+    /** Immediately execute any pending draw commands. */
+    flushDrawCommands(): void;
+}
+/**
+ * An extended API provided to plugins when they are installed on a {@link Textmodifier} instance.
+ */
+export interface TextmodePluginAPI extends TextmodePluginContext {
+    /**
+     * Register a callback to be invoked before each draw cycle. Happens outside of the draw framebuffer being bound.
+     */
+    registerPreDrawHook(callback: () => void): () => void;
+    /**
+     * Register a callback to be invoked after each draw cycle. Happens outside of the draw framebuffer being bound.
+     */
+    registerPostDrawHook(callback: () => void): () => void;
+}
+/**
+ * A plugin interface for extending the functionality of a {@link Textmodifier} instance.
+ *
+ * Users can create plugins by implementing this interface.
+ */
+export interface TextmodePlugin {
+    /** Unique name for the plugin. */
+    name: string;
+    /** Version string for the plugin. */
+    version?: string;
+    /**
+     * Called when the plugin is installed on a {@link Textmodifier} instance.
+     * @param textmodifier The Textmodifier instance the plugin is being installed on.
+     * @param api An API object providing access to the Textmodifier's context and hook registration methods.
+     */
+    install(textmodifier: Textmodifier, api: TextmodePluginAPI): void | Promise<void>;
+    /**
+     * Called when the plugin is uninstalled from a {@link Textmodifier} instance.
+     * @param textmodifier The Textmodifier instance the plugin is being uninstalled from.
+     * @param api An API object providing access to the Textmodifier's context and hook registration methods.
+     */
+    uninstall?(textmodifier: Textmodifier, api: TextmodePluginAPI): void | Promise<void>;
+}
+export declare class TextmodePluginManager {
+    private readonly _textmodifier;
+    private readonly _plugins;
+    private readonly _installationOrder;
+    private readonly _preDrawHooks;
+    private readonly _postDrawHooks;
+    constructor(textmodifier: Textmodifier);
+    $installMany(plugins: TextmodePlugin[]): Promise<void>;
+    $unuse(pluginName: string): Promise<void>;
+    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.2",
+  "version": "0.4.0",
   "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/base/DataExtractor.d.ts

@@ -1,34 +0,0 @@
-import type { GLFramebuffer } from '../../rendering';
-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 framebuffer The conversion pipeline containing framebuffers
-     * @returns Object containing all pixel data arrays
-     */
-    $extractFramebufferData(framebuffer: GLFramebuffer): 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

@@ -1,46 +0,0 @@
-/**
- * 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;
-    /**
-     * 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;
-    /**
-     * 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
-     */
-    $generateDefaultFilename(): string;
-}

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

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

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

@@ -1,3 +0,0 @@
-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,76 +0,0 @@
-import type { SVGCellData, SVGGenerationOptions } from './types';
-import type { TextmodeFont, TextmodeGrid } from '../../index';
-/**
- * Generates SVG content and markup from processed cell data.
- * This class handles the creation of SVG elements, groups, and styling.
- */
-export declare class SVGContentGenerator {
-    private _pathGenerator;
-    constructor();
-    /**
-     * Generates the SVG header with metadata
-     * @param gridInfo Grid dimensions
-     * @returns SVG header string
-     */
-    $generateSVGHeader(gridInfo: TextmodeGrid): string;
-    /**
-     * Generates the SVG footer
-     * @returns SVG footer string
-     */
-    $generateSVGFooter(): string;
-    /**
-     * Generates background rectangle if needed
-     * @param gridInfo Grid information
-     * @param options SVG generation options
-     * @returns Background rectangle SVG string or empty string
-     */
-    $generateBackground(gridInfo: TextmodeGrid, options: SVGGenerationOptions): string;
-    /**
-     * Generates SVG transform attribute string
-     * @param cellData Cell data with transform information
-     * @param gridInfo Grid information for center calculations
-     * @returns Transform attribute string or empty string
-     */
-    private _generateTransformAttribute;
-    /**
-     * Generates background rectangle for a cell
-     * @param cellData Cell data
-     * @param gridInfo Grid information
-     * @param options SVG generation options
-     * @returns Background rectangle SVG string or empty string
-     */
-    private _generateCellBackground;
-    /**
-     * Generates character path element for a cell
-     * @param cellData Cell data
-     * @param gridInfo Grid information
-     * @param fontInfo Font information
-     * @param options SVG generation options
-     * @returns Character path SVG string
-     */
-    private _generateCharacterPath;
-    /**
-     * Generates complete SVG content for a single cell
-     * @param cellData Cell data
-     * @param gridInfo Grid information
-     * @param fontInfo Font information
-     * @param options SVG generation options
-     * @returns Complete cell SVG content
-     */
-    $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 grid Grid information
-     * @param fontInfo Font information
-     * @param options SVG generation options
-     * @returns Complete SVG 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
-     * @returns Optimized SVG content
-     */
-    $optimizeSVGContent(svgContent: string): string;
-}

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

@@ -1,33 +0,0 @@
-import type { FramebufferData, SVGCellData } from './types';
-import { DataExtractor } from '../base';
-import type { TextmodeGrid } from '../../index';
-/**
- * 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 extends DataExtractor {
-    /**
-     * Extracts transform data from transform pixels
-     * @param transformPixels Transform framebuffer pixels
-     * @param rotationPixels Rotation framebuffer pixels
-     * @param pixelIndex Pixel index in the array
-     * @returns Transform data object
-     */
-    private _extractTransformData;
-    /**
-     * Calculates cell position information
-     * @param x Grid X coordinate
-     * @param y Grid Y coordinate
-     * @param gridInfo Grid information
-     * @returns Position data object
-     */
-    private _calculateCellPosition;
-    /**
-     * Processes all grid cells and extracts SVG cell data
-     * @param framebufferData Raw pixel data from framebuffers
-     * @param grid Grid information
-     * @param font Font information
-     * @returns Array of SVG cell data objects
-     */
-    $extractSVGCellData(framebufferData: FramebufferData, grid: TextmodeGrid): SVGCellData[];
-}

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

@@ -1,31 +0,0 @@
-import type { SVGExportOptions, TextmodeRenderingData } from './types';
-/**
- * Main SVG exporter for the textmode.js library.
- * Orchestrates the SVG export process by coordinating data extraction,
- * content generation, and file handling.
- */
-export declare class SVGExporter {
-    private _dataExtractor;
-    private _contentGenerator;
-    private _fileHandler;
-    constructor();
-    /**
-     * Applies default values to SVG export options
-     * @param options User-provided options
-     * @returns Complete options with defaults applied
-     */
-    private _applyDefaultOptions;
-    /**
-     * Generates SVG 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 SVG content as string
-     */
-    $generateSVG(renderingData: TextmodeRenderingData, options?: SVGExportOptions): string;
-    /**
-     * Exports SVG content to a downloadable file
-     * @param renderingData The textmode rendering data containing pipeline, grid, and font
-     * @param options Export options including filename
-     */
-    $saveSVG(renderingData: TextmodeRenderingData, options?: SVGExportOptions): void;
-}

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

@@ -1,25 +0,0 @@
-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 extends FileHandler {
-    /**
-     * Creates a downloadable blob from SVG content
-     * @param svgContent The SVG content string
-     * @returns Blob object containing the SVG data
-     */
-    $createSVGBlob(svgContent: string): Blob;
-    /**
-     * Downloads SVG content as a file
-     * @param svgContent The SVG content to download
-     * @param filename The filename (without extension)
-     */
-    private _downloadSVG;
-    /**
-     * Saves SVG content with automatic filename generation if not provided
-     * @param svgContent The SVG content to save
-     * @param filename Optional filename (will generate if not provided)
-     */
-    $saveSVG(svgContent: string, filename?: string): void;
-}

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

@@ -1,56 +0,0 @@
-import type { TyprFont } from '../../textmode/font/typr/types.ts';
-/**
- * Handles SVG path generation for character glyphs.
- * This class is responsible for converting font glyph data into SVG path strings.
- */
-export declare class SVGPathGenerator {
-    /**
-     * Gets the glyph index for a given Unicode code point in a Typr.js font
-     * @param fontData The Typr.js font data
-     * @param codePoint The Unicode code point to look up
-     * @returns The glyph index, or 0 if not found
-     */
-    private _getGlyphIndex;
-    /**
-     * Creates a path object for a glyph
-     * @param fontData Font data object
-     * @param glyphData Glyph data from font
-     * @param x X position
-     * @param y Y position
-     * @param fontSize Font size
-     * @returns Path object with bounding box and SVG methods
-     */
-    private _createGlyphPath;
-    /**
-     * Converts glyph data to SVG path string
-     * @param glyphData Glyph data from font
-     * @param x X position
-     * @param y Y position
-     * @param scale Scale factor
-     * @returns SVG path data string
-     */
-    private _glyphToSVGPath;
-    /**
-     * Generates an SVG path for a character glyph
-     * @param character The character to generate a path for
-     * @param fontData The font data object
-     * @param x X position
-     * @param y Y position
-     * @param fontSize Font size
-     * @returns Path object with SVG generation methods
-     */
-    private _generateCharacterPath;
-    /**
-     * Generates SVG path data for a character with positioning calculations
-     * @param character The character to render
-     * @param fontData The font data
-     * @param cellX Cell X position
-     * @param cellY Cell Y position
-     * @param cellWidth Cell width
-     * @param cellHeight Cell height
-     * @param fontSize Font size
-     * @param advanceWidth Character advance width
-     * @returns SVG path data string or null if generation fails
-     */
-    $generatePositionedCharacterPath(character: string, fontData: TyprFont, cellX: number, cellY: number, cellWidth: number, cellHeight: number, fontSize: number, advanceWidth: number): string | null;
-}

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

@@ -1,6 +0,0 @@
-export { SVGExporter } from './SVGExporter';
-export { SVGDataExtractor } from './SVGDataExtractor';
-export { SVGContentGenerator } from './SVGContentGenerator';
-export { SVGPathGenerator } from './SVGPathGenerator';
-export { SVGFileHandler } from './SVGFileHandler';
-export type { SVGExportOptions, SVGGenerationOptions, SVGCellData, FramebufferData, RGBA, Position, CellPosition, CellTransform, GlyphPath } from './types';