@askdkc/dsh-cli 0.11.3

package/lib/types/ink/parse-keypress.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Keyboard input parser - converts terminal input to key events
+ *
+ * Uses the termio tokenizer for escape sequence boundary detection,
+ * then interprets sequences as keypresses.
+ */
+import { Buffer } from 'buffer';
+import { type Tokenizer } from './termio/tokenize.js';
+/** DECRPM status values (response to DECRQM) */
+export declare const DECRPM_STATUS: {
+    readonly NOT_RECOGNIZED: 0;
+    readonly SET: 1;
+    readonly RESET: 2;
+    readonly PERMANENTLY_SET: 3;
+    readonly PERMANENTLY_RESET: 4;
+};
+/**
+ * A response sequence received from the terminal (not a keypress).
+ * Emitted in answer to queries like DECRQM, DA1, OSC 11, etc.
+ */
+export type TerminalResponse = 
+/** DECRPM: answer to DECRQM (request DEC private mode status) */
+{
+    type: 'decrpm';
+    mode: number;
+    status: number;
+}
+/** DA1: primary device attributes (used as a universal sentinel) */
+ | {
+    type: 'da1';
+    params: number[];
+}
+/** DA2: secondary device attributes (terminal version info) */
+ | {
+    type: 'da2';
+    params: number[];
+}
+/** Kitty keyboard protocol: current flags (answer to CSI ? u) */
+ | {
+    type: 'kittyKeyboard';
+    flags: number;
+}
+/** Kitty graphics protocol response to an a=q capability query. */
+ | {
+    type: 'kittyGraphics';
+    imageId: number;
+    status: string;
+}
+/** DSR: cursor position report (answer to CSI 6 n) */
+ | {
+    type: 'cursorPosition';
+    row: number;
+    col: number;
+}
+/** XTWINOPS: physical pixels for one cell or the terminal text area. */
+ | {
+    type: 'terminalPixelSize';
+    scope: 'cell' | 'window';
+    height: number;
+    width: number;
+}
+/** OSC response: generic operating-system-command reply (e.g. OSC 11 bg color) */
+ | {
+    type: 'osc';
+    code: number;
+    data: string;
+}
+/** XTVERSION: terminal name/version string (answer to CSI > 0 q).
+ *  Example values: "xterm.js(5.5.0)", "ghostty 1.2.0", "iTerm2 3.6". */
+ | {
+    type: 'xtversion';
+    name: string;
+};
+/** Mutable cross-call state for the decomposed-paste matcher. */
+export type Win32PasteState = {
+    /** true between the decomposed start and end markers */
+    active: boolean;
+    /** progress into the marker pattern currently being matched */
+    matched: number;
+    /** keys held while a marker prefix match is in flight */
+    held: ParsedKey[];
+    /** collected paste content while active */
+    buffer: string;
+};
+export type Win32ProtocolState = {
+    held: ParsedKey[];
+    sequence: string;
+};
+/**
+ * Parser state carried between parseMultipleKeypresses calls: paste mode,
+ * buffered incomplete input, and the internal tokenizer instance.
+ */
+export type KeyParseState = {
+    mode: 'NORMAL' | 'IN_PASTE';
+    incomplete: string;
+    pasteBuffer: string;
+    /**
+     * Pending high surrogate from a win32-input-mode record. Uc is a UTF-16
+     * code unit, so supplementary-plane characters (emoji, CJK ext-B) arrive
+     * as two consecutive records; the high half waits here for its low half.
+     */
+    win32HighSurrogate?: number;
+    /**
+     * Pending high surrogate for the Alt+numpad synthesis path — separate
+     * from win32HighSurrogate because the two Alt rounds of one supplementary
+     * char interleave with keydown records (Alt-down, numpad digits) that
+     * would settle the regular slot before the low half arrives.
+     */
+    win32AltHighSurrogate?: number;
+    /**
+     * Decomposed bracketed-paste tracking for win32-input-mode. Classic
+     * conhost synthesizes pastes as per-char KEY_EVENT_RECORDs — including
+     * the ESC[200~ / ESC[201~ markers themselves — so under W32IM the markers
+     * arrive as ordinary key records and must be reassembled here (issue #147).
+     */
+    win32Paste?: Win32PasteState;
+    /**
+     * Terminal CSI bytes synthesized by classic conhost as one win32 input
+     * record per character. Only Vk=0/Sc=0 records enter this matcher, keeping
+     * physically typed text out of the protocol path.
+     */
+    win32Protocol?: Win32ProtocolState;
+    /**
+     * Pending prefix of an SGR mouse report that fragmented mid-sequence
+     * (ConPTY split a report across reads and App's escape timer flushed the
+     * buffered ESC prefix). Holds at most one incomplete `[<btn;col;row` tail;
+     * the next chunk completes it (resynthesis) or it is discarded — typed
+     * `[`-led text never matches the guard pattern and passes through.
+     * A hold never survives evidence that its report died: report bytes are
+     * contiguous on the wire, so a fresh ESC sequence, a complete mouse
+     * report, or text that cannot continue the pattern all discard it.
+     */
+    mouseTailHold?: string;
+    /**
+     * Date.now() of the FIRST capture of the current mouseTailHold. The hold
+     * is discarded once this age exceeds MOUSE_TAIL_HOLD_GRACE_MS — checked at
+     * the top of EVERY parse call, not only on flush: continuous input keeps
+     * re-arming App's 50ms flush timer, so a flush-only check may never run
+     * while the user types. Surviving a single quiet flush is not enough
+     * either (the sentinel re-arms the timer, so the next quiet flush would
+     * otherwise kill a slow split).
+     */
+    mouseTailHoldAt?: number;
+    _tokenizer?: Tokenizer;
+};
+/** Initial `KeyParseState` for a fresh parser. */
+export declare const INITIAL_STATE: KeyParseState;
+/**
+ * Tokenize and parse a chunk of terminal input into parsed keys, mouse
+ * events, and terminal responses, maintaining paste-mode state.
+ * @param prevState - the state returned by the previous call, or INITIAL_STATE.
+ * @param input - the input chunk; null flushes the tokenizer's pending input.
+ * @returns the parsed inputs plus the state to pass to the next call.
+ */
+export declare function parseMultipleKeypresses(prevState: KeyParseState, input?: Buffer | string | null): [ParsedInput[], KeyParseState];
+/**
+ * Key names that never produce printable input (function keys, navigation,
+ * modifiers, mouse), used to filter parsed keypresses.
+ */
+export declare const nonAlphanumericKeys: string[];
+/**
+ * A parsed user keypress or paste: the key name, modifier flags, the raw
+ * escape sequence, and whether the input arrived via bracketed paste.
+ */
+export type ParsedKey = {
+    kind: 'key';
+    fn: boolean;
+    name: string | undefined;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    option: boolean;
+    super: boolean;
+    sequence: string | undefined;
+    raw: string | undefined;
+    code?: string;
+    isPasted: boolean;
+    /**
+     * Pointer column (0-indexed) for wheel keys — SGR/X10 wheel sequences
+     * carry the position the wheel event occurred at. Undefined for
+     * non-wheel keys.
+     */
+    mouseCol?: number;
+    /** Pointer row (0-indexed) for wheel keys. See mouseCol. */
+    mouseRow?: number;
+    /** Raw SGR/X10 button byte for wheel modifiers and direction. */
+    mouseButton?: number;
+};
+/** A terminal response sequence (DECRPM, DA1, OSC reply, etc.) parsed
+ *  out of the input stream. Not user input — consumers should dispatch
+ *  to a response handler. */
+export type ParsedResponse = {
+    kind: 'response';
+    /** Raw escape sequence bytes, for debugging/logging */
+    sequence: string;
+    response: TerminalResponse;
+};
+/** SGR mouse event with coordinates. Emitted for clicks, drags, and
+ *  releases (wheel events remain ParsedKey). col/row are 1-indexed
+ *  from the terminal sequence (CSI < btn;col;row M/m). */
+export type ParsedMouse = {
+    kind: 'mouse';
+    /** Raw SGR button code. Low 2 bits = button (0=left,1=mid,2=right),
+     *  bit 5 (0x20) = drag/motion, bit 6 (0x40) = wheel. */
+    button: number;
+    /** 'press' for M terminator, 'release' for m terminator */
+    action: 'press' | 'release';
+    /** 1-indexed column (from terminal) */
+    col: number;
+    /** 1-indexed row (from terminal) */
+    row: number;
+    sequence: string;
+};
+/** Everything that can come out of the input parser: a user keypress/paste,
+ *  a mouse click/drag event, or a terminal response to a query we sent. */
+export type ParsedInput = ParsedKey | ParsedMouse | ParsedResponse;
+//# sourceMappingURL=parse-keypress.d.ts.map

package/lib/types/ink/parse-keypress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-keypress.d.ts","sourceRoot":"","sources":["../../../src/ink/parse-keypress.ts"],"names":[],"mappings":"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"}