blecsd 0.3.0 → 0.6.0

package/dist/inputStream-COARA4CP.d.ts

@@ -0,0 +1,1182 @@
+import { z } from 'zod';
+import { K as KeyEvent } from './keyParser-DReXe2j-.js';
+import { M as MouseEvent, F as FocusEvent } from './mouseParser-CCqSEUVN.js';
+
+/**
+ * ANSI cursor control functions.
+ *
+ * Provides functions for cursor movement, positioning, visibility,
+ * shape, and color control. All functions return ANSI escape sequences
+ * as strings with no side effects.
+ *
+ * @module terminal/ansi/cursor
+ * @internal This module is internal and not exported from the main package.
+ */
+/**
+ * Cursor control functions.
+ * All functions return ANSI escape sequences as strings.
+ */
+declare const cursor: {
+    /**
+     * Move cursor to absolute position (1-indexed).
+     *
+     * @param x - Column (1-indexed)
+     * @param y - Row (1-indexed)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.move(10, 5) // Move to column 10, row 5
+     * // Returns: '\x1b[5;10H'
+     * ```
+     */
+    readonly move: (x: number, y: number) => string;
+    /**
+     * Move cursor to column (1-indexed) on current row.
+     *
+     * @param x - Column (1-indexed)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.column(1) // Move to column 1
+     * // Returns: '\x1b[1G'
+     * ```
+     */
+    readonly column: (x: number) => string;
+    /**
+     * Move cursor up n rows.
+     *
+     * @param n - Number of rows (default: 1)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.up(3) // Move up 3 rows
+     * // Returns: '\x1b[3A'
+     * ```
+     */
+    readonly up: (n?: number) => string;
+    /**
+     * Move cursor down n rows.
+     *
+     * @param n - Number of rows (default: 1)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.down(2) // Move down 2 rows
+     * // Returns: '\x1b[2B'
+     * ```
+     */
+    readonly down: (n?: number) => string;
+    /**
+     * Move cursor forward (right) n columns.
+     *
+     * @param n - Number of columns (default: 1)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.forward(5) // Move right 5 columns
+     * // Returns: '\x1b[5C'
+     * ```
+     */
+    readonly forward: (n?: number) => string;
+    /**
+     * Move cursor back (left) n columns.
+     *
+     * @param n - Number of columns (default: 1)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.back(3) // Move left 3 columns
+     * // Returns: '\x1b[3D'
+     * ```
+     */
+    readonly back: (n?: number) => string;
+    /**
+     * Move cursor to beginning of line n lines down.
+     *
+     * @param n - Number of lines (default: 1)
+     * @returns ANSI escape sequence
+     */
+    readonly nextLine: (n?: number) => string;
+    /**
+     * Move cursor to beginning of line n lines up.
+     *
+     * @param n - Number of lines (default: 1)
+     * @returns ANSI escape sequence
+     */
+    readonly prevLine: (n?: number) => string;
+    /**
+     * Save cursor position (DEC private mode).
+     *
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.save() // Save current position
+     * // Returns: '\x1b[s'
+     * ```
+     */
+    readonly save: () => string;
+    /**
+     * Restore cursor position (DEC private mode).
+     *
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.restore() // Restore saved position
+     * // Returns: '\x1b[u'
+     * ```
+     */
+    readonly restore: () => string;
+    /**
+     * Show cursor (make visible).
+     *
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.show() // Make cursor visible
+     * // Returns: '\x1b[?25h'
+     * ```
+     */
+    readonly show: () => string;
+    /**
+     * Hide cursor (make invisible).
+     *
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.hide() // Make cursor invisible
+     * // Returns: '\x1b[?25l'
+     * ```
+     */
+    readonly hide: () => string;
+    /**
+     * Request cursor position report.
+     * Terminal responds with CSI row ; col R
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly requestPosition: () => string;
+    /**
+     * Move cursor to home position (1,1).
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly home: () => string;
+    /**
+     * Set cursor shape.
+     *
+     * Shapes:
+     * - 0: Default (usually block)
+     * - 1: Blinking block
+     * - 2: Steady block
+     * - 3: Blinking underline
+     * - 4: Steady underline
+     * - 5: Blinking bar (xterm)
+     * - 6: Steady bar (xterm)
+     *
+     * @param shape - Cursor shape (0-6)
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.setShape(CursorShape.STEADY_BAR) // Steady bar cursor
+     * // Returns: '\x1b[6 q'
+     * ```
+     */
+    readonly setShape: (shape: number) => string;
+    /**
+     * Set cursor to blinking block.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly blinkingBlock: () => string;
+    /**
+     * Set cursor to steady (non-blinking) block.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly steadyBlock: () => string;
+    /**
+     * Set cursor to blinking underline.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly blinkingUnderline: () => string;
+    /**
+     * Set cursor to steady (non-blinking) underline.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly steadyUnderline: () => string;
+    /**
+     * Set cursor to blinking bar (I-beam).
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly blinkingBar: () => string;
+    /**
+     * Set cursor to steady (non-blinking) bar (I-beam).
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly steadyBar: () => string;
+    /**
+     * Reset cursor shape to default.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly resetShape: () => string;
+    /**
+     * Set cursor color (xterm extension).
+     * Uses OSC 12 to set cursor foreground color.
+     *
+     * @param color - Color as hex string (#RRGGBB) or color name
+     * @returns ANSI escape sequence
+     *
+     * @example
+     * ```typescript
+     * cursor.setColor('#ff0000') // Red cursor
+     * cursor.setColor('green')   // Green cursor
+     * ```
+     */
+    readonly setColor: (color: string) => string;
+    /**
+     * Reset cursor color to default.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly resetColor: () => string;
+    /**
+     * Save cursor style (DECSCUSR save - not widely supported).
+     * Use cursor.save() for position, this saves shape/blink state.
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly saveStyle: () => string;
+    /**
+     * Restore cursor style (DECSCUSR restore - not widely supported).
+     *
+     * @returns ANSI escape sequence
+     */
+    readonly restoreStyle: () => string;
+};
+/**
+ * Cursor shape constants for use with cursor.setShape()
+ */
+declare const CursorShape: {
+    /** Default cursor (terminal-dependent) */
+    readonly DEFAULT: 0;
+    /** Blinking block cursor */
+    readonly BLINKING_BLOCK: 1;
+    /** Steady (non-blinking) block cursor */
+    readonly STEADY_BLOCK: 2;
+    /** Blinking underline cursor */
+    readonly BLINKING_UNDERLINE: 3;
+    /** Steady (non-blinking) underline cursor */
+    readonly STEADY_UNDERLINE: 4;
+    /** Blinking bar (I-beam) cursor */
+    readonly BLINKING_BAR: 5;
+    /** Steady (non-blinking) bar (I-beam) cursor */
+    readonly STEADY_BAR: 6;
+};
+type CursorShapeType = (typeof CursorShape)[keyof typeof CursorShape];
+
+/**
+ * Terminal Response Parser
+ *
+ * Parses responses from terminal queries (DA, DSR, window manipulation, etc.).
+ * Used internally by the Program class to handle terminal communication.
+ *
+ * @module terminal/responseParser
+ * @internal This module is internal and not exported from the main package.
+ */
+
+/**
+ * Response type identifiers.
+ */
+declare const ResponseType: {
+    /** Primary Device Attributes (DA1) - ESC [ ? ... c */
+    readonly PRIMARY_DA: "primary_da";
+    /** Secondary Device Attributes (DA2) - ESC [ > ... c */
+    readonly SECONDARY_DA: "secondary_da";
+    /** Tertiary Device Attributes (DA3) - ESC P ! | ... ESC \ */
+    readonly TERTIARY_DA: "tertiary_da";
+    /** Cursor Position Report (CPR) - ESC [ Pr ; Pc R */
+    readonly CURSOR_POSITION: "cursor_position";
+    /** Device Status Report (DSR) - ESC [ Pn n */
+    readonly DEVICE_STATUS: "device_status";
+    /** Operating Status Report - ESC [ Pn n */
+    readonly OPERATING_STATUS: "operating_status";
+    /** Window Title - OSC L title ST */
+    readonly WINDOW_TITLE: "window_title";
+    /** Icon Label - OSC l label ST */
+    readonly ICON_LABEL: "icon_label";
+    /** Window State (iconified, normal, maximized) */
+    readonly WINDOW_STATE: "window_state";
+    /** Window Position (x, y in pixels) */
+    readonly WINDOW_POSITION: "window_position";
+    /** Window Size (width, height in pixels) */
+    readonly WINDOW_SIZE_PIXELS: "window_size_pixels";
+    /** Text Area Size (width, height in characters) */
+    readonly TEXT_AREA_SIZE: "text_area_size";
+    /** Screen Size (width, height in characters) */
+    readonly SCREEN_SIZE: "screen_size";
+    /** Character Cell Size (width, height in pixels) */
+    readonly CHAR_CELL_SIZE: "char_cell_size";
+    /** Locator Position */
+    readonly LOCATOR_POSITION: "locator_position";
+    /** Unknown/unrecognized response */
+    readonly UNKNOWN: "unknown";
+};
+type ResponseTypeValue = (typeof ResponseType)[keyof typeof ResponseType];
+/**
+ * Base interface for parsed terminal responses.
+ */
+interface ParsedResponse {
+    type: ResponseTypeValue;
+    raw: string;
+}
+/**
+ * Primary Device Attributes response.
+ */
+interface PrimaryDAResponse extends ParsedResponse {
+    type: typeof ResponseType.PRIMARY_DA;
+    /** Device class (typically 1 for VT100, 62 for VT220, etc.) */
+    deviceClass: number;
+    /** List of supported attribute codes */
+    attributes: number[];
+}
+/**
+ * Secondary Device Attributes response.
+ */
+interface SecondaryDAResponse extends ParsedResponse {
+    type: typeof ResponseType.SECONDARY_DA;
+    /** Terminal type ID */
+    terminalType: number;
+    /** Firmware version number */
+    firmwareVersion: number;
+    /** ROM cartridge registration number (often 0) */
+    romCartridge: number;
+}
+/**
+ * Cursor Position Report response.
+ */
+interface CursorPositionResponse extends ParsedResponse {
+    type: typeof ResponseType.CURSOR_POSITION;
+    /** Row (1-based) */
+    row: number;
+    /** Column (1-based) */
+    column: number;
+}
+/**
+ * Device Status Report response.
+ */
+interface DeviceStatusResponse extends ParsedResponse {
+    type: typeof ResponseType.DEVICE_STATUS;
+    /** Status code (0 = OK, 3 = Error) */
+    status: number;
+    /** Whether the terminal reports OK status */
+    ok: boolean;
+}
+/**
+ * Window Title response.
+ */
+interface WindowTitleResponse extends ParsedResponse {
+    type: typeof ResponseType.WINDOW_TITLE;
+    /** The window title text */
+    title: string;
+}
+/**
+ * Icon Label response.
+ */
+interface IconLabelResponse extends ParsedResponse {
+    type: typeof ResponseType.ICON_LABEL;
+    /** The icon label text */
+    label: string;
+}
+/**
+ * Window State response.
+ */
+interface WindowStateResponse extends ParsedResponse {
+    type: typeof ResponseType.WINDOW_STATE;
+    /** Window state: 1=open, 2=iconified */
+    state: number;
+    /** Whether window is iconified/minimized */
+    iconified: boolean;
+}
+/**
+ * Window Position response.
+ */
+interface WindowPositionResponse extends ParsedResponse {
+    type: typeof ResponseType.WINDOW_POSITION;
+    /** X position in pixels */
+    x: number;
+    /** Y position in pixels */
+    y: number;
+}
+/**
+ * Window Size in Pixels response.
+ */
+interface WindowSizePixelsResponse extends ParsedResponse {
+    type: typeof ResponseType.WINDOW_SIZE_PIXELS;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Text Area Size response.
+ */
+interface TextAreaSizeResponse extends ParsedResponse {
+    type: typeof ResponseType.TEXT_AREA_SIZE;
+    /** Columns (characters) */
+    columns: number;
+    /** Rows (characters) */
+    rows: number;
+}
+/**
+ * Screen Size response.
+ */
+interface ScreenSizeResponse extends ParsedResponse {
+    type: typeof ResponseType.SCREEN_SIZE;
+    /** Columns (characters) */
+    columns: number;
+    /** Rows (characters) */
+    rows: number;
+}
+/**
+ * Character Cell Size response.
+ */
+interface CharCellSizeResponse extends ParsedResponse {
+    type: typeof ResponseType.CHAR_CELL_SIZE;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Locator Position response.
+ */
+interface LocatorPositionResponse extends ParsedResponse {
+    type: typeof ResponseType.LOCATOR_POSITION;
+    /** Status code */
+    status: number;
+    /** Button state */
+    button: number;
+    /** Row */
+    row: number;
+    /** Column */
+    column: number;
+    /** Page number */
+    page: number;
+}
+/**
+ * Unknown/unrecognized response.
+ */
+interface UnknownResponse extends ParsedResponse {
+    type: typeof ResponseType.UNKNOWN;
+}
+/**
+ * Union type of all parsed response types.
+ */
+type TerminalResponse = PrimaryDAResponse | SecondaryDAResponse | CursorPositionResponse | DeviceStatusResponse | WindowTitleResponse | IconLabelResponse | WindowStateResponse | WindowPositionResponse | WindowSizePixelsResponse | TextAreaSizeResponse | ScreenSizeResponse | CharCellSizeResponse | LocatorPositionResponse | UnknownResponse;
+/**
+ * Zod schema for validating cursor position response.
+ */
+declare const CursorPositionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cursor_position">;
+    raw: z.ZodString;
+    row: z.ZodNumber;
+    column: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Parse a terminal response string.
+ *
+ * @param response - Raw response string from terminal
+ * @returns Parsed response object, or UnknownResponse if unrecognized
+ *
+ * @example
+ * ```typescript
+ * import { parseResponse, ResponseType } from 'blecsd/terminal/responseParser';
+ *
+ * const response = '\x1b[10;20R';
+ * const parsed = parseResponse(response);
+ *
+ * if (parsed.type === ResponseType.CURSOR_POSITION) {
+ *   console.log(`Cursor at row ${parsed.row}, column ${parsed.column}`);
+ * }
+ * ```
+ */
+declare function parseResponse(response: string): TerminalResponse;
+/**
+ * Check if response is a Primary DA response.
+ */
+declare function isPrimaryDA(response: TerminalResponse): response is PrimaryDAResponse;
+/**
+ * Check if response is a Secondary DA response.
+ */
+declare function isSecondaryDA(response: TerminalResponse): response is SecondaryDAResponse;
+/**
+ * Check if response is a Cursor Position response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a CursorPositionResponse
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseResponse('\x1b[10;20R');
+ * if (isCursorPosition(parsed)) {
+ *   console.log(`Row: ${parsed.row}, Column: ${parsed.column}`);
+ * }
+ * ```
+ */
+declare function isCursorPosition(response: TerminalResponse): response is CursorPositionResponse;
+/**
+ * Check if response is a Device Status response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a DeviceStatusResponse
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseResponse('\x1b[0n');
+ * if (isDeviceStatus(parsed)) {
+ *   console.log(`Status OK: ${parsed.ok}`);
+ * }
+ * ```
+ */
+declare function isDeviceStatus(response: TerminalResponse): response is DeviceStatusResponse;
+/**
+ * Check if response is a Window Title response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a WindowTitleResponse
+ */
+declare function isWindowTitle(response: TerminalResponse): response is WindowTitleResponse;
+/**
+ * Check if response is an Icon Label response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is an IconLabelResponse
+ */
+declare function isIconLabel(response: TerminalResponse): response is IconLabelResponse;
+/**
+ * Check if response is a Window State response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a WindowStateResponse
+ */
+declare function isWindowState(response: TerminalResponse): response is WindowStateResponse;
+/**
+ * Check if response is a Window Position response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a WindowPositionResponse
+ */
+declare function isWindowPosition(response: TerminalResponse): response is WindowPositionResponse;
+/**
+ * Check if response is a Window Size (pixels) response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a WindowSizePixelsResponse
+ */
+declare function isWindowSizePixels(response: TerminalResponse): response is WindowSizePixelsResponse;
+/**
+ * Check if response is a Text Area Size response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a TextAreaSizeResponse
+ */
+declare function isTextAreaSize(response: TerminalResponse): response is TextAreaSizeResponse;
+/**
+ * Check if response is a Screen Size response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a ScreenSizeResponse
+ */
+declare function isScreenSize(response: TerminalResponse): response is ScreenSizeResponse;
+/**
+ * Check if response is a Character Cell Size response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a CharCellSizeResponse
+ */
+declare function isCharCellSize(response: TerminalResponse): response is CharCellSizeResponse;
+/**
+ * Check if response is a Locator Position response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is a LocatorPositionResponse
+ */
+declare function isLocatorPosition(response: TerminalResponse): response is LocatorPositionResponse;
+/**
+ * Check if response is an unknown/unrecognized response.
+ *
+ * @param response - Parsed terminal response
+ * @returns true if response is an UnknownResponse
+ */
+declare function isUnknown(response: TerminalResponse): response is UnknownResponse;
+/**
+ * Query generators for terminal queries.
+ *
+ * These functions generate the escape sequences to send to the terminal
+ * to request information. The terminal will respond with data that can
+ * be parsed using parseResponse().
+ *
+ * @example
+ * ```typescript
+ * import { query, parseResponse, isCursorPosition } from 'blecsd/terminal';
+ *
+ * // Send cursor position query
+ * process.stdout.write(query.cursorPosition());
+ *
+ * // Read response from stdin and parse it
+ * // (In practice, you'd use async input handling)
+ * const response = await readTerminalResponse();
+ * const parsed = parseResponse(response);
+ *
+ * if (isCursorPosition(parsed)) {
+ *   console.log(`Cursor at row ${parsed.row}, column ${parsed.column}`);
+ * }
+ * ```
+ */
+declare const query: {
+    /**
+     * Request Primary Device Attributes (DA1).
+     * Response format: ESC [ ? Pn ; ... c
+     *
+     * @returns Query sequence
+     *
+     * @example
+     * ```typescript
+     * process.stdout.write(query.primaryDA());
+     * // Terminal responds with something like: \x1b[?62;1;2;6;7;8;9c
+     * ```
+     */
+    readonly primaryDA: () => string;
+    /**
+     * Request Secondary Device Attributes (DA2).
+     * Response format: ESC [ > Pn ; Pn ; Pn c
+     *
+     * @returns Query sequence
+     *
+     * @example
+     * ```typescript
+     * process.stdout.write(query.secondaryDA());
+     * // Terminal responds with: \x1b[>41;354;0c (xterm example)
+     * ```
+     */
+    readonly secondaryDA: () => string;
+    /**
+     * Request Tertiary Device Attributes (DA3).
+     * Response format: DCS ! | <hex> ST
+     *
+     * @returns Query sequence
+     */
+    readonly tertiaryDA: () => string;
+    /**
+     * Request Cursor Position Report (CPR).
+     * Response format: ESC [ Pr ; Pc R
+     *
+     * @returns Query sequence
+     *
+     * @example
+     * ```typescript
+     * process.stdout.write(query.cursorPosition());
+     * // Terminal responds with: \x1b[10;20R (row 10, column 20)
+     * ```
+     */
+    readonly cursorPosition: () => string;
+    /**
+     * Request Device Status Report (DSR).
+     * Response format: ESC [ 0 n (OK) or ESC [ 3 n (error)
+     *
+     * @returns Query sequence
+     *
+     * @example
+     * ```typescript
+     * process.stdout.write(query.deviceStatus());
+     * // Terminal responds with: \x1b[0n (OK)
+     * ```
+     */
+    readonly deviceStatus: () => string;
+    /**
+     * Request Window State (iconified or normal).
+     * Response format: ESC [ 1 t (open) or ESC [ 2 t (iconified)
+     *
+     * @returns Query sequence
+     */
+    readonly windowState: () => string;
+    /**
+     * Request Window Position.
+     * Response format: ESC [ 3 ; x ; y t
+     *
+     * @returns Query sequence
+     */
+    readonly windowPosition: () => string;
+    /**
+     * Request Window Size in pixels.
+     * Response format: ESC [ 4 ; height ; width t
+     *
+     * @returns Query sequence
+     */
+    readonly windowSizePixels: () => string;
+    /**
+     * Request Text Area Size in characters.
+     * Response format: ESC [ 8 ; rows ; columns t
+     *
+     * @returns Query sequence
+     */
+    readonly textAreaSize: () => string;
+    /**
+     * Request Screen Size in characters.
+     * Response format: ESC [ 9 ; rows ; columns t
+     *
+     * @returns Query sequence
+     */
+    readonly screenSize: () => string;
+    /**
+     * Request Character Cell Size in pixels.
+     * Response format: ESC [ 6 ; height ; width t
+     *
+     * @returns Query sequence
+     */
+    readonly charCellSize: () => string;
+    /**
+     * Request Window Title.
+     * Response format: OSC L ; title ST
+     *
+     * @returns Query sequence
+     */
+    readonly windowTitle: () => string;
+    /**
+     * Request Icon Label.
+     * Response format: OSC l ; label ST
+     *
+     * @returns Query sequence
+     */
+    readonly iconLabel: () => string;
+    /**
+     * Enable DEC Locator reporting.
+     *
+     * @param mode - 0=disabled, 1=one-shot, 2=continuous
+     * @returns Query sequence
+     */
+    readonly enableLocator: (mode?: 0 | 1 | 2) => string;
+    /**
+     * Request DEC Locator Position.
+     * Response format: ESC [ Pe ; Pb ; Pr ; Pc ; Pp & w
+     *
+     * @returns Query sequence
+     */
+    readonly locatorPosition: () => string;
+};
+
+/**
+ * Dynamic Terminal Capability Negotiation
+ *
+ * Queries terminal for modern features at startup. This module enables
+ * detection of advanced terminal capabilities like truecolor, Kitty keyboard
+ * protocol, graphics protocols, and synchronized output.
+ *
+ * @module terminal/capabilities/negotiation
+ */
+
+/**
+ * Default timeout for terminal queries (milliseconds).
+ */
+declare const DEFAULT_QUERY_TIMEOUT = 100;
+/**
+ * Minimum timeout allowed (milliseconds).
+ */
+declare const MIN_QUERY_TIMEOUT = 10;
+/**
+ * Maximum timeout allowed (milliseconds).
+ */
+declare const MAX_QUERY_TIMEOUT = 5000;
+/**
+ * Kitty keyboard protocol enhancement levels.
+ * Each level adds more capabilities on top of the previous.
+ */
+declare const KittyKeyboardLevel: {
+    /** Level 0: Disabled (legacy mode) */
+    readonly DISABLED: 0;
+    /** Level 1: Disambiguate escape codes */
+    readonly DISAMBIGUATE: 1;
+    /** Level 2: Report event types (press, repeat, release) */
+    readonly REPORT_EVENTS: 2;
+    /** Level 3: Report alternate keys */
+    readonly REPORT_ALTERNATES: 4;
+    /** Level 4: Report all keys as escape codes */
+    readonly REPORT_ALL: 8;
+    /** Level 5: Report associated text */
+    readonly REPORT_TEXT: 16;
+};
+type KittyKeyboardLevelValue = (typeof KittyKeyboardLevel)[keyof typeof KittyKeyboardLevel];
+/**
+ * Graphics protocol types.
+ */
+declare const GraphicsProtocol: {
+    /** No graphics support */
+    readonly NONE: "none";
+    /** Kitty graphics protocol */
+    readonly KITTY: "kitty";
+    /** iTerm2 inline images protocol */
+    readonly ITERM2: "iterm2";
+    /** Sixel graphics */
+    readonly SIXEL: "sixel";
+};
+type GraphicsProtocolValue = (typeof GraphicsProtocol)[keyof typeof GraphicsProtocol];
+/**
+ * Negotiation timing strategy.
+ */
+declare const NegotiationTiming: {
+    /** Query immediately on creation */
+    readonly EAGER: "eager";
+    /** Query on first capability access */
+    readonly LAZY: "lazy";
+    /** Skip negotiation, use environment detection only */
+    readonly SKIP: "skip";
+};
+type NegotiationTimingValue = (typeof NegotiationTiming)[keyof typeof NegotiationTiming];
+/**
+ * Terminal capabilities interface.
+ * Represents the detected capabilities of the terminal.
+ */
+interface TerminalCapabilities {
+    /** True if terminal supports 24-bit RGB colors */
+    readonly truecolor: boolean;
+    /** Kitty keyboard protocol level, or false if not supported */
+    readonly kittyKeyboard: KittyKeyboardLevelValue | false;
+    /** Graphics protocol supported, or false if none */
+    readonly graphics: GraphicsProtocolValue | false;
+    /** True if terminal supports focus events */
+    readonly focusEvents: boolean;
+    /** True if terminal supports bracketed paste mode */
+    readonly bracketedPaste: boolean;
+    /** True if terminal supports synchronized output */
+    readonly synchronizedOutput: boolean;
+    /** True if terminal supports OSC 8 hyperlinks */
+    readonly hyperlinks: boolean;
+    /** True if terminal supports styled underlines */
+    readonly styledUnderlines: boolean;
+    /** Primary DA response if available */
+    readonly primaryDA: PrimaryDAResponse | null;
+    /** Secondary DA response if available */
+    readonly secondaryDA: SecondaryDAResponse | null;
+    /** Terminal type identifier from DA2 */
+    readonly terminalType: number | null;
+    /** Firmware version from DA2 */
+    readonly firmwareVersion: number | null;
+}
+/**
+ * Capability negotiator configuration.
+ */
+interface NegotiatorConfig {
+    /** Query timeout in milliseconds (default: 100) */
+    readonly timeout?: number;
+    /** Negotiation timing strategy (default: eager) */
+    readonly timing?: NegotiationTimingValue;
+    /** Custom input stream (default: process.stdin) */
+    readonly input?: NodeJS.ReadStream;
+    /** Custom output stream (default: process.stdout) */
+    readonly output?: NodeJS.WriteStream;
+    /** Force specific capabilities (for testing) */
+    readonly forceCapabilities?: Partial<TerminalCapabilities>;
+}
+/**
+ * Zod schema for negotiator configuration.
+ */
+declare const NegotiatorConfigSchema: z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodNumber>;
+    timing: z.ZodOptional<z.ZodEnum<{
+        lazy: "lazy";
+        eager: "eager";
+        skip: "skip";
+    }>>;
+    forceCapabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Capability negotiator interface.
+ */
+interface CapabilityNegotiator {
+    /**
+     * Gets the negotiated terminal capabilities.
+     * If timing is 'lazy' and negotiation hasn't run, triggers it.
+     *
+     * @returns Promise resolving to capabilities
+     */
+    getCapabilities(): Promise<TerminalCapabilities>;
+    /**
+     * Gets cached capabilities without triggering negotiation.
+     * Returns null if not yet negotiated.
+     */
+    getCachedCapabilities(): TerminalCapabilities | null;
+    /**
+     * Forces re-negotiation of capabilities.
+     * Useful after SIGWINCH or terminal reconnection.
+     *
+     * @returns Promise resolving to new capabilities
+     */
+    renegotiate(): Promise<TerminalCapabilities>;
+    /**
+     * Checks if capabilities have been negotiated.
+     */
+    isNegotiated(): boolean;
+    /**
+     * Gets the query timeout.
+     */
+    getTimeout(): number;
+    /**
+     * Sets the query timeout.
+     *
+     * @param timeout - New timeout in milliseconds
+     */
+    setTimeout(timeout: number): void;
+    /**
+     * Cleans up resources.
+     */
+    destroy(): void;
+}
+/**
+ * Generates the XTVERSION query sequence.
+ * Response format: DCS > | version ST
+ */
+declare function queryXTVersion(): string;
+/**
+ * Generates Kitty keyboard protocol query.
+ * Response format: CSI ? flags u
+ */
+declare function queryKittyKeyboard(): string;
+/**
+ * Creates a capability negotiator.
+ *
+ * The negotiator queries the terminal for capabilities and caches the results.
+ * It supports three timing strategies:
+ * - `eager`: Query immediately on creation
+ * - `lazy`: Query on first capability access
+ * - `skip`: Use environment detection only, no queries
+ *
+ * @param config - Negotiator configuration
+ * @returns CapabilityNegotiator instance
+ *
+ * @example
+ * ```typescript
+ * import { createCapabilityNegotiator } from 'blecsd';
+ *
+ * // Create with eager negotiation (default)
+ * const negotiator = createCapabilityNegotiator();
+ *
+ * // Wait for capabilities
+ * const caps = await negotiator.getCapabilities();
+ *
+ * if (caps.truecolor) {
+ *   console.log('Truecolor supported!');
+ * }
+ *
+ * if (caps.kittyKeyboard) {
+ *   console.log(`Kitty keyboard level: ${caps.kittyKeyboard}`);
+ * }
+ *
+ * // Clean up
+ * negotiator.destroy();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create with lazy negotiation
+ * const negotiator = createCapabilityNegotiator({
+ *   timing: 'lazy',
+ *   timeout: 200,
+ * });
+ *
+ * // Capabilities are negotiated on first access
+ * const caps = await negotiator.getCapabilities();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip negotiation, use environment detection only
+ * const negotiator = createCapabilityNegotiator({
+ *   timing: 'skip',
+ * });
+ *
+ * // Returns immediately with environment-detected capabilities
+ * const caps = await negotiator.getCapabilities();
+ * ```
+ */
+declare function createCapabilityNegotiator(config?: NegotiatorConfig): CapabilityNegotiator;
+/**
+ * Gets the default capability negotiator.
+ * Creates one with eager timing on first call.
+ *
+ * @returns Default CapabilityNegotiator instance
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultNegotiator } from 'blecsd';
+ *
+ * const caps = await getDefaultNegotiator().getCapabilities();
+ * ```
+ */
+declare function getDefaultNegotiator(): CapabilityNegotiator;
+/**
+ * Resets the default negotiator.
+ * For testing purposes.
+ */
+declare function resetDefaultNegotiator(): void;
+/**
+ * Gets terminal capabilities using the default negotiator.
+ *
+ * @returns Promise resolving to terminal capabilities
+ *
+ * @example
+ * ```typescript
+ * import { getTerminalCapabilities } from 'blecsd';
+ *
+ * const caps = await getTerminalCapabilities();
+ * console.log(`Truecolor: ${caps.truecolor}`);
+ * console.log(`Graphics: ${caps.graphics}`);
+ * ```
+ */
+declare function getTerminalCapabilities(): Promise<TerminalCapabilities>;
+/**
+ * Checks if a specific capability is supported.
+ *
+ * @param capability - Capability name to check
+ * @returns Promise resolving to true if supported
+ *
+ * @example
+ * ```typescript
+ * import { hasCapability } from 'blecsd';
+ *
+ * if (await hasCapability('truecolor')) {
+ *   // Use 24-bit colors
+ * }
+ * ```
+ */
+declare function hasCapability(capability: keyof TerminalCapabilities): Promise<boolean>;
+/**
+ * Query generators for capability detection.
+ * Use these to manually query the terminal.
+ */
+declare const capabilityQuery: {
+    /**
+     * Primary Device Attributes query.
+     */
+    readonly primaryDA: () => string;
+    /**
+     * Secondary Device Attributes query.
+     */
+    readonly secondaryDA: () => string;
+    /**
+     * XTVERSION query.
+     */
+    readonly xtversion: typeof queryXTVersion;
+    /**
+     * Kitty keyboard protocol query.
+     */
+    readonly kittyKeyboard: typeof queryKittyKeyboard;
+};
+
+/**
+ * Input stream handler for keyboard and mouse events.
+ * Wraps a NodeJS readable stream and emits typed events.
+ * @module terminal/inputStream
+ */
+
+/**
+ * Handler for keyboard events.
+ */
+type KeyHandler = (event: KeyEvent) => void;
+/**
+ * Handler for mouse events.
+ */
+type MouseHandler = (event: MouseEvent) => void;
+/**
+ * Handler for focus events.
+ */
+type FocusHandler = (event: FocusEvent) => void;
+/**
+ * Unsubscribe function returned by event handlers.
+ */
+type Unsubscribe = () => void;
+/**
+ * Configuration for the input handler.
+ */
+interface InputHandlerConfig {
+    /** Maximum buffer size in bytes before forcing a flush (default: 4096) */
+    maxBufferSize?: number;
+    /** Timeout in ms to wait for escape sequences to complete (default: 100) */
+    escapeTimeout?: number;
+}
+/**
+ * Zod schema for InputHandlerConfig validation.
+ *
+ * @example
+ * ```typescript
+ * import { InputHandlerConfigSchema } from 'blecsd';
+ *
+ * const result = InputHandlerConfigSchema.safeParse({ maxBufferSize: 8192 });
+ * if (result.success) {
+ *   console.log('Valid config');
+ * }
+ * ```
+ */
+declare const InputHandlerConfigSchema: z.ZodObject<{
+    maxBufferSize: z.ZodOptional<z.ZodNumber>;
+    escapeTimeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * InputHandler interface for type-safe access.
+ */
+interface InputHandler {
+    start(): void;
+    stop(): void;
+    onKey(handler: KeyHandler): Unsubscribe;
+    onMouse(handler: MouseHandler): Unsubscribe;
+    onFocus(handler: FocusHandler): Unsubscribe;
+    isRunning(): boolean;
+    getBufferSize(): number;
+}
+/**
+ * Creates a new input handler instance.
+ *
+ * Processes raw terminal input and emits typed keyboard and mouse events.
+ *
+ * @param stream - The readable stream to process (typically process.stdin)
+ * @param config - Optional configuration
+ * @returns A new InputHandler instance
+ *
+ * @example
+ * ```typescript
+ * import { createInputHandler } from 'blecsd';
+ *
+ * const handler = createInputHandler(process.stdin);
+ *
+ * handler.onKey((event) => {
+ *   console.log(`Key: ${event.name}, ctrl: ${event.ctrl}`);
+ *   if (event.name === 'q' && event.ctrl) {
+ *     handler.stop();
+ *   }
+ * });
+ *
+ * handler.onMouse((event) => {
+ *   console.log(`Mouse: ${event.action} at ${event.x}, ${event.y}`);
+ * });
+ *
+ * handler.start();
+ * ```
+ */
+declare function createInputHandler(stream: NodeJS.ReadableStream, config?: InputHandlerConfig): InputHandler;
+
+export { type SecondaryDAResponse as $, type DeviceStatusResponse as A, type GraphicsProtocolValue as B, CursorShape as C, DEFAULT_QUERY_TIMEOUT as D, type IconLabelResponse as E, type FocusHandler as F, GraphicsProtocol as G, type InputHandlerConfig as H, type InputHandler as I, InputHandlerConfigSchema as J, type KeyHandler as K, KittyKeyboardLevel as L, type MouseHandler as M, type KittyKeyboardLevelValue as N, type LocatorPositionResponse as O, MAX_QUERY_TIMEOUT as P, MIN_QUERY_TIMEOUT as Q, NegotiationTiming as R, type NegotiationTimingValue as S, type TerminalCapabilities as T, type NegotiatorConfig as U, NegotiatorConfigSchema as V, type ParsedResponse as W, type PrimaryDAResponse as X, ResponseType as Y, type ResponseTypeValue as Z, type ScreenSizeResponse as _, getTerminalCapabilities as a, type TerminalResponse as a0, type TextAreaSizeResponse as a1, type UnknownResponse as a2, type Unsubscribe as a3, type WindowPositionResponse as a4, type WindowSizePixelsResponse as a5, type WindowStateResponse as a6, type WindowTitleResponse as a7, capabilityQuery as a8, cursor as a9, query as aa, createInputHandler as b, createCapabilityNegotiator as c, isCursorPosition as d, isDeviceStatus as e, isIconLabel as f, getDefaultNegotiator as g, hasCapability as h, isCharCellSize as i, isLocatorPosition as j, isPrimaryDA as k, isScreenSize as l, isSecondaryDA as m, isTextAreaSize as n, isUnknown as o, isWindowPosition as p, isWindowSizePixels as q, resetDefaultNegotiator as r, isWindowState as s, isWindowTitle as t, parseResponse as u, type CapabilityNegotiator as v, type CharCellSizeResponse as w, type CursorPositionResponse as x, CursorPositionSchema as y, type CursorShapeType as z };