ink-native 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,714 @@
+import { Readable, Writable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+
+/** 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 Parser
+ *
+ * Parses terminal ANSI escape sequences and converts them to draw commands
+ * for rendering in a native framebuffer window.
+ */
+
+/**
+ * ANSI sequence parser
+ *
+ * Parses ANSI escape sequences from terminal output and produces
+ * draw commands for framebuffer 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;
+}
+
+/**
+ * Bitmap Font Renderer
+ *
+ * Renders text using embedded Cozette bitmap font data directly into
+ * a Uint32Array framebuffer. Pure TypeScript -- no native dependencies,
+ * no caching needed (just bit tests and pixel writes).
+ */
+
+/**
+ * Bitmap Font Renderer
+ *
+ * Blits bitmap font glyphs directly into a Uint32Array pixel buffer.
+ */
+declare class BitmapFontRenderer {
+    private fallbackGlyph;
+    /**
+     * Get the fixed character cell dimensions
+     */
+    getCharDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Check if a glyph is double-width based on its data length
+     *
+     * Wide glyphs have 2 bytes per row (26 bytes total) vs 1 byte (13 bytes).
+     */
+    isWideGlyph(codepoint: number): boolean;
+    /**
+     * Get the pixel width of a glyph
+     */
+    getGlyphPixelWidth(codepoint: number): number;
+    /**
+     * Measure the total pixel width of a text string
+     */
+    measureText(text: string): number;
+    /**
+     * Render a single character into the framebuffer
+     */
+    renderChar(buf: Uint32Array, bufWidth: number, x: number, y: number, codepoint: number, fgColor: number, italic?: boolean): void;
+    /**
+     * Render a string of text into the framebuffer
+     *
+     * Returns the total pixel width rendered.
+     */
+    renderText(buf: Uint32Array, bufWidth: number, x: number, y: number, text: string, fgColor: number, italic?: boolean): number;
+    /**
+     * Render a single character scaled via nearest-neighbor into the framebuffer
+     *
+     * Maps each destination pixel back to the source glyph bitmap using
+     * nearest-neighbor sampling. Preserves the crisp, pixelated look of
+     * bitmap fonts on HiDPI displays.
+     */
+    renderCharScaled(buf: Uint32Array, bufWidth: number, bufHeight: number, x: number, y: number, codepoint: number, fgColor: number, destWidth: number, destHeight: number, italic?: boolean): void;
+    /**
+     * Render a string of text scaled via nearest-neighbor into the framebuffer
+     *
+     * Returns the total pixel width rendered.
+     */
+    renderTextScaled(buf: Uint32Array, bufWidth: number, bufHeight: number, x: number, y: number, text: string, fgColor: number, scale: number, italic?: boolean): number;
+    /**
+     * Measure the total scaled pixel width of a text string
+     */
+    measureTextScaled(text: string, scale: number): number;
+}
+
+/** Opaque pointer type for fenster bridge handle */
+type FensterPointer = unknown;
+/** Key event from fenster key state diffing */
+interface FensterKeyEvent {
+    /** Key index in fenster's keys[256] array (mostly ASCII) */
+    keyIndex: number;
+    /** Whether the key is pressed (true) or released (false) */
+    pressed: boolean;
+}
+
+/**
+ * Fenster FFI Bindings
+ *
+ * Provides fenster bindings for framebuffer-based window rendering
+ * using koffi for foreign function interface. No system dependencies
+ * required beyond the bundled native library.
+ */
+
+/**
+ * Fenster API wrapper class
+ *
+ * Provides type-safe access to the fenster bridge functions for
+ * framebuffer-based window rendering.
+ */
+declare class Fenster {
+    private lib;
+    private _create;
+    private _open;
+    private _loop;
+    private _close;
+    private _copyBuf;
+    private _getKeys;
+    private _getMod;
+    private _getSize;
+    private _getResized;
+    private _getScale;
+    private _setScale;
+    constructor();
+    private bindFunctions;
+    /**
+     * Create a new fenster window (does not open it yet)
+     */
+    create(title: string, width: number, height: number): FensterPointer;
+    /**
+     * Open the fenster window
+     */
+    open(f: FensterPointer): void;
+    /**
+     * Process events and present the buffer
+     *
+     * Returns 0 on success, non-zero if window should close.
+     */
+    loop(f: FensterPointer): number;
+    /**
+     * Close the fenster window and free resources
+     */
+    close(f: FensterPointer): void;
+    /**
+     * Copy pixel data into fenster's native buffer
+     *
+     * Accepts a Buffer (e.g. a view over a Uint32Array) and memcpy's it
+     * into the native pixel buffer so the next `loop()` call presents it.
+     */
+    copyBuf(f: FensterPointer, src: Buffer): void;
+    /**
+     * Get the keys state array
+     *
+     * 256 entries; each entry is 1 (pressed) or 0 (released).
+     */
+    getKeys(f: FensterPointer): number[];
+    /**
+     * Get the current modifier bitmask
+     *
+     * Bits: ctrl=1, shift=2, alt=4, meta=8
+     */
+    getMod(f: FensterPointer): number;
+    /**
+     * Check if the window was resized since the last call
+     *
+     * Returns the new dimensions if resized, or null if no resize occurred.
+     * Clears the resize flag on read.
+     */
+    getResized(f: FensterPointer): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Get the backing scale factor (1.0 = normal, 2.0 = Retina)
+     */
+    getScale(f: FensterPointer): number;
+    /**
+     * Override the backing scale factor
+     *
+     * Recomputes physical dimensions from logical size * scale.
+     */
+    setScale(f: FensterPointer, scale: number): void;
+    /**
+     * Get the window size
+     */
+    getSize(f: FensterPointer): {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Get the Fenster API singleton
+ */
+declare const getFenster: () => Fenster;
+/**
+ * Check if fenster is available without throwing
+ */
+declare const isFensterAvailable: () => boolean;
+
+/**
+ * Input Stream for Ink
+ *
+ * A Readable stream that provides keyboard input to Ink from native window events.
+ * Implements the TTY interface expected by Ink.
+ */
+
+/**
+ * Input Stream
+ *
+ * Wraps native keyboard events in a Node.js Readable stream that Ink
+ * can use as stdin.
+ */
+declare class InputStream 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, 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)
+     */
+    ref(): this;
+    /**
+     * Allow event loop to exit (no-op)
+     */
+    unref(): this;
+}
+
+/**
+ * OutputStream Types
+ */
+/** Duck-typed interface for any UI renderer compatible with OutputStream */
+interface UiRendererLike {
+    getDimensions(): {
+        columns: number;
+        rows: number;
+    };
+    processAnsi(text: string): void;
+    present(): void;
+    clear(): void;
+    getCursorPos(): {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Output Stream for Ink
+ *
+ * A Writable stream that intercepts Ink's ANSI output and renders it
+ * to a native window.
+ */
+
+/**
+ * Output Stream
+ *
+ * Wraps a UiRenderer in a Node.js Writable stream that Ink
+ * can use as stdout.
+ */
+declare class OutputStream extends Writable {
+    /** TTY interface property expected by Ink */
+    isTTY: boolean;
+    private uiRenderer;
+    constructor(uiRenderer: UiRendererLike);
+    /**
+     * 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(): UiRendererLike;
+    /**
+     * Clear the screen
+     */
+    clear(): void;
+    /**
+     * Write a string directly (bypasses Writable buffering)
+     */
+    writeSync(text: string): void;
+    /**
+     * Get cursor position
+     */
+    getCursorPos(): {
+        x: number;
+        y: number;
+    };
+}
+
+/** Options for creating a UiRenderer */
+interface UiRendererOptions {
+    /** Window width in pixels (default 800) */
+    width?: number;
+    /** Window height in pixels (default 600) */
+    height?: number;
+    /** Window title (default "ink-native") */
+    title?: string;
+    /** Background color as RGB tuple [r, g, b] or hex string "#RRGGBB" */
+    backgroundColor?: [number, number, number] | string | undefined;
+    /** HiDPI scale factor override (number = override, null/undefined = auto-detect) */
+    scaleFactor?: number | null;
+}
+/** Direct access to the native framebuffer pixel buffer */
+interface Framebuffer {
+    /** Pixel buffer in 0xAARRGGBB format (physical resolution) */
+    pixels: Uint32Array;
+    /** Physical width in pixels */
+    width: number;
+    /** Physical height in pixels */
+    height: number;
+}
+/** Result from processing native window events */
+interface ProcessEventsResult {
+    /** Key events detected by diffing the keys array */
+    keyEvents: FensterKeyEvent[];
+    /** Current modifier bitmask */
+    mod: number;
+    /** Whether the window was resized this frame */
+    resized: boolean;
+}
+
+/**
+ * UI Renderer
+ *
+ * Renders Ink UI to a native framebuffer window by parsing ANSI sequences
+ * and drawing bitmap font glyphs directly into a pixel buffer.
+ * No GPU, no textures -- pure TypeScript pixel manipulation.
+ */
+
+/**
+ * Pack RGB color into fenster's 0xAARRGGBB pixel format
+ */
+declare const packColor: (r: number, g: number, b: number) => number;
+/**
+ * UI Renderer
+ *
+ * Renders Ink UI to a native framebuffer by parsing ANSI sequences
+ * and drawing bitmap font glyphs. Uses a JS-side Uint32Array for
+ * rendering, then copies to the native buffer on present.
+ */
+declare class UiRenderer {
+    private fenster;
+    private fensterPtr;
+    private fontRenderer;
+    private ansiParser;
+    /** Logical window dimensions (in points) */
+    private windowWidth;
+    private windowHeight;
+    /** Physical framebuffer dimensions (in pixels) */
+    private physicalWidth;
+    private physicalHeight;
+    /** Backing scale factor */
+    private scaleFactor;
+    /** User-requested scale factor override (null = auto-detect) */
+    private userScaleFactor;
+    /** Scaled glyph dimensions (in physical pixels) */
+    private scaledGlyphWidth;
+    private scaledGlyphHeight;
+    private columns;
+    private rows;
+    /** JS-side framebuffer for rendering (at physical resolution) */
+    private framebuffer;
+    /** Previous key state for diff-based event detection */
+    private prevKeys;
+    private fgColor;
+    private bgColor;
+    private defaultBgColor;
+    private bold;
+    private dim;
+    private italic;
+    private underline;
+    private strikethrough;
+    private reverse;
+    private shouldQuit;
+    private pendingCommands;
+    constructor(options?: UiRendererOptions);
+    /**
+     * Copy JS framebuffer to native fenster buffer
+     */
+    private copyToNativeBuffer;
+    /**
+     * Process ANSI output from Ink
+     */
+    processAnsi(output: string): void;
+    /**
+     * Render pending commands and prepare for present
+     */
+    present(): void;
+    /**
+     * Process fenster events and present the buffer to screen
+     *
+     * Calls fenster_loop (which presents the buffer + polls events),
+     * then diffs the keys array to detect press/release events.
+     */
+    processEventsAndPresent(): ProcessEventsResult;
+    /**
+     * Handle window resize by updating dimensions and recreating the framebuffer
+     *
+     * Receives physical dimensions from getResized() and derives logical
+     * dimensions using the current scale factor.
+     */
+    private handleResize;
+    /**
+     * Convert a fenster key event to a terminal escape sequence
+     */
+    keyEventToSequence(event: FensterKeyEvent, mod: number): string | null;
+    /**
+     * Check if quit was requested
+     */
+    shouldClose(): boolean;
+    /**
+     * Reset input state (no-op for fenster, modifier state is polled)
+     */
+    resetInputState(): void;
+    /**
+     * Get the display refresh rate (fixed for fenster)
+     */
+    getDisplayRefreshRate(): number;
+    /**
+     * Get terminal dimensions
+     */
+    getDimensions(): {
+        columns: number;
+        rows: number;
+    };
+    /**
+     * Get direct access to the framebuffer pixel buffer.
+     *
+     * The returned `pixels` array is the same backing buffer used by the
+     * renderer, so writes are immediately visible on the next `present()` call.
+     * Pixel format is 0xAARRGGBB — use `packColor(r, g, b)` to create values.
+     */
+    getFramebuffer(): Framebuffer;
+    /**
+     * Clear the entire screen
+     */
+    clear(): void;
+    /**
+     * Get cursor position
+     */
+    getCursorPos(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Execute a single draw command
+     */
+    private executeCommand;
+    /**
+     * Render text at position (using scaled coordinates for physical resolution)
+     */
+    private renderText;
+    /**
+     * Fill a rectangle in the framebuffer (physical pixel coordinates)
+     */
+    private fillRect;
+    /**
+     * Clear a line from a specific position (scaled coordinates)
+     */
+    private clearLine;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+    /**
+     * Reset state for reuse
+     */
+    reset(): void;
+}
+
+/**
+ * Options for creating streams
+ */
+interface StreamsOptions {
+    /** Window title */
+    title?: string;
+    /** Window width in pixels */
+    width?: number;
+    /** Window height in pixels */
+    height?: number;
+    /** Background color as RGB tuple [r, g, b] or hex string "#RRGGBB" */
+    backgroundColor?: [number, number, number] | string | undefined;
+    /** Force a specific frame rate instead of default 60fps */
+    frameRate?: number | undefined;
+    /** HiDPI scale factor override (number = override, null/undefined = auto-detect) */
+    scaleFactor?: number | null;
+}
+/**
+ * Result of createStreams
+ */
+interface Streams {
+    /** Readable stream for keyboard input */
+    stdin: InputStream;
+    /** Writable stream for ANSI output */
+    stdout: OutputStream;
+    /** Window wrapper with events */
+    window: Window;
+    /** UI renderer (for advanced use) */
+    renderer: UiRenderer;
+}
+
+/**
+ * Window and Streams for Ink
+ *
+ * Factory function to create stdin/stdout streams that render to a
+ * native framebuffer window.
+ */
+
+/**
+ * Window wrapper that emits events
+ *
+ * Manages the event loop, key event processing, and stream coordination
+ * for the native window backend.
+ */
+declare class Window extends EventEmitter {
+    private renderer;
+    private eventLoopHandle;
+    private inputStream;
+    private outputStream;
+    private closed;
+    private paused;
+    private currentFrameRate;
+    constructor(renderer: UiRenderer, inputStream: InputStream, outputStream: OutputStream, frameRate?: number);
+    /**
+     * Start the event loop
+     */
+    private startEventLoop;
+    /**
+     * Run a single iteration of the event loop
+     */
+    private runEventLoopIteration;
+    /**
+     * Get terminal dimensions
+     */
+    getDimensions(): {
+        columns: number;
+        rows: number;
+    };
+    /**
+     * Clear the screen
+     */
+    clear(): void;
+    /**
+     * Close the window
+     */
+    close(): void;
+    /**
+     * Check if window is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Pause the Ink event loop so the caller can take over rendering.
+     *
+     * While paused, call `renderer.processEventsAndPresent()` manually
+     * in your own loop to poll events and present the framebuffer.
+     */
+    pause(): void;
+    /**
+     * Resume the Ink event loop after pausing.
+     */
+    resume(): void;
+    /**
+     * Check if the event loop is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Get the output stream
+     */
+    getOutputStream(): OutputStream;
+    /**
+     * Get the current frame rate
+     */
+    getFrameRate(): number;
+}
+/**
+ * Create streams for use with Ink
+ *
+ * Creates stdin/stdout streams backed by a native window.
+ *
+ * @example
+ * ```typescript
+ * import { render, Text, Box } from "ink";
+ * import { createStreams } from "ink-native";
+ *
+ * const App = () => (
+ *   <Box flexDirection="column">
+ *     <Text color="green">Hello from ink-native!</Text>
+ *   </Box>
+ * );
+ *
+ * const { stdin, stdout, window } = createStreams({
+ *   title: "My App",
+ *   width: 800,
+ *   height: 600,
+ * });
+ *
+ * render(<App />, { stdin, stdout });
+ *
+ * window.on("close", () => process.exit(0));
+ * ```
+ */
+declare const createStreams: (options?: StreamsOptions) => Streams;
+
+export { AnsiParser, BitmapFontRenderer, type Color, type DrawCommand, Fenster, type FensterKeyEvent, type FensterPointer, type Framebuffer, InputStream, OutputStream, type ProcessEventsResult, type Streams, type StreamsOptions, UiRenderer, type UiRendererOptions, Window, createStreams, getFenster, isFensterAvailable, packColor };