@openadapter/koda-tui 1.0.0-beta.3

package/dist/keys.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Keyboard input handling for terminal applications.
+ *
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ * Reference: https://github.com/sst/opentui/blob/7da92b4088aebfe27b9f691c04163a48821e49fd/packages/core/src/lib/parse.keypress.ts
+ *
+ * Symbol keys are also supported, however some ctrl+symbol combos
+ * overlap with ASCII codes, e.g. ctrl+[ = ESC.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#legacy-ctrl-mapping-of-ascii-keys
+ * Those can still be * used for ctrl+shift combos
+ *
+ * API:
+ * - matchesKey(data, keyId) - Check if input matches a key identifier
+ * - parseKey(data) - Parse input and return the key identifier
+ * - Key - Helper object for creating typed key identifiers
+ * - setKittyProtocolActive(active) - Set global Kitty protocol state
+ * - isKittyProtocolActive() - Query global Kitty protocol state
+ */
+/**
+ * Set the global Kitty keyboard protocol state.
+ * Called by ProcessTerminal after detecting protocol support.
+ */
+export declare function setKittyProtocolActive(active: boolean): void;
+/**
+ * Query whether Kitty keyboard protocol is currently active.
+ */
+export declare function isKittyProtocolActive(): boolean;
+type Letter = "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";
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
+type SpecialKey = "escape" | "esc" | "enter" | "return" | "tab" | "space" | "backspace" | "delete" | "insert" | "clear" | "home" | "end" | "pageUp" | "pageDown" | "up" | "down" | "left" | "right" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
+type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+type ModifierName = "ctrl" | "shift" | "alt" | "super";
+type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+    [M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
+}[RemainingModifiers];
+/**
+ * Union type of all valid key identifiers.
+ * Provides autocomplete and catches typos at compile time.
+ */
+export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
+/**
+ * Helper object for creating typed key identifiers with autocomplete.
+ *
+ * Usage:
+ * - Key.escape, Key.enter, Key.tab, etc. for special keys
+ * - Key.backtick, Key.comma, Key.period, etc. for symbol keys
+ * - Key.ctrl("c"), Key.alt("x"), Key.super("k") for single modifiers
+ * - Key.ctrlShift("p"), Key.ctrlAlt("x"), Key.ctrlSuper("k") for combined modifiers
+ */
+export declare const Key: {
+    readonly escape: "escape";
+    readonly esc: "esc";
+    readonly enter: "enter";
+    readonly return: "return";
+    readonly tab: "tab";
+    readonly space: "space";
+    readonly backspace: "backspace";
+    readonly delete: "delete";
+    readonly insert: "insert";
+    readonly clear: "clear";
+    readonly home: "home";
+    readonly end: "end";
+    readonly pageUp: "pageUp";
+    readonly pageDown: "pageDown";
+    readonly up: "up";
+    readonly down: "down";
+    readonly left: "left";
+    readonly right: "right";
+    readonly f1: "f1";
+    readonly f2: "f2";
+    readonly f3: "f3";
+    readonly f4: "f4";
+    readonly f5: "f5";
+    readonly f6: "f6";
+    readonly f7: "f7";
+    readonly f8: "f8";
+    readonly f9: "f9";
+    readonly f10: "f10";
+    readonly f11: "f11";
+    readonly f12: "f12";
+    readonly backtick: "`";
+    readonly hyphen: "-";
+    readonly equals: "=";
+    readonly leftbracket: "[";
+    readonly rightbracket: "]";
+    readonly backslash: "\\";
+    readonly semicolon: ";";
+    readonly quote: "'";
+    readonly comma: ",";
+    readonly period: ".";
+    readonly slash: "/";
+    readonly exclamation: "!";
+    readonly at: "@";
+    readonly hash: "#";
+    readonly dollar: "$";
+    readonly percent: "%";
+    readonly caret: "^";
+    readonly ampersand: "&";
+    readonly asterisk: "*";
+    readonly leftparen: "(";
+    readonly rightparen: ")";
+    readonly underscore: "_";
+    readonly plus: "+";
+    readonly pipe: "|";
+    readonly tilde: "~";
+    readonly leftbrace: "{";
+    readonly rightbrace: "}";
+    readonly colon: ":";
+    readonly lessthan: "<";
+    readonly greaterthan: ">";
+    readonly question: "?";
+    readonly ctrl: <K extends BaseKey>(key: K) => `ctrl+${K}`;
+    readonly shift: <K extends BaseKey>(key: K) => `shift+${K}`;
+    readonly alt: <K extends BaseKey>(key: K) => `alt+${K}`;
+    readonly super: <K extends BaseKey>(key: K) => `super+${K}`;
+    readonly ctrlShift: <K extends BaseKey>(key: K) => `ctrl+shift+${K}`;
+    readonly shiftCtrl: <K extends BaseKey>(key: K) => `shift+ctrl+${K}`;
+    readonly ctrlAlt: <K extends BaseKey>(key: K) => `ctrl+alt+${K}`;
+    readonly altCtrl: <K extends BaseKey>(key: K) => `alt+ctrl+${K}`;
+    readonly shiftAlt: <K extends BaseKey>(key: K) => `shift+alt+${K}`;
+    readonly altShift: <K extends BaseKey>(key: K) => `alt+shift+${K}`;
+    readonly ctrlSuper: <K extends BaseKey>(key: K) => `ctrl+super+${K}`;
+    readonly superCtrl: <K extends BaseKey>(key: K) => `super+ctrl+${K}`;
+    readonly shiftSuper: <K extends BaseKey>(key: K) => `shift+super+${K}`;
+    readonly superShift: <K extends BaseKey>(key: K) => `super+shift+${K}`;
+    readonly altSuper: <K extends BaseKey>(key: K) => `alt+super+${K}`;
+    readonly superAlt: <K extends BaseKey>(key: K) => `super+alt+${K}`;
+    readonly ctrlShiftAlt: <K extends BaseKey>(key: K) => `ctrl+shift+alt+${K}`;
+    readonly ctrlShiftSuper: <K extends BaseKey>(key: K) => `ctrl+shift+super+${K}`;
+};
+/**
+ * Event types from Kitty keyboard protocol (flag 2)
+ * 1 = key press, 2 = key repeat, 3 = key release
+ */
+export type KeyEventType = "press" | "repeat" | "release";
+/**
+ * Check if the last parsed key event was a key release.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ */
+export declare function isKeyRelease(data: string): boolean;
+/**
+ * Check if the last parsed key event was a key repeat.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ */
+export declare function isKeyRepeat(data: string): boolean;
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Super combinations: "super+k", "super+enter"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x", "ctrl+super+k"
+ *
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p"), Key.super("k")
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
+ */
+export declare function matchesKey(data: string, keyId: KeyId): boolean;
+export declare function parseKey(data: string): string | undefined;
+/**
+ * Decode a Kitty CSI-u sequence into a printable character, if applicable.
+ *
+ * When Kitty keyboard protocol flag 1 (disambiguate) is active, terminals send
+ * CSI-u sequences for all keys, including plain printable characters. This
+ * function extracts the printable character from such sequences.
+ *
+ * Only accepts plain or Shift-modified keys. Rejects Ctrl, Alt, and unsupported
+ * modifier combinations (those are handled by keybinding matching instead).
+ * Prefers the shifted keycode when Shift is held and a shifted key is reported.
+ *
+ * @param data - Raw input data from terminal
+ * @returns The printable character, or undefined if not a printable CSI-u sequence
+ */
+export declare function decodeKittyPrintable(data: string): string | undefined;
+export declare function decodePrintableKey(data: string): string | undefined;
+export {};

package/dist/keys.js

@@ -0,0 +1,5 @@
+var v=Object.defineProperty;var c=(e,t)=>v(e,"name",{value:t,configurable:!0});let m=!1;function Z(e){m=e}c(Z,"setKittyProtocolActive");function j(){return m}c(j,"isKittyProtocolActive");const X={escape:"escape",esc:"esc",enter:"enter",return:"return",tab:"tab",space:"space",backspace:"backspace",delete:"delete",insert:"insert",clear:"clear",home:"home",end:"end",pageUp:"pageUp",pageDown:"pageDown",up:"up",down:"down",left:"left",right:"right",f1:"f1",f2:"f2",f3:"f3",f4:"f4",f5:"f5",f6:"f6",f7:"f7",f8:"f8",f9:"f9",f10:"f10",f11:"f11",f12:"f12",backtick:"`",hyphen:"-",equals:"=",leftbracket:"[",rightbracket:"]",backslash:"\\",semicolon:";",quote:"'",comma:",",period:".",slash:"/",exclamation:"!",at:"@",hash:"#",dollar:"$",percent:"%",caret:"^",ampersand:"&",asterisk:"*",leftparen:"(",rightparen:")",underscore:"_",plus:"+",pipe:"|",tilde:"~",leftbrace:"{",rightbrace:"}",colon:":",lessthan:"<",greaterthan:">",question:"?",ctrl:c(e=>`ctrl+${e}`,"ctrl"),shift:c(e=>`shift+${e}`,"shift"),alt:c(e=>`alt+${e}`,"alt"),super:c(e=>`super+${e}`,"super"),ctrlShift:c(e=>`ctrl+shift+${e}`,"ctrlShift"),shiftCtrl:c(e=>`shift+ctrl+${e}`,"shiftCtrl"),ctrlAlt:c(e=>`ctrl+alt+${e}`,"ctrlAlt"),altCtrl:c(e=>`alt+ctrl+${e}`,"altCtrl"),shiftAlt:c(e=>`shift+alt+${e}`,"shiftAlt"),altShift:c(e=>`alt+shift+${e}`,"altShift"),ctrlSuper:c(e=>`ctrl+super+${e}`,"ctrlSuper"),superCtrl:c(e=>`super+ctrl+${e}`,"superCtrl"),shiftSuper:c(e=>`shift+super+${e}`,"shiftSuper"),superShift:c(e=>`super+shift+${e}`,"superShift"),altSuper:c(e=>`alt+super+${e}`,"altSuper"),superAlt:c(e=>`super+alt+${e}`,"superAlt"),ctrlShiftAlt:c(e=>`ctrl+shift+alt+${e}`,"ctrlShiftAlt"),ctrlShiftSuper:c(e=>`ctrl+shift+super+${e}`,"ctrlShiftSuper")},$=new Set(["`","-","=","[","]","\\",";","'",",",".","/","!","@","#","$","%","^","&","*","(",")","_","+","|","~","{","}",":","<",">","?"]),n={shift:1,alt:2,ctrl:4,super:8},w=192,l={escape:27,tab:9,enter:13,space:32,backspace:127,kpEnter:57414},x={up:-1,down:-2,right:-3,left:-4},b={delete:-10,insert:-11,pageUp:-12,pageDown:-13,home:-14,end:-15},B=new Map([[57399,48],[57400,49],[57401,50],[57402,51],[57403,52],[57404,53],[57405,54],[57406,55],[57407,56],[57408,57],[57409,46],[57410,47],[57411,42],[57412,45],[57413,43],[57415,61],[57416,44],[57417,x.left],[57418,x.right],[57419,x.up],[57420,x.down],[57421,b.pageUp],[57422,b.pageDown],[57423,b.home],[57424,b.end],[57425,b.insert],[57426,b.delete]]);function K(e){return B.get(e)??e}c(K,"normalizeKittyFunctionalCodepoint");function E(e,t){return(t&~w&n.shift)!==0&&e>=65&&e<=90?e+32:e}c(E,"normalizeShiftedLetterIdentityCodepoint");const y={up:["\x1B[A","\x1BOA"],down:["\x1B[B","\x1BOB"],right:["\x1B[C","\x1BOC"],left:["\x1B[D","\x1BOD"],home:["\x1B[H","\x1BOH","\x1B[1~","\x1B[7~"],end:["\x1B[F","\x1BOF","\x1B[4~","\x1B[8~"],insert:["\x1B[2~"],delete:["\x1B[3~"],pageUp:["\x1B[5~","\x1B[[5~"],pageDown:["\x1B[6~","\x1B[[6~"],clear:["\x1B[E","\x1BOE"],f1:["\x1BOP","\x1B[11~","\x1B[[A"],f2:["\x1BOQ","\x1B[12~","\x1B[[B"],f3:["\x1BOR","\x1B[13~","\x1B[[C"],f4:["\x1BOS","\x1B[14~","\x1B[[D"],f5:["\x1B[15~","\x1B[[E"],f6:["\x1B[17~"],f7:["\x1B[18~"],f8:["\x1B[19~"],f9:["\x1B[20~"],f10:["\x1B[21~"],f11:["\x1B[23~"],f12:["\x1B[24~"]},P={up:["\x1B[a"],down:["\x1B[b"],right:["\x1B[c"],left:["\x1B[d"],clear:["\x1B[e"],insert:["\x1B[2$"],delete:["\x1B[3$"],pageUp:["\x1B[5$"],pageDown:["\x1B[6$"],home:["\x1B[7$"],end:["\x1B[8$"]},H={up:["\x1BOa"],down:["\x1BOb"],right:["\x1BOc"],left:["\x1BOd"],clear:["\x1BOe"],insert:["\x1B[2^"],delete:["\x1B[3^"],pageUp:["\x1B[5^"],pageDown:["\x1B[6^"],home:["\x1B[7^"],end:["\x1B[8^"]},Y={"\x1BOA":"up","\x1BOB":"down","\x1BOC":"right","\x1BOD":"left","\x1BOH":"home","\x1BOF":"end","\x1B[E":"clear","\x1BOE":"clear","\x1BOe":"ctrl+clear","\x1B[e":"shift+clear","\x1B[2~":"insert","\x1B[2$":"shift+insert","\x1B[2^":"ctrl+insert","\x1B[3$":"shift+delete","\x1B[3^":"ctrl+delete","\x1B[[5~":"pageUp","\x1B[[6~":"pageDown","\x1B[a":"shift+up","\x1B[b":"shift+down","\x1B[c":"shift+right","\x1B[d":"shift+left","\x1BOa":"ctrl+up","\x1BOb":"ctrl+down","\x1BOc":"ctrl+right","\x1BOd":"ctrl+left","\x1B[5$":"shift+pageUp","\x1B[6$":"shift+pageDown","\x1B[7$":"shift+home","\x1B[8$":"shift+end","\x1B[5^":"ctrl+pageUp","\x1B[6^":"ctrl+pageDown","\x1B[7^":"ctrl+home","\x1B[8^":"ctrl+end","\x1BOP":"f1","\x1BOQ":"f2","\x1BOR":"f3","\x1BOS":"f4","\x1B[11~":"f1","\x1B[12~":"f2","\x1B[13~":"f3","\x1B[14~":"f4","\x1B[[A":"f1","\x1B[[B":"f2","\x1B[[C":"f3","\x1B[[D":"f4","\x1B[[E":"f5","\x1B[15~":"f5","\x1B[17~":"f6","\x1B[18~":"f7","\x1B[19~":"f8","\x1B[20~":"f9","\x1B[21~":"f10","\x1B[23~":"f11","\x1B[24~":"f12","\x1Bb":"alt+left","\x1Bf":"alt+right","\x1Bp":"alt+up","\x1Bn":"alt+down"},C=c((e,t)=>t.includes(e),"matchesLegacySequence"),S=c((e,t,s)=>s===n.shift?C(e,P[t]):s===n.ctrl?C(e,H[t]):!1,"matchesLegacyModifierSequence");let D="press";function J(e){return e.includes("\x1B[200~")?!1:!!(e.includes(":3u")||e.includes(":3~")||e.includes(":3A")||e.includes(":3B")||e.includes(":3C")||e.includes(":3D")||e.includes(":3H")||e.includes(":3F"))}c(J,"isKeyRelease");function ee(e){return e.includes("\x1B[200~")?!1:!!(e.includes(":2u")||e.includes(":2~")||e.includes(":2A")||e.includes(":2B")||e.includes(":2C")||e.includes(":2D")||e.includes(":2H")||e.includes(":2F"))}c(ee,"isKeyRepeat");function I(e){if(!e)return"press";const t=parseInt(e,10);return t===2?"repeat":t===3?"release":"press"}c(I,"parseEventType");function L(e){const t=e.match(/^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/);if(t){const h=parseInt(t[1],10),p=t[2]&&t[2].length>0?parseInt(t[2],10):void 0,g=t[3]?parseInt(t[3],10):void 0,r=t[4]?parseInt(t[4],10):1,u=I(t[5]);return D=u,{codepoint:h,shiftedKey:p,baseLayoutKey:g,modifier:r-1,eventType:u}}const s=e.match(/^\x1b\[1;(\d+)(?::(\d+))?([ABCD])$/);if(s){const h=parseInt(s[1],10),p=I(s[2]),g={A:-1,B:-2,C:-3,D:-4};return D=p,{codepoint:g[s[3]],modifier:h-1,eventType:p}}const i=e.match(/^\x1b\[(\d+)(?:;(\d+))?(?::(\d+))?~$/);if(i){const h=parseInt(i[1],10),p=i[2]?parseInt(i[2],10):1,g=I(i[3]),u={2:b.insert,3:b.delete,5:b.pageUp,6:b.pageDown,7:b.home,8:b.end}[h];if(u!==void 0)return D=g,{codepoint:u,modifier:p-1,eventType:g}}const o=e.match(/^\x1b\[1;(\d+)(?::(\d+))?([HF])$/);if(o){const h=parseInt(o[1],10),p=I(o[2]),g=o[3]==="H"?b.home:b.end;return D=p,{codepoint:g,modifier:h-1,eventType:p}}return null}c(L,"parseKittySequence");function f(e,t,s){const i=L(e);if(!i)return!1;const o=i.modifier&~w,h=s&~w;if(o!==h)return!1;const p=E(K(i.codepoint),i.modifier),g=E(K(t),s);if(p===g)return!0;if(i.baseLayoutKey!==void 0&&i.baseLayoutKey===t){const r=p,u=r>=97&&r<=122,d=$.has(String.fromCharCode(r));if(!u&&!d)return!0}return!1}c(f,"matchesKittySequence");function k(e){const t=e.match(/^\x1b\[27;(\d+);(\d+)~$/);if(!t)return null;const s=parseInt(t[1],10);return{codepoint:parseInt(t[2],10),modifier:s-1}}c(k,"parseModifyOtherKeysSequence");function O(e,t,s){const i=k(e);return i?i.codepoint===t&&i.modifier===s:!1}c(O,"matchesModifyOtherKeys");function U(){return!!process.env.WT_SESSION&&!process.env.SSH_CONNECTION&&!process.env.SSH_CLIENT&&!process.env.SSH_TTY}c(U,"isWindowsTerminalSession");function N(e,t){return e==="\x7F"?t===0:e!=="\b"?!1:U()?t===n.ctrl:t===0}c(N,"matchesRawBackspace");function R(e){const t=e.toLowerCase(),s=t.charCodeAt(0);return s>=97&&s<=122||t==="["||t==="\\"||t==="]"||t==="_"?String.fromCharCode(s&31):t==="-"?"":null}c(R,"rawCtrlChar");function T(e){return e>="0"&&e<="9"}c(T,"isDigitKey");function A(e,t,s){if(s===0)return!1;const i=k(e);return!i||i.modifier!==s?!1:E(i.codepoint,i.modifier)===E(t,s)}c(A,"matchesPrintableModifyOtherKeys");function q(e,t){const s=[],i=t&~w,o=n.shift|n.ctrl|n.alt|n.super;if((i&~o)===0)return i&n.shift&&s.push("shift"),i&n.ctrl&&s.push("ctrl"),i&n.alt&&s.push("alt"),i&n.super&&s.push("super"),s.length>0?`${s.join("+")}+${e}`:e}c(q,"formatKeyNameWithModifiers");function z(e){const t=e.toLowerCase().split("+"),s=t[t.length-1];return s?{key:s,ctrl:t.includes("ctrl"),shift:t.includes("shift"),alt:t.includes("alt"),super:t.includes("super")}:null}c(z,"parseKeyId");function re(e,t){const s=z(t);if(!s)return!1;const{key:i,ctrl:o,shift:h,alt:p,super:g}=s;let r=0;switch(h&&(r|=n.shift),p&&(r|=n.alt),o&&(r|=n.ctrl),g&&(r|=n.super),i){case"escape":case"esc":return r!==0?!1:e==="\x1B"||f(e,l.escape,0)||O(e,l.escape,0);case"space":return!m&&(r===n.ctrl&&e==="\0"||r===n.alt&&e==="\x1B ")?!0:r===0?e===" "||f(e,l.space,0)||O(e,l.space,0):f(e,l.space,r)||O(e,l.space,r);case"tab":return r===n.shift?e==="\x1B[Z"||f(e,l.tab,n.shift)||O(e,l.tab,n.shift):r===0?e==="	"||f(e,l.tab,0):f(e,l.tab,r)||O(e,l.tab,r);case"enter":case"return":return r===n.shift?f(e,l.enter,n.shift)||f(e,l.kpEnter,n.shift)||O(e,l.enter,n.shift)?!0:m?e==="\x1B\r"||e===`
+`:!1:r===n.alt?f(e,l.enter,n.alt)||f(e,l.kpEnter,n.alt)||O(e,l.enter,n.alt)?!0:m?!1:e==="\x1B\r":r===0?e==="\r"||!m&&e===`
+`||e==="\x1BOM"||f(e,l.enter,0)||f(e,l.kpEnter,0):f(e,l.enter,r)||f(e,l.kpEnter,r)||O(e,l.enter,r);case"backspace":return r===n.alt?e==="\x1B\x7F"||e==="\x1B\b"?!0:f(e,l.backspace,n.alt)||O(e,l.backspace,n.alt):r===n.ctrl?N(e,n.ctrl)?!0:f(e,l.backspace,n.ctrl)||O(e,l.backspace,n.ctrl):r===0?N(e,0)||f(e,l.backspace,0)||O(e,l.backspace,0):f(e,l.backspace,r)||O(e,l.backspace,r);case"insert":return r===0?C(e,y.insert)||f(e,b.insert,0):S(e,"insert",r)?!0:f(e,b.insert,r);case"delete":return r===0?C(e,y.delete)||f(e,b.delete,0):S(e,"delete",r)?!0:f(e,b.delete,r);case"clear":return r===0?C(e,y.clear):S(e,"clear",r);case"home":return r===0?C(e,y.home)||f(e,b.home,0):S(e,"home",r)?!0:f(e,b.home,r);case"end":return r===0?C(e,y.end)||f(e,b.end,0):S(e,"end",r)?!0:f(e,b.end,r);case"pageup":return r===0?C(e,y.pageUp)||f(e,b.pageUp,0):S(e,"pageUp",r)?!0:f(e,b.pageUp,r);case"pagedown":return r===0?C(e,y.pageDown)||f(e,b.pageDown,0):S(e,"pageDown",r)?!0:f(e,b.pageDown,r);case"up":return r===n.alt?e==="\x1Bp"||f(e,x.up,n.alt):r===0?C(e,y.up)||f(e,x.up,0):S(e,"up",r)?!0:f(e,x.up,r);case"down":return r===n.alt?e==="\x1Bn"||f(e,x.down,n.alt):r===0?C(e,y.down)||f(e,x.down,0):S(e,"down",r)?!0:f(e,x.down,r);case"left":return r===n.alt?e==="\x1B[1;3D"||!m&&e==="\x1BB"||e==="\x1Bb"||f(e,x.left,n.alt):r===n.ctrl?e==="\x1B[1;5D"||S(e,"left",n.ctrl)||f(e,x.left,n.ctrl):r===0?C(e,y.left)||f(e,x.left,0):S(e,"left",r)?!0:f(e,x.left,r);case"right":return r===n.alt?e==="\x1B[1;3C"||!m&&e==="\x1BF"||e==="\x1Bf"||f(e,x.right,n.alt):r===n.ctrl?e==="\x1B[1;5C"||S(e,"right",n.ctrl)||f(e,x.right,n.ctrl):r===0?C(e,y.right)||f(e,x.right,0):S(e,"right",r)?!0:f(e,x.right,r);case"f1":case"f2":case"f3":case"f4":case"f5":case"f6":case"f7":case"f8":case"f9":case"f10":case"f11":case"f12":return r!==0?!1:C(e,y[i])}if(i.length===1&&(i>="a"&&i<="z"||T(i)||$.has(i))){const u=i.charCodeAt(0),d=R(i),_=i>="a"&&i<="z",M=T(i);return r===n.ctrl+n.alt&&!m&&d&&e===`\x1B${d}`||r===n.alt&&!m&&(_||M)&&e===`\x1B${i}`?!0:r===n.ctrl?d&&e===d?!0:f(e,u,n.ctrl)||A(e,u,n.ctrl):r===n.shift+n.ctrl?f(e,u,n.shift+n.ctrl)||A(e,u,n.shift+n.ctrl):r===n.shift?_&&e===i.toUpperCase()?!0:f(e,u,n.shift)||A(e,u,n.shift):r!==0?f(e,u,r)||A(e,u,r):e===i||f(e,u,0)}return!1}c(re,"matchesKey");function F(e,t,s){const i=K(e),o=E(i,t),h=o>=97&&o<=122,p=o>=48&&o<=57,g=$.has(String.fromCharCode(o)),r=h||p||g?o:s??o;let u;if(r===l.escape?u="escape":r===l.tab?u="tab":r===l.enter||r===l.kpEnter?u="enter":r===l.space?u="space":r===l.backspace?u="backspace":r===b.delete?u="delete":r===b.insert?u="insert":r===b.home?u="home":r===b.end?u="end":r===b.pageUp?u="pageUp":r===b.pageDown?u="pageDown":r===x.up?u="up":r===x.down?u="down":r===x.left?u="left":r===x.right?u="right":(r>=48&&r<=57||r>=97&&r<=122||$.has(String.fromCharCode(r)))&&(u=String.fromCharCode(r)),!!u)return q(u,t)}c(F,"formatParsedKey");function te(e){const t=L(e);if(t)return F(t.codepoint,t.modifier,t.baseLayoutKey);const s=k(e);if(s)return F(s.codepoint,s.modifier);if(m&&(e==="\x1B\r"||e===`
+`))return"shift+enter";const i=Y[e];if(i)return i;if(e==="\x1B")return"escape";if(e==="")return"ctrl+\\";if(e==="")return"ctrl+]";if(e==="")return"ctrl+-";if(e==="\x1B\x1B")return"ctrl+alt+[";if(e==="\x1B")return"ctrl+alt+\\";if(e==="\x1B")return"ctrl+alt+]";if(e==="\x1B")return"ctrl+alt+-";if(e==="	")return"tab";if(e==="\r"||!m&&e===`
+`||e==="\x1BOM")return"enter";if(e==="\0")return"ctrl+space";if(e===" ")return"space";if(e==="\x7F")return"backspace";if(e==="\b")return U()?"ctrl+backspace":"backspace";if(e==="\x1B[Z")return"shift+tab";if(!m&&e==="\x1B\r")return"alt+enter";if(!m&&e==="\x1B ")return"alt+space";if(e==="\x1B\x7F"||e==="\x1B\b")return"alt+backspace";if(!m&&e==="\x1BB")return"alt+left";if(!m&&e==="\x1BF")return"alt+right";if(!m&&e.length===2&&e[0]==="\x1B"){const o=e.charCodeAt(1);if(o>=1&&o<=26)return`ctrl+alt+${String.fromCharCode(o+96)}`;if(o>=97&&o<=122||o>=48&&o<=57)return`alt+${String.fromCharCode(o)}`}if(e==="\x1B[A")return"up";if(e==="\x1B[B")return"down";if(e==="\x1B[C")return"right";if(e==="\x1B[D")return"left";if(e==="\x1B[H"||e==="\x1BOH")return"home";if(e==="\x1B[F"||e==="\x1BOF")return"end";if(e==="\x1B[3~")return"delete";if(e==="\x1B[5~")return"pageUp";if(e==="\x1B[6~")return"pageDown";if(e.length===1){const o=e.charCodeAt(0);if(o>=1&&o<=26)return`ctrl+${String.fromCharCode(o+96)}`;if(o>=32&&o<=126)return e}}c(te,"parseKey");const Q=/^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/,V=n.shift|w;function G(e){const t=e.match(Q);if(!t)return;const s=Number.parseInt(t[1]??"",10);if(!Number.isFinite(s))return;const i=t[2]&&t[2].length>0?Number.parseInt(t[2],10):void 0,o=t[4]?Number.parseInt(t[4],10):1,h=Number.isFinite(o)?o-1:0;if((h&~V)!==0||h&(n.alt|n.ctrl))return;let p=s;if(h&n.shift&&typeof i=="number"&&(p=i),p=K(p),!(!Number.isFinite(p)||p<32))try{return String.fromCodePoint(p)}catch{return}}c(G,"decodeKittyPrintable");function W(e){const t=k(e);if(!(!t||(t.modifier&~w&~n.shift)!==0)&&!(!Number.isFinite(t.codepoint)||t.codepoint<32))try{return String.fromCodePoint(t.codepoint)}catch{return}}c(W,"decodeModifyOtherKeysPrintable");function ne(e){return G(e)??W(e)}c(ne,"decodePrintableKey");export{X as Key,G as decodeKittyPrintable,ne as decodePrintableKey,J as isKeyRelease,ee as isKeyRepeat,j as isKittyProtocolActive,re as matchesKey,te as parseKey,Z as setKittyProtocolActive};

package/dist/kill-ring.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ring buffer for Emacs-style kill/yank operations.
+ *
+ * Tracks killed (deleted) text entries. Consecutive kills can accumulate
+ * into a single entry. Supports yank (paste most recent) and yank-pop
+ * (cycle through older entries).
+ */
+export declare class KillRing {
+    private ring;
+    /**
+     * Add text to the kill ring.
+     *
+     * @param text - The killed text to add
+     * @param opts - Push options
+     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+     */
+    push(text: string, opts: {
+        prepend: boolean;
+        accumulate?: boolean;
+    }): void;
+    /** Get most recent entry without modifying the ring. */
+    peek(): string | undefined;
+    /** Move last entry to front (for yank-pop cycling). */
+    rotate(): void;
+    get length(): number;
+}

package/dist/kill-ring.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var r=(n,i)=>s(n,"name",{value:i,configurable:!0});class e{static{r(this,"KillRing")}ring=[];push(i,t){if(i)if(t.accumulate&&this.ring.length>0){const h=this.ring.pop();this.ring.push(t.prepend?i+h:h+i)}else this.ring.push(i)}peek(){return this.ring.length>0?this.ring[this.ring.length-1]:void 0}rotate(){if(this.ring.length>1){const i=this.ring.pop();this.ring.unshift(i)}}get length(){return this.ring.length}}export{e as KillRing};

package/dist/native-modifiers.d.ts

@@ -0,0 +1,2 @@
+export type ModifierKey = "shift" | "command" | "control" | "option";
+export declare function isNativeModifierPressed(key: ModifierKey): boolean;

package/dist/native-modifiers.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var n=(e,r)=>f(e,"name",{value:r,configurable:!0});import{createRequire as c}from"node:module";import*as i from"node:path";import{fileURLToPath as u}from"node:url";const l=c(import.meta.url);let t;function p(e){return typeof e!="object"||e===null?!1:typeof e.isModifierPressed=="function"}n(p,"isNativeModifiersHelper");function m(){if(t!==void 0)return t??void 0;if(t=null,process.platform!=="darwin")return;const e=process.arch;if(e!=="x64"&&e!=="arm64")return;const r=i.dirname(u(import.meta.url)),o=i.join("native","darwin","prebuilds",`darwin-${e}`,"darwin-modifiers.node"),s=[i.join(r,"..",o),i.join(r,o),i.join(i.dirname(process.execPath),o)];for(const a of s)try{const d=l(a);if(p(d))return t=d,d}catch{}}n(m,"loadNativeModifiersHelper");function M(e){const r=m();if(!r)return!1;try{return r.isModifierPressed(e)===!0}catch{return!1}}n(M,"isNativeModifierPressed");export{M as isNativeModifierPressed};

package/dist/stdin-buffer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+import { EventEmitter } from "events";
+export type StdinBufferOptions = {
+    /**
+     * Maximum time to wait for sequence completion (default: 10ms)
+     * After this time, the buffer is flushed even if incomplete
+     */
+    timeout?: number;
+};
+export type StdinBufferEventMap = {
+    data: [string];
+    paste: [string];
+};
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
+    private buffer;
+    private timeout;
+    private readonly timeoutMs;
+    private pasteMode;
+    private pasteBuffer;
+    private pendingKittyPrintableCodepoint;
+    constructor(options?: StdinBufferOptions);
+    process(data: string | Buffer): void;
+    private emitDataSequence;
+    flush(): string[];
+    clear(): void;
+    getBuffer(): string;
+    destroy(): void;
+}

package/dist/stdin-buffer.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var h=(t,e)=>d(t,"name",{value:e,configurable:!0});import{EventEmitter as a}from"events";const u="\x1B",l="\x1B[200~",c="\x1B[201~";function b(t){if(!t.startsWith(u))return"not-escape";if(t.length===1)return"incomplete";const e=t.slice(1);return e.startsWith("[")?e.startsWith("[M")?t.length>=6?"complete":"incomplete":g(t):e.startsWith("]")?C(t):e.startsWith("P")?x(t):e.startsWith("_")?B(t):e.startsWith("O")?e.length>=2?"complete":"incomplete":(e.length===1,"complete")}h(b,"isCompleteSequence");function g(t){if(!t.startsWith(`${u}[`))return"complete";if(t.length<3)return"incomplete";const e=t.slice(2),i=e[e.length-1],s=i.charCodeAt(0);if(s>=64&&s<=126){if(e.startsWith("<")){if(/^<\d+;\d+;\d+[Mm]$/.test(e))return"complete";if(i==="M"||i==="m"){const n=e.slice(1,-1).split(";");if(n.length===3&&n.every(f=>/^\d+$/.test(f)))return"complete"}return"incomplete"}return"complete"}return"incomplete"}h(g,"isCompleteCsiSequence");function C(t){return!t.startsWith(`${u}]`)||t.endsWith(`${u}\\`)||t.endsWith("\x07")?"complete":"incomplete"}h(C,"isCompleteOscSequence");function x(t){return!t.startsWith(`${u}P`)||t.endsWith(`${u}\\`)?"complete":"incomplete"}h(x,"isCompleteDcsSequence");function B(t){return!t.startsWith(`${u}_`)||t.endsWith(`${u}\\`)?"complete":"incomplete"}h(B,"isCompleteApcSequence");function S(t){const e=t.match(/^\x1b\[(\d+)(?::\d*)?(?::\d+)?u$/);if(!e)return;const i=parseInt(e[1],10);return i>=32?i:void 0}h(S,"parseUnmodifiedKittyPrintableCodepoint");function p(t){const e=[];let i=0;for(;i<t.length;){const s=t.slice(i);if(s.startsWith(u)){let o=1;for(;o<=s.length;){const n=s.slice(0,o),f=b(n);if(f==="complete"){if(n==="\x1B\x1B"){const r=s[o];if(r==="["||r==="]"||r==="O"||r==="P"||r==="_"){e.push(u),i+=1;break}}e.push(n),i+=o;break}else if(f==="incomplete")o++;else{e.push(n),i+=o;break}}if(o>s.length)return{sequences:e,remainder:s}}else e.push(s[0]),i++}return{sequences:e,remainder:""}}h(p,"extractCompleteSequences");class q extends a{static{h(this,"StdinBuffer")}buffer="";timeout=null;timeoutMs;pasteMode=!1;pasteBuffer="";pendingKittyPrintableCodepoint;constructor(e={}){super(),this.timeoutMs=e.timeout??10}process(e){this.timeout&&(clearTimeout(this.timeout),this.timeout=null);let i;if(Buffer.isBuffer(e))if(e.length===1&&e[0]>127){const n=e[0]-128;i=`\x1B${String.fromCharCode(n)}`}else i=e.toString();else i=e;if(i.length===0&&this.buffer.length===0){this.emitDataSequence("");return}if(this.buffer+=i,this.pasteMode){this.pasteBuffer+=this.buffer,this.buffer="";const n=this.pasteBuffer.indexOf(c);if(n!==-1){const f=this.pasteBuffer.slice(0,n),r=this.pasteBuffer.slice(n+c.length);this.pasteMode=!1,this.pasteBuffer="",this.pendingKittyPrintableCodepoint=void 0,this.emit("paste",f),r.length>0&&this.process(r)}return}const s=this.buffer.indexOf(l);if(s!==-1){if(s>0){const f=this.buffer.slice(0,s),r=p(f);for(const m of r.sequences)this.emitDataSequence(m)}this.pendingKittyPrintableCodepoint=void 0,this.buffer=this.buffer.slice(s+l.length),this.pasteMode=!0,this.pasteBuffer=this.buffer,this.buffer="";const n=this.pasteBuffer.indexOf(c);if(n!==-1){const f=this.pasteBuffer.slice(0,n),r=this.pasteBuffer.slice(n+c.length);this.pasteMode=!1,this.pasteBuffer="",this.pendingKittyPrintableCodepoint=void 0,this.emit("paste",f),r.length>0&&this.process(r)}return}const o=p(this.buffer);this.buffer=o.remainder;for(const n of o.sequences)this.emitDataSequence(n);this.buffer.length>0&&(this.timeout=setTimeout(()=>{const n=this.flush();for(const f of n)this.emitDataSequence(f)},this.timeoutMs))}emitDataSequence(e){const i=e.length===1?e.codePointAt(0):void 0;if(i!==void 0&&i===this.pendingKittyPrintableCodepoint){this.pendingKittyPrintableCodepoint=void 0;return}this.pendingKittyPrintableCodepoint=S(e),this.emit("data",e)}flush(){if(this.timeout&&(clearTimeout(this.timeout),this.timeout=null),this.buffer.length===0)return[];const e=[this.buffer];return this.buffer="",this.pendingKittyPrintableCodepoint=void 0,e}clear(){this.timeout&&(clearTimeout(this.timeout),this.timeout=null),this.buffer="",this.pasteMode=!1,this.pasteBuffer="",this.pendingKittyPrintableCodepoint=void 0}getBuffer(){return this.buffer}destroy(){this.clear()}}export{q as StdinBuffer};

package/dist/terminal-image.d.ts

@@ -0,0 +1,89 @@
+export type ImageProtocol = "kitty" | "iterm2" | null;
+export interface TerminalCapabilities {
+    images: ImageProtocol;
+    trueColor: boolean;
+    hyperlinks: boolean;
+}
+export interface CellDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageRenderOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    preserveAspectRatio?: boolean;
+    /** Kitty image ID. If provided, reuses/replaces existing image with this ID. */
+    imageId?: number;
+    /** Whether Kitty should apply its default cursor movement after placement. */
+    moveCursor?: boolean;
+}
+export declare function getCellDimensions(): CellDimensions;
+export declare function setCellDimensions(dims: CellDimensions): void;
+export declare function detectCapabilities(tmuxForwardsHyperlink?: () => boolean): TerminalCapabilities;
+export declare function getCapabilities(): TerminalCapabilities;
+export declare function resetCapabilitiesCache(): void;
+/** Override the cached capabilities. Useful in tests to exercise both code paths. */
+export declare function setCapabilities(caps: TerminalCapabilities): void;
+export declare function isImageLine(line: string): boolean;
+/**
+ * Generate a random image ID for Kitty graphics protocol.
+ * Uses random IDs to avoid collisions between different module instances
+ * (e.g., main app vs extensions).
+ */
+export declare function allocateImageId(): number;
+export declare function encodeKitty(base64Data: string, options?: {
+    columns?: number;
+    rows?: number;
+    imageId?: number;
+    /** Whether Kitty should apply its default cursor movement after placement. Default: true. */
+    moveCursor?: boolean;
+}): string;
+/**
+ * Delete a Kitty graphics image by ID.
+ * Uses uppercase 'I' to also free the image data.
+ */
+export declare function deleteKittyImage(imageId: number): string;
+/**
+ * Delete all visible Kitty graphics images.
+ * Uses uppercase 'A' to also free the image data.
+ */
+export declare function deleteAllKittyImages(): string;
+export declare function encodeITerm2(base64Data: string, options?: {
+    width?: number | string;
+    height?: number | string;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}): string;
+export interface ImageCellSize {
+    columns: number;
+    rows: number;
+}
+export declare function calculateImageCellSize(imageDimensions: ImageDimensions, maxWidthCells: number, maxHeightCells?: number, cellDimensions?: CellDimensions): ImageCellSize;
+export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
+export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
+export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
+export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
+export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
+export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
+    sequence: string;
+    rows: number;
+    imageId?: number;
+} | null;
+/**
+ * Wrap text in an OSC 8 hyperlink sequence.
+ * The text is rendered as a clickable hyperlink in terminals that support OSC 8
+ * (Ghostty, Kitty, WezTerm, iTerm2, VSCode, and others).
+ * In terminals that do not support OSC 8, the escape sequences are ignored
+ * and only the plain text is displayed.
+ *
+ * @param text - The visible text to display
+ * @param url - The URL to link to
+ */
+export declare function hyperlink(text: string, url: string): string;
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;

package/dist/terminal-image.js

@@ -0,0 +1 @@
+var C=Object.defineProperty;var s=(t,e)=>C(t,"name",{value:e,configurable:!0});import{execSync as b}from"node:child_process";let c=null,g={widthPx:9,heightPx:18};function E(){return g}s(E,"getCellDimensions");function W(t){g=t}s(W,"setCellDimensions");function y(){try{return b("tmux display-message -p '#{client_termfeatures}'",{encoding:"utf8",timeout:250,stdio:["ignore","pipe","ignore"]}).split(",").map(e=>e.trim()).includes("hyperlinks")}catch{return!1}}s(y,"probeTmuxHyperlinks");function M(t=y){const e=process.env.TERM_PROGRAM?.toLowerCase()||"",r=process.env.TERMINAL_EMULATOR?.toLowerCase()||"",n=process.env.TERM?.toLowerCase()||"",u=process.env.COLORTERM?.toLowerCase()||"",i=u==="truecolor"||u==="24bit";return process.env.TMUX||n.startsWith("tmux")?{images:null,trueColor:i,hyperlinks:t()}:n.startsWith("screen")?{images:null,trueColor:i,hyperlinks:!1}:process.env.KITTY_WINDOW_ID||e==="kitty"?{images:"kitty",trueColor:!0,hyperlinks:!0}:e==="ghostty"||n.includes("ghostty")||process.env.GHOSTTY_RESOURCES_DIR?{images:"kitty",trueColor:!0,hyperlinks:!0}:process.env.WEZTERM_PANE||e==="wezterm"?{images:"kitty",trueColor:!0,hyperlinks:!0}:process.env.ITERM_SESSION_ID||e==="iterm.app"?{images:"iterm2",trueColor:!0,hyperlinks:!0}:process.env.WT_SESSION?{images:null,trueColor:!0,hyperlinks:!0}:e==="vscode"?{images:null,trueColor:!0,hyperlinks:!0}:e==="alacritty"?{images:null,trueColor:!0,hyperlinks:!0}:r==="jetbrains-jediterm"?{images:null,trueColor:!0,hyperlinks:!1}:{images:null,trueColor:i,hyperlinks:!1}}s(M,"detectCapabilities");function _(){return c||(c=M()),c}s(_,"getCapabilities");function B(){c=null}s(B,"resetCapabilitiesCache");function G(t){c=t}s(G,"setCapabilities");const x="\x1B_G",m="\x1B]1337;File=";function H(t){return t.startsWith(x)||t.startsWith(m)?!0:t.includes(x)||t.includes(m)}s(H,"isImageLine");function A(){return Math.floor(Math.random()*4294967294)+1}s(A,"allocateImageId");function k(t,e={}){const n=["a=T","f=100","q=2"];if(e.moveCursor===!1&&n.push("C=1"),e.columns&&n.push(`c=${e.columns}`),e.rows&&n.push(`r=${e.rows}`),e.imageId&&n.push(`i=${e.imageId}`),t.length<=4096)return`\x1B_G${n.join(",")};${t}\x1B\\`;const u=[];let i=0,o=!0;for(;i<t.length;){const l=t.slice(i,i+4096),h=i+4096>=t.length;o?(u.push(`\x1B_G${n.join(",")},m=1;${l}\x1B\\`),o=!1):h?u.push(`\x1B_Gm=0;${l}\x1B\\`):u.push(`\x1B_Gm=1;${l}\x1B\\`),i+=4096}return u.join("")}s(k,"encodeKitty");function F(t){return`\x1B_Ga=d,d=I,i=${t},q=2\x1B\\`}s(F,"deleteKittyImage");function K(){return"\x1B_Ga=d,d=A,q=2\x1B\\"}s(K,"deleteAllKittyImages");function S(t,e={}){const r=[`inline=${e.inline!==!1?1:0}`];if(e.width!==void 0&&r.push(`width=${e.width}`),e.height!==void 0&&r.push(`height=${e.height}`),e.name){const n=Buffer.from(e.name).toString("base64");r.push(`name=${n}`)}return e.preserveAspectRatio===!1&&r.push("preserveAspectRatio=0"),`\x1B]1337;File=${r.join(";")}:${t}\x07`}s(S,"encodeITerm2");function d(t,e,r,n={widthPx:9,heightPx:18}){const u=Math.max(1,Math.floor(e)),i=r===void 0?void 0:Math.max(1,Math.floor(r)),o=Math.max(1,t.widthPx),l=Math.max(1,t.heightPx),h=u*n.widthPx/o,p=i===void 0?h:i*n.heightPx/l,f=Math.min(h,p),I=o*f,w=l*f,P=Math.ceil(I/n.widthPx),a=Math.ceil(w/n.heightPx);return{columns:Math.max(1,Math.min(u,P)),rows:Math.max(1,i===void 0?a:Math.min(i,a))}}s(d,"calculateImageCellSize");function N(t,e,r={widthPx:9,heightPx:18}){return d(t,e,void 0,r).rows}s(N,"calculateImageRows");function R(t){try{const e=Buffer.from(t,"base64");if(e.length<24||e[0]!==137||e[1]!==80||e[2]!==78||e[3]!==71)return null;const r=e.readUInt32BE(16),n=e.readUInt32BE(20);return{widthPx:r,heightPx:n}}catch{return null}}s(R,"getPngDimensions");function $(t){try{const e=Buffer.from(t,"base64");if(e.length<2||e[0]!==255||e[1]!==216)return null;let r=2;for(;r<e.length-9;){if(e[r]!==255){r++;continue}const n=e[r+1];if(n>=192&&n<=194){const i=e.readUInt16BE(r+5);return{widthPx:e.readUInt16BE(r+7),heightPx:i}}if(r+3>=e.length)return null;const u=e.readUInt16BE(r+2);if(u<2)return null;r+=2+u}return null}catch{return null}}s($,"getJpegDimensions");function v(t){try{const e=Buffer.from(t,"base64");if(e.length<10)return null;const r=e.slice(0,6).toString("ascii");if(r!=="GIF87a"&&r!=="GIF89a")return null;const n=e.readUInt16LE(6),u=e.readUInt16LE(8);return{widthPx:n,heightPx:u}}catch{return null}}s(v,"getGifDimensions");function T(t){try{const e=Buffer.from(t,"base64");if(e.length<30)return null;const r=e.slice(0,4).toString("ascii"),n=e.slice(8,12).toString("ascii");if(r!=="RIFF"||n!=="WEBP")return null;const u=e.slice(12,16).toString("ascii");if(u==="VP8 "){if(e.length<30)return null;const i=e.readUInt16LE(26)&16383,o=e.readUInt16LE(28)&16383;return{widthPx:i,heightPx:o}}else if(u==="VP8L"){if(e.length<25)return null;const i=e.readUInt32LE(21),o=(i&16383)+1,l=(i>>14&16383)+1;return{widthPx:o,heightPx:l}}else if(u==="VP8X"){if(e.length<30)return null;const i=(e[24]|e[25]<<8|e[26]<<16)+1,o=(e[27]|e[28]<<8|e[29]<<16)+1;return{widthPx:i,heightPx:o}}return null}catch{return null}}s(T,"getWebpDimensions");function O(t,e){return e==="image/png"?R(t):e==="image/jpeg"?$(t):e==="image/gif"?v(t):e==="image/webp"?T(t):null}s(O,"getImageDimensions");function j(t,e,r={}){const n=_();if(!n.images)return null;const u=r.maxWidthCells??80,i=d(e,u,r.maxHeightCells,E());return n.images==="kitty"?{sequence:k(t,{columns:i.columns,rows:i.rows,imageId:r.imageId,moveCursor:r.moveCursor}),rows:i.rows,imageId:r.imageId}:n.images==="iterm2"?{sequence:S(t,{width:i.columns,height:"auto",preserveAspectRatio:r.preserveAspectRatio??!0}),rows:i.rows}:null}s(j,"renderImage");function q(t,e){return`\x1B]8;;${e}\x1B\\${t}\x1B]8;;\x1B\\`}s(q,"hyperlink");function Z(t,e,r){const n=[];return r&&n.push(r),n.push(`[${t}]`),e&&n.push(`${e.widthPx}x${e.heightPx}`),`[Image: ${n.join(" ")}]`}s(Z,"imageFallback");export{A as allocateImageId,d as calculateImageCellSize,N as calculateImageRows,K as deleteAllKittyImages,F as deleteKittyImage,M as detectCapabilities,S as encodeITerm2,k as encodeKitty,_ as getCapabilities,E as getCellDimensions,v as getGifDimensions,O as getImageDimensions,$ as getJpegDimensions,R as getPngDimensions,T as getWebpDimensions,q as hyperlink,Z as imageFallback,H as isImageLine,j as renderImage,B as resetCapabilitiesCache,G as setCapabilities,W as setCellDimensions};

package/dist/terminal.d.ts

@@ -0,0 +1,112 @@
+export type KeyboardProtocolNegotiationSequence = {
+    type: "kitty-flags";
+    flags: number;
+} | {
+    type: "device-attributes";
+};
+export declare function parseKeyboardProtocolNegotiationSequence(sequence: string): KeyboardProtocolNegotiationSequence | undefined;
+export declare function isAppleTerminalSession(): boolean;
+export declare function normalizeAppleTerminalInput(data: string, isAppleTerminal: boolean, isShiftPressed: boolean): string;
+/**
+ * Minimal terminal interface for TUI
+ */
+export interface Terminal {
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    /**
+     * Drain stdin before exiting to prevent Kitty key release events from
+     * leaking to the parent shell over slow SSH connections.
+     * @param maxMs - Maximum time to drain (default: 1000ms)
+     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+     */
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    get kittyProtocolActive(): boolean;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    private wasRaw;
+    private inputHandler?;
+    private resizeHandler?;
+    private _kittyProtocolActive;
+    private _modifyOtherKeysActive;
+    private keyboardProtocolPushed;
+    private keyboardProtocolNegotiationPending;
+    private keyboardProtocolLateResponsePending;
+    private keyboardProtocolNegotiationBuffer;
+    private keyboardProtocolFallbackTimer?;
+    private keyboardProtocolBufferFlushTimer?;
+    private stdinBuffer?;
+    private stdinDataHandler?;
+    private progressInterval?;
+    private writeLogPath;
+    get kittyProtocolActive(): boolean;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    /**
+     * Set up StdinBuffer to split batched input into individual sequences.
+     * This ensures components receive single events, making matchesKey/isKeyRelease work correctly.
+     *
+     * Also watches for Kitty protocol response and enables it when detected.
+     * This is done here (after stdinBuffer parsing) rather than on raw stdin
+     * to handle the case where the response arrives split across multiple events.
+     */
+    private setupStdinBuffer;
+    /**
+     * Query terminal for Kitty keyboard protocol support and enable it if available.
+     *
+     * Kitty's progressive enhancement detection requires requesting the desired
+     * flags before querying them. The trailing DA query is a sentinel supported by
+     * terminals that do not know Kitty keyboard protocol. A short timeout remains
+     * as a backup for terminals, PTYs, and SSH sessions that delay, split, or drop
+     * the DA response.
+     *
+     * The requested flags are:
+     * - 1 = disambiguate escape codes
+     * - 2 = report event types (press/repeat/release)
+     * - 4 = report alternate keys (shifted key, base layout key)
+     */
+    private queryAndEnableKittyProtocol;
+    private handleKeyboardProtocolNegotiationSequence;
+    private readKeyboardProtocolNegotiationSequence;
+    private setKeyboardProtocolNegotiationBuffer;
+    private clearKeyboardProtocolNegotiationBuffer;
+    private flushKeyboardProtocolNegotiationBufferAsInput;
+    private scheduleKeyboardProtocolNegotiationBufferFlush;
+    private clearKeyboardProtocolNegotiationBufferFlushTimer;
+    private forwardInputSequence;
+    private enableModifyOtherKeys;
+    private clearKeyboardProtocolFallbackTimer;
+    /**
+     * On Windows, add ENABLE_VIRTUAL_TERMINAL_INPUT (0x0200) to the stdin
+     * console handle so the terminal sends VT sequences for modified keys
+     * (e.g. \x1b[Z for Shift+Tab). Without this, libuv's ReadConsoleInputW
+     * discards modifier state and Shift+Tab arrives as plain \t.
+     */
+    private enableWindowsVTInput;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    stop(): void;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    private clearProgressInterval;
+}

package/dist/terminal.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var n=(o,t)=>m(o,"name",{value:t,configurable:!0});import*as f from"node:fs";import{createRequire as k}from"node:module";import*as a from"node:path";import{fileURLToPath as N}from"node:url";import{setKittyProtocolActive as c}from"./keys.js";import{isNativeModifierPressed as T}from"./native-modifiers.js";import{StdinBuffer as w}from"./stdin-buffer.js";const K=k(import.meta.url),B=1e3,h="\x1B]9;4;3\x07",P="\x1B]9;4;0;\x07",S="\x1B[13;2u",_=7,A=150,R=150,v=`\x1B[>${_}u\x1B[?u\x1B[c`;function b(o){const t=o.match(/^\x1b\[\?(\d+)u$/);if(t)return{type:"kitty-flags",flags:Number.parseInt(t[1],10)};if(/^\x1b\[\?[\d;]*c$/.test(o))return{type:"device-attributes"}}n(b,"parseKeyboardProtocolNegotiationSequence");function p(o,t){return t&&o==="\x1B"||o==="\x1B["||/^\x1b\[\?[\d;]*$/.test(o)}n(p,"isKeyboardProtocolNegotiationSequencePrefix");function I(){return process.platform==="darwin"&&process.env.TERM_PROGRAM==="Apple_Terminal"}n(I,"isAppleTerminalSession");function E(o,t,e){return t&&o==="\r"&&e?S:o}n(E,"normalizeAppleTerminalInput");class M{static{n(this,"ProcessTerminal")}wasRaw=!1;inputHandler;resizeHandler;_kittyProtocolActive=!1;_modifyOtherKeysActive=!1;keyboardProtocolPushed=!1;keyboardProtocolNegotiationPending=!1;keyboardProtocolLateResponsePending=!1;keyboardProtocolNegotiationBuffer="";keyboardProtocolFallbackTimer;keyboardProtocolBufferFlushTimer;stdinBuffer;stdinDataHandler;progressInterval;writeLogPath=(()=>{const t=process.env.KODA_TUI_WRITE_LOG||"";if(!t)return"";try{if(f.statSync(t).isDirectory()){const e=new Date,r=`${e.getFullYear()}-${String(e.getMonth()+1).padStart(2,"0")}-${String(e.getDate()).padStart(2,"0")}_${String(e.getHours()).padStart(2,"0")}-${String(e.getMinutes()).padStart(2,"0")}-${String(e.getSeconds()).padStart(2,"0")}`;return a.join(t,`tui-${r}-${process.pid}.log`)}}catch{}return t})();get kittyProtocolActive(){return this._kittyProtocolActive}start(t,e){this.inputHandler=t,this.resizeHandler=e,this.wasRaw=process.stdin.isRaw||!1,process.stdin.setRawMode&&process.stdin.setRawMode(!0),process.stdin.setEncoding("utf8"),process.stdin.resume(),process.stdout.write("\x1B[?2004h"),process.stdout.on("resize",this.resizeHandler),process.platform!=="win32"&&process.kill(process.pid,"SIGWINCH"),this.enableWindowsVTInput(),this.queryAndEnableKittyProtocol()}setupStdinBuffer(){this.stdinBuffer=new w({timeout:10}),this.stdinBuffer.on("data",t=>{if(this.keyboardProtocolNegotiationPending){const e=this.readKeyboardProtocolNegotiationSequence(t,!0);if(e==="pending"||this.handleKeyboardProtocolNegotiationSequence(e))return}if(this.keyboardProtocolLateResponsePending){const e=this.readKeyboardProtocolNegotiationSequence(t,!1);if(e==="pending"){this.scheduleKeyboardProtocolNegotiationBufferFlush();return}if(this.handleKeyboardProtocolNegotiationSequence(e))return}this.forwardInputSequence(t)}),this.stdinBuffer.on("paste",t=>{this.inputHandler&&this.inputHandler(`\x1B[200~${t}\x1B[201~`)}),this.stdinDataHandler=t=>{this.stdinBuffer.process(t)}}queryAndEnableKittyProtocol(){this.setupStdinBuffer(),process.stdin.on("data",this.stdinDataHandler),this.keyboardProtocolPushed=!0,this.keyboardProtocolNegotiationPending=!0,this.keyboardProtocolLateResponsePending=!1,this.clearKeyboardProtocolNegotiationBuffer(),process.stdout.write(v),this.keyboardProtocolFallbackTimer=setTimeout(()=>{this.keyboardProtocolFallbackTimer=void 0,this.keyboardProtocolNegotiationPending=!1,this.keyboardProtocolLateResponsePending=!0,this.keyboardProtocolNegotiationBuffer==="\x1B"?this.flushKeyboardProtocolNegotiationBufferAsInput():this.scheduleKeyboardProtocolNegotiationBufferFlush(),this.enableModifyOtherKeys()},A)}handleKeyboardProtocolNegotiationSequence(t){return t?t.type==="kitty-flags"?(t.flags!==0&&!this._kittyProtocolActive&&(this._kittyProtocolActive=!0,c(!0),this.keyboardProtocolNegotiationPending=!1,this.keyboardProtocolLateResponsePending=!0,this.clearKeyboardProtocolNegotiationBuffer(),this.clearKeyboardProtocolFallbackTimer()),!0):(this.keyboardProtocolNegotiationPending=!1,this.keyboardProtocolLateResponsePending=!0,this.clearKeyboardProtocolNegotiationBuffer(),this.clearKeyboardProtocolFallbackTimer(),this.enableModifyOtherKeys(),!0):!1}readKeyboardProtocolNegotiationSequence(t,e){if(this.keyboardProtocolNegotiationBuffer){const i=this.keyboardProtocolNegotiationBuffer+t,s=b(i);if(s)return this.clearKeyboardProtocolNegotiationBuffer(),s;if(p(i,e))return this.setKeyboardProtocolNegotiationBuffer(i),"pending";this.flushKeyboardProtocolNegotiationBufferAsInput()}const r=b(t);if(r)return r;if(p(t,e))return this.setKeyboardProtocolNegotiationBuffer(t),"pending"}setKeyboardProtocolNegotiationBuffer(t){this.clearKeyboardProtocolNegotiationBufferFlushTimer(),this.keyboardProtocolNegotiationBuffer=t}clearKeyboardProtocolNegotiationBuffer(){this.clearKeyboardProtocolNegotiationBufferFlushTimer(),this.keyboardProtocolNegotiationBuffer=""}flushKeyboardProtocolNegotiationBufferAsInput(){if(!this.keyboardProtocolNegotiationBuffer)return;const t=this.keyboardProtocolNegotiationBuffer;this.clearKeyboardProtocolNegotiationBuffer(),this.forwardInputSequence(t)}scheduleKeyboardProtocolNegotiationBufferFlush(){!this.keyboardProtocolNegotiationBuffer||this.keyboardProtocolBufferFlushTimer||(this.keyboardProtocolBufferFlushTimer=setTimeout(()=>{this.keyboardProtocolBufferFlushTimer=void 0,this.flushKeyboardProtocolNegotiationBufferAsInput()},R))}clearKeyboardProtocolNegotiationBufferFlushTimer(){this.keyboardProtocolBufferFlushTimer&&(clearTimeout(this.keyboardProtocolBufferFlushTimer),this.keyboardProtocolBufferFlushTimer=void 0)}forwardInputSequence(t){if(!this.inputHandler)return;const e=t==="\r"&&I(),r=E(t,e,e&&T("shift"));this.inputHandler(r)}enableModifyOtherKeys(){this._kittyProtocolActive||this._modifyOtherKeysActive||(process.stdout.write("\x1B[>4;2m"),this._modifyOtherKeysActive=!0)}clearKeyboardProtocolFallbackTimer(){this.keyboardProtocolFallbackTimer&&(clearTimeout(this.keyboardProtocolFallbackTimer),this.keyboardProtocolFallbackTimer=void 0)}enableWindowsVTInput(){if(process.platform==="win32")try{const t=process.arch;if(t!=="x64"&&t!=="arm64")return;const e=a.dirname(N(import.meta.url)),r=a.join("native","win32","prebuilds",`win32-${t}`,"win32-console-mode.node"),i=[a.join(e,"..",r),a.join(e,r),a.join(a.dirname(process.execPath),r)];for(const s of i)try{K(s).enableVirtualTerminalInput?.();return}catch{}}catch{}}async drainInput(t=1e3,e=50){const r=this.keyboardProtocolPushed||this._kittyProtocolActive||this.keyboardProtocolNegotiationPending;this.keyboardProtocolLateResponsePending=!1,this.clearKeyboardProtocolNegotiationBuffer(),this.clearKeyboardProtocolFallbackTimer(),r&&(process.stdout.write("\x1B[<u"),this.keyboardProtocolPushed=!1,this._kittyProtocolActive=!1,c(!1)),this.keyboardProtocolNegotiationPending=!1,this._modifyOtherKeysActive&&(process.stdout.write("\x1B[>4;0m"),this._modifyOtherKeysActive=!1);const i=this.inputHandler;this.inputHandler=void 0;let s=Date.now();const l=n(()=>{s=Date.now()},"onData");process.stdin.on("data",l);const y=Date.now()+t;try{for(;;){const d=Date.now(),u=y-d;if(u<=0||d-s>=e)break;await new Promise(g=>setTimeout(g,Math.min(e,u)))}}finally{process.stdin.removeListener("data",l),this.inputHandler=i}}stop(){this.clearProgressInterval()&&process.stdout.write(P),process.stdout.write("\x1B[?2004l");const t=this.keyboardProtocolPushed||this._kittyProtocolActive||this.keyboardProtocolNegotiationPending;this.keyboardProtocolLateResponsePending=!1,this.clearKeyboardProtocolNegotiationBuffer(),this.clearKeyboardProtocolFallbackTimer(),t&&(process.stdout.write("\x1B[<u"),this.keyboardProtocolPushed=!1,this._kittyProtocolActive=!1,c(!1)),this.keyboardProtocolNegotiationPending=!1,this._modifyOtherKeysActive&&(process.stdout.write("\x1B[>4;0m"),this._modifyOtherKeysActive=!1),this.stdinBuffer&&(this.stdinBuffer.destroy(),this.stdinBuffer=void 0),this.stdinDataHandler&&(process.stdin.removeListener("data",this.stdinDataHandler),this.stdinDataHandler=void 0),this.inputHandler=void 0,this.resizeHandler&&(process.stdout.removeListener("resize",this.resizeHandler),this.resizeHandler=void 0),process.stdin.pause(),process.stdin.setRawMode&&process.stdin.setRawMode(this.wasRaw)}write(t){if(process.stdout.write(t),this.writeLogPath)try{f.appendFileSync(this.writeLogPath,t,{encoding:"utf8"})}catch{}}get columns(){return process.stdout.columns||Number(process.env.COLUMNS)||80}get rows(){return process.stdout.rows||Number(process.env.LINES)||24}moveBy(t){t>0?process.stdout.write(`\x1B[${t}B`):t<0&&process.stdout.write(`\x1B[${-t}A`)}hideCursor(){process.stdout.write("\x1B[?25l")}showCursor(){process.stdout.write("\x1B[?25h")}clearLine(){process.stdout.write("\x1B[K")}clearFromCursor(){process.stdout.write("\x1B[J")}clearScreen(){process.stdout.write("\x1B[2J\x1B[H")}setTitle(t){process.stdout.write(`\x1B]0;${t}\x07`)}setProgress(t){t?(process.stdout.write(h),this.progressInterval||(this.progressInterval=setInterval(()=>{process.stdout.write(h)},B))):(this.clearProgressInterval(),process.stdout.write(P))}clearProgressInterval(){return this.progressInterval?(clearInterval(this.progressInterval),this.progressInterval=void 0,!0):!1}}export{M as ProcessTerminal,I as isAppleTerminalSession,E as normalizeAppleTerminalInput,b as parseKeyboardProtocolNegotiationSequence};