blecsd 0.1.0

package/dist/keyParser-Bwm8-l7v.d.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+
+/**
+ * Key event parser for ANSI escape sequences.
+ * Rewrite of blessed keys.js with strict typing.
+ * @module terminal/keyParser
+ */
+
+/**
+ * All recognized key names.
+ * Includes letters, numbers, function keys, and navigation keys.
+ */
+type KeyName = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'f1' | 'f2' | 'f3' | 'f4' | 'f5' | 'f6' | 'f7' | 'f8' | 'f9' | 'f10' | 'f11' | 'f12' | 'up' | 'down' | 'left' | 'right' | 'home' | 'end' | 'pageup' | 'pagedown' | 'insert' | 'delete' | 'clear' | 'return' | 'enter' | 'tab' | 'backspace' | 'escape' | 'space' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '-' | '_' | '=' | '+' | '[' | ']' | '{' | '}' | '\\' | '|' | ';' | ':' | "'" | '"' | ',' | '.' | '<' | '>' | '/' | '?' | '`' | '~' | 'undefined';
+/**
+ * Parsed keyboard event with modifiers.
+ *
+ * @example
+ * ```typescript
+ * import { parseKeySequence, KeyEvent } from 'blecsd';
+ *
+ * const event = parseKeySequence(Buffer.from([0x1b, 0x5b, 0x41]));
+ * if (event) {
+ *   console.log(event.name); // 'up'
+ *   console.log(event.ctrl); // false
+ * }
+ * ```
+ */
+interface KeyEvent {
+    /** The raw sequence string that generated this event */
+    readonly sequence: string;
+    /** Normalized key name */
+    readonly name: KeyName;
+    /** Ctrl modifier was pressed */
+    readonly ctrl: boolean;
+    /** Alt/Meta modifier was pressed */
+    readonly meta: boolean;
+    /** Shift modifier was pressed */
+    readonly shift: boolean;
+    /** Terminal-specific escape code (if applicable) */
+    readonly code?: string;
+    /** Raw buffer data */
+    readonly raw: Uint8Array;
+}
+/**
+ * Zod schema for KeyEvent validation.
+ *
+ * @example
+ * ```typescript
+ * import { KeyEventSchema } from 'blecsd';
+ *
+ * const result = KeyEventSchema.safeParse(event);
+ * if (result.success) {
+ *   console.log('Valid key event');
+ * }
+ * ```
+ */
+declare const KeyEventSchema: z.ZodObject<{
+    sequence: z.ZodString;
+    name: z.ZodEnum<{
+        undefined: "undefined";
+        x: "x";
+        y: "y";
+        r: "r";
+        g: "g";
+        b: "b";
+        a: "a";
+        0: "0";
+        1: "1";
+        2: "2";
+        3: "3";
+        4: "4";
+        escape: "escape";
+        5: "5";
+        6: "6";
+        7: "7";
+        "!": "!";
+        "#": "#";
+        ";": ";";
+        $: "$";
+        "-": "-";
+        left: "left";
+        z: "z";
+        "/": "/";
+        v: "v";
+        f: "f";
+        o: "o";
+        right: "right";
+        up: "up";
+        down: "down";
+        return: "return";
+        enter: "enter";
+        space: "space";
+        "*": "*";
+        end: "end";
+        insert: "insert";
+        delete: "delete";
+        home: "home";
+        backspace: "backspace";
+        tab: "tab";
+        k: "k";
+        j: "j";
+        pageup: "pageup";
+        pagedown: "pagedown";
+        "|": "|";
+        "\\": "\\";
+        8: "8";
+        9: "9";
+        "[": "[";
+        "]": "]";
+        c: "c";
+        m: "m";
+        h: "h";
+        l: "l";
+        s: "s";
+        u: "u";
+        "?": "?";
+        ",": ",";
+        "%": "%";
+        d: "d";
+        e: "e";
+        i: "i";
+        n: "n";
+        p: "p";
+        q: "q";
+        t: "t";
+        w: "w";
+        f1: "f1";
+        f2: "f2";
+        f3: "f3";
+        f4: "f4";
+        f5: "f5";
+        f6: "f6";
+        f7: "f7";
+        f8: "f8";
+        f9: "f9";
+        f10: "f10";
+        f11: "f11";
+        f12: "f12";
+        clear: "clear";
+        "@": "@";
+        "^": "^";
+        "&": "&";
+        "(": "(";
+        ")": ")";
+        _: "_";
+        "=": "=";
+        "+": "+";
+        "{": "{";
+        "}": "}";
+        ":": ":";
+        "'": "'";
+        "\"": "\"";
+        ".": ".";
+        "<": "<";
+        ">": ">";
+        "`": "`";
+        "~": "~";
+    }>;
+    ctrl: z.ZodBoolean;
+    meta: z.ZodBoolean;
+    shift: z.ZodBoolean;
+    code: z.ZodOptional<z.ZodString>;
+    raw: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+/**
+ * Check if a buffer starts with a mouse sequence.
+ * Mouse sequences are handled separately by the mouse parser.
+ *
+ * @param buffer - Input buffer to check
+ * @returns true if buffer contains a mouse sequence
+ *
+ * @internal
+ */
+declare function isMouseSequence(buffer: Uint8Array): boolean;
+/**
+ * Parse a key sequence from a buffer.
+ *
+ * Handles:
+ * - Regular characters (a-z, A-Z, 0-9)
+ * - Control characters (Ctrl+A through Ctrl+Z)
+ * - Function keys (F1-F12)
+ * - Navigation keys (arrows, home, end, pageup, pagedown)
+ * - Modifier combinations (shift, ctrl, alt/meta)
+ * - Special keys (escape, enter, tab, backspace, space)
+ *
+ * @param buffer - Raw input buffer to parse
+ * @returns Parsed KeyEvent or null if not a key sequence
+ *
+ * @example
+ * ```typescript
+ * import { parseKeySequence } from 'blecsd';
+ *
+ * // Parse Ctrl+C
+ * const ctrlC = parseKeySequence(Buffer.from([0x03]));
+ * console.log(ctrlC?.name); // 'c'
+ * console.log(ctrlC?.ctrl); // true
+ *
+ * // Parse Up arrow
+ * const up = parseKeySequence(Buffer.from([0x1b, 0x5b, 0x41]));
+ * console.log(up?.name); // 'up'
+ *
+ * // Parse F1
+ * const f1 = parseKeySequence(Buffer.from([0x1b, 0x4f, 0x50]));
+ * console.log(f1?.name); // 'f1'
+ * ```
+ */
+declare function parseKeySequence(buffer: Uint8Array): KeyEvent | null;
+/**
+ * Parse multiple key sequences from a buffer.
+ * Handles cases where multiple keypresses arrive in a single read.
+ *
+ * @param buffer - Raw input buffer that may contain multiple key sequences
+ * @returns Array of parsed KeyEvents
+ *
+ * @example
+ * ```typescript
+ * import { parseKeyBuffer } from 'blecsd';
+ *
+ * // Parse buffer with multiple characters
+ * const events = parseKeyBuffer(Buffer.from('abc'));
+ * console.log(events.length); // 3
+ * console.log(events[0].name); // 'a'
+ * console.log(events[1].name); // 'b'
+ * console.log(events[2].name); // 'c'
+ * ```
+ */
+declare function parseKeyBuffer(buffer: Uint8Array): readonly KeyEvent[];
+
+export { type KeyName as K, KeyEventSchema as a, type KeyEvent as b, parseKeySequence as c, isMouseSequence as i, parseKeyBuffer as p };

package/dist/mouseParser-Cfrbn3AX.d.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+
+/**
+ * Mouse event parser for terminal mouse protocols.
+ * Supports X10, SGR, URXVT, DEC, and VT300 protocols.
+ * @module terminal/mouseParser
+ */
+
+/**
+ * Mouse button identifiers.
+ */
+type MouseButton = 'left' | 'middle' | 'right' | 'wheelUp' | 'wheelDown' | 'unknown';
+/**
+ * Mouse action types.
+ */
+type MouseAction = 'press' | 'release' | 'move' | 'wheel';
+/**
+ * Mouse protocol types.
+ */
+type MouseProtocol = 'x10' | 'sgr' | 'urxvt' | 'dec' | 'vt300';
+/**
+ * Parsed mouse event with position and modifiers.
+ *
+ * @example
+ * ```typescript
+ * import { parseMouseSequence, MouseEvent } from 'blecsd';
+ *
+ * const event = parseMouseSequence(Buffer.from('\x1b[<0;10;20M'));
+ * if (event) {
+ *   console.log(event.x);      // 10
+ *   console.log(event.y);      // 20
+ *   console.log(event.button); // 'left'
+ *   console.log(event.action); // 'press'
+ * }
+ * ```
+ */
+interface MouseEvent {
+    /** X coordinate (0-indexed) */
+    readonly x: number;
+    /** Y coordinate (0-indexed) */
+    readonly y: number;
+    /** Mouse button */
+    readonly button: MouseButton;
+    /** Action type */
+    readonly action: MouseAction;
+    /** Ctrl modifier was pressed */
+    readonly ctrl: boolean;
+    /** Alt/Meta modifier was pressed */
+    readonly meta: boolean;
+    /** Shift modifier was pressed */
+    readonly shift: boolean;
+    /** Protocol used to encode this event */
+    readonly protocol: MouseProtocol;
+    /** Raw buffer data */
+    readonly raw: Uint8Array;
+}
+/**
+ * Zod schema for MouseEvent validation.
+ *
+ * @example
+ * ```typescript
+ * import { MouseEventSchema } from 'blecsd';
+ *
+ * const result = MouseEventSchema.safeParse(event);
+ * if (result.success) {
+ *   console.log('Valid mouse event');
+ * }
+ * ```
+ */
+declare const MouseEventSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    button: z.ZodEnum<{
+        unknown: "unknown";
+        left: "left";
+        right: "right";
+        middle: "middle";
+        wheelUp: "wheelUp";
+        wheelDown: "wheelDown";
+    }>;
+    action: z.ZodEnum<{
+        press: "press";
+        release: "release";
+        move: "move";
+        wheel: "wheel";
+    }>;
+    ctrl: z.ZodBoolean;
+    meta: z.ZodBoolean;
+    shift: z.ZodBoolean;
+    protocol: z.ZodEnum<{
+        x10: "x10";
+        sgr: "sgr";
+        urxvt: "urxvt";
+        dec: "dec";
+        vt300: "vt300";
+    }>;
+    raw: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+/**
+ * Focus event result (not a full mouse event).
+ */
+interface FocusEvent {
+    /** Whether the terminal gained or lost focus */
+    readonly focused: boolean;
+    /** Raw buffer data */
+    readonly raw: Uint8Array;
+}
+/**
+ * Zod schema for FocusEvent validation.
+ */
+declare const FocusEventSchema: z.ZodObject<{
+    focused: z.ZodBoolean;
+    raw: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+/**
+ * Result of parsing a mouse/focus sequence.
+ */
+type ParseMouseResult = {
+    type: 'mouse';
+    event: MouseEvent;
+} | {
+    type: 'focus';
+    event: FocusEvent;
+} | null;
+/**
+ * Parse a mouse or focus sequence from a buffer.
+ *
+ * Supports multiple mouse protocols:
+ * - X10/X11: Basic mouse reporting (ESC [ M ...)
+ * - SGR: Extended mouse reporting with release info (ESC [ < ...)
+ * - URXVT: rxvt-unicode mouse format (ESC [ ... M)
+ * - DEC: DEC locator format (ESC [ < ... & w)
+ * - VT300: VT300 locator format (ESC [ 24X ~ ...)
+ *
+ * Also handles terminal focus events (ESC [ I/O).
+ *
+ * @param buffer - Raw input buffer to parse
+ * @returns Parsed result or null if not a mouse sequence
+ *
+ * @example
+ * ```typescript
+ * import { parseMouseSequence } from 'blecsd';
+ *
+ * // Parse SGR mouse press at (10, 20)
+ * const result = parseMouseSequence(Buffer.from('\x1b[<0;10;20M'));
+ * if (result?.type === 'mouse') {
+ *   console.log(result.event.x);      // 9 (0-indexed)
+ *   console.log(result.event.y);      // 19 (0-indexed)
+ *   console.log(result.event.button); // 'left'
+ *   console.log(result.event.action); // 'press'
+ * }
+ *
+ * // Parse focus event
+ * const focus = parseMouseSequence(Buffer.from('\x1b[I'));
+ * if (focus?.type === 'focus') {
+ *   console.log(focus.event.focused); // true
+ * }
+ * ```
+ */
+declare function parseMouseSequence(buffer: Uint8Array): ParseMouseResult;
+/**
+ * Check if a buffer contains a mouse sequence.
+ *
+ * @param buffer - Input buffer to check
+ * @returns true if buffer contains a mouse sequence
+ *
+ * @example
+ * ```typescript
+ * import { isMouseBuffer } from 'blecsd';
+ *
+ * const buffer = Buffer.from('\x1b[<0;10;20M');
+ * console.log(isMouseBuffer(buffer)); // true
+ * ```
+ */
+declare function isMouseBuffer(buffer: Uint8Array): boolean;
+
+export { type FocusEvent as F, type MouseEvent as M, type ParseMouseResult as P, FocusEventSchema as a, type MouseAction as b, type MouseButton as c, MouseEventSchema as d, type MouseProtocol as e, isMouseBuffer as i, parseMouseSequence as p };

package/dist/parser-iMHmQuUh.d.ts

@@ -0,0 +1,265 @@
+import { z } from 'zod';
+
+/**
+ * ANSI SGR Attribute Code Parser
+ *
+ * Parses ANSI SGR (Select Graphic Rendition) codes from escape sequences
+ * and converts them to internal attribute representations.
+ *
+ * @module terminal/ansi/parser
+ * @internal This module is internal and not exported from the main package.
+ */
+
+/**
+ * Text style flags packed as a bitmask.
+ */
+declare const TextStyle: {
+    readonly NONE: 0;
+    readonly BOLD: number;
+    readonly DIM: number;
+    readonly ITALIC: number;
+    readonly UNDERLINE: number;
+    readonly BLINK: number;
+    readonly RAPID_BLINK: number;
+    readonly INVERSE: number;
+    readonly HIDDEN: number;
+    readonly STRIKETHROUGH: number;
+    readonly DOUBLE_UNDERLINE: number;
+    readonly OVERLINE: number;
+};
+/**
+ * Color type enum for internal representation.
+ */
+declare const ColorType: {
+    readonly DEFAULT: 0;
+    readonly BASIC: 1;
+    readonly COLOR_256: 2;
+    readonly RGB: 3;
+};
+type ColorTypeValue = (typeof ColorType)[keyof typeof ColorType];
+/**
+ * Internal color representation.
+ */
+interface InternalColor {
+    type: ColorTypeValue;
+    /** For BASIC: 0-15, for COLOR_256: 0-255, for RGB: packed as 0xRRGGBB */
+    value: number;
+}
+/**
+ * Terminal attribute representation.
+ */
+interface Attribute {
+    /** Foreground color */
+    fg: InternalColor;
+    /** Background color */
+    bg: InternalColor;
+    /** Style flags bitmask */
+    styles: number;
+}
+/**
+ * Zod schema for Attribute validation.
+ */
+declare const AttributeSchema: z.ZodObject<{
+    fg: z.ZodObject<{
+        type: z.ZodNumber;
+        value: z.ZodNumber;
+    }, z.core.$strip>;
+    bg: z.ZodObject<{
+        type: z.ZodNumber;
+        value: z.ZodNumber;
+    }, z.core.$strip>;
+    styles: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Default attribute (reset state).
+ */
+declare const DEFAULT_ATTRIBUTE: Readonly<Attribute>;
+/**
+ * Create a new attribute with default values.
+ *
+ * @returns New attribute object
+ *
+ * @example
+ * ```typescript
+ * const attr = createAttribute();
+ * // attr.fg.type === ColorType.DEFAULT
+ * ```
+ */
+declare function createAttribute(): Attribute;
+/**
+ * Clone an attribute.
+ *
+ * @param attr - Attribute to clone
+ * @returns New attribute object
+ */
+declare function cloneAttribute(attr: Attribute): Attribute;
+/**
+ * Extract SGR code sequences from a string.
+ *
+ * @param input - String containing ANSI sequences
+ * @returns Array of SGR code arrays
+ *
+ * @example
+ * ```typescript
+ * const codes = extractSgrCodes('\x1b[1;31m');
+ * // codes = [[1, 31]]
+ * ```
+ */
+declare function extractSgrCodes(input: string): number[][];
+/**
+ * Apply a sequence of SGR codes to an attribute.
+ *
+ * @param codes - Array of SGR code numbers
+ * @param attr - Attribute to modify (mutated in place)
+ *
+ * @example
+ * ```typescript
+ * const attr = createAttribute();
+ * applySgrCodes([1, 31], attr);
+ * // attr now has bold style and red foreground
+ * ```
+ */
+declare function applySgrCodes(codes: readonly number[], attr: Attribute): void;
+declare function parseSgrString(input: string, attr: Attribute): void;
+/**
+ * Apply a single SGR code to an attribute, returning a new attribute.
+ * This is the main entry point for processing individual codes.
+ *
+ * @param code - SGR code number or array of codes
+ * @param attr - Current attribute
+ * @param defaultAttr - Default attribute to reset to (default: DEFAULT_ATTRIBUTE)
+ * @returns New attribute with code applied
+ *
+ * @example
+ * ```typescript
+ * const attr = createAttribute();
+ * const newAttr = attrCode(1, attr); // Apply bold
+ * const redAttr = attrCode([31], newAttr); // Apply red
+ * ```
+ */
+declare function attrCode(code: number | readonly number[], attr: Attribute, defaultAttr?: Attribute): Attribute;
+/**
+ * Color depth for output.
+ */
+type OutputColorDepth = 'truecolor' | '256' | '16' | 'none';
+/**
+ * Options for codeAttr.
+ */
+interface CodeAttrOptions {
+    /** Maximum color depth to output. Defaults to 'truecolor'. */
+    colorDepth?: OutputColorDepth;
+    /** Include reset code at start. Defaults to false. */
+    includeReset?: boolean;
+}
+/**
+ * Convert an attribute to an SGR escape sequence string.
+ *
+ * This is the reverse of attrCode() - it takes an internal Attribute
+ * and converts it to an ANSI escape sequence that will produce that attribute.
+ *
+ * @param attr - Attribute to convert
+ * @param options - Conversion options
+ * @returns SGR escape sequence string
+ *
+ * @example
+ * ```typescript
+ * import { codeAttr, createAttribute, attrCode, TextStyle } from 'blecsd';
+ *
+ * // Create a bold red attribute
+ * let attr = createAttribute();
+ * attr = attrCode([1, 31], attr);
+ *
+ * // Convert to SGR string
+ * const sgr = codeAttr(attr);
+ * // sgr = '\x1b[1;31m'
+ *
+ * // With color depth reduction
+ * const sgrReduced = codeAttr(attr, { colorDepth: '16' });
+ * ```
+ */
+declare function codeAttr(attr: Attribute, options?: CodeAttrOptions): string;
+/**
+ * Convert an attribute to SGR codes array.
+ *
+ * @param attr - Attribute to convert
+ * @param options - Conversion options
+ * @returns Array of SGR code numbers
+ *
+ * @example
+ * ```typescript
+ * const codes = attrToSgrCodes(attr);
+ * // [1, 31] for bold red
+ * ```
+ */
+declare function attrToSgrCodes(attr: Attribute, options?: CodeAttrOptions): number[];
+/**
+ * Get the SGR reset sequence.
+ *
+ * @returns Reset SGR sequence
+ */
+declare function sgrReset(): string;
+/**
+ * Check if an attribute has a specific style.
+ *
+ * @param attr - Attribute to check
+ * @param style - Style flag from TextStyle
+ * @returns true if style is set
+ *
+ * @example
+ * ```typescript
+ * const attr = attrCode(1, createAttribute()); // bold
+ * hasStyle(attr, TextStyle.BOLD); // true
+ * hasStyle(attr, TextStyle.ITALIC); // false
+ * ```
+ */
+declare function hasStyle(attr: Attribute, style: number): boolean;
+/**
+ * Check if two attributes are equal.
+ *
+ * @param a - First attribute
+ * @param b - Second attribute
+ * @returns true if attributes are equal
+ */
+declare function attributesEqual(a: Attribute, b: Attribute): boolean;
+/**
+ * Unpack RGB value to components.
+ *
+ * @param packed - Packed RGB value (0xRRGGBB)
+ * @returns RGB components
+ */
+declare function unpackRgb(packed: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Pack RGB components into a single value.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Packed RGB value
+ */
+declare function packRgb(r: number, g: number, b: number): number;
+/**
+ * Strip all ANSI escape sequences from a string.
+ *
+ * @param input - String with ANSI sequences
+ * @returns String without ANSI sequences
+ *
+ * @example
+ * ```typescript
+ * stripAnsi('\x1b[1;31mHello\x1b[0m');
+ * // 'Hello'
+ * ```
+ */
+declare function stripAnsi(input: string): string;
+/**
+ * Get the visible length of a string (excluding ANSI sequences).
+ *
+ * @param input - String with possible ANSI sequences
+ * @returns Length of visible characters
+ */
+declare function visibleLength(input: string): number;
+
+export { type Attribute as A, type CodeAttrOptions as C, DEFAULT_ATTRIBUTE as D, type InternalColor as I, type OutputColorDepth as O, TextStyle as T, AttributeSchema as a, ColorType as b, applySgrCodes as c, attrCode as d, attrToSgrCodes as e, attributesEqual as f, cloneAttribute as g, codeAttr as h, createAttribute as i, extractSgrCodes as j, hasStyle as k, parseSgrString as l, stripAnsi as m, packRgb as p, sgrReset as s, unpackRgb as u, visibleLength as v };