textmode.js 0.9.0 → 0.9.1

package/dist/types/Textmode.d.ts

@@ -0,0 +1,133 @@
+import { type TextmodeErrorLevel } from './errors';
+import { Textmodifier } from './textmode/Textmodifier';
+import type { TextmodeOptions } from './textmode/types';
+/**
+ * The main entry point for the `textmode.js` library.
+ *
+ * Provides static methods for creating {@link Textmodifier} instances and managing global settings.
+ *
+ * @example
+ * ```javascript
+ * // Basic usage pattern
+ * const t = textmode.create({
+ *   width: window.innerWidth,
+ *   height: window.innerHeight
+ * });
+ *
+ * t.draw(() => {
+ *   t.background(0);
+ *   t.charColor(255);
+ *   t.char('T');
+ *   t.rect(5, 5);
+ * });
+ *
+ * t.windowResized(() => {
+ *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+ * });
+ * ```
+ */
+export declare class Textmode {
+    private constructor();
+    /**
+     * Create a new {@link Textmodifier} instance with optional configuration.
+     * @param opts Configuration options for the Textmodifier instance
+     * @returns A new Textmodifier instance
+     *
+     * @example
+     * ```javascript
+     * // Initialize with custom font size and responsive canvas
+     * const t = textmode.create({
+     *   width: window.innerWidth,
+     *   height: window.innerHeight,
+     *   fontSize: 16
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(10, 15, 20);
+     *
+     *   // Draw a field of rhythmic characters
+     *   for (let x = -20; x <= 20; x += 5) {
+     *     for (let y = -15; y <= 15; y += 5) {
+     *       const dist = Math.sqrt(x*x + y*y);
+     *       const offset = Math.sin(t.frameCount * 0.1 - dist * 0.5) * 2;
+     *
+     *       t.push();
+     *       t.translate(x, y + offset);
+     *       t.charColor(255 - dist * 10, 150, 200);
+     *       t.char(dist < 10 ? '█' : '░');
+     *       t.point();
+     *       t.pop();
+     *     }
+     *   }
+     * });
+     *
+     * t.windowResized(() => {
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    static create(opts?: TextmodeOptions): Textmodifier;
+    /**
+     * Set the global error handling level for the library. This applies to all {@link Textmodifier} instances present.
+     *
+     * @param level The error handling level to set.
+     *
+     * @example
+     * ```javascript
+     * // Configuring error behavior
+     * import { TextmodeErrorLevel } from 'textmode.js';
+     *
+     * // Suppress non-critical warnings in production
+     * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
+     *
+     * const t = textmode.create({ width: window.innerWidth, height: window.innerHeight });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('!');
+     *   t.charColor(255, 255, 0);
+     *   t.rect(10, 10);
+     * });
+     *
+     * t.windowResized(() => {
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    static setErrorLevel(level: TextmodeErrorLevel): void;
+    /**
+     * Returns the version of `textmode.js` being used.
+     *
+     * @returns The version string of the library.
+     *
+     * @example
+     * ```javascript
+     * // Display the library version in a retro terminal style
+     * const t = textmode.create({ width: window.innerWidth, height: window.innerHeight });
+     *
+     * const v = `VERSION: ${textmode.version}`;
+     *
+     * t.draw(() => {
+     *   t.background(0, 20, 0); // CRT Dark Green
+     *
+     *   t.push();
+     *   t.translate(-v.length / 2, 0);
+     *   t.charColor(0, 255, 0);
+     *
+     *   for (let i = 0; i < v.length; i++) {
+     *     t.push();
+     *     t.translate(i, 0);
+     *     t.char(v[i]);
+     *     t.point();
+     *     t.pop();
+     *   }
+     *   t.pop();
+     * });
+     *
+     * t.windowResized(() => {
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    static get version(): string;
+}

package/dist/types/errors/Error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Custom error class for textmode.js exceptions.
+ *
+ * Provides formatted error messages with optional context data to help
+ * debug issues.
+ *
+ */
+export declare class TextmodeError extends Error {
+    /**
+     * Creates a new TextmodeError instance.
+     * @param message The main error message
+     * @param context Optional context data to include in the error message
+     */
+    constructor(message: string, context?: Record<string, unknown>);
+    /**
+     * Create a formatted error message that includes context
+     * @ignore
+     */
+    static $createFormattedMessage(message: string, context?: Record<string, unknown>): string;
+    /**
+     * Format values for better display in error messages
+     */
+    private static _formatValue;
+}

package/dist/types/errors/ErrorHandler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Error handling levels to control how errors are reported and handled.
+ *
+ * Determines how validation failures and errors are processed throughout the library.
+ * Each level provides different behavior for error reporting and execution flow control.
+ *
+ * > [!NOTE]
+ * > This feature is currently not fully implemented across all modules,
+ * > and most `textmode.js` functions will still throw errors if used incorrectly.
+ *
+ * @example
+ * ```js
+ * // Set to `WARNING` level to log errors without stopping execution
+ * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
+ * ```
+ */
+export declare enum TextmodeErrorLevel {
+    /**
+     * Suppress all error output.
+     * Validation failures are handled silently without any console messages.
+     */
+    SILENT = 0,
+    /**
+     * Log validation failures as warnings.
+     */
+    WARNING = 1,
+    /**
+     * Log validation failures as errors.
+     */
+    ERROR = 2,
+    /**
+     * Throw exceptions on validation failures *(default behavior)*.
+     */
+    THROW = 3
+}
+/**
+ * Options for configuring the error handler.
+ * @ignore
+ */
+export interface ErrorHandlerOptions {
+    /** Global error level */
+    globalLevel: TextmodeErrorLevel;
+}
+/**
+ * Singleton error handler for textmode.js
+ * This class handles errors based on the configured error level.
+ * It can log warnings, errors, or throw exceptions based on the global error level.
+ * @ignore
+ */
+export declare class TextmodeErrorHandler {
+    private static _instance;
+    private _options;
+    private constructor();
+    static $getInstance(): TextmodeErrorHandler;
+    /**
+     * Handle an error based on the configured settings
+     * @returns true if execution should continue, false if error was handled
+     */
+    private _handle;
+    /**
+     * Validate a condition and handle errors if validation fails
+     * @param condition The condition to validate
+     * @param message Error message if validation fails
+     * @param context Additional context for debugging
+     * @returns true if validation passed, false if validation failed and was handled
+     */
+    $validate(condition: boolean, message: string, context?: Record<string, unknown>): boolean;
+    /**
+     * Set global error level
+     */
+    $setGlobalLevel(level: TextmodeErrorLevel): void;
+}
+/**
+ * Singleton instance of the textmode.js error handler.
+ * @ignore
+ */
+export declare const errorHandler: TextmodeErrorHandler;

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

@@ -0,0 +1,2 @@
+export { TextmodeError } from './Error';
+export { TextmodeErrorHandler, errorHandler, TextmodeErrorLevel, type ErrorHandlerOptions } from './ErrorHandler';

package/dist/types/exports/conversion.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/conversion';

package/dist/types/exports/filters.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/filters';

package/dist/types/exports/input.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/managers';

package/dist/types/exports/layering.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/layers';

package/dist/types/exports/loadables.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/loadables';

package/dist/types/exports/loading.d.ts

@@ -0,0 +1 @@
+export * from '../textmode/loading';

package/dist/types/exports/plugins.d.ts

@@ -0,0 +1 @@
+export type { TextmodePlugin, TextmodePluginAPI, TextmodePluginHook, LayerLifecycleHook, LayerRenderHook, SetupLifecycleHook, } from '../textmode/managers/PluginManager';

package/dist/types/index.d.ts

@@ -0,0 +1,85 @@
+import { Textmode } from './Textmode';
+export { Textmodifier } from './textmode/Textmodifier';
+export { GLFramebuffer as TextmodeFramebuffer } from './rendering';
+export { TextmodeColor } from './textmode/TextmodeColor';
+export { TextmodeCanvas } from './textmode/Canvas';
+export { TextmodeGrid } from './textmode/Grid';
+export type { TextmodeOptions } from './textmode/types';
+export type { TextmodeFramebufferOptions } from './rendering/webgl';
+/**
+ * All media conversion related modules and types.
+ *
+ * Responsible for converting images and videos into textmode-renderable formats
+ * using various conversion strategies, like brightness- or edge-detection-based conversion.
+ *
+ * `textmode.js` only comes with a built-in `'brightness'`-based conversion strategy,
+ * but custom strategies can be registered via {@link TextmodeConversionManager.register}.
+ */
+export * as conversion from './textmode/conversion';
+/**
+ * Plugin system types for extending textmode.js functionality.
+ *
+ * Plugins can:
+ * - Add methods to TextmodeLayer instances (e.g., `.synth()`)
+ * - Hook into the render lifecycle (pre/post draw, per-layer rendering)
+ * - React to layer creation and disposal events
+ * - Access the WebGL renderer, framebuffers, and other internals
+ *
+ * @example
+ * ```ts
+ * import type { TextmodePlugin, TextmodePluginAPI } from 'textmode.js/plugins';
+ *
+ * const MyPlugin: TextmodePlugin = {
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install(textmodifier, api) {
+ *     // Extend layers with a new method
+ *     api.extendLayer('setMyState', function(value: number) {
+ *       // `this` is bound to the TextmodeLayer instance
+ *       this.setPluginState('my-plugin', { value });
+ *     });
+ *
+ *     // Hook into layer rendering
+ *     api.registerLayerPreRenderHook((layer) => {
+ *       const state = layer.getPluginState<{ value: number }>('my-plugin');
+ *       if (state && state.value > 0.5) {
+ *         // Render custom content based on plugin state
+ *       }
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export * as plugins from './textmode/managers/PluginManager';
+/**
+ * All filter related modules and types.
+ *
+ * Provides various image processing filters that can be applied in sequence on a layer's textmode-converted output,
+ * such as blur, sharpen, edge detection, and color adjustments. Filters can also be applied globally to all layers as post-processing effects.
+ *
+ * While `textmode.js` only offers a basic set of filters, additional filters can be implemented and registered via the {@link TextmodeFilterManager},
+ * which is accessible through {@link Textmodifier.filters}.
+ */
+export * as filters from './textmode/filters';
+export { TextmodeErrorLevel } from './errors/ErrorHandler';
+export { TextmodeError } from './errors/Error';
+export { GLShader as TextmodeShader } from './rendering/webgl/core/Shader';
+export { Textmode as textmode } from './Textmode';
+/** All loading screen related modules and types. */
+export * as loading from './textmode/loading';
+/** All loadable assets related to textmode rendering. */
+export * as loadables from './textmode/loadables';
+/** All types and interfaces related to input event handling. */
+export * as input from './textmode/managers';
+/** All modules and types related to multi-layered textmode rendering. */
+export * as layering from './textmode/layers';
+/**
+ * Exports the create, setErrorLevel, and version functions from the Textmode class for UMD compatibility,
+ * so calls like `textmode.create()` can be used.
+ */
+/** @ignore */
+export declare const create: typeof Textmode.create;
+/** @ignore */
+export declare const setErrorLevel: typeof Textmode.setErrorLevel;
+/** @ignore */
+export declare const version: string;

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

@@ -0,0 +1,4 @@
+export { GLShader } from './webgl/core/Shader';
+export type { UniformValue } from './webgl/types/UniformTypes';
+export { GLRenderer } from './webgl/core/Renderer';
+export { GLFramebuffer } from './webgl/core/Framebuffer';

package/dist/types/rendering/webgl/batching/DrawQueue.d.ts

@@ -0,0 +1,89 @@
+import { RenderState } from '../state/RenderState';
+import type { DrawCommand } from '../types/DrawCommand';
+import type { Material } from '../materials/Material';
+import type { RectangleParams, LineParams, EllipseParams, ArcParams, TriangleParams, BezierCurveParams } from '../types/GeometryTypes';
+/**
+ * Global draw queue preserving user-issued draw order across geometry types.
+ *
+ * Performance optimizations:
+ * - Object pooling: Command slots are reused across frames to eliminate allocations
+ * - Direct property assignment: Maintains V8 hidden classes for optimal JIT performance
+ * - Type-specific enqueue methods: Eliminates conditional branching
+ */
+export declare class DrawQueue implements Iterable<DrawCommand> {
+    private _commands;
+    private _nextId;
+    private _size;
+    /** Reserve or reuse a pooled slot */
+    private _acquireSlot;
+    /**
+     * Enqueue a rectangle draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Rectangle parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueRectangle(params: RectangleParams, renderState: RenderState, material: Material): number;
+    /**
+     * Enqueue a line draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Line parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueLine(params: LineParams, renderState: RenderState, material: Material): number;
+    /**
+     * Enqueue an ellipse draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Ellipse parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueEllipse(params: EllipseParams, renderState: RenderState, material: Material): number;
+    /**
+     * Enqueue an arc draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Arc parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueArc(params: ArcParams, renderState: RenderState, material: Material): number;
+    /**
+     * Enqueue a triangle draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Triangle parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueTriangle(params: TriangleParams, renderState: RenderState, material: Material): number;
+    /**
+     * Enqueue a bezier curve draw command.
+     * Zero-allocation in steady state (reuses pooled slots).
+     * Direct property assignment preserves V8 hidden classes for optimal performance.
+     *
+     * @param params Bezier curve parameters
+     * @param renderState Current render state
+     * @param material Material to use for rendering
+     * @returns Command ID
+     */
+    $enqueueBezierCurve(params: BezierCurveParams, renderState: RenderState, material: Material): number;
+    /** Clear all queued commands */
+    $clear(): void;
+    /** Iterate in the exact order of insertion */
+    [Symbol.iterator](): Iterator<DrawCommand>;
+}

package/dist/types/rendering/webgl/batching/GeometryAttributeCache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal VAO manager that caches unit-geometry attribute setup per (program, geometry type).
+ * It binds only non-instanced attributes (a_position, a_texCoord). Instanced attributes are
+ * still configured by InstanceBatch per draw to keep buffers flexible.
+ */
+import { GLShader } from '../core/Shader';
+import type { UnitGeometryData } from '../types/GeometryTypes';
+export declare class GeometryAttributeCache {
+    private _gl;
+    private _cache;
+    private _currentVAO;
+    constructor(gl: WebGL2RenderingContext);
+    /** Bind or create a VAO for the given program and geometry key. */
+    $bind(shader: GLShader, geometryKey: string, unit: UnitGeometryData, geometryBuffer: WebGLBuffer): void;
+    private _onShaderDisposed;
+    $unbind(): void;
+    $dispose(): void;
+}

package/dist/types/rendering/webgl/batching/InstanceAttributeBinder.d.ts

@@ -0,0 +1,83 @@
+import { GLShader } from '../core/Shader';
+/**
+ * Manages WebGL attribute binding and GPU buffer synchronization.
+ *
+ * Responsibilities:
+ * - WebGL buffer creation and management
+ * - GPU data upload (full buffer or sub-buffer updates)
+ * - Attribute location caching per shader program
+ * - Vertex attribute binding/unbinding
+ *
+ * This class is the ONLY one that knows about WebGL state.
+ * It has NO knowledge of instance data layout details (delegates to InstanceAttributeLayout).
+ */
+export declare class InstanceAttributeBinder {
+    private _gl;
+    private _glBuffer;
+    private _bufferCapacity;
+    private _attributeLocationCache;
+    private _version;
+    private _programSetupCache;
+    /**
+     * Create a new attribute binder.
+     * @param gl WebGL2 rendering context
+     * @param initialCapacity Initial GPU buffer capacity in instances
+     */
+    constructor(gl: WebGL2RenderingContext, initialCapacity?: number);
+    /**
+     * Create or recreate the WebGL buffer with specified capacity.
+     * @param capacity Buffer capacity in number of instances
+     */
+    private _createBuffer;
+    /**
+     * Recreate GPU buffer with new capacity.
+     * Called when CPU buffer grows beyond current GPU buffer capacity.
+     *
+     * @param newCapacity New capacity in number of instances
+     */
+    $recreateBuffer(newCapacity: number): void;
+    /**
+     * Get the current GPU buffer capacity in instances.
+     */
+    get $capacity(): number;
+    /**
+     * Upload instance data to GPU buffer.
+     *
+     * Performance-critical: This uploads data to the GPU every frame.
+     * Optimizations applied:
+     * - Only uploads used portion of buffer (not full capacity)
+     * - Uses bufferSubData for partial updates (faster than bufferData)
+     * - Binds buffer once and keeps it bound for attribute setup
+     *
+     * Pattern follows modern graphics engines (three.js, babylon.js):
+     * - Minimize data transfer size
+     * - Avoid redundant buffer bindings
+     * - Use streaming pattern for per-frame data
+     *
+     * @param data Float32Array containing instance data to upload
+     * @param instanceCount Number of instances in the data
+     */
+    $upload(data: Float32Array, instanceCount: number): void;
+    /**
+     * Get cached attribute locations for a shader program.
+     * Queries locations once per program and caches them for performance.
+     *
+     * @param program WebGL shader program
+     * @returns Map of attribute name to location
+     */
+    private _getAttributeLocations;
+    /**
+     * Bind instance buffer and configure vertex attributes for instanced rendering.
+     *
+     * IMPORTANT: Assumes instance buffer is already bound to gl.ARRAY_BUFFER from upload().
+     * If upload() was not called immediately before this, the buffer will not be bound correctly.
+     * The buffer remains bound after this call for use by the draw command.
+     *
+     * @param shader The shader program to bind attributes for
+     */
+    $bindAttributes(shader: GLShader): void;
+    /**
+     * Dispose of WebGL resources.
+     */
+    $dispose(): void;
+}

package/dist/types/rendering/webgl/batching/InstanceBatch.d.ts

@@ -0,0 +1,87 @@
+import { type InstanceData } from './InstanceData';
+import { GLShader } from '../core/Shader';
+import { InstanceBuffer } from './InstanceBuffer';
+import { InstanceWriter, type InstanceWriteData } from './InstanceWriter';
+export type { InstanceWriteData };
+/**
+ * High-performance instance batch manager for WebGL instanced rendering.
+ *
+ * This is a facade that orchestrates three specialized components:
+ * - InstanceBuffer: CPU-side memory management
+ * - InstanceWriter: Zero-allocation instance data writing
+ * - InstanceAttributeBinder: WebGL state and attribute binding
+ *
+ * Features:
+ * - Direct Float32Array writing (zero allocations per instance)
+ * - Automatic buffer growth with configurable growth factor
+ * - Efficient sub-buffer updates for animated content
+ * - Optimized WebGL attribute binding
+ * - Struct-of-arrays layout for maximum GPU efficiency
+ *
+ * Architecture:
+ * This class maintains the same public API as before but delegates work
+ * to specialized components. This improves maintainability and testability
+ * while preserving performance.
+ */
+export declare class InstanceBatch {
+    private _gl;
+    private readonly _buffer;
+    private readonly _writer;
+    private readonly _binder;
+    /**
+     * Creates a new instance batch.
+     * @param gl WebGL2 rendering context
+     * @param initialCapacity Initial buffer capacity (number of instances)
+     * @param growthFactor Buffer growth factor when capacity is exceeded
+     */
+    constructor(gl: WebGL2RenderingContext, initialCapacity?: number, growthFactor?: number);
+    /**
+     * Add a new instance to the batch (legacy object-based path).
+     * @param instance Instance data to add
+     * @returns Index of the added instance
+     */
+    $addInstance(instance: InstanceData): number;
+    /**
+     * Synchronize GPU buffer capacity with CPU buffer capacity.
+     * Must be called after writing directly to the instance buffer.
+     */
+    $syncGPUBuffer(): void;
+    /**
+     * Get the underlying instance buffer for direct write access.
+     * @internal Performance optimization for BaseGeometry
+     */
+    get instanceBuffer(): InstanceBuffer;
+    /**
+     * Get the underlying instance writer for direct write access.
+     * @internal Performance optimization for BaseGeometry
+     */
+    get writer(): InstanceWriter;
+    /**
+     * Get the current number of instances in the batch.
+     */
+    get $count(): number;
+    /**
+     * Check if the batch is empty.
+     */
+    get $isEmpty(): boolean;
+    /**
+     * Clear all instances from the batch.
+     */
+    $clear(): void;
+    /**
+     * Bind instance buffer and configure vertex attributes for instanced rendering.
+     * @param shader The shader program to bind attributes for
+     */
+    $bindAttributes(shader: GLShader): void;
+    /**
+     * Execute instanced draw call for all instances in the batch.
+     * @param primitiveType WebGL primitive type (e.g., gl.TRIANGLES)
+     * @param vertexCount Number of vertices in the base geometry
+     */
+    $draw(primitiveType: number, vertexCount: number): void;
+    /**
+     * Dispose of WebGL resources.
+     * Call this when the batch is no longer needed.
+     */
+    $dispose(): void;
+}