ink-sdl 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,891 @@
+import { EventEmitter } from 'events';
+import { Writable, Readable } from 'stream';
+
+/**
+ * SDL Type Definitions
+ */
+/** Opaque pointer type for SDL handles (windows, renderers, textures, etc.) */
+type SDLPointer = unknown;
+/**
+ * Keyboard event from SDL
+ */
+interface SdlKeyEvent {
+    keycode: number;
+    pressed: boolean;
+    repeat: boolean;
+}
+
+/**
+ * SDL2 FFI Bindings
+ *
+ * Provides minimal SDL2 and SDL2_ttf bindings for window-based rendering
+ * using koffi for foreign function interface.
+ */
+
+/**
+ * SDL2 API wrapper class
+ *
+ * Provides type-safe access to SDL2 functions for window rendering.
+ */
+declare class SDL2API {
+    private lib;
+    private initialized;
+    private _SDL_Init;
+    private _SDL_Quit;
+    private _SDL_GetError;
+    private _SDL_CreateWindow;
+    private _SDL_DestroyWindow;
+    private _SDL_SetWindowTitle;
+    private _SDL_GetWindowSize;
+    private _SDL_RaiseWindow;
+    private _SDL_CreateRenderer;
+    private _SDL_DestroyRenderer;
+    private _SDL_RenderClear;
+    private _SDL_RenderPresent;
+    private _SDL_RenderCopy;
+    private _SDL_SetRenderDrawColor;
+    private _SDL_CreateTexture;
+    private _SDL_DestroyTexture;
+    private _SDL_UpdateTexture;
+    private _SDL_CreateTextureFromSurface;
+    private _SDL_SetTextureBlendMode;
+    private _SDL_SetTextureColorMod;
+    private _SDL_FreeSurface;
+    private _SDL_GetRendererOutputSize;
+    private _SDL_RenderFillRect;
+    private _SDL_SetRenderTarget;
+    private _SDL_GL_GetDrawableSize;
+    private _SDL_PollEvent;
+    constructor();
+    private bindFunctions;
+    /**
+     * Initialize SDL with the given subsystems
+     */
+    init(flags?: number): boolean;
+    /**
+     * Shutdown SDL
+     */
+    quit(): void;
+    /**
+     * Get the last SDL error message
+     */
+    getError(): string;
+    /**
+     * Create a window
+     */
+    createWindow(title: string, x: number, y: number, width: number, height: number, flags: number): SDLPointer;
+    /**
+     * Destroy a window
+     */
+    destroyWindow(window: SDLPointer): void;
+    /**
+     * Set window title
+     */
+    setWindowTitle(window: SDLPointer, title: string): void;
+    /**
+     * Get window size
+     */
+    getWindowSize(window: SDLPointer): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Raise window to front and give it keyboard focus
+     */
+    raiseWindow(window: SDLPointer): void;
+    /**
+     * Create a renderer for a window
+     */
+    createRenderer(window: SDLPointer, index?: number, flags?: number): SDLPointer;
+    /**
+     * Destroy a renderer
+     */
+    destroyRenderer(renderer: SDLPointer): void;
+    /**
+     * Clear the renderer
+     */
+    renderClear(renderer: SDLPointer): void;
+    /**
+     * Present the renderer (flip buffers)
+     */
+    renderPresent(renderer: SDLPointer): void;
+    /**
+     * Copy texture to renderer
+     */
+    renderCopy(renderer: SDLPointer, texture: SDLPointer, srcRect?: SDLPointer | null, dstRect?: SDLPointer | null): void;
+    /**
+     * Set render draw color
+     */
+    setRenderDrawColor(renderer: SDLPointer, r: number, g: number, b: number, a?: number): void;
+    /**
+     * Create a texture
+     */
+    createTexture(renderer: SDLPointer, format: number, access: number, width: number, height: number): SDLPointer;
+    /**
+     * Destroy a texture
+     */
+    destroyTexture(texture: SDLPointer): void;
+    /**
+     * Update texture with pixel data
+     */
+    updateTexture(texture: SDLPointer, pixels: Buffer, pitch: number): void;
+    /**
+     * Create a texture from an SDL surface
+     */
+    createTextureFromSurface(renderer: SDLPointer, surface: SDLPointer): SDLPointer;
+    /**
+     * Set texture blend mode
+     */
+    setTextureBlendMode(texture: SDLPointer, blendMode: number): void;
+    /**
+     * Set texture color modulation (tint)
+     */
+    setTextureColorMod(texture: SDLPointer, r: number, g: number, b: number): void;
+    /**
+     * Free an SDL surface
+     */
+    freeSurface(surface: SDLPointer): void;
+    /**
+     * Get the output size of a renderer (physical pixels)
+     */
+    getRendererOutputSize(renderer: SDLPointer): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Fill a rectangle with the current draw color
+     */
+    renderFillRect(renderer: SDLPointer, rect: Buffer | null): void;
+    /**
+     * Set the render target (null for default window)
+     */
+    setRenderTarget(renderer: SDLPointer, texture: SDLPointer | null): void;
+    /**
+     * Get drawable size (physical pixels) for HiDPI windows
+     */
+    getDrawableSize(window: SDLPointer): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get the scale factor between logical and physical pixels
+     */
+    getScaleFactor(window: SDLPointer): number;
+    /**
+     * Get the scale factor using renderer output size (more reliable for non-GL windows)
+     */
+    getScaleFactorFromRenderer(window: SDLPointer, renderer: SDLPointer): number;
+    /**
+     * Poll for pending events
+     */
+    pollEvent(): {
+        type: number;
+        windowEvent?: number;
+        keycode?: number;
+        pressed?: boolean;
+        repeat?: boolean;
+    } | null;
+    /**
+     * Check if SDL is initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Get the SDL2 API singleton
+ */
+declare const getSDL2: () => SDL2API;
+/**
+ * Check if SDL2 is available without throwing
+ */
+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
+ *
+ * Main renderer for Ink-based UI in SDL mode. Intercepts ANSI output
+ * from Ink and renders it to an SDL window using text rendering.
+ */
+
+interface SdlUiRendererOptions {
+    width?: number;
+    height?: number;
+    title?: string;
+    vsync?: boolean;
+    fontSize?: number;
+    scaleFactor?: number | null;
+}
+/**
+ * SDL UI Renderer
+ *
+ * Renders Ink UI to an SDL window by parsing ANSI sequences and
+ * drawing text with SDL_ttf.
+ */
+declare class SdlUiRenderer {
+    private sdl;
+    private window;
+    private renderer;
+    private textRenderer;
+    private ansiParser;
+    private inputBridge;
+    private windowWidth;
+    private windowHeight;
+    private columns;
+    private rows;
+    private charWidth;
+    private charHeight;
+    private fgColor;
+    private bgColor;
+    private bold;
+    private dim;
+    private reverse;
+    private shouldQuit;
+    private pendingCommands;
+    private scaleFactor;
+    private userScaleFactor;
+    constructor(options?: SdlUiRendererOptions);
+    /**
+     * Initialize SDL window and renderer
+     */
+    private initSDL;
+    /**
+     * Update terminal dimensions based on window size
+     */
+    private updateTerminalDimensions;
+    /**
+     * Get terminal dimensions
+     */
+    getDimensions(): {
+        columns: number;
+        rows: number;
+    };
+    /**
+     * Process ANSI output from Ink
+     */
+    processAnsi(output: string): void;
+    /**
+     * Render pending commands and present
+     */
+    present(): void;
+    /**
+     * Execute a single draw command
+     */
+    private executeCommand;
+    /**
+     * Render text at position
+     */
+    private renderText;
+    /**
+     * Clear the entire screen
+     */
+    clear(): void;
+    /**
+     * Clear a line from a specific position
+     */
+    private clearLine;
+    /**
+     * Process SDL events
+     */
+    processEvents(): SdlKeyEvent[];
+    /**
+     * Convert SDL key event to terminal sequence
+     */
+    keyEventToSequence(event: SdlKeyEvent): string | null;
+    /**
+     * Handle window resize
+     */
+    private handleResize;
+    /**
+     * Check if quit was requested
+     */
+    shouldClose(): boolean;
+    /**
+     * Get cursor position
+     */
+    getCursorPos(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Get the SDL window
+     */
+    getWindow(): SDLPointer | null;
+    /**
+     * Get the SDL renderer
+     */
+    getRenderer(): SDLPointer | null;
+    /**
+     * Set the scale factor
+     */
+    setScaleFactor(scaleFactor: number | null): void;
+    /**
+     * Get current scale factor
+     */
+    getScaleFactor(): number;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+    /**
+     * Reset state for reuse
+     */
+    reset(): void;
+}
+
+/**
+ * SDL Output Stream for Ink
+ *
+ * A Writable stream that intercepts Ink's ANSI output and renders it
+ * to an SDL window.
+ */
+
+/**
+ * SDL Output Stream
+ *
+ * Wraps an SdlUiRenderer in a Node.js Writable stream that Ink
+ * can use as stdout.
+ */
+declare class SdlOutputStream extends Writable {
+    /** TTY interface property expected by Ink */
+    isTTY: boolean;
+    private uiRenderer;
+    constructor(uiRenderer: SdlUiRenderer);
+    /**
+     * Get terminal columns
+     */
+    get columns(): number;
+    /**
+     * Get terminal rows
+     */
+    get rows(): number;
+    /**
+     * Notify Ink of resize
+     */
+    notifyResize(): void;
+    /**
+     * Implement Writable._write
+     */
+    _write(chunk: Buffer | string, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    /**
+     * Get the underlying renderer
+     */
+    getRenderer(): SdlUiRenderer;
+    /**
+     * Clear the screen
+     */
+    clear(): void;
+    /**
+     * Write a string directly (bypasses Writable buffering)
+     */
+    writeSync(text: string): void;
+    /**
+     * Get cursor position
+     */
+    getCursorPos(): {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * SDL Input Stream for Ink
+ *
+ * A Readable stream that provides keyboard input to Ink from SDL events.
+ * Implements the TTY interface expected by Ink.
+ */
+
+/**
+ * SDL Input Stream
+ *
+ * Wraps SDL keyboard events in a Node.js Readable stream that Ink
+ * can use as stdin.
+ */
+declare class SdlInputStream extends Readable {
+    /** TTY interface properties expected by Ink */
+    isTTY: boolean;
+    isRaw: boolean;
+    private buffer;
+    private waiting;
+    constructor();
+    /**
+     * Push a key sequence into the stream
+     */
+    pushKey(sequence: string): void;
+    /**
+     * Implement Readable._read
+     */
+    _read(): void;
+    /**
+     * Set raw mode (no-op for SDL, we're always raw)
+     */
+    setRawMode(_mode: boolean): this;
+    /**
+     * Check if stream has buffered data
+     */
+    hasData(): boolean;
+    /**
+     * Clear the input buffer
+     */
+    clear(): void;
+    /**
+     * Close the stream
+     */
+    close(): void;
+    /**
+     * Keep the event loop alive (no-op for SDL)
+     */
+    ref(): this;
+    /**
+     * Allow event loop to exit (no-op for SDL)
+     */
+    unref(): this;
+}
+
+/**
+ * SDL Streams for Ink
+ *
+ * Factory function to create stdin/stdout streams that render to SDL.
+ */
+
+/**
+ * Options for creating SDL streams
+ */
+interface SdlStreamsOptions {
+    /** Window title */
+    title?: string;
+    /** Window width in pixels */
+    width?: number;
+    /** Window height in pixels */
+    height?: number;
+    /** Enable vsync */
+    vsync?: boolean;
+    /** Font size in points */
+    fontSize?: number;
+    /** Override scale factor (null = auto-detect) */
+    scaleFactor?: number | null;
+}
+/**
+ * SDL Window wrapper that emits events
+ */
+declare class SdlWindow extends EventEmitter {
+    private renderer;
+    private eventLoopHandle;
+    private inputStream;
+    private outputStream;
+    private closed;
+    constructor(renderer: SdlUiRenderer, inputStream: SdlInputStream, outputStream: SdlOutputStream);
+    /**
+     * Start the SDL event loop
+     */
+    private startEventLoop;
+    /**
+     * Get terminal dimensions
+     */
+    getDimensions(): {
+        columns: number;
+        rows: number;
+    };
+    /**
+     * Set window title
+     */
+    setTitle(title: string): void;
+    /**
+     * Clear the screen
+     */
+    clear(): void;
+    /**
+     * Close the window
+     */
+    close(): void;
+    /**
+     * Check if window is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Get the output stream
+     */
+    getOutputStream(): SdlOutputStream;
+}
+/**
+ * Result of createSdlStreams
+ */
+interface SdlStreams {
+    /** Readable stream for keyboard input */
+    stdin: SdlInputStream;
+    /** Writable stream for ANSI output */
+    stdout: SdlOutputStream;
+    /** SDL window wrapper with events */
+    window: SdlWindow;
+}
+/**
+ * Create SDL streams for use with Ink
+ *
+ * @example
+ * ```typescript
+ * import { render, Text, Box } from "ink";
+ * import { createSdlStreams } from "ink-sdl";
+ *
+ * const App = () => (
+ *   <Box flexDirection="column">
+ *     <Text color="green">Hello from SDL!</Text>
+ *   </Box>
+ * );
+ *
+ * const { stdin, stdout, window } = createSdlStreams({
+ *   title: "My App",
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * render(<App />, { stdin, stdout });
+ *
+ * window.on("close", () => process.exit(0));
+ * ```
+ */
+declare const createSdlStreams: (options?: SdlStreamsOptions) => SdlStreams;
+
+/**
+ * SDL Input Bridge
+ *
+ * Maps SDL keyboard events to terminal escape sequences for Ink compatibility.
+ */
+
+/**
+ * Terminal-style key event for Ink
+ */
+interface InkKeyEvent {
+    sequence: string;
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+}
+/**
+ * Track modifier key state
+ */
+interface ModifierState {
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+}
+/**
+ * SDL to Terminal Input Bridge
+ *
+ * Converts SDL keyboard events to terminal-compatible sequences
+ * that Ink can understand.
+ */
+declare class InputBridge {
+    private modifiers;
+    /**
+     * Process an SDL key event and return terminal sequence
+     */
+    processKeyEvent(event: SdlKeyEvent): string | null;
+    /**
+     * Check if a keycode is a modifier key
+     */
+    private isModifierKey;
+    /**
+     * Update modifier key state
+     */
+    private updateModifierState;
+    /**
+     * Get terminal escape sequence for special keys
+     */
+    private getSpecialKeySequence;
+    /**
+     * Get Ctrl+key sequence
+     */
+    private getCtrlSequence;
+    /**
+     * Convert SDL key event to Ink-style key event
+     */
+    toInkKeyEvent(event: SdlKeyEvent): InkKeyEvent | null;
+    /**
+     * Get human-readable key name
+     */
+    private getKeyName;
+    /**
+     * Reset modifier state
+     */
+    reset(): void;
+    /**
+     * Get current modifier state
+     */
+    getModifiers(): ModifierState;
+}
+
+/**
+ * ink-sdl
+ *
+ * Render Ink TUI applications to an SDL window instead of the terminal.
+ *
+ * @example
+ * ```typescript
+ * import { render, Text, Box } from "ink";
+ * import { createSdlStreams } from "ink-sdl";
+ *
+ * const App = () => (
+ *   <Box flexDirection="column">
+ *     <Text color="green">Hello from SDL!</Text>
+ *   </Box>
+ * );
+ *
+ * const { stdin, stdout, window } = createSdlStreams({
+ *   title: "My App",
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * render(<App />, { stdin, stdout });
+ *
+ * window.on("close", () => process.exit(0));
+ * ```
+ */
+
+/**
+ * Check if SDL is available for rendering
+ */
+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 };