textmode.js 0.2.0 → 0.2.1-beta.2

package/dist/types/rendering/webgl/RenderPipeline.d.ts

@@ -2,6 +2,10 @@ import type { IGeometry } from './types/GeometryTypes';
 import { GeometryType } from './types/GeometryTypes';
 import type { RenderContext } from './types/RenderTypes';
 import type { DrawCommand } from './types/DrawCommand';
+import { GLShader } from './Shader';
+interface IShaderProvider {
+    $getCopyShader(): GLShader;
+}
 /**
  * Execute draw commands exactly in the order they were enqueued while
  * still batching consecutive commands of the same geometry type to minimize
@@ -10,13 +14,16 @@ import type { DrawCommand } from './types/DrawCommand';
 export declare class RenderPipeline {
     private readonly _vaoMgr;
     private readonly _gl;
-    private _copyShader;
+    private readonly _renderer;
     private _tempRectFBO;
     private _tempRectFBOSize;
-    constructor(gl: WebGL2RenderingContext);
+    constructor(gl: WebGL2RenderingContext, renderer: IShaderProvider);
     $execute(context: RenderContext, commands: Iterable<DrawCommand>, geometries: Map<GeometryType, IGeometry>): void;
-    /** Immediate custom-rect draw using provided shader/uniforms; mirrors prior GLRenderer path */
+    /** Execute a custom-shaded rectangle using provided shader/uniforms */
     private _drawCustomRect;
+    /** Draw a rectangle with the specified shader, uniforms, and viewport handling */
+    private _drawRectangleWithShader;
     private _getCopyShader;
     private _getTempRectFBO;
 }
+export {};

package/dist/types/rendering/webgl/RenderState.d.ts

@@ -2,17 +2,17 @@
  * Represents a snapshot of the current rendering state
  */
 export interface IRenderState {
-    lineWeight: number;
-    rotationX: number;
-    rotationY: number;
-    rotationZ: number;
-    character: [number, number, number];
-    charColor: [number, number, number, number];
-    cellColor: [number, number, number, number];
-    flipHorizontally: boolean;
-    flipVertically: boolean;
-    invert: boolean;
-    charRotation: [number, number];
+    _lineWeight: number;
+    _rotationX: number;
+    _rotationY: number;
+    _rotationZ: number;
+    _character: [number, number, number];
+    _charColor: [number, number, number, number];
+    _cellColor: [number, number, number, number];
+    _flipHorizontally: boolean;
+    _flipVertically: boolean;
+    _invert: boolean;
+    _charRotation: [number, number];
 }
 /**
  * Manages rendering state and provides push/pop functionality for state management

package/dist/types/rendering/webgl/Renderer.d.ts

@@ -2,12 +2,14 @@ import { GLFramebuffer } from "./Framebuffer";
 import type { FramebufferOptions } from '../webgl/Framebuffer';
 import { GLShader } from "./Shader";
 import { RenderState } from "./RenderState";
+import type { ShaderSource } from './types/ShaderTypes';
 /**
  * Core WebGL renderer that manages the WebGL context and provides high-level rendering operations
  */
 export declare class GLRenderer {
     private _gl;
     private _currentShader;
+    private _shaderManager;
     private _userShader;
     private _userUniforms;
     private _ndcQuadBuffer;
@@ -15,6 +17,7 @@ export declare class GLRenderer {
     private readonly _renderPipeline;
     private readonly _drawQueue;
     private _renderState;
+    private _stateStack;
     constructor(gl: WebGL2RenderingContext);
     /** Get or create a geometry instance */
     private _getGeometry;
@@ -22,7 +25,19 @@ export declare class GLRenderer {
      * Set the current shader
      */
     $shader(shader: GLShader): void;
-    $createShader(vertexSource: string, fragmentSource: string): GLShader;
+    $createShader(vertexSource: ShaderSource, fragmentSource: ShaderSource): GLShader;
+    /**
+     * Get the shared MRT copy shader
+     */
+    $getCopyShader(): GLShader;
+    /**
+     * Get the main MRT draw shader
+     */
+    $getMainDrawShader(): GLShader;
+    /**
+     * Get the ASCII conversion shader
+     */
+    $getConversionShader(): GLShader;
     /**
      * Set a custom user shader for subsequent rendering operations
      */
@@ -30,7 +45,7 @@ export declare class GLRenderer {
     /**
      * Set a uniform value for the current user shader
      */
-    $setUserUniform(name: string, value: any): void;
+    $setUniform(name: string, value: any): void;
     /**
      * Set multiple uniform values for the current user shader
      */
@@ -39,6 +54,11 @@ export declare class GLRenderer {
      * Create a filter shader using the standard instanced vertex shader
      */
     $createFilterShader(fragmentSource: string): GLShader;
+    /**
+     * Enqueue an image blit from a source MRT framebuffer to the current render target.
+     * This uses the internal copy shader and preserves draw ordering within the pipeline.
+     */
+    $imageRect(src: GLFramebuffer, x: number, y: number, width: number, height: number): void;
     /**
      * Draw a quad covering the pixel rectangle (x, y, width, height) on the canvas.
      * The quad is converted to NDC and rendered with the current shader using only a_position.
@@ -109,6 +129,10 @@ export declare class GLRenderer {
      */
     get context(): WebGLRenderingContext;
     get state(): RenderState;
+    /** Internal: push a specific render state as current (used by user FBO begin) */
+    $pushState(state: RenderState): void;
+    /** Internal: pop the render state after user FBO end */
+    $popState(): void;
     /**
      * Flush all batched instances for instanced rendering.
      * This must be called at the end of each frame to actually render the batched geometry.

package/dist/types/rendering/webgl/Shader.d.ts

@@ -1,27 +1,26 @@
 import { GLFramebuffer } from './Framebuffer';
+import type { ShaderSource } from './types/ShaderTypes';
 /**
  * Supported uniform value types
  */
 type UniformValue = number | boolean | number[] | Float32Array | Int32Array | GLFramebuffer | WebGLTexture;
 /**
  * WebGL implementation of the shader abstraction.
- * Provides GPU shader program management with automatic uniform handling.
+ * Provides GPU shader program management with automatic uniform handling and minification support.
  */
 export declare class GLShader {
     private _gl;
     private _program;
     private _uniformLocations;
-    private _uniformTypes;
     private _textureUnitCounter;
-    private _maxTextureUnits;
     /**
      * Creates a new GLShader instance.
      * @param gl The WebGL rendering context.
-     * @param vertexSource The source code for the vertex shader.
-     * @param fragmentSource The source code for the fragment shader.
+     * @param vertexSource The source code for the vertex shader (or ShaderData object).
+     * @param fragmentSource The source code for the fragment shader (or ShaderData object).
      * @ignore
      */
-    constructor(gl: WebGLRenderingContext, vertexSource: string, fragmentSource: string);
+    constructor(gl: WebGLRenderingContext, vertexSource: ShaderSource, fragmentSource: ShaderSource);
     private _cacheLocations;
     private _createProgram;
     private _createShader;
@@ -39,7 +38,7 @@ export declare class GLShader {
      */
     $hasUniform(name: string): boolean;
     /**
-     * Set a single uniform value with automatic texture unit management
+     * Set a single uniform value with automatic texture unit management and minification support
      */
     $setUniform(name: string, value: UniformValue): void;
     private _getNextTextureUnit;

package/dist/types/rendering/webgl/ShaderManager.d.ts

@@ -1 +1,65 @@
-export {};
+import { GLShader } from './Shader';
+import type { ShaderSource } from './types/ShaderTypes';
+/**
+ * Registry keys for built-in shaders
+ */
+export declare enum BuiltInShader {
+    MRT_DRAW = "mrt-draw",
+    MRT_COPY = "mrt-copy",
+    ASCII_CONVERSION = "ascii-conversion"
+}
+/**
+ * Centralized shader management system for textmode.js
+ *
+ * Provides a registry pattern for managing shared shaders, eliminating
+ * duplication and providing a single source of truth for shader lifecycle.
+ *
+ * Key benefits:
+ * - Eliminates shader duplication (especially copy shader)
+ * - Centralizes vertex shader imports
+ * - Provides lazy initialization
+ * - Supports future extensibility (shader variants, hot-reloading)
+ * - Consistent resource management
+ */
+export declare class ShaderManager {
+    private _shaders;
+    private _gl;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Get or create a shader with lazy initialization
+     * @param key Unique identifier for the shader
+     * @param factory Function that creates the shader if it doesn't exist
+     * @returns The shader instance
+     */
+    $getOrCreateShader(key: string, factory: () => GLShader): GLShader;
+    /**
+     * Get the shared MRT copy shader used for framebuffer compositing
+     * This shader handles copying 5-attachment MRT data with proper transparency
+     */
+    $getCopyShader(): GLShader;
+    /**
+     * Get the main MRT draw shader used for standard geometry rendering
+     * This shader outputs to all 5 MRT attachments for textmode rendering
+     */
+    $getMainDrawShader(): GLShader;
+    /**
+     * Get the ASCII conversion shader used for final display output
+     * This shader converts MRT data to final ASCII characters
+     */
+    $getConversionShader(): GLShader;
+    /**
+     * Create a custom filter shader using the standard instanced vertex shader
+     * These shaders are not cached as they are user-specific
+     */
+    $createFilterShader(fragmentSource: string): GLShader;
+    /**
+     * Create a custom shader with arbitrary vertex and fragment sources
+     * These shaders are not cached as they are user-specific
+     */
+    $createCustomShader(vertexSource: ShaderSource, fragmentSource: ShaderSource): GLShader;
+    /**
+     * Dispose of all managed shaders and clear the registry
+     * This method is idempotent and safe to call multiple times
+     */
+    $dispose(): void;
+}

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

@@ -1,6 +1,7 @@
 export * from './Framebuffer';
 export * from './Renderer';
 export * from './Shader';
+export * from './ShaderManager';
 export * from './StateCache';
 export { GeometryType } from './types/GeometryTypes';
 export type { IGeometry as IInstancedGeometry, UnitGeometryData, RectangleParams, LineParams, EllipseParams, ArcParams, TriangleParams, BezierCurveParams, GeometryParams } from './types/GeometryTypes';

package/dist/types/rendering/webgl/types/GeometryTypes.d.ts

@@ -19,20 +19,20 @@ export declare enum GeometryType {
  */
 export interface UnitGeometryData {
     /** Vertex data as Float32Array (position + texCoord interleaved) */
-    vertices: Float32Array;
+    _vertices: Float32Array;
     /** Number of vertices in the geometry */
-    vertexCount: number;
+    _vertexCount: number;
     /** WebGL primitive type (gl.TRIANGLES, gl.LINES, etc.) */
-    primitiveType: number;
+    _primitiveType: number;
     /** Stride in bytes between vertices */
-    stride: number;
+    _stride: number;
     /** Attribute configuration for position and texCoord */
-    attributes: {
-        position: {
+    _attributes: {
+        _position: {
             size: number;
             offset: number;
         };
-        texCoord: {
+        _texCoord: {
             size: number;
             offset: number;
         };

package/dist/types/rendering/webgl/types/ShaderTypes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Interface for shader data with minification support
+ */
+export interface ShaderData {
+    /** The shader source code (minified in production, original in development) */
+    sourceCode: string;
+    /** Original unminified source code (available in development builds) */
+    originalCode?: string;
+    /** Mapping of original uniform names to minified names and types */
+    uniforms: Record<string, {
+        /** Minified uniform name used in the shader */
+        variableName: string;
+        /** GLSL type of the uniform (vec2, sampler2D, etc.) */
+        variableType: string;
+    }>;
+    /** Mapping of const variables (if any) */
+    consts: Record<string, {
+        /** Substitution value for the const */
+        variableName: string;
+        /** GLSL type of the const */
+        variableType: string;
+    }>;
+}
+/**
+ * Union type for shader imports - either ShaderData or plain string (for backward compatibility)
+ */
+export type ShaderSource = ShaderData | string;
+/**
+ * Helper to normalize shader source to ShaderData format
+ */
+export declare function normalizeShaderData(source: ShaderSource): ShaderData;
+/**
+ * Extract just the source code from ShaderSource
+ */
+export declare function getShaderCode(source: ShaderSource): string;

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

@@ -3,11 +3,15 @@ import { TextmodeFont } from './font';
 import { TextmodeGrid } from './Grid';
 import { TextmodeCanvas } from './Canvas';
 import { AnimationController } from './AnimationController';
+import { MouseManager } from './managers';
+import { KeyboardManager } from './managers';
 import { type TextmodifierContext } from './mixins';
 import type { RenderingCapabilities } from './mixins/RenderingMixin';
 import type { ExportCapabilities } from './mixins/ExportMixin';
 import type { FontCapabilities } from './mixins/FontMixin';
 import type { AnimationCapabilities } from './mixins/AnimationMixin';
+import type { MouseCapabilities } from './mixins/MouseMixin';
+import type { KeyboardCapabilities } from './mixins/KeyboardMixin';
 import type { GLFramebuffer, Shader } from '../rendering';
 /**
  * Options for creating a {@link Textmodifier} instance.
@@ -41,6 +45,8 @@ declare class TextmodifierCore implements TextmodifierContext {
     _canvas: TextmodeCanvas;
     _grid: TextmodeGrid;
     _animationController: AnimationController;
+    _mouseManager: MouseManager;
+    _keyboardManager: KeyboardManager;
     _textmodeDrawShader: Shader;
     _textmodeDrawFramebuffer: GLFramebuffer;
     _textmodeConversionShader: Shader;
@@ -211,8 +217,8 @@ export declare class Textmodifier extends Textmodifier_base {
     /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;
     /** Get the draw framebuffer used for offscreen rendering. @ignore */
-    get drawFramebuffer(): any;
+    get drawFramebuffer(): GLFramebuffer;
 }
-export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities, AnimationCapabilities {
+export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities, AnimationCapabilities, MouseCapabilities, KeyboardCapabilities {
 }
 export {};

package/dist/types/textmode/managers/KeyboardManager.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Key event data passed to event handlers
+ */
+export interface KeyboardEventData {
+    /** The key that was pressed/released (e.g., 'a', 'Enter', 'ArrowLeft') */
+    key: string;
+    /** The key code (for compatibility) */
+    keyCode: number;
+    /** Whether Ctrl key is held down */
+    ctrlKey: boolean;
+    /** Whether Shift key is held down */
+    shiftKey: boolean;
+    /** Whether Alt key is held down */
+    altKey: boolean;
+    /** Whether Meta key (Windows/Cmd) is held down */
+    metaKey: boolean;
+    /** Whether this key is currently being held down (for keyPressed) or was released (for keyReleased) */
+    isPressed: boolean;
+    /** Original DOM keyboard event */
+    originalEvent: KeyboardEvent;
+}
+/**
+ * Keyboard event handler function type
+ */
+export type KeyboardEventHandler = (data: KeyboardEventData) => void;
+/**
+ * Key state information
+ */
+export interface KeyState {
+    /** Whether the key is currently pressed */
+    isPressed: boolean;
+    /** Timestamp when the key was last pressed */
+    lastPressTime: number;
+    /** Timestamp when the key was last released */
+    lastReleaseTime: number;
+}
+/**
+ * Manages all keyboard interaction for a Textmodifier instance.
+ * Handles event listeners, key state tracking, and event dispatching.
+ *
+ * Provides p5.js-like keyboard functionality including:
+ * - keyPressed() and keyReleased() callbacks
+ * - Current key state tracking
+ * - Special key handling (arrows, function keys, etc.)
+ * - Modifier key support (Ctrl, Shift, Alt, Meta)
+ */
+export declare class KeyboardManager {
+    private _keyStates;
+    private _lastKeyPressed;
+    private _lastKeyReleased;
+    private _keyDownListener;
+    private _keyUpListener;
+    private _areListenersSetup;
+    private _keyPressedCallback?;
+    private _keyReleasedCallback?;
+    private readonly _specialKeyMap;
+    constructor();
+    /**
+     * Setup keyboard event listeners.
+     */
+    $setupListeners(): void;
+    /**
+     * Remove keyboard event listeners.
+     */
+    $cleanupListeners(): void;
+    /**
+     * Set a callback function that will be called when a key is pressed down.
+     * @param callback The function to call when a key is pressed
+     */
+    $setPressedCallback(callback: KeyboardEventHandler): void;
+    /**
+     * Set a callback function that will be called when a key is released.
+     * @param callback The function to call when a key is released
+     */
+    $setReleasedCallback(callback: KeyboardEventHandler): void;
+    /**
+     * Check if a specific key is currently being pressed.
+     * @param key The key to check (e.g., 'a', 'Enter', 'ArrowLeft', or special constants like 'SPACE')
+     * @returns true if the key is currently pressed, false otherwise
+     */
+    $isKeyPressed(key: string): boolean;
+    /**
+     * Get the last key that was pressed.
+     * @returns The key string of the last pressed key, or null if no key has been pressed
+     */
+    $getLastKeyPressed(): string | null;
+    /**
+     * Get the last key that was released.
+     * @returns The key string of the last released key, or null if no key has been released
+     */
+    $getLastKeyReleased(): string | null;
+    /**
+     * Get all currently pressed keys.
+     * @returns Array of key strings that are currently pressed
+     */
+    $getPressedKeys(): string[];
+    /**
+     * Check if any modifier key is currently pressed.
+     * @returns Object with boolean properties for each modifier key
+     */
+    $getModifierState(): {
+        ctrl: boolean;
+        shift: boolean;
+        alt: boolean;
+        meta: boolean;
+    };
+    /**
+     * Clear all key states (useful for focus loss scenarios).
+     */
+    $clearKeyStates(): void;
+    /**
+     * Handle key down events
+     */
+    private _handleKeyDown;
+    /**
+     * Handle key up events
+     */
+    private _handleKeyUp;
+    /**
+     * Normalize key names for consistency (map to p5.js-like constants where applicable)
+     */
+    private _normalizeKey;
+}

package/dist/types/textmode/managers/MouseManager.d.ts

@@ -0,0 +1,130 @@
+import type { TextmodeCanvas } from '../Canvas';
+import type { TextmodeGrid } from '../Grid';
+/**
+ * Mouse coordinates in grid space
+ */
+export interface MousePosition {
+    /** Grid X coordinate (column), -1 if mouse is outside grid */
+    x: number;
+    /** Grid Y coordinate (row), -1 if mouse is outside grid */
+    y: number;
+}
+/**
+ * Mouse event data passed to event handlers
+ */
+export interface MouseEventData {
+    /** Current mouse position in grid coordinates */
+    position: MousePosition;
+    /** Previous mouse position in grid coordinates */
+    previousPosition: MousePosition;
+    /** Mouse button that triggered the event (for click events) */
+    button?: number;
+    /** Scroll delta for wheel events */
+    delta?: {
+        x: number;
+        y: number;
+    };
+    /** Original DOM event */
+    originalEvent: MouseEvent | WheelEvent;
+}
+/**
+ * Mouse event handler function type
+ */
+export type MouseEventHandler = (data: MouseEventData) => void;
+/**
+ * Manages all mouse interaction for a Textmodifier instance.
+ * Handles event listeners, coordinate conversion, and event dispatching.
+ */
+export declare class MouseManager {
+    private _canvas;
+    private _grid;
+    private _mousePosition;
+    private _previousMousePosition;
+    private _lastClientCoordinates;
+    private _mouseMoveListener;
+    private _mouseLeaveListener;
+    private _mouseDownListener;
+    private _mouseUpListener;
+    private _clickListener;
+    private _wheelListener;
+    private _areListenersSetup;
+    private _mouseClickedCallback?;
+    private _mousePressedCallback?;
+    private _mouseReleasedCallback?;
+    private _mouseMovedCallback?;
+    private _mouseScrolledCallback?;
+    constructor(canvas: TextmodeCanvas);
+    /**
+     * Update the grid reference (useful when grid changes after font loading)
+     */
+    $initialize(grid: TextmodeGrid): void;
+    /**
+     * Setup mouse event listeners on the canvas.
+     */
+    $setupListeners(): void;
+    /**
+     * Remove mouse event listeners from the canvas.
+     */
+    $cleanupListeners(): void;
+    /**
+     * Force an immediate update of the mouse position.
+     * This is useful when grid dimensions change (font size, window resize, etc.)
+     * and we need to recalculate the mouse coordinates without waiting for a mouse event.
+     */
+    $updatePosition(): void;
+    /**
+     * Set a callback function that will be called when the mouse is clicked.
+     * @param callback The function to call when the mouse is clicked
+     */
+    $setClickedCallback(callback: MouseEventHandler): void;
+    /**
+     * Set a callback function that will be called when the mouse is pressed down.
+     * @param callback The function to call when the mouse is pressed
+     */
+    $setPressedCallback(callback: MouseEventHandler): void;
+    /**
+     * Set a callback function that will be called when the mouse is released.
+     * @param callback The function to call when the mouse is released
+     */
+    $setReleasedCallback(callback: MouseEventHandler): void;
+    /**
+     * Set a callback function that will be called when the mouse moves.
+     * @param callback The function to call when the mouse moves
+     */
+    $setMovedCallback(callback: MouseEventHandler): void;
+    /**
+     * Set a callback function that will be called when the mouse wheel is scrolled.
+     * @param callback The function to call when the mouse wheel is scrolled
+     */
+    $setScrolledCallback(callback: MouseEventHandler): void;
+    /**
+     * Get the current mouse position in grid coordinates.
+     * Returns a copy to prevent external modification.
+     */
+    $getPosition(): MousePosition;
+    /**
+     * Handle mouse moved events
+     */
+    private _handleMouseMoved;
+    /**
+     * Handle mouse pressed events
+     */
+    private _handleMousePressed;
+    /**
+     * Handle mouse released events
+     */
+    private _handleMouseReleased;
+    /**
+     * Handle mouse clicked events
+     */
+    private _handleMouseClicked;
+    /**
+     * Handle mouse scrolled events
+     */
+    private _handleMouseScrolled;
+    /**
+     * Update mouse position based on mouse event.
+     * Converts pixel coordinates to grid coordinates.
+     */
+    private _updateMousePosition;
+}

package/dist/types/textmode/managers/index.d.ts

@@ -0,0 +1,4 @@
+export { KeyboardManager } from '../managers/KeyboardManager';
+export type { KeyboardEventData, KeyboardEventHandler, KeyState } from '../managers/KeyboardManager';
+export { MouseManager } from '../managers/MouseManager';
+export type { MousePosition, MouseEventData, MouseEventHandler } from '../managers/MouseManager';

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

@@ -0,0 +1,39 @@
+import type { Mixin } from './TextmodifierMixin';
+import type { KeyboardEventHandler } from '../managers';
+/**
+ * Capabilities provided by the KeyboardMixin
+ */
+export interface KeyboardCapabilities {
+    /** Check if a specific key is currently pressed */
+    isKeyPressed(key: string): boolean;
+    /** Get the last key that was pressed */
+    readonly lastKeyPressed: string | null;
+    /** Get the last key that was released */
+    readonly lastKeyReleased: string | null;
+    /** Get all currently pressed keys */
+    readonly pressedKeys: string[];
+    /** Get current modifier key states */
+    readonly modifierState: {
+        ctrl: boolean;
+        shift: boolean;
+        alt: boolean;
+        meta: boolean;
+    };
+    /** Set a callback for when a key is pressed down */
+    keyPressed(callback: KeyboardEventHandler): void;
+    /** Set a callback for when a key is released */
+    keyReleased(callback: KeyboardEventHandler): void;
+    /** Clear all key states */
+    clearKeyStates(): void;
+}
+/**
+ * Mixin that adds keyboard interaction capabilities to Textmodifier.
+ *
+ * This is a thin wrapper around KeyboardManager that provides the public API
+ * for keyboard interaction. All the actual implementation is handled by the
+ * KeyboardManager instance in the TextmodifierContext.
+ *
+ * Provides p5.js-like keyboard functionality including key state tracking,
+ * event callbacks, and special key handling.
+ */
+export declare const KeyboardMixin: Mixin<KeyboardCapabilities>;