textmode.js 0.6.0-beta.4 → 0.6.0

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { Textmode } from './Textmode';
 export { Textmodifier } from './textmode/Textmodifier';
-export { GLFramebuffer as TextmodeFramebuffer, Shader } from './rendering';
+export { GLFramebuffer as TextmodeFramebuffer } from './rendering';
 export { TextmodeColor } from './textmode/TextmodeColor';
 export { TextmodeCanvas } from './textmode/Canvas';
 export { TextmodeGrid } from './textmode/Grid';

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

@@ -1,3 +1,3 @@
-export { GLShader as Shader } from './webgl/core/Shader';
+export { GLShader } from './webgl/core/Shader';
 export { GLRenderer } from './webgl/core/Renderer';
 export { GLFramebuffer } from './webgl/core/Framebuffer';

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

@@ -31,10 +31,7 @@ export declare class GLRenderer implements IRenderer {
      * Used by framebuffer end() to restore previous state.
      * @internal
      */
-    $popFramebufferState(): {
-        framebuffer: WebGLFramebuffer | null;
-        viewport: [number, number, number, number];
-    };
+    $popFramebufferState(): void;
     /**
      * Bind a framebuffer and update CPU-side tracking.
      * @internal

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

@@ -43,7 +43,6 @@ export declare class GLShader {
     get $glProgram(): WebGLProgram;
     /**
      * Dispose of WebGL resources used by this shader.
-     * This method is idempotent and safe to call multiple times.
      */
-    $dispose(): void;
+    dispose(): void;
 }

package/dist/types/rendering/webgl/materials/MaterialManager.d.ts

@@ -15,7 +15,6 @@ import { GLShader } from '../core/Shader';
  * - Separate tracking of user vs built-in materials
  */
 export declare class MaterialManager {
-    private _gl;
     private _nextMaterialId;
     private readonly _shader;
     private readonly _solidColorMaterial;

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

@@ -1,5 +1,3 @@
-type GlyphColor = [number, number, number];
-type GlyphColorResolver = (chars: string) => GlyphColor[];
 type ColorTuple = [number, number, number] | [number, number, number, number];
 /**
  * Represents a color in the `textmode.js` rendering system.
@@ -12,7 +10,6 @@ type ColorTuple = [number, number, number] | [number, number, number, number];
 export declare class TextmodeColor {
     private readonly _rgba;
     private readonly _normalized;
-    private readonly _character?;
     /** Red component *(0-255)* */
     readonly r: number;
     /** Green component *(0-255)* */
@@ -27,8 +24,9 @@ export declare class TextmodeColor {
      * Accepts an existing {@link TextmodeColor}, CSS hex strings, single characters
      * (resolved through a glyph resolver), grayscale values, RGB(A) tuples, or
      * normalized component arrays.
+     * @ignore
      */
-    static $from(value: TextmodeColor | string | number | ColorTuple, gOrResolver?: number | GlyphColorResolver, b?: number, a?: number): TextmodeColor;
+    static $from(value: TextmodeColor | string | number | ColorTuple, g?: number, b?: number, a?: number): TextmodeColor;
     /**
      * Create a color from RGB or RGBA components (0-255 range).
      * @ignore
@@ -44,20 +42,12 @@ export declare class TextmodeColor {
      * @ignore
      */
     static $fromHex(hex: string): TextmodeColor;
-    /**
-     * Create a color representing a textmode character encoded as RGB triplet
-     * (values already normalized 0-1 for shader usage).
-     * @ignore
-     */
-    static $fromCharacter(characterColor: [number, number, number]): TextmodeColor;
     /** Returns a plain RGB array with integer components. */
     get rgb(): [number, number, number];
     /** Returns a plain RGBA array with integer components. */
     get rgba(): [number, number, number, number];
     /** Returns the normalized *(0-1)* RGBA array. */
     get normalized(): [number, number, number, number];
-    /** Returns the character encoding *(0-1 range)* if this color was created from a glyph. */
-    get character(): [number, number, number] | undefined;
     /**
      * Create a copy of this color with a different alpha value.
      */
@@ -68,5 +58,4 @@ export declare class TextmodeColor {
      */
     static $isColor(value: unknown): value is TextmodeColor;
 }
-export type ColorLike = TextmodeColor | string | number | [number, number, number] | [number, number, number, number];
 export {};

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

@@ -9,7 +9,7 @@ import { MouseManager } from './managers/MouseManager';
 import { KeyboardManager } from './managers/KeyboardManager';
 import { TouchManager } from './managers/TouchManager';
 import type { ITextmodifier } from './interfaces';
-import type { GLFramebuffer, Shader } from '../rendering';
+import type { GLFramebuffer, GLShader } from '../rendering';
 import type { TextmodeOptions } from './types';
 import type { IAnimationMixin } from './mixins/interfaces/IAnimationMixin';
 import type { IFontMixin } from './mixins/interfaces/IFontMixin';
@@ -40,9 +40,9 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     _keyboardManager: KeyboardManager;
     _loading: LoadingScreenManager;
     _textmodeDrawFramebuffer: GLFramebuffer;
-    _textmodeConversionShader: Shader;
+    _textmodeConversionShader: GLShader;
     _textmodeFramebuffer: GLFramebuffer;
-    _presentShader: Shader;
+    _presentShader: GLShader;
     private _pluginManager;
     private _destroyRequested;
     private _isRenderingFrame;
@@ -55,7 +55,7 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     private _resizeObserver?;
     private _isOverlay;
     private _targetCanvasImage?;
-    private _sources;
+    _sources: Set<TextmodeSource>;
     /**
      * Create a new Textmodifier instance.
      * @param opts Configuration options for the Textmodifier instance.
@@ -85,7 +85,6 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     get overlay(): TextmodeImage | undefined;
     get loading(): LoadingScreenManager;
     $registerSource(source: TextmodeSource): void;
-    $notifyFontChange(): void;
 }
 export interface Textmodifier extends IRenderingMixin, IFontMixin, IAnimationMixin, IMouseMixin, ITouchMixin, IKeyboardMixin {
 }

package/dist/types/textmode/conversion/ConversionRegistry.d.ts

@@ -1,8 +1,16 @@
-import type { Shader } from '../../rendering';
+import type { GLShader } from '../../rendering';
 import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
 import type { TextmodeFont } from '../loadables/font/TextmodeFont';
 import type { TextmodeSource } from '../loadables/TextmodeSource';
+/**
+ * Type representing the available textmode conversion modes
+ * @ignore
+ */
 export type TextmodeConversionMode = 'brightness' | 'accurate' | (string & {});
+/**
+ * Interface for the context provided to conversion strategies
+ * @ignore
+ */
 export interface TextmodeConversionContext {
     renderer: GLRenderer;
     gl: WebGL2RenderingContext;
@@ -11,11 +19,31 @@ export interface TextmodeConversionContext {
     gridWidth: number;
     gridHeight: number;
 }
+/**
+ * Interface for a textmode conversion strategy
+ * @ignore
+ */
 export interface TextmodeConversionStrategy {
     readonly id: TextmodeConversionMode;
-    createShader(context: TextmodeConversionContext): Shader;
+    createShader(context: TextmodeConversionContext): GLShader;
     createUniforms(context: TextmodeConversionContext): Record<string, any>;
 }
+/**
+ * Register a conversion strategy
+ * @param strategy The conversion strategy to register
+ * @ignore
+ */
 export declare function registerConversionStrategy(strategy: TextmodeConversionStrategy): void;
+/**
+ * Unregister a conversion strategy by its ID
+ * @param id The ID of the conversion strategy to unregister
+ * @ignore
+ */
 export declare function unregisterConversionStrategy(id: TextmodeConversionMode): void;
+/**
+ * Get a registered conversion strategy by its ID
+ * @param id The ID of the conversion strategy
+ * @returns The conversion strategy, or undefined if not found
+ * @ignore
+ */
 export declare function getConversionStrategy(id: TextmodeConversionMode): TextmodeConversionStrategy | undefined;

package/dist/types/textmode/interfaces/ITextmodifier.d.ts

@@ -4,7 +4,7 @@ import type { TextmodeImage } from '../loadables/TextmodeImage';
 import type { TextmodeSource } from '../loadables/TextmodeSource';
 import type { TextmodeCanvas } from '../Canvas';
 import type { AnimationController } from '../AnimationController';
-import type { GLFramebuffer, Shader } from '../../rendering';
+import type { GLFramebuffer, GLShader } from '../../rendering';
 import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
 import type { MouseManager } from '../managers/MouseManager';
 import type { KeyboardManager } from '../managers/KeyboardManager';
@@ -44,17 +44,17 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
     /** Framebuffer used for offscreen rendering @ignore */
     readonly _textmodeDrawFramebuffer: GLFramebuffer;
     /** Shader used for converting pixels to textmode grid format @ignore */
-    readonly _textmodeConversionShader: Shader;
+    readonly _textmodeConversionShader: GLShader;
     /** Framebuffer used for textmode conversion @ignore */
     readonly _textmodeFramebuffer: GLFramebuffer;
     /** Shader used for final presentation to the screen @ignore */
-    readonly _presentShader: Shader;
+    readonly _presentShader: GLShader;
     /** Loading screen manager for boot-time UX @ignore */
     readonly _loading: LoadingScreenManager;
+    /** Sources registered for rendering @ignore */
+    readonly _sources: Set<TextmodeSource>;
     /** @ignore */
     $registerSource(source: TextmodeSource): void;
-    /** @ignore */
-    $notifyFontChange(): void;
     /** Main render method @ignore */
     $render(): void;
     /**

package/dist/types/textmode/loadables/TextmodeImage.d.ts

@@ -43,6 +43,6 @@ export declare class TextmodeImage extends TextmodeSource {
      * Texture parameters use NEAREST and CLAMP to align with grid sampling.
      * @ignore
      */
-    static $fromSource(renderer: GLRenderer, font: TextmodeFont, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, gridCols: number, gridRows: number, glyphResolver: (s: string) => ([number, number, number])[]): TextmodeImage;
+    static $fromSource(renderer: GLRenderer, font: TextmodeFont, source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, gridCols: number, gridRows: number): TextmodeImage;
     protected $getActiveTexture(): WebGLTexture;
 }

package/dist/types/textmode/loadables/TextmodeSource.d.ts

@@ -3,11 +3,7 @@ import type { Material } from '../../rendering/webgl/materials/Material';
 import { TextmodeColor } from '../TextmodeColor';
 import type { TextmodeFont } from './font/TextmodeFont';
 import { type TextmodeConversionMode } from '../conversion';
-export interface TextmodeConversionOptions {
-    sampleRate?: number;
-}
 type GlyphColor = [number, number, number];
-export type TextmodeColorFilterInput = TextmodeColor | string | [number, number, number] | [number, number, number, number];
 /**
  * Base class for drawable textmode sources (images, videos, canvas, etc.).
  * Handles shared WebGL texture state, material creation, and color/character settings.
@@ -34,7 +30,6 @@ export declare abstract class TextmodeSource {
     protected _cellColor: [number, number, number, number];
     protected _backgroundColor: [number, number, number, number];
     protected _glyphColors: GlyphColor[];
-    protected _glyphColorResolver: (s: string) => GlyphColor[];
     private _characterString;
     private _disposeListeners;
     private _colorFilterPalette;
@@ -42,7 +37,11 @@ export declare abstract class TextmodeSource {
     protected constructor(gl: WebGL2RenderingContext, renderer: GLRenderer, texture: WebGLTexture, font: TextmodeFont, originalWidth: number, originalHeight: number, width: number, height: number);
     /**
      * Select the conversion mode for this source.
-     * `'brightness'` uses single-sample conversion, while `'accurate'` performs glyph matching.
+     *
+     * `textmode.js` includes only a single built-in conversion strategy `'brightness'`.
+     *
+     * Additional conversion strategies may be provided via add-on libraries.
+     *
      * @param mode Conversion mode to use.
      */
     conversionMode(mode: TextmodeConversionMode): this;
@@ -51,6 +50,11 @@ export declare abstract class TextmodeSource {
      * @ignore
      */
     $dispose(): void;
+    /**
+     * Register a callback to be invoked when this source is disposed.
+     * @param callback The callback function to register
+     * @ignore
+     */
     $onDispose(callback: () => void): void;
     /**
      * Set the invert flag, swapping character and cell colors when enabled.
@@ -123,7 +127,7 @@ export declare abstract class TextmodeSource {
      * @param palette A list of colors defined as {@link TextmodeColor} instances, hex strings, or RGBA tuples (0-255).
      * Providing an empty array or `null` disables the filter.
      */
-    colorFilter(palette?: TextmodeColorFilterInput[] | null): this;
+    colorFilter(palette?: TextmodeColor[] | string[] | [number, number, number][] | [number, number, number, number][] | null): this;
     /**
      * Define the characters to use for brightness mapping as a string.
      * Maximum length is 255; excess characters are ignored.
@@ -131,6 +135,11 @@ export declare abstract class TextmodeSource {
      * @returns This instance for chaining.
      */
     characters(chars: string): this;
+    /**
+     * Handle font change notification from the Textmodifier.
+     * @param font The new font
+     * @ignore
+     */
     $handleFontChange(font: TextmodeFont): void;
     /** Return the WebGL texture currently backing this source. */
     get texture(): WebGLTexture;
@@ -154,6 +163,11 @@ export declare abstract class TextmodeSource {
     private _updateMaterial;
     private _setColor;
     private _applyCharacterPalette;
+    /**
+     * Create base conversion uniforms shared across all strategies.
+     * @returns Uniforms object
+     * @ignore
+     */
     createBaseConversionUniforms(): Record<string, any>;
     private _getActiveConversionStrategy;
     private _createConversionContext;

package/dist/types/textmode/loadables/font/CharacterColorMapper.d.ts

@@ -9,11 +9,15 @@ export declare class CharacterColorMapper {
     constructor();
     /**
      * Creates TextmodeCharacter objects with unique color assignments.
+     * Returns both an array (for public API and iteration) and a Map (for O(1) lookups).
      * @param characters Array of character strings
      * @param font The parsed font object from Typr
-     * @returns Array of TextmodeCharacter objects with colors
+     * @returns Object containing both array and map of TextmodeCharacter objects
      */
-    createCharacterObjects(characters: string[], font: TyprFont): TextmodeCharacter[];
+    $createCharacterObjects(characters: string[], font: TyprFont): {
+        array: TextmodeCharacter[];
+        map: Map<string, TextmodeCharacter>;
+    };
     /**
      * Generates a unique RGB color for a character based on its index.
      * @param index The index of the character
@@ -21,17 +25,10 @@ export declare class CharacterColorMapper {
      */
     private _generateCharacterColor;
     /**
-     * Gets the color for a specific character.
-     * @param character The character to get the color for
-     * @param characters Array of TextmodeCharacter objects
-     * @returns RGB color as a tuple [r, g, b], or [0, 0, 0] if not found
-     */
-    $getCharacterColor(character: string, characters: TextmodeCharacter[]): [number, number, number];
-    /**
-     * Gets colors for multiple characters.
-     * @param characterString String of characters to get colors for
-     * @param characters Array of TextmodeCharacter objects
-     * @returns Array of RGB colors for each character
+     * Gets glyph data for a character including advance width and path information.
+     * @param font The parsed font object from Typr
+     * @param character Character to get glyph data for
+     * @returns Parsed glyph data with advance width, or null if not found
      */
-    $getCharacterColors(characterString: string, characters: TextmodeCharacter[]): [number, number, number][];
+    private _getGlyphData;
 }

package/dist/types/textmode/loadables/font/MetricsCalculator.d.ts

@@ -20,8 +20,4 @@ export declare class FontMetricsCalculator {
      * @returns Object containing width and height dimensions
      */
     $calculateMaxGlyphDimensions(characters: string[], fontSize: number, font: TyprFont): GlyphDimensions;
-    /**
-     * Clears internal caches. Useful for memory management.
-     */
-    $clearCache(): void;
 }

package/dist/types/textmode/loadables/font/TextmodeFont.d.ts

@@ -1,7 +1,7 @@
 import type { GLRenderer } from '../../../rendering/webgl/core/Renderer.ts';
 import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts';
 import type { TextmodeCharacter } from './types.ts';
-import type { TyprFont, GlyphData } from './typr/types.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Manages the font used for rendering characters via {@link Textmodifier.loadFont}.
  *
@@ -14,13 +14,13 @@ import type { TyprFont, GlyphData } from './typr/types.ts';
 export declare class TextmodeFont {
     private _font;
     private _characters;
+    private _characterMap;
     private _fontFramebuffer;
     private _fontSize;
     private _textureColumns;
     private _textureRows;
     private _maxGlyphDimensions;
     private _fontFace;
-    private _glyphCache;
     private _characterExtractor;
     private _textureAtlas;
     private _metricsCalculator;
@@ -62,41 +62,29 @@ export declare class TextmodeFont {
      */
     private _initializeFont;
     /**
-     * Get the color associated with a character.
+     * Get the color associated with a character using O(1) Map lookup.
      * @param character The character to get the color for.
      * @returns The RGB color as an array `[r, g, b]`.
      * @ignore
      */
     $getCharacterColor(character: string): [number, number, number];
     /**
-     * Get the colors associated with a string of characters.
+     * Get the colors associated with a string of characters using O(1) Map lookups.
      * @param characters The string of characters to get colors for.
      * @returns An array of RGB colors for each character in the string.
      * Each color is represented as an array `[r, g, b]`.
      * @ignore
      */
     $getCharacterColors(characters: string): [number, number, number][];
-    /**
-     * Lazily retrieves glyph data for the given Unicode code point.
-     *
-     * Glyph data is cached after the first access to avoid repeated Typr parsing.
-     *
-     * @param codePoint Unicode code point
-     * @returns Parsed glyph data or null if unavailable
-     * @ignore
-     */
-    getGlyphData(codePoint: number): GlyphData | null;
-    private _getGlyphIndex;
     /**
      * Dispose of all resources used by this font manager.
      * @ignore
      */
     $dispose(): void;
-    /**
-     * Returns the WebGL framebuffer containing the font texture atlas.
-     * @ignore
-     */
+    /** Returns the WebGL framebuffer containing the font texture atlas. */
     get fontFramebuffer(): GLFramebuffer;
+    /** Returns the character map for O(1) lookups. */
+    get characterMap(): Map<string, TextmodeCharacter>;
     /** Returns the array of {@link TextmodeCharacter} objects in the font. */
     get characters(): TextmodeCharacter[];
     /** Returns the number of columns in the texture atlas. */

package/dist/types/textmode/loadables/font/TextureAtlas.d.ts

@@ -8,11 +8,10 @@ import type { TyprFont } from './typr/types.ts';
  * Supports both Typr.js path-based rendering for uniform cross-browser text
  * and fallback fillText rendering.
  */
-export declare class TextureAtlasCreation {
+export declare class TextureAtlas {
     private _textureCanvas;
     private _textureContext;
     private _renderer;
-    private _fontTableReader;
     /**
      * Creates a new TextureAtlasCreation instance.
      * @param renderer The WebGL renderer instance
@@ -46,13 +45,6 @@ export declare class TextureAtlasCreation {
      * @param fontData Typr.js font data
      */
     private _renderCharacters;
-    /**
-     * Gets glyph data for a character using Typr.js
-     * @param fontData Typr.js font data
-     * @param character Character to get glyph data for
-     * @returns Parsed glyph data or null if not found
-     */
-    private _getGlyphData;
     /**
      * Renders a glyph to the canvas using direct path rendering from glyph outline data.
      * @param glyphData Glyph data from Typr.js

package/dist/types/textmode/loadables/font/index.d.ts

@@ -3,6 +3,6 @@ export type { TextmodeCharacter, GlyphDimensions } from './types.ts';
 export type { TyprFont, CmapTable, CmapTableFormat4, CmapTableFormat12, HeadTable, HheaTable, HmtxTable, MaxpTable, CmapData, GlyphData, LocaTable, TyprStatic } from './typr/types.ts';
 export { default as Typr } from './typr/Typr.ts';
 export { CharacterExtraction } from './CharacterExtractor.ts';
-export { TextureAtlasCreation } from './TextureAtlas.ts';
+export { TextureAtlas as TextureAtlasCreation } from './TextureAtlas.ts';
 export { FontMetricsCalculator as MetricsCalculation } from './MetricsCalculator.ts';
 export { CharacterColorMapper as CharacterColorMapping } from './CharacterColorMapper.ts';

package/dist/types/textmode/loadables/font/types.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Glyph outline data for a character
+ */
+export type GlyphData = {
+    /** Number of contours (-1 for composite glyphs) */
+    noc: number;
+    /** Bounding box coordinates */
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+    /** End points of each contour */
+    endPts: number[];
+    /** Point flags indicating curve/line segments */
+    flags: number[];
+    /** X coordinates of all points */
+    xs: number[];
+    /** Y coordinates of all points */
+    ys: number[];
+    /** Advance width of the character */
+    advanceWidth: number;
+    /** Composite glyph parts (for composite glyphs) */
+    parts?: any[];
+} | null;
 /**
  * Represents a single character in the {@link TextmodeFont.characters} array.
  */
@@ -8,8 +32,8 @@ export type TextmodeCharacter = {
     unicode: number;
     /** The shader color associated with the character. */
     color: [number, number, number];
-    /** The advance width of the character. @ignore */
-    advanceWidth: number;
+    /** Glyph outline data including advance width and path information. */
+    glyphData: GlyphData;
 };
 /**
  * Font glyph dimensions

package/dist/types/textmode/loadables/font/utils/FontTableReader.d.ts

@@ -1,15 +1,12 @@
 import type { TyprFont } from '../typr/types.ts';
 /**
  * Centralized font table reader that eliminates redundant font data access.
- * Provides cached access to font tables and metrics with consistent error handling.
+ * Provides access to font tables and metrics with consistent error handling.
  */
 export declare class FontTableReader {
-    private _glyphIndexCache;
-    private _cmapTableCache;
     /**
      * Gets the glyph index for a given Unicode code point.
      * Searches through all available cmap tables to find the character.
-     * Results are cached per font and character.
      */
     $getGlyphIndex(font: TyprFont, codePoint: number): number;
     /**
@@ -32,14 +29,6 @@ export declare class FontTableReader {
         unitsPerEm: number;
         scale: number;
     };
-    /**
-     * Clears all caches. Useful when fonts are updated or memory needs to be freed.
-     */
-    $clearCache(): void;
-    /**
-     * Gets a unique identifier for a font based on its data offset and length.
-     */
-    private _getFontId;
     /**
      * Gets glyph index from format 4 cmap table (BMP Unicode).
      */

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

@@ -1,8 +1,6 @@
 export { TextmodeImage } from './TextmodeImage';
-export { TextmodeVideo } from './TextmodeVideo';
-export { TextmodeSource } from './TextmodeSource';
+export { TextmodeVideo } from './video/TextmodeVideo';
 export { TextmodeFont } from './font/TextmodeFont';
 export type { TextmodeCharacter } from './font/types';
-export type { TextmodeVideoOptions } from './TextmodeVideo';
-export type { TextmodeConversionOptions } from './TextmodeSource';
+export type { TextmodeVideoOptions } from './video/TextmodeVideo';
 export type { TextmodeConversionMode } from '../conversion';