textmode.js 0.2.1-beta.1 → 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,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/KeyboardMixin.d.ts

@@ -1,5 +1,5 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { KeyboardEventHandler } from '../keyboard';
+import type { KeyboardEventHandler } from '../managers';
 /**
  * Capabilities provided by the KeyboardMixin
  */

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

@@ -1,5 +1,5 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { MousePosition, MouseEventHandler } from '../mouse';
+import type { MousePosition, MouseEventHandler } from '../managers';
 /**
  * Capabilities provided by the MouseMixin
  */

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

@@ -1,5 +1,10 @@
 import type { Mixin } from './TextmodifierMixin';
 import type { GLShader } from '../../rendering/webgl/Shader';
+import type { GLFramebuffer } from '../../rendering';
+export interface UserFramebufferOptions {
+    width: number;
+    height: number;
+}
 /**
  * Supported uniform value types for shader parameters
  */
@@ -39,6 +44,86 @@ export interface RenderingCapabilities {
      * ```
      */
     shader(shader: GLShader): void;
+    /**
+         * Create a new framebuffer for offscreen rendering.
+         *
+         * The framebuffer uses the same 5-attachment MRT structure as the main
+         * rendering pipeline, allowing all standard drawing operations to work
+         * seamlessly when rendering to the framebuffer.
+         *
+         * @param options Configuration options for the framebuffer
+         * @returns A new UserFramebuffer instance
+         *
+         * @example
+         * ```javascript
+         * const t = textmode.create({
+         *   width: 800,
+         *   height: 600,
+         * });
+         *
+         * // Create a framebuffer with 50x30 grid cells
+         * const fb = t.createFramebuffer({
+         *   width: 50,
+         *   height: 30
+         * });
+         *
+         * t.draw(() => {
+         *   // Render to framebuffer
+         *   fb.begin();
+         *   t.background(255, 0, 0);
+         *   t.charColor(255);
+         *   t.rect(10, 10, 20, 10);
+         *   fb.end();
+         *
+         *   // Render framebuffer to main canvas
+         *   t.background(0);
+         *   t.image(fb, 0, 0);
+         * });
+         * ```
+         */
+    createFramebuffer(options: UserFramebufferOptions): GLFramebuffer;
+    /**
+     * Render a framebuffer to the current render target.
+     *
+     * This method takes the 5 MRT attachments from the source framebuffer
+     * and renders them as a textmode rectangle at the specified position.
+     * The framebuffer content will be processed through the same rendering
+     * pipeline as normal drawing operations.
+     *
+     * @param framebuffer The framebuffer to render
+     * @param x X position on the grid where to place the framebuffer content
+     * @param y Y position on the grid where to place the framebuffer content
+     * @param width Optional width to scale the framebuffer content (defaults to framebuffer width)
+     * @param height Optional height to scale the framebuffer content (defaults to framebuffer height)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * });
+     *
+     * const fb = t.createFramebuffer({width: 30, height: 20});
+     *
+     * t.draw(() => {
+     *   // Draw something to the framebuffer
+     *   fb.begin();
+     *   t.charColor(255, 0, 0);
+     *   t.rect(5, 5, 20, 10);
+     *   fb.end();
+     *
+     *   // Clear main canvas and render framebuffer content
+     *   t.background(0);
+     *
+     *   // Render at original size
+     *   t.image(fb, 10, 10);
+     *
+     *   // Render scaled version
+     *   t.image(fb, 50, 10, 60, 40);
+     * });
+     * ```
+     */
+    image(framebuffer: GLFramebuffer, x: number, y: number, width?: number, height?: number): void;
     /**
      * Set a uniform value for the current custom shader.
      * @param name The name of the uniform variable

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

@@ -7,8 +7,8 @@ import type { TextmodeCanvas } from '../Canvas';
 import type { TextmodeGrid } from '../Grid';
 import type { AnimationController } from '../AnimationController';
 import type { GLFramebuffer, Shader } from '../../rendering';
-import type { MouseManager } from '../mouse';
-import type { KeyboardManager } from '../keyboard';
+import type { MouseManager } from '../managers';
+import type { KeyboardManager } from '../managers';
 /**
  * Constructor type for mixin pattern
  */

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

@@ -5,5 +5,5 @@ export { FontMixin, type FontCapabilities } from './FontMixin';
 export { AnimationMixin, type AnimationCapabilities } from './AnimationMixin';
 export { MouseMixin, type MouseCapabilities } from './MouseMixin';
 export { KeyboardMixin, type KeyboardCapabilities } from './KeyboardMixin';
-export type { MousePosition, MouseEventData, MouseEventHandler } from '../mouse';
-export type { KeyboardEventData, KeyboardEventHandler, KeyState } from '../keyboard';
+export type { MousePosition, MouseEventData, MouseEventHandler } from '../managers';
+export type { KeyboardEventData, KeyboardEventHandler, KeyState } from '../managers';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.2.1-beta.1",
+  "version": "0.2.1-beta.2",
   "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",
@@ -32,6 +32,7 @@
     "test:coverage": "vitest --coverage"
   },
   "devDependencies": {
+    "@mapwhit/glsl-minify": "^1.0.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.13",
@@ -41,7 +42,7 @@
     "tslib": "^2.8.1",
     "typedoc": "^0.28.7",
     "typedoc-plugin-markdown": "^4.7.0",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "vite": "^6.3.4",
     "vite-plugin-glsl": "^1.5.1",
     "vitest": "^3.1.2"

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

@@ -1,2 +0,0 @@
-export { KeyboardManager } from './KeyboardManager';
-export type { KeyboardEventData, KeyboardEventHandler, KeyState } from './KeyboardManager';

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

@@ -1,2 +0,0 @@
-export { MouseManager } from './MouseManager';
-export type { MousePosition, MouseEventData, MouseEventHandler } from './MouseManager';