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

package/dist/gl/index.d.ts

@@ -0,0 +1,802 @@
+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;
+};
+
+/**
+ * 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 = Map<number, Uint8Array>;
+
+/**
+ * WebGL compatibility report
+ */
+interface WebGLCompatibilityReport {
+    /** WebGL 1.0 support */
+    webgl1: boolean;
+    /** OES_element_index_uint extension (Uint32 indices) */
+    uint32Indices: boolean;
+    /** Maximum texture size */
+    maxTextureSize: number;
+    /** Maximum viewport dimensions */
+    maxViewportDims: [number, number];
+    /** Maximum terminal size with Uint16 indices (cols × rows) */
+    maxCellsUint16: number;
+    /** Maximum terminal size with Uint32 indices (cols × rows) */
+    maxCellsUint32: number;
+    /** Recommended maximum terminal size for this device */
+    recommendedMaxCells: number;
+    /** Warnings (empty if fully compatible) */
+    warnings: string[];
+    /** Errors (empty if compatible) */
+    errors: string[];
+}
+/**
+ * Options for WebGL terminal configuration
+ */
+interface TerminalGLOptions {
+    /** Number of columns (required) */
+    cols: number;
+    /** Number of rows (required) */
+    rows: number;
+    /** Character width in pixels */
+    charWidth?: number;
+    /** Character height in pixels */
+    charHeight?: number;
+    /** Canvas background color (CSS format, for gl.clearColor) */
+    canvasBgColor?: string | null;
+    /** Show cell delimitation grid (debug) */
+    showGrid?: boolean;
+    /** Force Uint16 indices (for compatibility testing, auto-detected by default) */
+    forceUint16?: boolean;
+    /**
+     * Scaling mode for pixel-perfect rendering (default: ScalingMode.None)
+     *
+     * Controls how the canvas is scaled to fit the container:
+     * - ScalingMode.None: Fills available space, may have sub-pixel artifacts (default)
+     * - 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
+     */
+    scalingMode?: ScalingMode;
+    /**
+     * Ambient effect configuration
+     *
+     * Creates a blurred glow effect around the terminal when using pixel-perfect
+     * scaling modes that leave empty space around the canvas.
+     *
+     * - false or undefined: Disabled (default)
+     * - true: Enabled with default settings (blur: 30px, scale: 1.15, opacity: 0.7)
+     * - object: Custom configuration
+     */
+    ambientEffect?: boolean | {
+        /** Blur radius in pixels (default: 30) */
+        blur?: number;
+        /** Scale factor for the background canvas (default: 1.15) */
+        scale?: number;
+        /** Opacity of the ambient effect (0-1, default: 0.7) */
+        opacity?: number;
+    };
+}
+/**
+ * Simplified terminal using WebGL for basic rendering
+ * Only supports bitmap fonts with atlas
+ * Implements IRenderer interface for dependency injection with core
+ *
+ * ✨ SIMPLIFIED VERSION: Only backgrounds + colored characters
+ */
+declare class TerminalGL implements IRenderer {
+    /**
+     * Check WebGL 1.0 compatibility and device capabilities
+     *
+     * Tests all required WebGL features and returns a detailed compatibility report.
+     * Use this before creating a TerminalGL instance to ensure device support.
+     *
+     * @returns Detailed compatibility report with warnings and errors
+     *
+     * @example
+     * ```typescript
+     * const report = TerminalGL.checkCompatibility();
+     * if (report.errors.length > 0) {
+     *   console.error('WebGL not supported:', report.errors);
+     *   // Fallback to Canvas 2D renderer
+     * } else if (report.warnings.length > 0) {
+     *   console.warn('WebGL limitations:', report.warnings);
+     * }
+     * console.log(`Max terminal size: ${report.recommendedMaxCells} cells`);
+     * ```
+     */
+    static checkCompatibility(): WebGLCompatibilityReport;
+    private canvas;
+    private gl;
+    private parentElement;
+    private containerDiv;
+    private cols;
+    private rows;
+    private charWidth;
+    private charHeight;
+    private cellWidth;
+    private cellHeight;
+    private glyphOffsetX;
+    private glyphOffsetY;
+    private canvasBgColor;
+    private showGrid;
+    private supportsUint32Indices;
+    private useUint16Indices;
+    private gridOverlay?;
+    private bitmapFont?;
+    private atlasTexture;
+    private atlasCanvas?;
+    private atlasColumns;
+    private fontLoaded;
+    private paletteTexture;
+    private program;
+    private positionBuffer;
+    private texCoordBuffer;
+    private colorIndexBuffer;
+    private indexBuffer;
+    private aPosition?;
+    private aTexCoord?;
+    private aColorIndex?;
+    private uResolution;
+    private uTexture;
+    private uPalette;
+    private resizeObserver?;
+    private charCodeToAtlasIndex;
+    private atlasUVs;
+    private cachedAtlasWidth;
+    private cachedAtlasHeight;
+    private paletteFloat;
+    private maxCells;
+    private renderPositions;
+    private renderTexCoords;
+    private renderColorIndices;
+    private renderIndices;
+    private cachedResolution;
+    private cachedTextureUnit;
+    private cachedPaletteUnit;
+    private cachedTextureUniform;
+    private cachedPaletteUniform;
+    private paletteHash;
+    private currentScale;
+    private scalingMode;
+    private ambientEffectEnabled;
+    private ambientEffectCanvas;
+    private ambientEffectCtx;
+    private ambientEffectBlur;
+    private ambientEffectScale;
+    private ambientEffectOpacity;
+    private onResizeCallback?;
+    private staticPositionsInitialized;
+    private vaoExtension;
+    private vao;
+    private instancedExtension;
+    private useInstancing;
+    private instanceDataBuffer;
+    private instanceData;
+    private templateQuadPositions;
+    private templateQuadIndices;
+    constructor(parentDiv: HTMLDivElement, options: TerminalGLOptions);
+    /**
+     * 🚀 INSTANCING: Initialize template quad and instance buffers
+     * Called once at init if instancing is supported
+     */
+    private initInstancedBuffers;
+    /**
+     * 🚀 OPTIMIZATION: Initialize pre-allocated buffers for rendering
+     * Avoids allocations each frame
+     * Uses Uint16 or Uint32 indices based on device support
+     */
+    private initRenderBuffers;
+    /**
+     * 🚀 MEGA OPTIMIZATION: Pre-compute static positions for ALL possible quads
+     * Called only once after font load, or after resize
+     * Positions never change during rendering - only colors and UVs change!
+     */
+    private precomputeStaticPositions;
+    /**
+     * Initialize WebGL (shaders, buffers, etc.)
+     */
+    private initWebGL;
+    /**
+     * Compile a shader
+     */
+    private compileShader;
+    /**
+     * 🔲 Initialize 2D canvas overlay for debug grid
+     * Performance: 2D canvas drawn only once, 0ms per frame
+     */
+    private initGridOverlay;
+    /**
+     * 🔲 Draw grid lines on 2D canvas overlay
+     * Called only once at init and resize
+     *
+     * The grid must match the terminal's pixel-perfect scaling:
+     * - Same base size as the main canvas
+     * - Same transform: scale() factor
+     * - Centered in the container like the main canvas (via flexbox or calculated position)
+     */
+    private updateGridOverlay;
+    /**
+     * Configure bitmap font and generate atlas
+     *
+     * ⚠️ **INTERNAL USE ONLY** - This method is called automatically by ClientRuntime's
+     * event system when Core.loadBitmapFontById() is called. Do NOT call this directly
+     * unless you're implementing a custom runtime.
+     *
+     * Event flow: Core.loadBitmapFontById() → Core.onBitmapFontChangedCallback
+     * → ClientRuntime.onCoreBitmapFontChanged() → RendererManager.setBitmapFont()
+     *
+     * @param font - Bitmap font mapping (charCode → byte array)
+     * @param charWidth - Width of each character in pixels
+     * @param charHeight - Height of each character in pixels
+     * @param cellWidth - Width of each cell in pixels
+     * @param cellHeight - Height of each cell in pixels
+     * @throws {Error} If atlas generation fails
+     *
+     * @example
+     * ```typescript
+     * // ❌ DON'T: Call setBitmapFont directly
+     * renderer.setBitmapFont(font, 8, 16, 8, 16);
+     *
+     * // ✅ DO: Use Core's loadBitmapFontById (triggers event automatically)
+     * core.loadBitmapFontById(1, {
+     *   charWidth: 8, charHeight: 16,
+     *   cellWidth: 8, cellHeight: 16,
+     *   glyphs: new Map([[65, new Uint8Array([...])]])
+     * });
+     * ```
+     */
+    setBitmapFont(font: BitmapFont, charWidth: number, charHeight: number, cellWidth: number, cellHeight: number): void;
+    /**
+     * Set image font (PNG atlas) for extended character rendering
+     * Supports 1, 4, or 16 blocks (256, 1024, or 4096 characters)
+     *
+     * @param imageData - PNG image data as Uint8Array
+     * @param glyphWidth - Glyph width in pixels
+     * @param glyphHeight - Glyph height in pixels
+     * @param cellWidth - Cell width in pixels
+     * @param cellHeight - Cell height in pixels
+     * @param atlasBlocks - Number of 256-char blocks (1, 4, or 16)
+     */
+    setImageFont(imageData: Uint8Array, glyphWidth: number, glyphHeight: number, cellWidth: number, cellHeight: number, atlasBlocks: AtlasBlocks): Promise<void>;
+    /**
+     * Load PNG image and create WebGL texture
+     */
+    private loadImageFontAtlas;
+    /**
+     * Pre-compute UVs for ImageFont (block-based grid layout)
+     *
+     * Atlas layout for multi-block fonts:
+     * - Each block contains 256 chars in a 16×16 grid
+     * - Blocks are arranged visually:
+     *   - 1 block:  1×1 (16×16 chars)
+     *   - 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.
+     */
+    private precomputeImageFontUVs;
+    /**
+     * Generate texture atlas from bitmap font
+     */
+    private generateAtlas;
+    /**
+     * 🚀 OPTIMIZED: Build charCode → atlas index using direct array lookup
+     */
+    private buildCharCodeMap;
+    /**
+     * 🚀 MEGA OPTIMIZATION: Pre-compute ALL atlas UVs
+     * Called once after atlas generation - UVs never change!
+     * Eliminates per-frame division and modulo operations
+     */
+    private precomputeAtlasUVs;
+    /**
+     * Create WebGL texture from atlas
+     */
+    private createAtlasTexture;
+    /**
+     * Clear entire terminal
+     *
+     * Clears the WebGL canvas. Note: Actual terminal content clearing is handled
+     * by Core's RenderState, not by this renderer.
+     *
+     * @example
+     * ```typescript
+     * renderer.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Parse CSS color to normalized RGBA (0-1)
+     */
+    private parseColor;
+    /**
+     * Configure ResizeObserver to adapt canvas
+     */
+    private setupResizeObserver;
+    /**
+     * Update canvas display size
+     *
+     * Supports multiple scaling modes:
+     *
+     * 🎯 INTEGER MODE (ScalingMode.Integer):
+     * Uses integer scaling (1x, 2x, 3x...) for crisp pixels without artifacts.
+     * The canvas is centered in the container via flexbox.
+     * May leave empty space around the canvas.
+     *
+     * 📐 HALF MODE (ScalingMode.Half):
+     * Snaps to half increments (1.0, 1.5, 2.0...).
+     * Good balance between space usage and visual quality.
+     *
+     * 📏 QUARTER MODE (ScalingMode.Quarter):
+     * Snaps to quarter increments (1.0, 1.25, 1.5, 1.75, 2.0...).
+     * Finer control over scaling with minimal artifacts.
+     *
+     * 🔲 NONE MODE (ScalingMode.None):
+     * Scales to fill as much space as possible while maintaining aspect ratio.
+     * May cause some lines to appear thicker due to sub-pixel rendering.
+     * Useful when maximizing screen usage is more important than pixel purity.
+     */
+    private updateCanvasSize;
+    /**
+     * 🌈 AMBIENT EFFECT: Copy main canvas to ambient effect background
+     *
+     * This creates a glow effect around the terminal by copying the main
+     * WebGL canvas to a 2D canvas behind it, which has CSS blur applied.
+     */
+    private updateAmbientEffect;
+    /**
+     * Set color palette and upload to GPU
+     *
+     * ⚠️ IMPORTANT: This is the ONLY way to update the palette.
+     * Typically called automatically by ClientRuntime via Core.onPaletteChanged() event.
+     * Do NOT call this directly unless you know what you're doing.
+     *
+     * @param palette - Array of 256 RGB colors
+     *
+     * @example
+     * ```typescript
+     * // ✅ Normal usage: Core handles this automatically
+     * core.loadPalette([...]);
+     * // → Core emits event
+     * // → ClientRuntime receives event
+     * // → renderer.setPalette() called automatically
+     *
+     * // ⚠️ Manual usage (advanced):
+     * const myPalette: RGBColor[] = [
+     *   { r: 0, g: 0, b: 0, a: 255 },      // Color 0: Black
+     *   { r: 255, g: 0, b: 0, a: 255 },    // Color 1: Red
+     *   // ... 254 more colors
+     * ];
+     * renderer.setPalette(myPalette);
+     * ```
+     */
+    setPalette(palette: RGBColor[]): void;
+    /**
+     * 🚀 GPU OPTIMIZATION: Upload palette to GPU texture (256×1 RGBA)
+     */
+    private updatePaletteTexture;
+    /**
+     * Render display data from core engine (ULTRA-OPTIMIZED)
+     *
+     * Bypasses internal cells and renders directly from RenderState for maximum performance.
+     * Uses GPU palette texture lookup to minimize CPU→GPU bandwidth (4× reduction).
+     *
+     * @param data - Render state containing cells, dimensions, and palette
+     *
+     * @example
+     * ```typescript
+     * const renderState: RenderState = {
+     *   cells: [...],
+     *   width: 80,
+     *   height: 25,
+     *   palette: [...]
+     * };
+     * renderer.renderDisplayData(renderState);
+     * ```
+     */
+    renderDisplayData(data: RenderState): void;
+    /**
+     * 🚀 NEW METHOD: Render directly from RenderState
+     * Bypass this.cells for maximum performance
+     */
+    private renderDirect;
+    /**
+     * 🚀 INSTANCED RENDERING: 1 draw call for entire terminal
+     * MASSIVE performance boost - reduces draw calls from cols×rows×2 to just 1!
+     */
+    private renderInstanced;
+    /**
+     * 🚀 ULTRA-OPTIMIZED: Update ONLY dynamic data (colors + UVs)
+     * Positions are static and pre-computed - only updated on resize!
+     * This is a MASSIVE performance win - positions never change during normal rendering
+     */
+    private renderDirectBuffers;
+    /**
+     * Resize the terminal dimensions
+     *
+     * Changes the number of columns and rows. Preserves existing cell content
+     * where possible. Reallocates render buffers if needed.
+     *
+     * @param cols - New number of columns (must be positive integer)
+     * @param rows - New number of rows (must be positive integer)
+     *
+     * @example
+     * ```typescript
+     * renderer.resize(120, 40); // Resize to 120×40
+     * ```
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Get canvas element
+     */
+    getCanvas(): HTMLCanvasElement;
+    /**
+     * Get grid dimensions
+     */
+    getGridSize(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Get cell width
+     */
+    getCellWidth(): number;
+    /**
+     * Get cell height
+     */
+    getCellHeight(): number;
+    /**
+     * Get current integer scale factor
+     * Used by PostProcessOverlay to sync dimensions
+     */
+    getCurrentScale(): number;
+    /**
+     * Get base canvas dimensions (before scaling)
+     * Used by PostProcessOverlay to sync dimensions
+     */
+    getBaseDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Set callback to be called after every resize
+     * Used by ClientRuntime to sync PostProcessOverlay
+     */
+    setOnResizeCallback(callback: () => void): void;
+    /**
+     * Clear the resize callback
+     */
+    clearOnResizeCallback(): void;
+    /**
+     * Set scaling mode
+     *
+     * @param mode - ScalingMode enum value:
+     *   - ScalingMode.None: Fill space, may have sub-pixel artifacts
+     *   - ScalingMode.Eighth: Snap to 0.125 increments (1.0, 1.125, 1.25...)
+     *   - ScalingMode.Quarter: Snap to 0.25 increments (1.0, 1.25, 1.5...)
+     *   - ScalingMode.Half: Snap to 0.5 increments (1.0, 1.5, 2.0...)
+     *   - ScalingMode.Integer: Crisp pixels, may waste space (1x, 2x, 3x...)
+     */
+    setScalingMode(mode: ScalingMode): void;
+    /**
+     * Get current scaling mode
+     */
+    getScalingMode(): ScalingMode;
+    /**
+     * Enable or configure debug grid overlay
+     *
+     * The grid shows cell boundaries aligned with the terminal grid.
+     * Useful for debugging layout and alignment issues.
+     *
+     * @param config - Configuration options:
+     *   - enabled: Whether to show the grid
+     *   - color: CSS color string (e.g., 'rgba(255,0,0,0.5)', '#ff0000')
+     *   - lineWidth: Line width in pixels (1-10)
+     *
+     * @example
+     * ```typescript
+     * // Enable with default red color
+     * renderer.setGrid({ enabled: true });
+     *
+     * // Custom green grid
+     * renderer.setGrid({ enabled: true, color: 'rgba(0, 255, 0, 0.5)' });
+     *
+     * // Disable grid
+     * renderer.setGrid({ enabled: false });
+     * ```
+     */
+    setGrid(config: {
+        enabled: boolean;
+        color?: string;
+        lineWidth?: number;
+    }): void;
+    /**
+     * Check if grid is currently enabled
+     */
+    isGridEnabled(): boolean;
+    /**
+     * Enable or configure ambient effect
+     *
+     * Ambient effect creates a blurred glow around the terminal canvas,
+     * filling the unused space with colors from the terminal content.
+     *
+     * @param config - true to enable with defaults, false to disable,
+     *                 or object with blur and scale settings
+     *
+     * @example
+     * ```typescript
+     * // Enable with defaults (blur: 30px, scale: 1.3)
+     * renderer.setAmbientEffect(true);
+     *
+     * // Disable
+     * renderer.setAmbientEffect(false);
+     *
+     * // Custom settings
+     * renderer.setAmbientEffect({ blur: 50, scale: 1.5 });
+     * ```
+     */
+    setAmbientEffect(config: boolean | {
+        blur?: number;
+        scale?: number;
+    }): void;
+    /**
+     * Create the ambient effect canvas element (called lazily if needed)
+     */
+    private createAmbientEffectCanvas;
+    /**
+     * Check if ambient effect is enabled
+     */
+    isAmbientEffectEnabled(): boolean;
+    /**
+     * Get current ambient effect configuration
+     */
+    getAmbientEffectConfig(): {
+        enabled: boolean;
+        blur: number;
+        scale: number;
+    };
+    /**
+     * Get number of columns (IRenderer interface)
+     *
+     * @returns Current number of columns
+     *
+     * @example
+     * ```typescript
+     * const cols = renderer.getCols(); // 80
+     * ```
+     */
+    getCols(): number;
+    /**
+     * Get number of rows (IRenderer interface)
+     *
+     * @returns Current number of rows
+     *
+     * @example
+     * ```typescript
+     * const rows = renderer.getRows(); // 25
+     * ```
+     */
+    getRows(): number;
+    /**
+     * Check if renderer is ready (IRenderer interface)
+     *
+     * Returns true when bitmap font, atlas texture, and shader program are initialized.
+     *
+     * @returns true if ready to render, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (renderer.isReady()) {
+     *   renderer.renderDisplayData(data);
+     * }
+     * ```
+     */
+    isReady(): boolean;
+    /**
+     * Destroy/cleanup resources (IRenderer interface)
+     *
+     * Destroys WebGL resources (textures, buffers), disconnects ResizeObserver,
+     * and removes canvases from DOM. Call this before removing the renderer.
+     *
+     * @example
+     * ```typescript
+     * renderer.destroy();
+     * renderer = null;
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Cleanup resources
+     */
+    dispose(): 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 { DEFAULT_PALETTE, GridOverlay, TerminalGL, colorToPaletteIndex, getAtlasColumns, getCharGridPosition, getMaxCharCode, paletteIndexToColor };
+export type { AtlasBlocks, BitmapFont, TerminalGLOptions, WebGLCompatibilityReport };