textmode.js 0.1.8-beta.2 → 0.1.8

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

@@ -0,0 +1,254 @@
+/**
+ * Type definitions for Typr.js - Font parsing library
+ *
+ * Comprehensive TypeScript types for all Typr font parsing structures,
+ * tables, and interfaces used throughout the font processing pipeline.
+ */
+/**
+ * Binary reading utilities interface
+ */
+export interface TyprBinary {
+    /** Read signed 16-bit integer */
+    readShort: (buff: Uint8Array, p: number) => number;
+    /** Read unsigned 16-bit integer */
+    readUshort: (buff: Uint8Array, p: number) => number;
+    /** Read array of unsigned 16-bit integers */
+    readUshorts: (buff: Uint8Array, p: number, len: number) => number[];
+    /** Read unsigned 32-bit integer */
+    readUint: (buff: Uint8Array, p: number) => number;
+    /** Read ASCII string */
+    readASCII: (buff: Uint8Array, p: number, l: number) => string;
+    /** Shared typed array buffers for efficient reading */
+    t: {
+        uint8: Uint8Array;
+        int16: Int16Array;
+        uint16: Uint16Array;
+        uint32: Uint32Array;
+    };
+}
+/**
+ * Interface for cmap table Format 4 (Basic Multilingual Plane)
+ * Used for Unicode BMP character mapping
+ */
+export interface CmapTableFormat4 {
+    format: 4;
+    searchRange: number;
+    entrySelector: number;
+    rangeShift: number;
+    startCount: number[];
+    endCount: number[];
+    idRangeOffset: number[];
+    idDelta: number[];
+    glyphIdArray: number[];
+}
+/**
+ * Interface for cmap table Format 12 (Extended Unicode ranges)
+ * Used for full Unicode character mapping including supplementary planes
+ */
+export interface CmapTableFormat12 {
+    format: 12;
+    groups: Uint32Array;
+}
+/**
+ * Union type for supported cmap table formats
+ */
+export type CmapTable = CmapTableFormat4 | CmapTableFormat12 | {
+    format: number;
+};
+/**
+ * Character map data from OpenType/TrueType font
+ * Contains multiple encoding tables and platform-specific mappings
+ */
+export interface CmapData {
+    /** Array of character mapping tables */
+    tables: CmapTable[];
+    /** Platform+encoding ID mappings to table indices */
+    ids: Record<string, number>;
+    /** Offset of cmap table in font data */
+    off: number;
+}
+/**
+ * Head table from OpenType/TrueType font
+ * Contains global font metrics and metadata
+ */
+export interface HeadTable {
+    /** Units per EM square */
+    unitsPerEm: number;
+    /** Minimum x coordinate across all glyphs */
+    xMin: number;
+    /** Minimum y coordinate across all glyphs */
+    yMin: number;
+    /** Maximum x coordinate across all glyphs */
+    xMax: number;
+    /** Maximum y coordinate across all glyphs */
+    yMax: number;
+    /** Format of location table (0 = short, 1 = long) */
+    indexToLocFormat: number;
+}
+/**
+ * Horizontal header table from OpenType/TrueType font
+ * Contains horizontal layout metrics
+ */
+export interface HheaTable {
+    /** Typographic ascender */
+    ascender: number;
+    /** Typographic descender */
+    descender: number;
+    /** Typographic line gap */
+    lineGap: number;
+    /** Maximum advance width */
+    advanceWidthMax: number;
+    /** Minimum left side bearing */
+    minLeftSideBearing: number;
+    /** Minimum right side bearing */
+    minRightSideBearing: number;
+    /** Maximum extent */
+    xMaxExtent: number;
+    /** Caret slope rise */
+    caretSlopeRise: number;
+    /** Caret slope run */
+    caretSlopeRun: number;
+    /** Caret offset */
+    caretOffset: number;
+    /** Reserved fields */
+    res0: number;
+    res1: number;
+    res2: number;
+    res3: number;
+    /** Metric data format */
+    metricDataFormat: number;
+    /** Number of horizontal metrics */
+    numberOfHMetrics: number;
+}
+/**
+ * Horizontal metrics table from OpenType/TrueType font
+ * Contains advance widths and left side bearings for all glyphs
+ */
+export interface HmtxTable {
+    /** Array of advance widths for each glyph */
+    aWidth: number[];
+    /** Array of left side bearings for each glyph */
+    lsBearing: number[];
+}
+/**
+ * Maximum profile table from OpenType/TrueType font
+ * Contains the number of glyphs and other maximums
+ */
+export interface MaxpTable {
+    /** Total number of glyphs in the font */
+    numGlyphs: number;
+}
+/**
+ * Location table for glyph offsets
+ * Maps glyph indices to their byte offsets in the glyf table
+ */
+export type LocaTable = number[];
+/**
+ * Glyph data structure for parsed glyphs
+ * Contains the actual glyph outline data
+ */
+export interface 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[];
+    /** Composite glyph parts (for composite glyphs) */
+    parts?: any[];
+}
+/**
+ * Font table parser interface
+ * Each table parser implements this interface
+ */
+export interface TableParser<T = any> {
+    parseTab: (data: Uint8Array, offset: number, length: number, font?: TyprFont) => T;
+}
+/**
+ * Extended cmap parser with format-specific methods
+ */
+export interface CmapParser extends TableParser<CmapData> {
+    parse4: (data: Uint8Array, offset: number) => CmapTableFormat4;
+    parse12: (data: Uint8Array, offset: number) => CmapTableFormat12;
+}
+/**
+ * Collection of all table parsers
+ */
+export interface TyprTableParsers {
+    cmap: CmapParser;
+    head: TableParser<HeadTable>;
+    hhea: TableParser<HheaTable>;
+    maxp: TableParser<MaxpTable>;
+    hmtx: TableParser<HmtxTable>;
+    loca: TableParser<LocaTable>;
+    glyf: TableParser<(GlyphData | null)[]> & {
+        _parseGlyf: (font: TyprFont, glyphIndex: number) => GlyphData | null;
+    };
+}
+/**
+ * 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 */
+    loca: LocaTable;
+    /** Glyph data table - stores parsed glyph data (populated on demand) */
+    glyf: (GlyphData | null)[];
+    /** Additional font tables that may be present */
+    [tableName: string]: any;
+}
+/**
+ * Glyph outline data structure
+ * Contains coordinate and control point information for rendering glyphs
+ */
+export interface GlyphData {
+    /** Number of contours in the glyph */
+    noc: number;
+    /** X coordinates of glyph points */
+    xs: number[];
+    /** Y coordinates of glyph points */
+    ys: number[];
+    /** Indices of the last point in each contour */
+    endPts: number[];
+    /** Flags indicating point types (on-curve, off-curve, etc.) */
+    flags: number[];
+}
+/**
+ * Main Typr interface
+ * Provides font parsing and table lookup functionality
+ */
+export interface TyprStatic {
+    /** Parse font buffer and return array of fonts */
+    parse: (buffer: ArrayBuffer) => TyprFont[];
+    /** Find a specific table in font data */
+    findTable: (data: Uint8Array, tableName: string, offset: number) => [number, number] | null;
+    /** Collection of table parsers */
+    T: TyprTableParsers;
+    /** Binary reading utilities */
+    B: TyprBinary;
+}

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

@@ -0,0 +1,47 @@
+import type { TyprFont } from '../typr/types.ts';
+import { FontTableReader } from './FontTableReader.ts';
+/**
+ * Specialized utility for character mapping operations.
+ * Provides high-level character extraction and validation functions.
+ */
+export declare class CmapParser {
+    private _tableReader;
+    constructor(tableReader: FontTableReader);
+    /**
+     * Extracts all available characters from a font's cmap tables.
+     * Returns an array of unique character strings.
+     */
+    $extractAllCharacters(font: TyprFont): string[];
+    /**
+     * Validates whether a character exists in the font.
+     */
+    $characterExists(font: TyprFont, character: string): boolean;
+    /**
+     * Validates whether all characters in a string exist in the font.
+     */
+    $allCharactersExist(font: TyprFont, text: string): boolean;
+    /**
+     * Filters out characters that don't exist in the font.
+     */
+    $filterExistingCharacters(font: TyprFont, characters: string[]): string[];
+    /**
+     * Filters out problematic characters that might cause rendering issues.
+     */
+    $filterProblematicCharacters(characters: string[]): string[];
+    /**
+     * Extracts characters from a Format 4 cmap table (Basic Multilingual Plane).
+     */
+    private _extractCharactersFromFormat4;
+    /**
+     * Extracts characters from a Format 12 cmap table (Extended Unicode ranges).
+     */
+    private _extractCharactersFromFormat12;
+    /**
+     * Calculates the glyph index for a character in a Format 4 cmap table.
+     */
+    private _calculateGlyphIndexFormat4;
+    /**
+     * Checks if a character is valid for rendering.
+     */
+    private _isValidCharacter;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Font-related constants and configuration values.
+ * Centralizes magic numbers and configuration to improve maintainability.
+ */
+/**
+ * Character mapping platform and encoding preferences.
+ * Ordered by preference for Unicode character mapping.
+ */
+export declare const CMAP_PLATFORM_PREFERENCES: readonly ["p3e1", "p3e10", "p0e3", "p0e4"];
+/**
+ * Control characters that are allowed in text rendering.
+ * Most control characters are filtered out, but these common ones are preserved.
+ */
+export declare const ALLOWED_CONTROL_CHARACTERS: readonly [9, 10, 13];
+/**
+ * Character code ranges to filter out during character extraction.
+ */
+export declare const FILTERED_CHARACTER_RANGES: readonly [{
+    readonly start: 0;
+    readonly end: 31;
+}, {
+    readonly start: 127;
+    readonly end: 159;
+}];
+/**
+ * Font table format constants.
+ */
+export declare const CMAP_FORMATS: {
+    readonly BMP_UNICODE: 4;
+    readonly FULL_UNICODE: 12;
+};
+/**
+ * Default font metrics and sizing constants.
+ */
+export declare const FONT_DEFAULTS: {
+    readonly SIZE: 16;
+    readonly FAMILY_NAME: "UrsaFont";
+    readonly ATLAS_PADDING: 1;
+};
+/**
+ * Cache size limits to prevent excessive memory usage.
+ */
+export declare const CACHE_LIMITS: {
+    readonly GLYPH_INDEX_CACHE: 10000;
+    readonly CMAP_TABLE_CACHE: 100;
+    readonly FONT_METRICS_CACHE: 1000;
+};
+/**
+ * Sentinel values used in font tables.
+ */
+export declare const FONT_SENTINELS: {
+    readonly CMAP_END_MARKER: 65535;
+};
+/**
+ * WebGL texture configuration for font atlases.
+ */
+export declare const TEXTURE_CONFIG: {
+    readonly FILTER: "nearest";
+    readonly WRAP: "clamp-to-edge";
+};

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

@@ -0,0 +1,56 @@
+import type { TyprFont, CmapTable } 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.
+ */
+export declare class FontTableReader {
+    private _glyphIndexCache;
+    private _cmapTableCache;
+    /**
+     * Gets the best character mapping table for Unicode text.
+     * Prefers format 4 (BMP Unicode) or format 12 (full Unicode).
+     * Results are cached per font.
+     */
+    $getBestCmapTable(font: TyprFont): CmapTable | null;
+    /**
+     * Gets the glyph index for a given Unicode code point.
+     * Results are cached per font and character.
+     */
+    $getGlyphIndex(font: TyprFont, codePoint: number): number;
+    /**
+     * Gets the glyph index for a character string.
+     * Convenience method that extracts the code point first.
+     */
+    $getGlyphIndexForCharacter(font: TyprFont, character: string): number;
+    /**
+     * Gets the advance width for a glyph from the horizontal metrics table.
+     */
+    $getGlyphAdvanceWidth(font: TyprFont, glyphIndex: number): number;
+    /**
+     * Gets font-level metrics scaled to the specified font size.
+     */
+    $getFontMetrics(font: TyprFont, fontSize: number): {
+        ascender: number;
+        descender: number;
+        lineGap: number;
+        lineHeight: number;
+        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).
+     */
+    private _getGlyphIndexFormat4;
+    /**
+     * Gets glyph index from format 12 cmap table (full Unicode).
+     */
+    private _getGlyphIndexFormat12;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Font utilities - centralized font processing functionality.
+ *
+ * This module provides shared utilities that eliminate code duplication
+ * across the font system components.
+ */
+export { FontTableReader } from './FontTableReader.ts';
+export { CmapParser } from './CmapParser.ts';
+export * from './FontConstants.ts';

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

@@ -6,7 +6,6 @@ import type { TextmodeConverter } from '../converters';
 export interface ConversionCapabilities {
     /**
      * Adds a new converter to the pipeline.
-     * @param name A unique name for the converter.
      * @param type The type of converter to add. Can be either "brightness" or "custom".
      * @returns The newly created {@link TextmodeConverter} instance or `void` if the addition failed.
      *
@@ -19,17 +18,17 @@ export interface ConversionCapabilities {
      * const textmodifier = await textmode.create(canvas);
      *
      * // Add a new brightness converter
-     * const myConverter = textmodifier.addConverter('my-brightness', 'brightness');
+     * const myConverter = textmodifier.addConverter('brightness');
      *
      * // Configure the new converter
      * myConverter.characters("▓▒░ ");
      * myConverter.enabled(true);
      *
      * // Add a custom converter
-     * const customConverter = textmodifier.addConverter('my-custom', 'custom');
+     * const customConverter = textmodifier.addConverter('custom');
      * ```
      */
-    addConverter(name: string, type: 'brightness' | 'custom'): TextmodeConverter | void;
+    addConverter(type: 'brightness' | 'custom'): TextmodeConverter | void;
     /**
      * Removes a converter from the pipeline by name or instance.
      * @param nameOrInstance The unique name of the converter or the converter instance to remove.

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

@@ -1,7 +1,7 @@
 import type { Mixin } from './TextmodifierMixin';
 import { type SVGExportOptions } from '../../export/svg';
 import { type TXTExportOptions } from '../../export/txt';
-import { type ImageExportOptions, type ImageFormat } from '../../export/image';
+import { type ImageExportOptions } from '../../export/image';
 /**
  * Interface for export capabilities that will be mixed into Textmodifier
  */
@@ -30,18 +30,6 @@ export interface ExportCapabilities {
      *
      * // Print to console or use otherwise
      * console.log(textString);
-     *
-     * ////////
-     *
-     * // Example with video element
-     * const video = document.querySelector('video#myVideo');
-     * const videoTextmodifier = await textmode.create(video);
-     *
-     * // The textmode overlay will automatically update as the video plays
-     * video.play();
-     *
-     * // Get current frame as ASCII
-     * const videoFrame = videoTextmodifier.toString();
      * ```
      */
     toString(options?: Omit<TXTExportOptions, 'filename'>): string;
@@ -145,7 +133,7 @@ export interface ExportCapabilities {
      * });
      * ```
      */
-    saveCanvas(filename: string, format?: ImageFormat, options?: Omit<ImageExportOptions, 'filename' | 'format'>): Promise<void>;
+    saveCanvas(filename: string, format?: 'png' | 'jpg' | 'webp', options?: Omit<ImageExportOptions, 'filename' | 'format'>): Promise<void>;
 }
 /**
  * Mixin that adds export capabilities to a class

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

@@ -381,6 +381,7 @@ export interface RenderingCapabilities {
      * @param vertexSource The GLSL source code for the vertex shader.
      * @param fragmentSource The GLSL source code for the fragment shader.
      * @returns The created shader program for use in `textmode.js`.
+     * @ignore
      */
     createShader(vertexSource: string, fragmentSource: string): Shader;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.1.8-beta.2",
+  "version": "0.1.8",
   "description": "Apply real-time ASCII conversion to any HTML canvas.",
   "type": "module",
   "types": "./dist/types/index.d.ts",