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

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

@@ -1,3 +1,4 @@
+import type { GLRenderer } from './Renderer';
 export type FramebufferOptions = {
     /** Texture filtering mode */
     filter?: 'nearest' | 'linear';
@@ -9,10 +10,7 @@ export type FramebufferOptions = {
     type?: 'unsigned_byte' | 'float';
 };
 /**
- * WebGL2 implementation of the framebuffer abstraction.
- * Provides GPU-accelerated render targets with automatic texture creation.
- * Supports both single-texture and Multiple Render Targets (MRT) functionality.
- * Can also be used as a standalone texture (without render target functionality).
+ * Framebuffer class for managing offscreen rendering targets.
  */
 export declare class GLFramebuffer {
     protected _width: number;
@@ -25,46 +23,59 @@ export declare class GLFramebuffer {
     private _attachmentCount;
     private _previousState;
     private _attachmentPixels;
-    constructor(gl: WebGL2RenderingContext, width: number, height?: number, attachmentCount?: number, options?: FramebufferOptions);
+    private _renderer;
+    private _isolatedState;
+    private _stateForFBO;
+    /**
+     * Create a new GLFramebuffer instance.
+     * @param gl WebGL2 rendering context
+     * @param width Framebuffer width
+     * @param height Framebuffer height
+     * @param attachmentCount Number of color attachments
+     * @param options Framebuffer options
+     * @param renderer Optional GLRenderer instance for state management
+     * @param isolatedState Optional flag to isolate framebuffer state from renderer
+     * @ignore
+     */
+    constructor(gl: WebGL2RenderingContext, width: number, height?: number, attachmentCount?: number, options?: FramebufferOptions, renderer?: GLRenderer | null, isolatedState?: boolean);
     private _createTextures;
     private _attachTextures;
     /**
      * Update the framebuffer texture with canvas or video content
      * Note: Only updates the first attachment in multi-attachment mode
+     * @ignore
      */
     $update(source: HTMLCanvasElement | HTMLVideoElement): void;
     /**
-     * Resize the framebuffer
+     * Resize the framebuffer.
+     * @param width New width
+     * @param height New height
      */
-    $resize(width: number, height: number): void;
+    resize(width: number, height: number): void;
     /**
      * Read pixels from a specific color attachment into an RGBA Uint8Array.
      * Rows are flipped to top-left origin to match row-major iteration in exporters.
+     * @ignore
      */
     $readAttachment(attachmentIndex: number): Uint8Array;
-    /** Read and cache all attachments. */
-    $readAll(): void;
     /**
-     * Begin rendering to this framebuffer
+     * Begin rendering to this framebuffer.
      */
-    $begin(): void;
+    begin(): void;
     /**
-     * End rendering to this framebuffer and restore previous state
+     * End rendering to this framebuffer and restore previous state.
      */
-    $end(): void;
+    end(): void;
     /**
      * Dispose of WebGL resources used by this framebuffer.
      * This method is idempotent and safe to call multiple times.
+     * @ignore
      */
     $dispose(): void;
+    /** Get the current framebuffer width. */
     get width(): number;
+    /** Get the current framebuffer height. */
     get height(): number;
-    get pixels(): Uint8Array | null;
-    get options(): FramebufferOptions;
-    get framebuffer(): WebGLFramebuffer | null;
-    get texture(): WebGLTexture;
+    /** Get all textures associated with this framebuffer. */
     get textures(): WebGLTexture[];
-    get attachmentCount(): number;
-    /** Return a cached copy of pixels for an attachment if previously read, else null. */
-    getAttachmentPixels(attachmentIndex: number): Uint8Array | null;
 }

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

@@ -5,7 +5,7 @@
 export interface InstanceData {
     position: [number, number];
     size: [number, number];
-    character: [number, number, number];
+    _character: [number, number, number];
     primaryColor: [number, number, number, number];
     secondaryColor: [number, number, number, number];
     rotation: [number, number];

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;
+type UniformValue = number | boolean | number[] | 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,8 +3,8 @@ import { TextmodeFont } from './font';
 import { TextmodeGrid } from './Grid';
 import { TextmodeCanvas } from './Canvas';
 import { AnimationController } from './AnimationController';
-import { MouseManager } from './mouse';
-import { KeyboardManager } from './keyboard';
+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';

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

@@ -3,10 +3,6 @@ import type { Mixin } from './TextmodifierMixin';
  * Interface for animation capabilities that will be mixed into Textmodifier
  */
 export interface AnimationCapabilities {
-    /**
-     * Get or set the current frame count.
-     */
-    frameCount: number;
     /**
      * Set the maximum frame rate. If called without arguments, returns the current measured frame rate.
      * @param fps The maximum frames per second for rendering.

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

@@ -1,30 +1,86 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { KeyboardEventHandler } from '../keyboard';
+import type { KeyboardEventHandler } from '../managers';
 /**
  * Capabilities provided by the KeyboardMixin
  */
 export interface KeyboardCapabilities {
-    /** Check if a specific key is currently pressed */
+    /**
+     * Check if a specific key is currently being pressed.
+     *
+     * @param key The key to check (e.g., 'a', 'Enter', 'ArrowLeft')
+     * @returns true if the key is currently pressed, false otherwise
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * let playerX = 0;
+     * let playerY = 0;
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Check for arrow keys to move a character
+     *   if (t.isKeyPressed('ArrowUp')) {
+     *     playerY -= 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowDown')) {
+     *     playerY += 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowLeft')) {
+     *     playerX -= 1;
+     *   }
+     *   if (t.isKeyPressed('ArrowRight')) {
+     *     playerX += 1;
+     *   }
+     *
+     *   // Draw player character
+     *   t.char('@');
+     *   t.charColor(255, 255, 0);
+     *   t.point(playerX, playerY);
+     * });
+     * ```
+     */
     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 */
+    /**
+     * 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
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.keyPressed((data) => {
+     *   console.log(`Key pressed: ${data.key}`);
+     *   if (data.key === 'Enter') {
+     *     console.log('Enter key was pressed!');
+     *   }
+     *   if (data.ctrlKey && data.key === 's') {
+     *     console.log('Ctrl+S was pressed!');
+     *   }
+     * });
+     * ```
+     */
     keyPressed(callback: KeyboardEventHandler): void;
-    /** Set a callback for when a key is released */
+    /**
+     * Set a callback function that will be called when a key is released.
+     *
+     * @param callback The function to call when a key is released
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.keyReleased((data) => {
+     *   console.log(`Key released: ${data.key}`);
+     *   if (data.key === ' ') {
+     *     console.log('Spacebar was released!');
+     *   }
+     * });
+     * ```
+     */
     keyReleased(callback: KeyboardEventHandler): void;
-    /** Clear all key states */
-    clearKeyStates(): void;
 }
 /**
  * Mixin that adds keyboard interaction capabilities to Textmodifier.