@zakmandhro/bunti 0.1.4 → 0.2.0

package/dist/input.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Bunti Input Tokenizer & Key Event Model
+ *
+ * A stateful tokenizer that turns raw stdin chunks into discrete input
+ * tokens. It handles the realities of terminal input that a naive
+ * chunk-per-key parser gets wrong:
+ *
+ * - Escape sequences split across stdin chunks (the tail is carried until
+ *   the sequence completes or the ESC-disambiguation timeout fires).
+ * - Multiple key/mouse events packed into a single chunk (each one becomes
+ *   its own token, including every SGR mouse event in the chunk).
+ * - CSI modifier parameters (xterm encoding: 2=shift 3=alt 5=ctrl ...),
+ *   SS3 sequences, navigation keys, ctrl bytes (\x01-\x1a), and
+ *   alt-prefixed ESC+char.
+ * - Terminal RESPONSES (cursor position reports, DA1/DA2, DECRQM, DCS
+ *   replies like XTVERSION) are routed to a separate response channel and
+ *   never enter the key stream — capability-detection probes depend on this.
+ * - Printable text is segmented per grapheme (Intl.Segmenter), so emoji
+ *   arrive as whole key events.
+ *
+ * The KeyEvent shape below is FROZEN for launch. Post-launch protocol work
+ * (kitty keyboard protocol, bracketed paste) must slot into this shape
+ * without breaking it:
+ * - `kind: 'release'` is currently only synthesized by the HeldKeyTracker
+ *   when a held key's repeat stream expires (legacy terminals never report
+ *   releases). The kitty protocol will later produce real release events.
+ * - `kind: 'repeat'` is classified by the HeldKeyTracker heuristic, not by
+ *   the terminal.
+ */
+/** Frozen key event shape. See module docs for the evolution contract. */
+export interface KeyEvent {
+    /**
+     * Normalized key name. Printable keys are the literal grapheme
+     * ('a', 'A', ' ', 'é', emoji); specials are lowercase names ('up',
+     * 'enter', 'escape', 'tab', 'backspace', 'f1'..'f12'); mouse events
+     * arrive as 'click' / 'wheel_up' / 'wheel_down'.
+     */
+    key: string;
+    /**
+     * 'press' on first arrival, 'repeat' while auto-repeating within the
+     * hold window, 'release' when a held key's repeat stream expires
+     * (synthesized — legacy terminals report no real releases).
+     */
+    kind: 'press' | 'repeat' | 'release';
+    /** Ctrl was held (e.g. ctrl+a arrives as { key: 'a', ctrl: true }). */
+    ctrl: boolean;
+    /** Alt/meta was held (ESC-prefixed input). */
+    alt: boolean;
+    /** Shift was held (CSI-modifier encoded; plain 'A' stays shift: false). */
+    shift: boolean;
+    /** The raw byte sequence that produced this event ('' for synthesized). */
+    raw: string;
+}
+export type TerminalResponseKind = 'cursor-position' | 'device-attributes' | 'device-attributes-secondary' | 'mode-report' | 'terminal-version' | 'osc' | 'unknown';
+/**
+ * A reply from the terminal to a capability/status probe. These are routed
+ * to `state.terminalResponses` (consumers drain the array) and NEVER into
+ * the key queue.
+ */
+export interface TerminalResponse {
+    kind: TerminalResponseKind;
+    raw: string;
+    /** Parsed cursor row (1-based), cursor-position responses only. */
+    row?: number;
+    /** Parsed cursor column (1-based), cursor-position responses only. */
+    col?: number;
+}
+/** A discrete unit of parsed input. */
+export type InputToken = {
+    type: 'key';
+    event: KeyEvent;
+}
+/** SGR mouse report. x/y are the raw 1-based protocol coordinates.
+ *  action mirrors the final byte: 'M' = press/motion/wheel, 'm' = release.
+ *  Wheel and motion states are encoded in the button bits (64 / 32). */
+ | {
+    type: 'mouse';
+    button: number;
+    x: number;
+    y: number;
+    action: 'press' | 'release';
+    raw: string;
+} | {
+    type: 'focus';
+    focused: boolean;
+    raw: string;
+} | {
+    type: 'response';
+    response: TerminalResponse;
+};
+export interface InputTokenizerOptions {
+    /** How long a bare ESC waits for a follow-up before flushing as the
+     *  'escape' key. Default 30ms. */
+    escTimeoutMs?: number;
+    /** Called with tokens produced by the ESC-disambiguation timer. */
+    onFlush?: (tokens: InputToken[]) => void;
+    /** Injectable timer for tests. Defaults to setTimeout. */
+    schedule?: (callback: () => void, ms: number) => unknown;
+    /** Injectable timer cancel for tests. Defaults to clearTimeout. */
+    cancel?: (handle: unknown) => void;
+}
+/** Creates a KeyEvent with press semantics and explicit defaults. */
+export declare function createKeyEvent(key: string, raw?: string, mods?: Partial<Pick<KeyEvent, 'ctrl' | 'alt' | 'shift' | 'kind'>>): KeyEvent;
+/**
+ * Stateful input tokenizer. Feed it stdin chunks via push(); it returns the
+ * tokens completed by that chunk and carries any trailing partial escape
+ * sequence into the next call. A bare ESC (or unfinished sequence) is only
+ * flushed as the 'escape' key after `escTimeoutMs` with no follow-up bytes
+ * (tokens produced that way arrive via `onFlush`).
+ */
+export declare class InputTokenizer {
+    private options;
+    private pending;
+    private timer;
+    onFlush?: (tokens: InputToken[]) => void;
+    constructor(options?: InputTokenizerOptions);
+    /** Parses a chunk. Returns completed tokens; partial tails are carried. */
+    push(chunk: string): InputToken[];
+    /** True if a partial sequence is being carried. */
+    hasPending(): boolean;
+    /**
+     * Force-resolves the carried partial sequence (what the ESC timer does):
+     * a bare ESC becomes the 'escape' key; a partial DCS/OSC becomes a
+     * response; anything else becomes 'escape' plus its remainder as text.
+     */
+    flushPending(): InputToken[];
+    /** Cancels the ESC-disambiguation timer (loop teardown). */
+    dispose(): void;
+    private scheduleTimer;
+    private cancelTimer;
+    private parse;
+    /**
+     * Parses one escape sequence starting at buffer[i] (=== ESC).
+     * Returns the number of chars consumed, or -1 if incomplete.
+     */
+    private parseEscape;
+    /**
+     * Parses a CSI sequence starting at buffer[i] (=== ESC, buffer[i+1] === '[').
+     * Returns chars consumed or -1 if the final byte hasn't arrived yet.
+     */
+    private parseCsi;
+    /** Tokenizes a run of non-ESC text: control bytes + printable graphemes. */
+    private tokenizeText;
+}
+export interface HeldKeyOptions {
+    /** A key is considered held until this long passes without a repeat.
+     *  Default 150ms. */
+    holdWindowMs?: number;
+    /** Injectable clock for tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Held-key heuristic for legacy terminals (which report no key releases):
+ * a key is "held" from its first press until no repeat arrives within the
+ * hold window. On expiry a synthetic kind:'release' KeyEvent is emitted.
+ * Good enough for platformer-style movement pre-kitty-protocol.
+ */
+export declare class HeldKeyTracker {
+    private options;
+    private held;
+    constructor(options?: HeldKeyOptions);
+    private get window();
+    private now;
+    /**
+     * Records a press-stream event and classifies it: a key seen again within
+     * the hold window becomes kind:'repeat'. Release events pass through.
+     */
+    record(event: KeyEvent): KeyEvent;
+    /** True while the key's repeat stream is inside the hold window. */
+    isHeld(key: string): boolean;
+    /**
+     * Expires held keys whose repeat stream went silent and synthesizes a
+     * kind:'release' KeyEvent for each (raw '' — there were no real bytes).
+     */
+    collectReleases(): KeyEvent[];
+}
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

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