ink-sdl 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -18,7 +18,7 @@ interface SdlKeyEvent {
 /**
  * SDL2 FFI Bindings
  *
- * Provides minimal SDL2 and SDL2_ttf bindings for window-based rendering
+ * Provides minimal SDL2 bindings for window-based rendering
  * using koffi for foreign function interface.
  */
 
@@ -27,7 +27,7 @@ interface SdlKeyEvent {
  *
  * Provides type-safe access to SDL2 functions for window rendering.
  */
-declare class SDL2API {
+declare class Sdl2 {
     private lib;
     private initialized;
     private _SDL_Init;
@@ -38,6 +38,8 @@ declare class SDL2API {
     private _SDL_SetWindowTitle;
     private _SDL_GetWindowSize;
     private _SDL_RaiseWindow;
+    private _SDL_SetWindowMinimumSize;
+    private _SDL_SetWindowMaximumSize;
     private _SDL_CreateRenderer;
     private _SDL_DestroyRenderer;
     private _SDL_RenderClear;
@@ -93,6 +95,14 @@ declare class SDL2API {
      * Raise window to front and give it keyboard focus
      */
     raiseWindow(window: SDLPointer): void;
+    /**
+     * Set the minimum size of a window
+     */
+    setWindowMinimumSize(window: SDLPointer, minW: number, minH: number): void;
+    /**
+     * Set the maximum size of a window
+     */
+    setWindowMaximumSize(window: SDLPointer, maxW: number, maxH: number): void;
     /**
      * Create a renderer for a window
      */
@@ -193,253 +203,15 @@ declare class SDL2API {
 /**
  * Get the SDL2 API singleton
  */
-declare const getSDL2: () => SDL2API;
+declare const getSdl2: () => Sdl2;
 /**
  * Check if SDL2 is available without throwing
  */
-declare const isSDL2Available: () => boolean;
+declare const isSdl2Available: () => boolean;
 /**
  * Create an SDL_Rect buffer for use with SDL functions
  */
 declare const createSDLRect: (x: number, y: number, w: number, h: number) => Buffer;
-/**
- * SDL_ttf API wrapper class for TrueType font rendering
- */
-declare class SDL_ttfAPI {
-    private lib;
-    private initialized;
-    private _TTF_Init;
-    private _TTF_Quit;
-    private _TTF_OpenFont;
-    private _TTF_CloseFont;
-    private _TTF_RenderUTF8_Blended;
-    private _TTF_SizeUTF8;
-    constructor();
-    private bindFunctions;
-    /**
-     * Initialize SDL_ttf
-     */
-    init(): boolean;
-    /**
-     * Shutdown SDL_ttf
-     */
-    quit(): void;
-    /**
-     * Get the last SDL_ttf error message
-     */
-    getError(): string;
-    /**
-     * Open a TrueType font file
-     */
-    openFont(file: string, ptsize: number): SDLPointer;
-    /**
-     * Close a font
-     */
-    closeFont(font: SDLPointer): void;
-    /**
-     * Render UTF-8 text to a surface with blended (anti-aliased) rendering
-     */
-    renderTextBlended(font: SDLPointer, text: string, r: number, g: number, b: number, a?: number): SDLPointer;
-    /**
-     * Get the dimensions of rendered text without actually rendering
-     */
-    sizeText(font: SDLPointer, text: string): {
-        width: number;
-        height: number;
-    };
-    /**
-     * Check if SDL_ttf is initialized
-     */
-    isInitialized(): boolean;
-}
-/**
- * Get the SDL_ttf API singleton
- */
-declare const getSDL_ttf: () => SDL_ttfAPI;
-/**
- * Check if SDL_ttf is available without throwing
- */
-declare const isSDL_ttfAvailable: () => boolean;
-
-/**
- * ANSI Parser for SDL UI Rendering
- *
- * Parses terminal ANSI escape sequences and converts them to draw commands
- * for rendering in an SDL window.
- */
-/** RGB color value */
-interface Color {
-    r: number;
-    g: number;
-    b: number;
-}
-/** Types of draw commands */
-type DrawCommandType = "text" | "clear_screen" | "clear_line" | "cursor_move" | "set_fg" | "set_bg" | "reset_style" | "set_bold" | "set_dim" | "set_reverse";
-/** A single draw command from parsed ANSI output */
-interface DrawCommand {
-    type: DrawCommandType;
-    text?: string;
-    row?: number;
-    col?: number;
-    color?: Color;
-    enabled?: boolean;
-}
-/**
- * ANSI sequence parser
- *
- * Parses ANSI escape sequences from terminal output and produces
- * draw commands for SDL rendering.
- */
-declare class AnsiParser {
-    private cursorRow;
-    private cursorCol;
-    private fgColor;
-    private bgColor;
-    private bold;
-    /**
-     * Parse an ANSI string and return draw commands
-     */
-    parse(input: string): DrawCommand[];
-    /**
-     * Process an escape sequence and emit draw commands
-     */
-    private processEscapeSequence;
-    /**
-     * Process cursor position sequence
-     */
-    private processCursorPosition;
-    /**
-     * Process erase display sequence
-     */
-    private processEraseDisplay;
-    /**
-     * Process erase line sequence
-     */
-    private processEraseLine;
-    /**
-     * Process SGR (Select Graphic Rendition) sequence
-     */
-    private processSGR;
-    /**
-     * Parse extended color (256-color or 24-bit)
-     */
-    private parseExtendedColor;
-    /**
-     * Reset all styles to default
-     */
-    private resetStyle;
-    /**
-     * Get current cursor position
-     */
-    getCursor(): {
-        row: number;
-        col: number;
-    };
-    /**
-     * Get current foreground color
-     */
-    getFgColor(): Color;
-    /**
-     * Get current background color
-     */
-    getBgColor(): Color;
-    /**
-     * Reset parser state
-     */
-    reset(): void;
-}
-
-/**
- * SDL Text Renderer
- *
- * Handles TrueType font loading and text rendering with glyph caching
- * for efficient SDL UI rendering.
- */
-
-/**
- * SDL Text Renderer
- *
- * Loads TTF fonts and renders text with glyph caching for performance.
- * Supports HiDPI displays by scaling font size based on scale factor.
- */
-declare class TextRenderer {
-    private sdl;
-    private ttf;
-    private font;
-    private renderer;
-    private baseFontSize;
-    private scaleFactor;
-    private glyphCache;
-    private accessCounter;
-    private charWidth;
-    private charHeight;
-    constructor(renderer: SDLPointer, options?: {
-        fontSize?: number;
-        scaleFactor?: number;
-        fontPath?: string;
-    });
-    /**
-     * Get the path to the bundled Cozette font
-     */
-    private getDefaultFontPath;
-    /**
-     * Load a TTF font at the current scaled size
-     */
-    private loadFont;
-    /**
-     * Update scale factor (for HiDPI display changes)
-     */
-    updateScaleFactor(scaleFactor: number): void;
-    /**
-     * Get character dimensions
-     */
-    getCharDimensions(): {
-        width: number;
-        height: number;
-    };
-    /**
-     * Generate cache key for a glyph
-     */
-    private getCacheKey;
-    /**
-     * Get or create a cached glyph texture
-     */
-    private getGlyph;
-    /**
-     * Evict least recently used glyphs
-     */
-    private evictOldGlyphs;
-    /**
-     * Render a single character at the specified position
-     */
-    renderChar(char: string, x: number, y: number, color: Color): void;
-    /**
-     * Render a string of text at the specified position
-     */
-    renderText(text: string, x: number, y: number, color: Color): void;
-    /**
-     * Get text dimensions
-     */
-    measureText(text: string): {
-        width: number;
-        height: number;
-    };
-    /**
-     * Clear the glyph cache
-     */
-    clearCache(): void;
-    /**
-     * Get cache statistics
-     */
-    getCacheStats(): {
-        size: number;
-        maxSize: number;
-    };
-    /**
-     * Clean up resources
-     */
-    destroy(): void;
-}
 
 /**
  * SDL UI Renderer
@@ -455,6 +227,31 @@ interface SdlUiRendererOptions {
     vsync?: boolean;
     fontSize?: number;
     scaleFactor?: number | null;
+    /** Use system font instead of bundled Cozette font */
+    systemFont?: boolean;
+    /** Path to a custom TTF font file */
+    fontPath?: string;
+    /** Font name to search for in system font directories */
+    fontName?: string;
+    /** Background color as RGB tuple [r, g, b] or hex string "#RRGGBB" */
+    backgroundColor?: [number, number, number] | string | undefined;
+    /** Fullscreen mode: true for exclusive fullscreen, "desktop" for borderless fullscreen */
+    fullscreen?: boolean | "desktop" | undefined;
+    /** Remove window decorations (title bar, borders) */
+    borderless?: boolean | undefined;
+    /** Minimum window width in pixels */
+    minWidth?: number | undefined;
+    /** Minimum window height in pixels */
+    minHeight?: number | undefined;
+}
+/** Result from processing SDL events */
+interface ProcessEventsResult {
+    /** Key events that occurred */
+    keyEvents: SdlKeyEvent[];
+    /** Whether a resize event occurred */
+    resized: boolean;
+    /** Whether focus was lost (modifier keys should be reset) */
+    focusLost: boolean;
 }
 /**
  * SDL UI Renderer
@@ -467,6 +264,7 @@ declare class SdlUiRenderer {
     private window;
     private renderer;
     private textRenderer;
+    private renderTarget;
     private ansiParser;
     private inputBridge;
     private windowWidth;
@@ -477,8 +275,12 @@ declare class SdlUiRenderer {
     private charHeight;
     private fgColor;
     private bgColor;
+    private defaultBgColor;
     private bold;
     private dim;
+    private italic;
+    private underline;
+    private strikethrough;
     private reverse;
     private shouldQuit;
     private pendingCommands;
@@ -500,6 +302,10 @@ declare class SdlUiRenderer {
         columns: number;
         rows: number;
     };
+    /**
+     * Create or recreate the render target texture
+     */
+    private createRenderTarget;
     /**
      * Process ANSI output from Ink
      */
@@ -508,6 +314,14 @@ declare class SdlUiRenderer {
      * Render pending commands and present
      */
     present(): void;
+    /**
+     * Refresh the display by copying the render target to the screen
+     *
+     * Call this periodically to keep the display updated even when no new
+     * content is being rendered. Required for SDL's double-buffering to work
+     * correctly - without continuous presents, the window can go black.
+     */
+    refreshDisplay(): void;
     /**
      * Execute a single draw command
      */
@@ -527,7 +341,7 @@ declare class SdlUiRenderer {
     /**
      * Process SDL events
      */
-    processEvents(): SdlKeyEvent[];
+    processEvents(): ProcessEventsResult;
     /**
      * Convert SDL key event to terminal sequence
      */
@@ -571,6 +385,21 @@ declare class SdlUiRenderer {
      * Reset state for reuse
      */
     reset(): void;
+    /**
+     * Reset input state (modifier keys)
+     *
+     * Call this when focus is lost to prevent "stuck" modifier keys.
+     */
+    resetInputState(): void;
+    /**
+     * Get glyph cache statistics
+     *
+     * Useful for profiling and tuning cache size.
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
 }
 
 /**
@@ -683,7 +512,7 @@ declare class SdlInputStream extends Readable {
 }
 
 /**
- * SDL Streams for Ink
+ * SDL Window and Streams for Ink
  *
  * Factory function to create stdin/stdout streams that render to SDL.
  */
@@ -704,6 +533,22 @@ interface SdlStreamsOptions {
     fontSize?: number;
     /** Override scale factor (null = auto-detect) */
     scaleFactor?: number | null;
+    /** Use system font instead of bundled Cozette font */
+    systemFont?: boolean;
+    /** Path to a custom TTF font file */
+    fontPath?: string;
+    /** Font name to search for in system font directories */
+    fontName?: string;
+    /** Background color as RGB tuple [r, g, b] or hex string "#RRGGBB" */
+    backgroundColor?: [number, number, number] | string | undefined;
+    /** Fullscreen mode: true for exclusive fullscreen, "desktop" for borderless fullscreen */
+    fullscreen?: boolean | "desktop" | undefined;
+    /** Remove window decorations (title bar, borders) */
+    borderless?: boolean | undefined;
+    /** Minimum window width in pixels */
+    minWidth?: number | undefined;
+    /** Minimum window height in pixels */
+    minHeight?: number | undefined;
 }
 /**
  * SDL Window wrapper that emits events
@@ -746,6 +591,23 @@ declare class SdlWindow extends EventEmitter {
      * Get the output stream
      */
     getOutputStream(): SdlOutputStream;
+    /**
+     * Get glyph cache statistics
+     *
+     * Useful for profiling and tuning cache performance.
+     *
+     * @example
+     * ```typescript
+     * const stats = window.getCacheStats();
+     * if (stats) {
+     *   console.log(`Cache: ${stats.size}/${stats.maxSize} glyphs`);
+     * }
+     * ```
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
 }
 /**
  * Result of createSdlStreams
@@ -757,6 +619,8 @@ interface SdlStreams {
     stdout: SdlOutputStream;
     /** SDL window wrapper with events */
     window: SdlWindow;
+    /** UI renderer (for advanced use) */
+    renderer: SdlUiRenderer;
 }
 /**
  * Create SDL streams for use with Ink
@@ -785,6 +649,309 @@ interface SdlStreams {
  */
 declare const createSdlStreams: (options?: SdlStreamsOptions) => SdlStreams;
 
+/**
+ * SDL2_ttf FFI Bindings
+ *
+ * Provides SDL2_ttf bindings for TrueType font rendering
+ * using koffi for foreign function interface.
+ */
+
+/**
+ * SDL_ttf API wrapper class for TrueType font rendering
+ */
+declare class SdlTtf {
+    private lib;
+    private initialized;
+    private _TTF_Init;
+    private _TTF_Quit;
+    private _TTF_OpenFont;
+    private _TTF_CloseFont;
+    private _TTF_RenderUTF8_Blended;
+    private _TTF_SizeUTF8;
+    private _TTF_SetFontStyle;
+    private _TTF_GetFontStyle;
+    private _TTF_GlyphIsProvided32;
+    constructor();
+    private bindFunctions;
+    /**
+     * Initialize SDL_ttf
+     */
+    init(): boolean;
+    /**
+     * Shutdown SDL_ttf
+     */
+    quit(): void;
+    /**
+     * Get the last SDL_ttf error message
+     */
+    getError(): string;
+    /**
+     * Open a TrueType font file
+     */
+    openFont(file: string, ptsize: number): SDLPointer;
+    /**
+     * Close a font
+     */
+    closeFont(font: SDLPointer): void;
+    /**
+     * Render UTF-8 text to a surface with blended (anti-aliased) rendering
+     */
+    renderTextBlended(font: SDLPointer, text: string, r: number, g: number, b: number, a?: number): SDLPointer;
+    /**
+     * Get the dimensions of rendered text without actually rendering
+     */
+    sizeText(font: SDLPointer, text: string): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Check if SDL_ttf is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Set font style (bold, italic, underline, strikethrough)
+     */
+    setFontStyle(font: SDLPointer, style: number): void;
+    /**
+     * Get current font style
+     */
+    getFontStyle(font: SDLPointer): number;
+    /**
+     * Check if a font provides a glyph for the given Unicode codepoint
+     */
+    glyphIsProvided(font: SDLPointer, codepoint: number): boolean;
+}
+/**
+ * Get the SDL_ttf API singleton
+ */
+declare const getSdlTtf: () => SdlTtf;
+/**
+ * Check if SDL_ttf is available without throwing
+ */
+declare const isSdlTtfAvailable: () => boolean;
+
+/**
+ * ANSI Parser for SDL UI Rendering
+ *
+ * Parses terminal ANSI escape sequences and converts them to draw commands
+ * for rendering in an SDL window.
+ */
+/** RGB color value */
+interface Color {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Types of draw commands */
+type DrawCommandType = "text" | "clear_screen" | "clear_line" | "cursor_move" | "set_fg" | "set_bg" | "reset_style" | "set_bold" | "set_dim" | "set_italic" | "set_underline" | "set_strikethrough" | "set_reverse";
+/** A single draw command from parsed ANSI output */
+interface DrawCommand {
+    type: DrawCommandType;
+    text?: string;
+    row?: number;
+    col?: number;
+    color?: Color;
+    enabled?: boolean;
+}
+/**
+ * ANSI sequence parser
+ *
+ * Parses ANSI escape sequences from terminal output and produces
+ * draw commands for SDL rendering.
+ */
+declare class AnsiParser {
+    private cursorRow;
+    private cursorCol;
+    private fgColor;
+    private bgColor;
+    private bold;
+    /**
+     * Parse an ANSI string and return draw commands
+     */
+    parse(input: string): DrawCommand[];
+    /**
+     * Process an escape sequence and emit draw commands
+     */
+    private processEscapeSequence;
+    /**
+     * Process cursor position sequence
+     */
+    private processCursorPosition;
+    /**
+     * Process erase display sequence
+     */
+    private processEraseDisplay;
+    /**
+     * Process erase line sequence
+     */
+    private processEraseLine;
+    /**
+     * Process SGR (Select Graphic Rendition) sequence
+     */
+    private processSGR;
+    /**
+     * Parse extended color (256-color or 24-bit)
+     */
+    private parseExtendedColor;
+    /**
+     * Reset all styles to default
+     */
+    private resetStyle;
+    /**
+     * Get current cursor position
+     */
+    getCursor(): {
+        row: number;
+        col: number;
+    };
+    /**
+     * Get current foreground color
+     */
+    getFgColor(): Color;
+    /**
+     * Get current background color
+     */
+    getBgColor(): Color;
+    /**
+     * Reset parser state
+     */
+    reset(): void;
+}
+
+/**
+ * SDL Text Renderer
+ *
+ * Handles TrueType font loading and text rendering with glyph caching
+ * for efficient SDL UI rendering.
+ */
+
+/**
+ * SDL Text Renderer
+ *
+ * Loads TTF fonts and renders text with glyph caching for performance.
+ * Supports HiDPI displays by scaling font size based on scale factor.
+ */
+declare class TextRenderer {
+    private sdl;
+    private ttf;
+    private font;
+    private fallbackFont;
+    private renderer;
+    private baseFontSize;
+    private scaleFactor;
+    private glyphCache;
+    private accessCounter;
+    private charWidth;
+    private charHeight;
+    private currentFontPath;
+    constructor(renderer: SDLPointer, options?: {
+        fontSize?: number;
+        scaleFactor?: number;
+        fontPath?: string;
+        fontName?: string;
+        systemFont?: boolean;
+    });
+    /**
+     * Get system font directories for the current platform
+     */
+    private getSystemFontDirectories;
+    /**
+     * Get system font paths for the default font filename
+     */
+    private getSystemFontPaths;
+    /**
+     * Find a font by name in system font directories
+     *
+     * Searches for common font file extensions (.ttf, .ttc, .otf)
+     */
+    private findFontByName;
+    /**
+     * Get the path to the Cozette font (system or bundled)
+     */
+    private getDefaultFontPath;
+    /**
+     * Get fallback fonts for the current platform
+     */
+    private getFallbackFontPaths;
+    /**
+     * Find an available font, trying default first then fallbacks
+     */
+    private findAvailableFont;
+    /**
+     * Find a system font, skipping the default bundled font
+     */
+    private findSystemFont;
+    /**
+     * Get emoji font paths for the current platform
+     */
+    private getEmojiFontPaths;
+    /**
+     * Find an available emoji font
+     */
+    private findEmojiFont;
+    /**
+     * Load the fallback emoji font if available
+     */
+    private loadFallbackFont;
+    /**
+     * Load a TTF font at the current scaled size
+     */
+    private loadFont;
+    /**
+     * Update scale factor (for HiDPI display changes)
+     */
+    updateScaleFactor(scaleFactor: number): void;
+    /**
+     * Get character dimensions
+     */
+    getCharDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Generate cache key for a glyph
+     */
+    private getCacheKey;
+    /**
+     * Get or create a cached glyph texture
+     */
+    private getGlyph;
+    /**
+     * Evict least recently used glyphs
+     */
+    private evictOldGlyphs;
+    /**
+     * Render a single character at the specified position
+     */
+    renderChar(char: string, x: number, y: number, color: Color, italic?: boolean): void;
+    /**
+     * Render a string of text at the specified position
+     */
+    renderText(text: string, x: number, y: number, color: Color, italic?: boolean): void;
+    /**
+     * Get text dimensions
+     */
+    measureText(text: string): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Clear the glyph cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
 /**
  * SDL Input Bridge
  *
@@ -888,4 +1055,4 @@ declare class InputBridge {
  */
 declare const isSdlAvailable: () => boolean;
 
-export { AnsiParser, type Color, type DrawCommand, type InkKeyEvent, InputBridge, SDL2API, type SDLPointer, SDL_ttfAPI, SdlInputStream, type SdlKeyEvent, SdlOutputStream, type SdlStreams, type SdlStreamsOptions, SdlUiRenderer, type SdlUiRendererOptions, SdlWindow, TextRenderer, createSDLRect, createSdlStreams, getSDL2, getSDL_ttf, isSDL2Available, isSDL_ttfAvailable, isSdlAvailable };
+export { AnsiParser, type Color, type DrawCommand, type InkKeyEvent, InputBridge, type SDLPointer, Sdl2, SdlInputStream, type SdlKeyEvent, SdlOutputStream, type SdlStreams, type SdlStreamsOptions, SdlTtf, SdlUiRenderer, type SdlUiRendererOptions, SdlWindow, TextRenderer, createSDLRect, createSdlStreams, getSdl2, getSdlTtf, isSdl2Available, isSdlAvailable, isSdlTtfAvailable };