textmode.js 0.1.8-beta.2 → 0.1.8

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

@@ -9,9 +9,10 @@ import type { ExportCapabilities } from './mixins/ExportMixin';
 import type { FontCapabilities } from './mixins/FontMixin';
 import type { ConversionCapabilities } from './mixins/ConversionMixin';
 /**
- * Supported capture sources for textmode rendering
+ * Supported capture sources for textmode rendering.
+ * @ignore
  */
-export type CaptureSource = HTMLCanvasElement | HTMLVideoElement;
+export type TextmodeCaptureSource = HTMLCanvasElement | HTMLVideoElement;
 /**
  * Options for creating a {@link Textmodifier} instance.
  */
@@ -21,7 +22,7 @@ export type TextmodeOptions = {
     /**
      * Automatic rendering mode. Defaults to 'auto'.
      * - 'manual': Requires manual `render()` calls
-     * - 'auto': Automatically renders using requestAnimationFrame
+     * - 'auto': Automatically renders using [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
      */
     renderMode?: 'manual' | 'auto';
     /** Maximum frames per second for auto rendering. Defaults to 60. */
@@ -31,9 +32,9 @@ export type TextmodeOptions = {
     /** The height of the canvas in standalone mode. Defaults to 600. */
     height?: number;
     /**
-     * URL or path to a custom font file (.otf/.ttf).
-     * Required when using minified builds that don't include embedded fonts.
-     * Optional for full builds (will override embedded font if provided).
+     * URL or path to a custom font file *(.otf/.ttf)*.
+     * Required when using minified builds that don't include a default font.
+     * Optional for full builds *(will override embedded font if provided)*.
      */
     fontSource?: string;
 };
@@ -51,8 +52,10 @@ declare const Textmodifier_base: typeof TextmodifierCore;
 /**
  * Manages textmode rendering on a canvas or video element.
  *
- * Each `Textmodifier` instance can be applied to a specific HTML canvas or video element via {@link textmode.create},
- * or created as a standalone instance for independent rendering.
+ * Each `Textmodifier` instance applies a `HTMLCanvasElement` with custom WebGL rendering on top of the original content.
+ *
+ * If the `Textmodifier` instance is created in `standalone` mode without a capture source,
+ * it simply creates a new `HTMLCanvasElement` to draw on using the `textmode.js` drawing API.
  */
 export declare class Textmodifier extends Textmodifier_base {
     /** The element to capture content from (optional for standalone mode) */
@@ -76,14 +79,24 @@ export declare class Textmodifier extends Textmodifier_base {
     private _drawCallback;
     private _resizedCallback;
     private _windowResizeListener;
-    constructor(source?: CaptureSource | null, opts?: TextmodeOptions);
+    /**
+     * Creates an instance of Textmodifier.
+     * @param source The HTML canvas or video element to capture content from. Pass `null` for standalone mode.
+     * @param opts Optional configuration options for the Textmodifier instance.
+     * @ignore
+     */
+    constructor(source?: TextmodeCaptureSource | null, opts?: TextmodeOptions);
     /**
      * Static factory method for creating and initializing a Textmodifier instance.
      * @param source The HTML canvas or video element to capture content from. Pass `null` for standalone mode.
      * @param opts Optional configuration options for the `Textmodifier` instance.
      * @ignore
      */
-    static create<T extends Textmodifier>(source?: CaptureSource | null, opts?: TextmodeOptions): Promise<T>;
+    static create(source?: TextmodeCaptureSource | null, opts?: TextmodeOptions): Promise<Textmodifier>;
+    /**
+     * Setup event listeners for resize handling.
+     * @ignore
+     */
     $setupEventListeners(): void;
     /**
      * Apply textmode rendering to the canvas.
@@ -141,8 +154,6 @@ export declare class Textmodifier extends Textmodifier_base {
     /**
      * Update the rendering mode.
      *
-     * If called without arguments, returns the current mode.
-     *
      * - `'manual'`: Requires manual [render](#render) calls
      * - `'auto'`: Automatically renders using [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
      *
@@ -299,7 +310,8 @@ export declare class Textmodifier extends Textmodifier_base {
     isLooping(): boolean;
     /**
      * Set a draw callback function that will be executed before each render.
-     * This method is primarily useful for standalone textmodifier instances.
+     * This method is primarily useful for standalone textmodifier instances,
+     * but can also be used to draw on top of the captured video or canvas.
      * @param callback The function to call before each render
      *
      * @example
@@ -354,6 +366,8 @@ export declare class Textmodifier extends Textmodifier_base {
     windowResized(callback: () => void): void;
     /**
      * Resize the `textmode.js` canvas.
+     *
+     * Can only be used in `standalone` mode since the textmode canvas otherwise automatically adjusts to the video/canvas size.
      * @param width The new width of the canvas.
      * @param height The new height of the canvas.
      */
@@ -361,14 +375,8 @@ export declare class Textmodifier extends Textmodifier_base {
     /**
      * Completely destroy this Textmodifier instance and free all associated resources.
      *
-     * This method performs comprehensive cleanup of:
-     * - WebGL resources (framebuffers, textures, shaders)
-     * - Animation frames and timers
-     * - Event listeners
-     * - DOM elements
-     * - Font resources
-     *
      * After calling this method, the instance should not be used and will be eligible for garbage collection.
+     *
      * This method is idempotent and safe to call multiple times.
      *
      * @example
@@ -402,6 +410,7 @@ export declare class Textmodifier extends Textmodifier_base {
     get width(): number;
     /** Get the height of the canvas. */
     get height(): number;
+    /** Get the textmodifier canvas containing the rendered output. */
     get canvas(): TextmodeCanvas;
     /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;

package/dist/types/textmode/converters/Converter.d.ts

@@ -31,9 +31,9 @@ export declare class TextmodeConverter {
     $resize(): void;
     /**
      * Enables or disables the converter.
-     * @param enabled Whether to enable or disable the converter.
+     * @param enabled Whether to enable or disable the converter.<br/>Accepts boolean or number *(0 = false, any other number = true)*.
      */
-    enabled(enabled: boolean): void;
+    enabled(enabled: boolean | number): void;
     /**
      * Enables the converter.
      */
@@ -44,7 +44,7 @@ export declare class TextmodeConverter {
     disable(): void;
     /**
      * Dispose of all framebuffers used by this converter.
-     * This method is idempotent and safe to call multiple times.
+     * @ignore
      */
     $dispose(): void;
     /** Returns the framebuffer containing character data. */
@@ -57,6 +57,6 @@ export declare class TextmodeConverter {
     get rotationFramebuffer(): Framebuffer;
     /** Returns the framebuffer containing transformation data. */
     get transformFramebuffer(): Framebuffer;
-    /** Returns the renderer used by this converter. */
+    /** Returns the defined options for this converter. */
     get options(): any;
 }

package/dist/types/textmode/converters/FeatureConverter.d.ts

@@ -18,13 +18,13 @@ export declare abstract class TextmodeFeatureConverter extends TextmodeConverter
     abstract $convert(sourceFramebuffer: Framebuffer): void;
     /**
      * Sets the characters used for mapping.
-     * @param characters The characters to use for mapping, usually ordered from darkest to brightest.
+     * @param characters The characters to use for mapping, usually ordered from least dense to most dense.
      */
     characters(characters: string): void;
     /**
      * Sets the color of the characters affected by the converter.
      * This is only used when `characterColorMode` is set to `'fixed'`.
-     * @param r Red component (0-255) or hex string (e.g., '#FF0000', '#F00', 'FF0000', 'F00').
+     * @param r Red component (0-255) or hex string *(e.g., '#FF0000', '#F00', 'FF0000', 'F00')*.
      * @param g Green component (0-255).
      * @param b Blue component (0-255).
      * @param a Alpha component (0-255).
@@ -40,7 +40,7 @@ export declare abstract class TextmodeFeatureConverter extends TextmodeConverter
     /**
      * Sets the cell color for all cells affected by the converter.
      * This is only used when `cellColorMode` is set to `'fixed'`.
-     * @param r Red component (0-255) or hex string (e.g., '#FF0000', '#F00', 'FF0000', 'F00').
+     * @param r Red component (0-255) or hex string *(e.g., '#FF0000', '#F00', 'FF0000', 'F00')*.
      * @param g Green component (0-255).
      * @param b Blue component (0-255).
      * @param a Alpha component (0-255).

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

@@ -1,9 +1,12 @@
-import type { TextmodeCharacter, TyprFont } from './types.ts';
+import type { TextmodeCharacter } from './types.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Handles color generation and mapping for characters.
  * This class manages the unique RGB color assignment for character identification.
  */
 export declare class CharacterColorMapper {
+    private _fontTableReader;
+    constructor();
     /**
      * Creates TextmodeCharacter objects with unique color assignments.
      * @param characters Array of character strings
@@ -11,14 +14,6 @@ export declare class CharacterColorMapper {
      * @returns Array of TextmodeCharacter objects with colors
      */
     createCharacterObjects(characters: string[], font: TyprFont): TextmodeCharacter[];
-    /**
-     * Gets the glyph index for a given Unicode code point in a Typr.js font
-     * This is a simplified version for advance width lookup only
-     * @param fontData The Typr.js font data
-     * @param codePoint The Unicode code point to look up
-     * @returns The glyph index, or 0 if not found
-     */
-    private _getGlyphIndex;
     /**
      * Generates a unique RGB color for a character based on its index.
      * @param index The index of the character

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

@@ -1,35 +1,17 @@
-import type { TyprFont } from './types.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Handles extraction of characters from font cmap tables.
  * This class encapsulates the complex logic for reading different cmap table formats.
  */
 export declare class CharacterExtraction {
+    private _cmapParser;
+    constructor();
     /**
      * Extracts all available characters from a font's cmap tables.
      * @param font The parsed font object from Typr
      * @returns Array of unique character strings
      */
     extractCharacters(font: TyprFont): string[];
-    /**
-     * Extracts characters from a Format 4 cmap table (Basic Multilingual Plane).
-     * @param table The Format 4 cmap table
-     * @returns Array of character strings
-     */
-    private _extractCharactersFromFormat4Table;
-    /**
-     * Extracts characters from a Format 12 cmap table (Extended Unicode ranges).
-     * @param table The Format 12 cmap table
-     * @returns Array of character strings
-     */
-    private _extractCharactersFromFormat12Table;
-    /**
-     * Calculates the glyph index for a character in a Format 4 cmap table.
-     * @param table The Format 4 cmap table
-     * @param codePoint The Unicode code point
-     * @param rangeIndex The index of the character range
-     * @returns The glyph index, or 0 if not found
-     */
-    private _calculateGlyphIndexFormat4;
     /**
      * Filters out problematic characters that might cause rendering issues.
      * @param characters Array of character strings to filter
@@ -37,9 +19,17 @@ export declare class CharacterExtraction {
      */
     filterProblematicCharacters(characters: string[]): string[];
     /**
-     * Checks if a character is valid for rendering.
-     * @param char The character to check
-     * @returns True if the character is valid, false otherwise
+     * Checks if a character exists in the font.
+     * @param font The parsed font object from Typr
+     * @param character The character to check
+     * @returns True if the character exists in the font
+     */
+    characterExists(font: TyprFont, character: string): boolean;
+    /**
+     * Checks if all characters in a string exist in the font.
+     * @param font The parsed font object from Typr
+     * @param text The text string to check
+     * @returns True if all characters exist in the font
      */
-    private _isValidCharacter;
+    allCharactersExist(font: TyprFont, text: string): boolean;
 }

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

@@ -1,22 +1,47 @@
 import type { GlyphDimensions } from './types.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Handles calculation of font metrics and glyph dimensions.
- * This class encapsulates the logic for measuring text and calculating font properties.
+ * This class encapsulates the logic for measuring text and calculating font properties
+ * directly from font data using Typr.ts, eliminating the need for Canvas-based measurement.
  */
 export declare class FontMetricsCalculator {
-    private _tempCanvas;
-    private _tempContext;
+    private _tableReader;
     /**
-     * Creates a new MetricsCalculation instance.
+     * Creates a new FontMetricsCalculator instance.
      */
     constructor();
     /**
-     * Calculates the maximum glyph dimensions for a given set of characters.
+     * Calculates the maximum glyph dimensions for a given set of characters
+     * using direct font metrics from the parsed font data.
      * @param characters Array of character strings
-     * @param fontSize Font size to use for measurement
-     * @param fontFamilyName Font family name
-     * @param fontFace FontFace object (optional, for validation)
+     * @param fontSize Font size to use for scaling measurements
+     * @param font Parsed TyprFont object containing font data
      * @returns Object containing width and height dimensions
      */
-    calculateMaxGlyphDimensions(characters: string[], fontSize: number, fontFamilyName: string): GlyphDimensions;
+    calculateMaxGlyphDimensions(characters: string[], fontSize: number, font: TyprFont): GlyphDimensions;
+    /**
+     * Gets the character advance width for a specific character and font size.
+     * @param character The character to measure
+     * @param fontSize Font size to use for scaling
+     * @param font Parsed TyprFont object
+     * @returns Advance width in pixels
+     */
+    getCharacterAdvanceWidth(character: string, fontSize: number, font: TyprFont): number;
+    /**
+     * Gets the font-level ascender, descender, and line gap values for a given font size.
+     * @param fontSize Font size to use for scaling
+     * @param font Parsed TyprFont object
+     * @returns Object containing ascender, descender, and lineGap in pixels
+     */
+    getFontMetrics(fontSize: number, font: TyprFont): {
+        ascender: number;
+        descender: number;
+        lineGap: number;
+        lineHeight: number;
+    };
+    /**
+     * Clears internal caches. Useful for memory management.
+     */
+    $clearCache(): void;
 }

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

@@ -1,6 +1,7 @@
 import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
 import type { Framebuffer } from '../../rendering/webgl/Framebuffer.ts';
-import type { TextmodeCharacter, TyprFont } from './types.ts';
+import type { TextmodeCharacter } from './types.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Manages the textmode font used for rendering characters.
  *
@@ -78,7 +79,7 @@ export declare class TextmodeFont {
     hasAllCharacters(str: string): boolean;
     /**
      * Dispose of all resources used by this font manager.
-     * This method is idempotent and safe to call multiple times.
+     * @ignore
      */
     $dispose(): void;
     /**

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

@@ -1,14 +1,18 @@
 import type { TextmodeCharacter, GlyphDimensions } from './types.ts';
 import type { GLRenderer } from '../../rendering/webgl/Renderer.ts';
 import type { Framebuffer } from '../../rendering/webgl/Framebuffer.ts';
+import type { TyprFont } from './typr/types.ts';
 /**
  * Handles creation of texture atlases for font rendering.
  * This class manages the Canvas 2D rendering and WebGL framebuffer creation.
+ * Supports both Typr.js path-based rendering for uniform cross-browser text
+ * and fallback fillText rendering.
  */
 export declare class TextureAtlasCreation {
     private _textureCanvas;
     private _textureContext;
     private _renderer;
+    private _fontTableReader;
     /**
      * Creates a new TextureAtlasCreation instance.
      * @param renderer The WebGL renderer instance
@@ -19,10 +23,10 @@ export declare class TextureAtlasCreation {
      * @param characters Array of TextmodeCharacter objects
      * @param maxGlyphDimensions Maximum dimensions of glyphs
      * @param fontSize Font size for rendering
-     * @param fontFamilyName Font family name to use
+     * @param fontDataOrFamilyName Either Typr.js font data object for path rendering, or font family name string for fillText rendering
      * @returns Object containing framebuffer, columns, and rows
      */
-    createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, fontFamilyName: string): {
+    createTextureAtlas(characters: TextmodeCharacter[], maxGlyphDimensions: GlyphDimensions, fontSize: number, fontDataOrFamilyName: TyprFont | string): {
         framebuffer: Framebuffer;
         columns: number;
         rows: number;
@@ -31,25 +35,37 @@ export declare class TextureAtlasCreation {
      * Sets up the canvas for rendering.
      * @param width Canvas buffer width
      * @param height Canvas buffer height
-     * @param fontSize Font size
-     * @param fontFamilyName Font family name
-     * @param logicalWidth Logical width for scaling context
-     * @param logicalHeight Logical height for scaling context
      */
     private _setupCanvas;
     /**
-     * Renders all characters to the canvas in a grid layout.
+     * Renders all characters to the canvas in a grid layout using Typr.js paths.
      * @param characters Array of characters to render
      * @param maxGlyphDimensions Maximum glyph dimensions
      * @param textureColumns Number of columns in the texture
      * @param fontSize Font size
+     * @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;
+    /**
+     * Gets the advance width for a glyph
+     * @param fontData The Typr.js font data
+     * @param glyphIndex The glyph index
+     * @returns The advance width in font units
      */
-    private _renderCharactersToCanvas;
+    private _getGlyphAdvanceWidth;
     /**
-     * Applies a black and white threshold filter to the canvas.
-     * This converts antialiased grayscale pixels to pure black or white,
-     * ensuring crisp text rendering suitable for NEAREST texture filtering.
-     * @param threshold Threshold value (0-255) for black/white conversion
+     * Renders a glyph to the canvas using direct path rendering from glyph outline data.
+     * @param glyphData Glyph data from Typr.js
+     * @param x X position
+     * @param y Y position (baseline position)
+     * @param scale Scale factor
      */
-    private _applyBlackWhiteThreshold;
+    private _renderGlyphToCanvas;
 }

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

@@ -1,5 +1,7 @@
 export { TextmodeFont } from './TextmodeFont.ts';
-export type { TextmodeCharacter, GlyphDimensions, TyprFont, CmapTable, CmapTableFormat4, CmapTableFormat12, HeadTable, HheaTable, HmtxTable, MaxpTable, CmapData, GlyphData, LocaTable } from './types.ts';
+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 { FontMetricsCalculator as MetricsCalculation } from './MetricsCalculator.ts';

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

@@ -1,5 +1,5 @@
 /**
- * Represents a single character in the textmode font.
+ * Represents a single character in the {@link TextmodeFont.characters} array.
  */
 export type TextmodeCharacter = {
     /** The character itself. */
@@ -8,33 +8,9 @@ export type TextmodeCharacter = {
     unicode: number;
     /** The RGB color associated with the character for identification. */
     color: [number, number, number];
-    /** The advance width of the character. */
+    /** The advance width of the character. @ignore */
     advanceWidth: number;
 };
-/**
- * Interface for cmap table Format 4 (Basic Multilingual Plane)
- */
-export interface CmapTableFormat4 {
-    format: 4;
-    startCount: number[];
-    endCount: number[];
-    idRangeOffset: number[];
-    idDelta: number[];
-    glyphIdArray?: number[];
-}
-/**
- * Interface for cmap table Format 12 (Extended Unicode ranges)
- */
-export interface CmapTableFormat12 {
-    format: 12;
-    groups: number[];
-}
-/**
- * Union type for supported cmap table formats
- */
-export type CmapTable = CmapTableFormat4 | CmapTableFormat12 | {
-    format: number;
-};
 /**
  * Font glyph dimensions
  */
@@ -42,113 +18,3 @@ export interface GlyphDimensions {
     width: number;
     height: number;
 }
-/**
- * Head table from OpenType/TrueType font
- */
-export interface HeadTable {
-    fontRevision: number;
-    flags: number;
-    unitsPerEm: number;
-    created: number;
-    modified: number;
-    xMin: number;
-    yMin: number;
-    xMax: number;
-    yMax: number;
-    macStyle: number;
-    lowestRecPPEM: number;
-    fontDirectionHint: number;
-    indexToLocFormat: number;
-    glyphDataFormat: number;
-}
-/**
- * Horizontal header table from OpenType/TrueType font
- */
-export interface HheaTable {
-    ascender: number;
-    descender: number;
-    lineGap: number;
-    advanceWidthMax: number;
-    minLeftSideBearing: number;
-    minRightSideBearing: number;
-    xMaxExtent: number;
-    caretSlopeRise: number;
-    caretSlopeRun: number;
-    caretOffset: number;
-    res0: number;
-    res1: number;
-    res2: number;
-    res3: number;
-    metricDataFormat: number;
-    numberOfHMetrics: number;
-}
-/**
- * Horizontal metrics table from OpenType/TrueType font
- */
-export interface HmtxTable {
-    aWidth: number[];
-    lsBearing: number[];
-}
-/**
- * Maximum profile table from OpenType/TrueType font
- */
-export interface MaxpTable {
-    numGlyphs: number;
-}
-/**
- * Character map data from OpenType/TrueType font
- */
-export interface CmapData {
-    tables: CmapTable[];
-    ids: Record<string, number>;
-    off: number;
-}
-/**
- * Glyph data structure for parsed glyphs
- */
-export interface GlyphData {
-    xs: number[];
-    ys: number[];
-    endPts: number[];
-    flags: number[];
-    xMin: number;
-    yMin: number;
-    xMax: number;
-    yMax: number;
-}
-/**
- * Location table for glyph offsets
- */
-export interface LocaTable {
-    [glyphIndex: number]: number;
-}
-/**
- * Complete TyprFont interface representing a parsed OpenType/TrueType font
- * This interface describes the structure returned by Typr.parse()
- */
-export interface TyprFont {
-    /** Internal font data buffer */
-    _data: Uint8Array;
-    /** Font index in collection */
-    _index: number;
-    /** Font offset in data */
-    _offset: number;
-    /** Character map table */
-    cmap: CmapData;
-    /** Font header table */
-    head: HeadTable;
-    /** Horizontal header table */
-    hhea: HheaTable;
-    /** Horizontal metrics table */
-    hmtx: HmtxTable;
-    /** Maximum profile table */
-    maxp: MaxpTable;
-    /** Glyph location table (optional) */
-    loca?: LocaTable;
-    /** Glyph data table - stores parsed glyph data (optional, populated on demand) */
-    glyf?: {
-        [glyphIndex: number]: GlyphData | null;
-    };
-    /** Additional font tables that may be present */
-    [tableName: string]: any;
-}

package/dist/types/textmode/font/typr/Typr.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typr.ts - TypeScript Font Parsing Library for textmode.js
+ *
+ * A comprehensive TypeScript implementation of font parsing capabilities
+ * for OpenType and TrueType fonts. Provides essential functionality including
+ * character mapping, glyph data extraction, and font metrics processing.
+ *
+ * Originally based on Typr.js by photopea (https://github.com/photopea/Typr.js)
+ * Rewritten in TypeScript with enhanced type safety and optimizations for textmode.js
+ *
+ * @license MIT
+ */
+import type { TyprStatic } from './types';
+/**
+ * Main Typr class implementation
+ */
+declare const Typr: TyprStatic;
+export default Typr;