@utsp/render 0.11.0-nightly.20251213152020.671c815 → 0.11.0-nightly.20251213232121.8b318c1

package/dist/2d/index.d.ts

@@ -0,0 +1,907 @@
+import { IRenderer, ScalingMode, RGBColor, RenderState } from '@utsp/types';
+export { IRenderer, RenderState, ScalingMode } from '@utsp/types';
+
+/**
+ * Atlas Utilities
+ *
+ * Shared utilities for block-based font atlas calculations.
+ * Used by both TerminalGL (WebGL) and ImageFontAtlas (Canvas2D).
+ */
+/**
+ * Number of 256-char blocks in an atlas
+ * - 1 block = 16×16 grid = 256 chars (8-bit)
+ * - 4 blocks = 32×32 grid = 1024 chars (10-bit)
+ * - 16 blocks = 64×64 grid = 4096 chars (12-bit)
+ */
+type AtlasBlocks = 1 | 4 | 16;
+/**
+ * Get the number of columns in the atlas grid
+ * @param blocks - Number of 256-char blocks (1, 4, or 16)
+ * @returns Number of character columns (16, 32, or 64)
+ */
+declare function getAtlasColumns(blocks: AtlasBlocks): number;
+/**
+ * Get the maximum valid charCode for a given atlas size
+ * @param blocks - Number of 256-char blocks (1, 4, or 16)
+ * @returns Maximum charCode (255, 1023, or 4095)
+ */
+declare function getMaxCharCode(blocks: AtlasBlocks): number;
+/**
+ * Get character grid position in a block-based atlas
+ *
+ * Atlas layout for multi-block fonts:
+ * - Each block contains 256 chars in a 16×16 grid
+ * - Blocks are arranged in a square:
+ *   - 1 block:  1×1 (16×16 chars total)
+ *   - 4 blocks: 2×2 (32×32 chars total)
+ *   - 16 blocks: 4×4 (64×64 chars total)
+ *
+ * CharCode mapping:
+ *   charCode 0-255   → Block 0 (top-left)
+ *   charCode 256-511 → Block 1 (top-right for 4+ blocks)
+ *   charCode 512-767 → Block 2 (bottom-left for 4 blocks)
+ *   etc.
+ *
+ * @param charCode - Character code (0 to maxCharCode)
+ * @param blocks - Number of 256-char blocks (1, 4, or 16)
+ * @returns Grid position { col, row } in the atlas
+ */
+declare function getCharGridPosition(charCode: number, blocks: AtlasBlocks): {
+    col: number;
+    row: number;
+};
+
+/**
+ * Représente une cellule du terminal
+ */
+interface TerminalCell {
+    /** Le caractère à afficher */
+    char: string;
+    /** Couleur du caractère (format CSS) */
+    fgColor: string;
+    /** Couleur de fond de la cellule (format CSS) */
+    bgColor: string;
+}
+/**
+ * Données brutes pour définir le terminal en une fois
+ */
+interface TerminalData {
+    /** Largeur en cellules */
+    width: number;
+    /** Hauteur en cellules */
+    height: number;
+    /** Tableau de cellules (longueur = width * height) */
+    cells: Array<{
+        /** Code du caractère ou le caractère lui-même */
+        char: string;
+        /** Couleur du texte (format CSS) */
+        fgColor: string;
+        /** Couleur de fond (format CSS) */
+        bgColor: string;
+    }>;
+}
+/**
+ * Police bitmap matricielle
+ * Map qui associe un code de caractère (charCode) à une représentation bitmap 8x8
+ * Chaque Uint8Array contient 8 octets, un par ligne de pixels
+ */
+type BitmapFont$1 = Map<number, Uint8Array>;
+/**
+ * Type de police à utiliser
+ */
+type FontType = {
+    type: 'web';
+    fontFamily: string;
+    fontSize: number;
+} | {
+    type: 'bitmap';
+    font: BitmapFont$1;
+    charWidth: number;
+    charHeight: number;
+};
+/**
+ * Options pour la configuration du terminal
+ */
+interface RenderOptions {
+    /** Largeur d'une cellule en pixels (défaut: 10) - ignoré en mode fixedGrid */
+    cellWidth?: number;
+    /** Hauteur d'une cellule en pixels (défaut: 14) - ignoré en mode fixedGrid */
+    cellHeight?: number;
+    /** Taille de la police en pixels (défaut: 12) */
+    fontSize?: number;
+    /** Famille de police (défaut: "monospace") */
+    fontFamily?: string;
+    /** Couleur de texte par défaut (défaut: "#ffffff") */
+    defaultFgColor?: string;
+    /** Couleur de fond par défaut (défaut: "#000000") */
+    defaultBgColor?: string;
+    /** Couleur de fond du canvas lui-même (défaut: transparent). Si null ou undefined, le canvas sera transparent */
+    canvasBgColor?: string | null;
+    /** Afficher une grille de débogage (défaut: false) */
+    showDebugGrid?: boolean;
+    /** Couleur de la grille de débogage (défaut: "rgba(255, 0, 0, 0.3)") */
+    debugGridColor?: string;
+    /** Classes CSS additionnelles pour le canvas */
+    className?: string;
+    /** Style inline pour le canvas */
+    style?: Partial<CSSStyleDeclaration>;
+    /** Nombre de colonnes fixe (active le mode fixedGrid) */
+    fixedCols?: number;
+    /** Nombre de lignes fixe (active le mode fixedGrid) */
+    fixedRows?: number;
+    /** Ratio largeur/hauteur de cellule pour mode fixedGrid (défaut: 10/14 ≈ 0.714) */
+    cellAspectRatio?: number;
+    /**
+     * Scaling mode for pixel-perfect rendering (default: ScalingMode.None)
+     *
+     * Controls how the canvas is scaled to fit the container:
+     * - ScalingMode.None: Scales cells to fill space, may have sub-pixel artifacts
+     * - ScalingMode.Eighth: Snaps to 0.125 increments (1.0, 1.125, 1.25...)
+     * - ScalingMode.Quarter: Snaps to 0.25 increments (1.0, 1.25, 1.5...)
+     * - ScalingMode.Half: Snaps to 0.5 increments (1.0, 1.5, 2.0...)
+     * - ScalingMode.Integer: Integer scaling only (1x, 2x, 3x...), crispest pixels
+     *
+     * Note: For ImageFont mode, this uses native glyph sizes + CSS transform scaling.
+     */
+    scalingMode?: ScalingMode;
+}
+/**
+ * UTSP Render - Gère une grille de caractères avec couleurs
+ * Similaire à un terminal mais avec contrôle total de chaque cellule
+ *
+ * Implements IRenderer interface for compatibility with TerminalGL and dependency injection.
+ */
+declare class Terminal2D implements IRenderer {
+    private containerDiv;
+    private canvas;
+    private ctx;
+    private parentElement;
+    private cells;
+    private cols;
+    private rows;
+    private fontSize;
+    private fontFamily;
+    private defaultFgColor;
+    private defaultBgColor;
+    private canvasBgColor;
+    private cellWidth;
+    private cellHeight;
+    private offsetX;
+    private offsetY;
+    private fontType;
+    private bitmapFont?;
+    private bitmapAtlas?;
+    private imageAtlas?;
+    private bitmapCharWidth;
+    private bitmapCharHeight;
+    private showDebugGrid;
+    private debugGridColor;
+    private gridOverlay?;
+    private fixedGridMode;
+    private fixedCols?;
+    private fixedRows?;
+    private cellAspectRatio;
+    private resizeObserver?;
+    private imageDataBuffer?;
+    private useImageDataRendering;
+    private paletteCache?;
+    private scalingMode;
+    private currentScale;
+    /**
+     * Crée une instance de UTSPRender
+     * @param parentDiv - L'élément HTML parent dans lequel créer le canvas
+     * @param options - Options de configuration du terminal
+     */
+    constructor(parentDiv: HTMLElement, options?: RenderOptions);
+    /**
+     * Calcule le nombre de colonnes et de lignes en fonction de la taille du parent
+     * et centre le terminal dans le canvas
+     *
+     * 🎯 PIXEL-PERFECT APPROACH (like TerminalGL):
+     * 1. Cell dimensions are ALWAYS integers (native font size)
+     * 2. Canvas renders at native resolution (cols * cellWidth)
+     * 3. CSS transform: scale() handles visual upscaling
+     * 4. Flexbox handles centering
+     */
+    private calculateGridSize;
+    /**
+     * Crée une grille vide avec les valeurs par défaut
+     */
+    private createEmptyGrid;
+    /**
+     * Active le redimensionnement automatique
+     * Recalcule le nombre de colonnes/lignes quand le parent change de taille
+     */
+    private enableAutoResize;
+    /**
+     * Définit le contenu d'une cellule
+     * @param col - Colonne (0-indexed)
+     * @param row - Ligne (0-indexed)
+     * @param char - Caractère à afficher
+     * @param fgColor - Couleur du texte (optionnel, utilise la valeur par défaut si non fourni)
+     * @param bgColor - Couleur de fond (optionnel, utilise la valeur par défaut si non fourni)
+     */
+    setCell(col: number, row: number, char: string, fgColor?: string, bgColor?: string): void;
+    /**
+     * Récupère le contenu d'une cellule
+     * @param col - Colonne (0-indexed)
+     * @param row - Ligne (0-indexed)
+     */
+    getCell(col: number, row: number): TerminalCell | null;
+    /**
+     * Écrit une chaîne de caractères à partir d'une position
+     * @param col - Colonne de départ
+     * @param row - Ligne
+     * @param text - Texte à écrire
+     * @param fgColor - Couleur du texte (optionnel)
+     * @param bgColor - Couleur de fond (optionnel)
+     */
+    write(col: number, row: number, text: string, fgColor?: string, bgColor?: string): void;
+    /**
+     * Remplit une zone rectangulaire
+     * @param startCol - Colonne de départ
+     * @param startRow - Ligne de départ
+     * @param width - Largeur en cellules
+     * @param height - Hauteur en cellules
+     * @param char - Caractère de remplissage
+     * @param fgColor - Couleur du texte (optionnel)
+     * @param bgColor - Couleur de fond (optionnel)
+     */
+    fillRect(startCol: number, startRow: number, width: number, height: number, char?: string, fgColor?: string, bgColor?: string): void;
+    /**
+     * Efface tout le terminal (remplit avec des espaces)
+     */
+    clear(): void;
+    /**
+     * Définit tout le contenu du terminal à partir d'un tableau de données
+     * Le tableau doit contenir width * height éléments
+     * Les cellules sont lues ligne par ligne (row-major order)
+     *
+     * @param data - Données du terminal avec dimensions et cellules
+     * @throws Error si le tableau n'a pas la bonne taille
+     *
+     * @example
+     * terminal.setFromArray({
+     *   width: 3,
+     *   height: 2,
+     *   cells: [
+     *     { char: 'A', fgColor: '#ff0000', bgColor: '#000000' }, // (0,0)
+     *     { char: 'B', fgColor: '#00ff00', bgColor: '#000000' }, // (1,0)
+     *     { char: 'C', fgColor: '#0000ff', bgColor: '#000000' }, // (2,0)
+     *     { char: 'D', fgColor: '#ffff00', bgColor: '#000000' }, // (0,1)
+     *     { char: 'E', fgColor: '#ff00ff', bgColor: '#000000' }, // (1,1)
+     *     { char: 'F', fgColor: '#00ffff', bgColor: '#000000' }, // (2,1)
+     *   ]
+     * });
+     */
+    setFromArray(data: TerminalData): void;
+    /**
+     * Rend la grille sur le canvas
+     */
+    render(): void;
+    /**
+     * Rendu ultra-rapide avec ImageData (bitmap)
+     * ~10-20× plus rapide que fillRect en boucle
+     * Fonctionne avec scaling : buffer natif 8×8 puis drawImage() pour upscale
+     */
+    private renderWithImageData;
+    /**
+     * Parse une couleur CSS en composantes RGBA
+     */
+    private parseColorToRGB;
+    /**
+     * Rendu classique avec fillRect/fillText (compatible scaling, web fonts, etc.)
+     */
+    private renderClassic;
+    /**
+     * Dessine un caractère en utilisant une police bitmap
+     */
+    private drawBitmapChar;
+    /**
+     * Dessine une grille de débogage pour visualiser les cellules
+     */
+    private drawDebugGrid;
+    /**
+     * Obtient le canvas HTML
+     */
+    getCanvas(): HTMLCanvasElement;
+    /**
+     * Obtient le contexte 2D
+     */
+    getContext(): CanvasRenderingContext2D;
+    /**
+     * Obtient les dimensions de la grille
+     */
+    getDimensions(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Obtient les dimensions des cellules
+     */
+    getCellDimensions(): {
+        cellWidth: number;
+        cellHeight: number;
+    };
+    /**
+     * Obtient la largeur d'une cellule
+     */
+    getCellWidth(): number;
+    /**
+     * Obtient la hauteur d'une cellule
+     */
+    getCellHeight(): number;
+    /**
+     * Get current scaling factor (for pixel-perfect modes)
+     * Returns 1 if scalingMode is None or not using ImageFont
+     */
+    getCurrentScale(): number;
+    /**
+     * Get scaling mode
+     */
+    getScalingMode(): ScalingMode;
+    /**
+     * Obtient les décalages de centrage du terminal
+     */
+    getOffsets(): {
+        offsetX: number;
+        offsetY: number;
+    };
+    /**
+     * Active ou désactive la grille de débogage
+     * @param show - true pour afficher la grille, false pour la masquer
+     */
+    setDebugGrid(show: boolean): void;
+    /**
+     * Change la couleur de fond du canvas
+     * @param color - Couleur CSS (ex: "#000000", "rgba(0,0,0,0.5)") ou null pour transparent
+     */
+    setCanvasBackgroundColor(color: string | null): void;
+    /**
+     * Obtient la couleur de fond actuelle du canvas
+     * @returns La couleur de fond ou null si transparent
+     */
+    getCanvasBackgroundColor(): string | null;
+    /**
+     * Active le mode grille fixe avec le nombre de colonnes/lignes spécifié
+     * Les cellules s'adapteront en taille pour maintenir les dimensions demandées
+     * @param cols - Nombre de colonnes fixe
+     * @param rows - Nombre de lignes fixe
+     * @param aspectRatio - Ratio largeur/hauteur de cellule (optionnel, défaut: 10/14)
+     */
+    setFixedGrid(cols: number, rows: number, aspectRatio?: number): void;
+    /**
+     * Désactive le mode grille fixe et revient au mode adaptatif
+     * @param cellWidth - Largeur de cellule en pixels (optionnel)
+     * @param cellHeight - Hauteur de cellule en pixels (optionnel)
+     */
+    setAdaptiveGrid(cellWidth?: number, cellHeight?: number): void;
+    /**
+     * Vérifie si le terminal est en mode grille fixe
+     */
+    isFixedGridMode(): boolean;
+    /**
+     * Définit la couleur de la grille de débogage
+     * @param color - Couleur CSS (ex: "rgba(255, 0, 0, 0.3)" ou "#ff0000")
+     */
+    setDebugGridColor(color: string): void;
+    /**
+     * Vérifie si la grille de débogage est activée
+     */
+    isDebugGridEnabled(): boolean;
+    /**
+     * Active ou désactive le rendu optimisé avec ImageData
+     * Uniquement disponible pour les polices bitmap à taille native (pas de scaling)
+     * Environ 10-20× plus rapide que le rendu classique, idéal pour les benchmarks
+     *
+     * @param enable - true pour activer, false pour désactiver
+     */
+    setImageDataRendering(enable: boolean): void;
+    /**
+     * Vérifie si le rendu ImageData est activé
+     */
+    isImageDataRenderingEnabled(): boolean;
+    /**
+     * Configure une police web (CSS)
+     * @param fontFamily - Nom de la police CSS (ex: "Courier New", "monospace")
+     * @param fontSize - Taille de la police en pixels (optionnel, garde la taille actuelle si non spécifié)
+     */
+    setWebFont(fontFamily: string, fontSize?: number): void;
+    /**
+     * Configure une police bitmap matricielle
+     * @param font - Map contenant les définitions bitmap des caractères (charCode -> Uint8Array)
+     * @param charWidth - Largeur du glyphe en pixels (bitmap source)
+     * @param charHeight - Hauteur du glyphe en pixels (bitmap source)
+     * @param cellWidth - Largeur de la cellule de rendu en pixels
+     * @param cellHeight - Hauteur de la cellule de rendu en pixels
+     */
+    setBitmapFont(font: BitmapFont$1, charWidth: number, charHeight: number, cellWidth: number, cellHeight: number): void;
+    /**
+     * Configure une police image (atlas PNG)
+     * @param imageData - Données PNG brutes
+     * @param glyphWidth - Largeur du glyphe en pixels
+     * @param glyphHeight - Hauteur du glyphe en pixels
+     * @param cellWidth - Largeur de la cellule en pixels
+     * @param cellHeight - Hauteur de la cellule en pixels
+     * @param atlasBlocks - Nombre de blocs de 256 caractères (1, 4, ou 16)
+     */
+    setImageFont(imageData: Uint8Array, glyphWidth: number, glyphHeight: number, cellWidth: number, cellHeight: number, atlasBlocks: AtlasBlocks): Promise<void>;
+    /**
+     * Retourne le type de police actuellement utilisé
+     */
+    getFontType(): 'web' | 'bitmap' | 'image';
+    /**
+     * Retourne la police bitmap actuelle (si applicable)
+     */
+    getBitmapFont(): BitmapFont$1 | undefined;
+    /**
+     * Retourne les dimensions de caractère bitmap (si applicable)
+     */
+    getBitmapCharDimensions(): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Set color palette (IRenderer contract).
+     * Called by ClientRuntime when Core palette changes.
+     *
+     * @param palette - Array of 256 RGBA colors
+     */
+    setPalette(palette: RGBColor[]): void;
+    /**
+     * Render display data (IRenderer contract).
+     * Converts RenderState from Core to cell-based rendering.
+     *
+     * @param display - Display data with palette indices
+     */
+    renderDisplayData(display: RenderState): void;
+    /**
+     * Check if renderer is ready to render (IRenderer contract).
+     * Canvas 2D is always ready immediately (no async initialization).
+     *
+     * @returns Always true for Canvas 2D
+     */
+    isReady(): boolean;
+    /**
+     * Get width in columns (IRenderer contract).
+     */
+    getCols(): number;
+    /**
+     * Get height in rows (IRenderer contract).
+     */
+    getRows(): number;
+    /**
+     * Resize renderer dimensions (IRenderer contract).
+     *
+     * @param cols - New width in columns
+     * @param rows - New height in rows
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Détruit le terminal et nettoie les ressources
+     */
+    destroy(): void;
+}
+
+/**
+ * Police bitmap matricielle
+ * Map qui associe un code de caractère (charCode) à une représentation bitmap
+ */
+type BitmapFont = Map<number, Uint8Array>;
+/**
+ * Atlas à une résolution spécifique
+ */
+interface AtlasResolution {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    scale: number;
+    charWidth: number;
+    charHeight: number;
+}
+/**
+ * Classe pour générer et gérer un atlas de police bitmap multi-résolution
+ * Convertit une police matricielle (bits) en plusieurs textures canvas à différentes échelles
+ * pour un rendu ultra-rapide avec qualité optimale quelque soit le zoom
+ *
+ * Utilise un cache LRU de glyphes colorés pour éviter la re-colorisation
+ */
+declare class BitmapFontAtlas {
+    private atlases;
+    private charMap;
+    private baseCharWidth;
+    private baseCharHeight;
+    private baseCellWidth;
+    private baseCellHeight;
+    private atlasColumns;
+    private font;
+    private readonly SCALES;
+    private colorCache;
+    private readonly MAX_CACHE_SIZE;
+    /**
+     * Construit un atlas de police bitmap multi-résolution
+     * @param font La police bitmap source
+     * @param charWidth Largeur de base d'un caractère en pixels (taille du glyphe dans l'atlas)
+     * @param charHeight Hauteur de base d'un caractère en pixels (taille du glyphe dans l'atlas)
+     * @param cellWidth Largeur de base d'une cellule en pixels (peut être > charWidth pour l'espacement)
+     * @param cellHeight Hauteur de base d'une cellule en pixels (peut être > charHeight pour l'espacement)
+     */
+    constructor(font: BitmapFont, charWidth: number, charHeight: number, cellWidth?: number, cellHeight?: number); /**
+     * Génère les 4 atlas à différentes résolutions (1x, 2x, 4x, 8x)
+     * Très rapide: ~4-8ms pour 256 caractères × 4 résolutions
+     */
+    private generateAtlases;
+    /**
+     * Récupère ou crée un atlas pour une échelle donnée
+     */
+    private getOrCreateAtlas;
+    /**
+     * Rend un caractère bitmap dans un atlas à une résolution donnée
+     * Utilise fillRect pour un rendu ultra-rapide
+     */
+    private renderBitmapToAtlas;
+    /**
+     * Dessine un caractère en utilisant le cache de glyphes colorés
+     * Ultra-rapide: 1 seul drawImage() par caractère
+     * Utilise ImageData pour coloriser + Canvas cache pour éviter la re-colorisation
+     *
+     * @param ctx - Contexte de destination
+     * @param charCode - Code du caractère à dessiner
+     * @param x - Position X de destination (coin de la cellule)
+     * @param y - Position Y de destination (coin de la cellule)
+     * @param width - Largeur de la cellule de destination
+     * @param height - Hauteur de la cellule de destination
+     * @param color - Couleur du caractère (format CSS)
+     */
+    drawChar(ctx: CanvasRenderingContext2D, charCode: number, x: number, y: number, width: number, height: number, color: string): void;
+    /**
+     * Crée un glyphe colorisé à partir de l'atlas blanc
+     * Utilise ImageData pour une colorisation ultra-rapide
+     */
+    private createColoredGlyph;
+    /**
+     * Convertit une couleur hex en RGB
+     */
+    private hexToRgb;
+    /**
+     * Élimine les entrées les moins récemment utilisées du cache (LRU)
+     */
+    private evictLRU;
+    /**
+     * Retourne le canvas d'atlas pour une résolution donnée (pour débogage/visualisation)
+     * Par défaut retourne l'atlas 1x
+     */
+    getAtlasCanvas(scale?: number): HTMLCanvasElement | undefined;
+    /**
+     * Retourne tous les atlas disponibles
+     */
+    getAllAtlases(): Map<number, AtlasResolution>;
+    /**
+     * Retourne les dimensions de base d'un caractère
+     */
+    getCharDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Retourne le nombre de caractères dans l'atlas
+     */
+    getCharCount(): number;
+    /**
+     * Vérifie si un caractère existe dans l'atlas
+     */
+    hasChar(charCode: number): boolean;
+    /**
+     * Retourne les dimensions d'un atlas à une résolution donnée
+     */
+    getAtlasDimensions(scale?: number): {
+        width: number;
+        height: number;
+    } | undefined;
+    /**
+     * Exporte un atlas en Data URL (pour débogage)
+     * Permet de visualiser l'atlas ou de le sauvegarder
+     */
+    toDataURL(scale?: number, type?: string): string | undefined;
+    /**
+     * Retourne les statistiques du cache de glyphes colorés
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hitRate?: number;
+    };
+    /**
+     * Vide le cache de glyphes colorés
+     */
+    clearCache(): void;
+    /**
+     * Libère les ressources
+     */
+    destroy(): void;
+}
+
+/**
+ * ImageFontAtlas - Atlas for PNG-based fonts with multi-block support
+ *
+ * Supports 1, 4, or 16 blocks of 256 characters each:
+ * - 1 block = 16×16 grid = 256 chars (8-bit)
+ * - 4 blocks = 32×32 grid = 1024 chars (10-bit)
+ * - 16 blocks = 64×64 grid = 4096 chars (12-bit)
+ */
+
+/**
+ * Configuration for ImageFontAtlas
+ */
+interface ImageFontAtlasConfig {
+    glyphWidth: number;
+    glyphHeight: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    atlasBlocks: AtlasBlocks;
+}
+/**
+ * ImageFontAtlas class
+ * Manages a PNG-based font atlas with support for extended character sets
+ */
+declare class ImageFontAtlas {
+    private atlasCanvas;
+    private atlasCtx;
+    private atlasImage;
+    private readonly glyphWidth;
+    private readonly glyphHeight;
+    private readonly cellWidth;
+    private readonly cellHeight;
+    private readonly atlasBlocks;
+    private readonly atlasColumns;
+    private readonly maxCharCode;
+    private isLoaded;
+    private colorCache;
+    private readonly MAX_CACHE_SIZE;
+    constructor(config: ImageFontAtlasConfig);
+    /**
+     * Load atlas from PNG binary data
+     * @param pngData PNG image as Uint8Array
+     * @returns Promise that resolves when atlas is loaded
+     */
+    loadFromPNG(pngData: Uint8Array): Promise<void>;
+    /**
+     * Check if atlas is loaded and ready
+     */
+    isReady(): boolean;
+    /**
+     * Get glyph position in atlas
+     * @param charCode Character code (0 to maxCharCode)
+     * @returns Position { x, y } or null if out of range
+     */
+    getGlyphPosition(charCode: number): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Get UV coordinates for a character (block-based layout)
+     * @param charCode Character code
+     * @returns UV coordinates { u1, v1, u2, v2 } or null if invalid
+     */
+    getCharUV(charCode: number): {
+        u1: number;
+        v1: number;
+        u2: number;
+        v2: number;
+    } | null;
+    /**
+     * Draw a character to a canvas context
+     * @param ctx Destination context
+     * @param charCode Character to draw
+     * @param x Destination X
+     * @param y Destination Y
+     * @param width Destination width
+     * @param height Destination height
+     * @param color Color for the glyph (CSS color string)
+     */
+    drawChar(ctx: CanvasRenderingContext2D, charCode: number, x: number, y: number, width: number, height: number, color: string): void;
+    /**
+     * Create a colored glyph from the atlas
+     */
+    private createColoredGlyph;
+    /**
+     * Parse CSS color to RGB
+     */
+    private parseColor;
+    /**
+     * Evict least recently used cache entry
+     */
+    private evictLRU;
+    /**
+     * Get the atlas canvas (for WebGL texture upload)
+     */
+    getAtlasCanvas(): HTMLCanvasElement | null;
+    /**
+     * Get the atlas image (for WebGL texture upload)
+     */
+    getAtlasImage(): HTMLImageElement | null;
+    /**
+     * Get atlas configuration
+     */
+    getConfig(): ImageFontAtlasConfig;
+    /**
+     * Get glyph dimensions
+     */
+    getGlyphDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get cell dimensions
+     */
+    getCellDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get atlas dimensions
+     */
+    getAtlasDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get number of atlas columns
+     */
+    getAtlasColumns(): number;
+    /**
+     * Get maximum supported character code
+     */
+    getMaxCharCode(): number;
+    /**
+     * Check if a character code is valid
+     */
+    isValidCharCode(charCode: number): boolean;
+    /**
+     * Clear the color cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+    /**
+     * Destroy and release resources
+     */
+    destroy(): void;
+}
+
+/**
+ * 🔲 GridOverlay - Classe réutilisable pour gérer le canvas de grille de débogage
+ *
+ * Gère un canvas 2D superposé qui affiche une grille de cellules.
+ * Au lieu de simples lignes, dessine un cadre fin à l'intérieur de chaque cellule
+ * pour une meilleure visualisation.
+ *
+ * @example
+ * ```typescript
+ * const grid = new GridOverlay(containerElement);
+ * grid.setDimensions(80, 24, 10, 16);
+ * grid.render();
+ * ```
+ */
+declare class GridOverlay {
+    private canvas;
+    private ctx;
+    private container;
+    private cols;
+    private rows;
+    private cellWidth;
+    private cellHeight;
+    private offsetX;
+    private offsetY;
+    private strokeColor;
+    private lineWidth;
+    /**
+     * Crée une nouvelle overlay de grille
+     * @param container - Élément parent qui contiendra le canvas
+     * @param options - Options de configuration
+     */
+    constructor(container: HTMLElement, options?: {
+        strokeColor?: string;
+        lineWidth?: number;
+        zIndex?: number;
+    });
+    /**
+     * Configure les dimensions de la grille
+     * @param cols - Nombre de colonnes
+     * @param rows - Nombre de lignes
+     * @param cellWidth - Largeur d'une cellule en pixels
+     * @param cellHeight - Hauteur d'une cellule en pixels
+     * @param offsetX - Décalage horizontal (optionnel)
+     * @param offsetY - Décalage vertical (optionnel)
+     */
+    setDimensions(cols: number, rows: number, cellWidth: number, cellHeight: number, offsetX?: number, offsetY?: number): void;
+    /**
+     * Configure la taille physique du canvas
+     * Le canvas doit avoir la MÊME approche que le canvas principal WebGL :
+     * - Résolution physique = dimensions de base (SANS DPR)
+     * - Taille CSS = dimensions de base
+     * - Le scaling visuel est fait via transform: scale()
+     *
+     * @param baseWidth - Largeur de base en pixels
+     * @param baseHeight - Hauteur de base en pixels
+     */
+    setCanvasSize(baseWidth: number, baseHeight: number): void;
+    /**
+     * Configure les options visuelles
+     * @param options - Options de rendu
+     */
+    setStyle(options: {
+        strokeColor?: string;
+        lineWidth?: number;
+    }): void;
+    /**
+     * Configure la transformation et le positionnement du canvas de grille
+     * pour qu'il corresponde exactement au canvas principal (pixel-perfect scaling)
+     *
+     * APPROCHE SIMPLE : On ne fait PAS de transform: scale().
+     * On définit le canvas à la taille finale (scalée) directement,
+     * et on le positionne exactement où est le canvas principal.
+     *
+     * Le dessin de la grille doit alors être fait à l'échelle scalée.
+     *
+     * @param scale - Facteur de scale (même valeur que le canvas principal)
+     * @param baseWidth - Largeur de base du canvas (avant scale)
+     * @param baseHeight - Hauteur de base du canvas (avant scale)
+     * @param mainCanvasRect - Le getBoundingClientRect() du canvas principal
+     * @param containerRect - Le getBoundingClientRect() du container
+     */
+    setTransform(_scale: number, _baseWidth: number, _baseHeight: number, mainCanvasRect: DOMRect, containerRect: DOMRect): void;
+    /**
+     * Dessine la grille avec des lignes fines continues
+     * Les lignes sont dessinées aux bords exacts des cellules.
+     */
+    render(): void;
+    /**
+     * Met à jour et redessine la grille avec de nouvelles dimensions
+     * Méthode pratique qui combine setDimensions, setCanvasSize et render
+     *
+     * @param cols - Nombre de colonnes
+     * @param rows - Nombre de lignes
+     * @param cellWidth - Largeur d'une cellule
+     * @param cellHeight - Hauteur d'une cellule
+     * @param displayWidth - Largeur d'affichage du canvas
+     * @param displayHeight - Hauteur d'affichage du canvas
+     * @param offsetX - Décalage horizontal (optionnel)
+     * @param offsetY - Décalage vertical (optionnel)
+     */
+    update(cols: number, rows: number, cellWidth: number, cellHeight: number, displayWidth: number, displayHeight: number, offsetX?: number, offsetY?: number): void;
+    /**
+     * Affiche ou cache la grille
+     * @param visible - true pour afficher, false pour cacher
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Supprime le canvas de grille du DOM
+     */
+    destroy(): void;
+    /**
+     * Retourne le canvas HTML
+     */
+    getCanvas(): HTMLCanvasElement;
+}
+
+/**
+ * Default color palette (VGA colors + extended)
+ * Maps palette index to CSS color string
+ */
+declare const DEFAULT_PALETTE: readonly string[];
+/**
+ * Convert a color palette index to CSS color string
+ */
+declare function paletteIndexToColor(index: number, palette?: readonly string[]): string;
+/**
+ * Convert CSS color string to palette index (finds closest match)
+ */
+declare function colorToPaletteIndex(color: string, palette?: readonly string[]): number;
+
+export { BitmapFontAtlas, DEFAULT_PALETTE, GridOverlay, ImageFontAtlas, Terminal2D, colorToPaletteIndex, getAtlasColumns, getCharGridPosition, getMaxCharCode, paletteIndexToColor };
+export type { AtlasBlocks, BitmapFont$1 as BitmapFont, FontType, ImageFontAtlasConfig, RenderOptions, TerminalCell, TerminalData };