@sayknow-cli/tui 0.2.3 → 0.2.5

package/dist/types/components/editor.d.ts

@@ -38,6 +38,7 @@ export declare class Editor implements Component, Focusable {
     onAltEnter?: (text: string) => void;
     onChange?: (text: string) => void;
     onAutocompleteCancel?: () => void;
+    onTabDeclined?: (text: string) => void;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
     setAutocompleteProvider(provider: AutocompleteProvider): void;

package/dist/types/keybindings.d.ts

@@ -35,6 +35,7 @@ export interface Keybindings {
     "tui.select.pageDown": true;
     "tui.select.confirm": true;
     "tui.select.cancel": true;
+    "tui.global.debug": true;
 }
 export type Keybinding = keyof Keybindings;
 export type { KeyId };
@@ -169,6 +170,10 @@ export declare const TUI_KEYBINDINGS: {
         readonly defaultKeys: ["escape", "ctrl+c"];
         readonly description: "Cancel selection";
     };
+    readonly "tui.global.debug": {
+        readonly defaultKeys: "shift+ctrl+d";
+        readonly description: "Toggle debug overlay";
+    };
 };
 export interface KeybindingConflict {
     key: KeyId;
@@ -185,5 +190,12 @@ export declare class KeybindingsManager {
     getUserBindings(): KeybindingsConfig;
     getResolvedBindings(): KeybindingsConfig;
 }
+/**
+ * Detect default-key collisions across the registry: keys whose default
+ * binding is claimed by more than one action. Cross-context collisions are
+ * often intentional (the dispatch context disambiguates them), so this is a
+ * diagnostics aid for auditing the surface, not an error by itself.
+ */
+export declare function detectDefaultKeyCollisions(definitions: KeybindingDefinitions): KeybindingConflict[];
 export declare function setKeybindings(keybindings: KeybindingsManager): void;
 export declare function getKeybindings(): KeybindingsManager;

package/dist/types/terminal.d.ts

@@ -11,6 +11,8 @@
  * Korean correctly.
  */
 export declare function keyboardEnhancementEnabled(): boolean;
+/** Error codes for terminal/pipe write failures that should never crash the process. */
+export declare function isBenignTerminalWriteError(err: unknown): boolean;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance
@@ -62,6 +64,8 @@ export declare class ProcessTerminal implements Terminal {
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;
+    /** Invoked by the durable module-level stdout write guard (see installStdoutWriteGuard). */
+    markStdoutUnavailable(err: unknown): void;
     get available(): boolean;
     get columns(): number;
     get rows(): number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.2.3",
-		"@sayknow-cli/utils": "0.2.3",
+		"@sayknow-cli/natives": "0.2.5",
+		"@sayknow-cli/utils": "0.2.5",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -447,6 +447,7 @@ export class Editor implements Component, Focusable {
 	onAltEnter?: (text: string) => void;
 	onChange?: (text: string) => void;
 	onAutocompleteCancel?: () => void;
+	onTabDeclined?: (text: string) => void;
 	disableSubmit: boolean = false;
 
 	// Custom top border (for status line integration)
@@ -1248,11 +1249,12 @@ export class Editor implements Component, Focusable {
 		else if (
 			(data.charCodeAt(0) === 10 && data.length > 1) || // Ctrl+Enter with modifiers
 			matchesKey(data, "ctrl+enter") || // Ctrl+Enter (Kitty/modifyOtherKeys, including lock bits/keypad Enter)
+			matchesKey(data, "ctrl+shift+enter") || // Ctrl+Shift+Enter (Kitty/modifyOtherKeys combined modifier)
 			data === "\x1b\r" || // Option+Enter in some terminals (legacy)
 			data === "\x1b[13;2~" || // Shift+Enter in some terminals (legacy format)
 			kb.matches(data, "tui.input.newLine") || // Shift+Enter (Kitty protocol, handles lock bits)
 			(data.length > 1 && data.includes("\x1b") && data.includes("\r")) ||
-			(data === "\n" && data.length === 1) // Shift+Enter from iTerm2 mapping
+			(data === "\n" && data.length === 1 && process.platform !== "win32") // Shift+Enter from iTerm2 mapping
 		) {
 			if (this.#shouldSubmitOnBackslashEnter(data, kb)) {
 				this.#handleBackspace();
@@ -2616,6 +2618,9 @@ export class Editor implements Component, Focusable {
 
 	// Autocomplete methods
 	async #tryTriggerAutocomplete(explicitTab: boolean = false): Promise<void> {
+		const declineExplicitTab = (): void => {
+			if (explicitTab) this.onTabDeclined?.(this.getText());
+		};
 		if (!this.#autocompleteProvider) return;
 		// Check if we should trigger file completion on Tab
 		if (explicitTab) {
@@ -2624,6 +2629,7 @@ export class Editor implements Component, Focusable {
 				!provider.shouldTriggerFileCompletion ||
 				provider.shouldTriggerFileCompletion(this.#state.lines, this.#state.cursorLine, this.#state.cursorCol);
 			if (!shouldTrigger) {
+				declineExplicitTab();
 				return;
 			}
 		}
@@ -2645,6 +2651,7 @@ export class Editor implements Component, Focusable {
 		} else {
 			this.#cancelAutocomplete();
 			this.onAutocompleteUpdate?.();
+			declineExplicitTab();
 		}
 	}
 	#createAutocompleteList(
@@ -2659,7 +2666,10 @@ export class Editor implements Component, Focusable {
 	}
 
 	#handleTabCompletion(): void {
-		if (!this.#autocompleteProvider) return;
+		if (!this.#autocompleteProvider) {
+			this.onTabDeclined?.(this.getText());
+			return;
+		}
 
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
@@ -2730,6 +2740,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 		} else {
 			this.#cancelAutocomplete();
 			this.onAutocompleteUpdate?.();
+			if (explicitTab) this.onTabDeclined?.(this.getText());
 		}
 	}
 

package/src/keybindings.ts

@@ -39,6 +39,8 @@ export interface Keybindings {
 	"tui.select.pageDown": true;
 	"tui.select.confirm": true;
 	"tui.select.cancel": true;
+	// Global engine actions
+	"tui.global.debug": true;
 }
 
 export type Keybinding = keyof Keybindings;
@@ -134,6 +136,10 @@ export const TUI_KEYBINDINGS = {
 		defaultKeys: ["escape", "ctrl+c"],
 		description: "Cancel selection",
 	},
+	"tui.global.debug": {
+		defaultKeys: "shift+ctrl+d",
+		description: "Toggle debug overlay",
+	},
 } as const satisfies KeybindingDefinitions;
 
 export interface KeybindingConflict {
@@ -265,6 +271,30 @@ export class KeybindingsManager {
 	}
 }
 
+/**
+ * Detect default-key collisions across the registry: keys whose default
+ * binding is claimed by more than one action. Cross-context collisions are
+ * often intentional (the dispatch context disambiguates them), so this is a
+ * diagnostics aid for auditing the surface, not an error by itself.
+ */
+export function detectDefaultKeyCollisions(definitions: KeybindingDefinitions): KeybindingConflict[] {
+	const claims = new Map<KeyId, Set<Keybinding>>();
+	for (const [id, definition] of Object.entries(definitions)) {
+		for (const key of normalizeKeys(definition.defaultKeys)) {
+			const claimants = claims.get(key) ?? new Set<Keybinding>();
+			claimants.add(id as Keybinding);
+			claims.set(key, claimants);
+		}
+	}
+	const collisions: KeybindingConflict[] = [];
+	for (const [key, keybindings] of claims) {
+		if (keybindings.size > 1) {
+			collisions.push({ key, keybindings: [...keybindings] });
+		}
+	}
+	return collisions;
+}
+
 let globalKeybindings: KeybindingsManager | null = null;
 
 export function setKeybindings(keybindings: KeybindingsManager): void {

package/src/keys.ts

@@ -305,6 +305,7 @@ const KITTY_MOD_SUPER = 8;
 const KITTY_MOD_NUM_LOCK = 128;
 const KITTY_LOCK_MASK = 64 + 128; // Caps Lock + Num Lock
 const MODIFY_OTHER_KEYS_PATTERN = /^\x1b\[27;(\d+);(\d+)~$/;
+const PSMUX_MODIFIED_ENTER_PATTERN = /^\x1b\[13;(2|6)~$/;
 const KITTY_KEYPAD_OPERATOR_TEXT: Record<number, string> = {
 	57410: "/",
 	57411: "*",
@@ -378,6 +379,20 @@ export function parseKittySequence(data: string): ParsedKittySequence | null {
 	};
 }
 
+function parsePsmuxModifiedEnter(data: string): string | undefined {
+	const match = data.match(PSMUX_MODIFIED_ENTER_PATTERN);
+	if (!match) return undefined;
+	return match[1] === "6" ? "shift+ctrl+enter" : "shift+enter";
+}
+
+function matchesPsmuxModifiedEnter(data: string, keyId: KeyId): boolean {
+	const parsed = parsePsmuxModifiedEnter(data);
+	if (!parsed) return false;
+	const expected = String(keyId);
+	if (parsed === expected) return true;
+	return parsed === "shift+ctrl+enter" && expected === "ctrl+shift+enter";
+}
+
 function hasControlChars(data: string): boolean {
 	return [...data].some(ch => {
 		const code = ch.charCodeAt(0);
@@ -521,7 +536,7 @@ export function decodePrintableKey(data: string): string | undefined {
  * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
  */
 export function matchesKey(data: string, keyId: KeyId): boolean {
-	return matchesKeyNative(data, keyId, kittyProtocolActive);
+	return matchesPsmuxModifiedEnter(data, keyId) || matchesKeyNative(data, keyId, kittyProtocolActive);
 }
 
 /**
@@ -533,5 +548,5 @@ export function matchesKey(data: string, keyId: KeyId): boolean {
  * @param data - Raw input data from terminal
  */
 export function parseKey(data: string): string | undefined {
-	return parseKeyNative(data, kittyProtocolActive) ?? undefined;
+	return parsePsmuxModifiedEnter(data) ?? parseKeyNative(data, kittyProtocolActive) ?? undefined;
 }

package/src/terminal.ts

@@ -33,6 +33,43 @@ let activeTerminal: ProcessTerminal | null = null;
 // Track if a terminal was ever started (for emergency restore logic)
 let terminalEverStarted = false;
 
+// ── Durable stdout write guard ───────────────────────────────────────────────
+// Bun flushes TTY writes asynchronously, so a write that fails after the terminal
+// disconnects (controlling-terminal hangup, external-volume stall, etc.) surfaces as
+// an "error" event on process.stdout on a LATER tick. During shutdown, stop() removes
+// its per-instance "error" handler synchronously, but the restore writes it just issued
+// flush afterwards — so their EIO/EPIPE error arrives with no listener attached and
+// becomes an uncaughtException. That crashes the process with a nonzero exit, turning a
+// benign terminal hangup into a "[Process exited] / press any key to restart" loop.
+//
+// This guard is installed once and never removed, so such asynchronous write errors are
+// always handled (swallowed) instead of crashing. It is intentionally minimal: a stdout
+// write failure in a TUI is never recoverable beyond "stop writing", which the active
+// terminal's #markUnavailable already handles.
+let stdoutWriteGuardInstalled = false;
+/** Error codes for terminal/pipe write failures that should never crash the process. */
+export function isBenignTerminalWriteError(err: unknown): boolean {
+	const code = (err as { code?: unknown } | null | undefined)?.code;
+	return (
+		code === "EIO" ||
+		code === "EPIPE" ||
+		code === "EBADF" ||
+		code === "ENXIO" ||
+		code === "ENOTTY" ||
+		code === "ECONNRESET"
+	);
+}
+function installStdoutWriteGuard(): void {
+	if (stdoutWriteGuardInstalled) return;
+	stdoutWriteGuardInstalled = true;
+	process.stdout.on("error", (err: Error) => {
+		// Best-effort: mark the active terminal dead so it stops issuing further writes.
+		// The crucial part is simply that a listener EXISTS, so an asynchronous write
+		// failure is "handled" rather than promoted to a fatal uncaughtException.
+		activeTerminal?.markStdoutUnavailable(err);
+	});
+}
+
 const STD_INPUT_HANDLE = -10;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
 /**
@@ -41,6 +78,9 @@ const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
  */
 export function emergencyTerminalRestore(): void {
 	try {
+		// Ensure the durable guard is present even if we reach here via the blind-restore
+		// path below without a live ProcessTerminal (idempotent).
+		installStdoutWriteGuard();
 		const terminal = activeTerminal;
 		if (terminal) {
 			terminal.stop();
@@ -175,6 +215,10 @@ export class ProcessTerminal implements Terminal {
 		// Register for emergency cleanup
 		activeTerminal = this;
 		terminalEverStarted = true;
+		// Install the durable stdout write guard before issuing ANY terminal writes, so
+		// an asynchronous EIO/EPIPE flush failure can never escape as an uncaughtException
+		// (which would crash the process and trigger a host restart loop).
+		installStdoutWriteGuard();
 
 		// Save previous state and enable raw mode
 		this.#wasRaw = process.stdin.isRaw || false;
@@ -700,6 +744,11 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	/** Invoked by the durable module-level stdout write guard (see installStdoutWriteGuard). */
+	markStdoutUnavailable(err: unknown): void {
+		this.#markUnavailable(err, "stdout-error");
+	}
+
 	#markUnavailable(err: unknown, operation: string): void {
 		if (this.#dead) return;
 		this.#dead = true;

package/src/tui.ts

@@ -5,7 +5,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { $flag, getDebugLogPath } from "@sayknow-cli/utils";
-import { isKeyRelease, matchesKey } from "./keys";
+import { getKeybindings } from "./keybindings";
+import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
 import type { Terminal } from "./terminal";
 import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
@@ -842,8 +843,8 @@ export class TUI extends Container {
 			return;
 		}
 
-		// Global debug key handler (Shift+Ctrl+D)
-		if (matchesKey(data, "shift+ctrl+d") && this.onDebug) {
+		// Global debug key handler (registry: tui.global.debug, default Shift+Ctrl+D)
+		if (getKeybindings().matches(data, "tui.global.debug") && this.onDebug) {
 			this.onDebug();
 			return;
 		}