@prometheus-ai/tui 0.5.3 → 0.5.8

package/src/index.ts

@@ -27,8 +27,10 @@ export * from "./fuzzy";
 export * from "./keybindings";
 // Kitty keyboard protocol helpers
 export * from "./keys";
-// Kitty graphics: Unicode placeholders + temp-file transmission
+// Kitty graphics: Unicode placeholders
 export * from "./kitty-graphics";
+// SGR mouse report parsing
+export * from "./mouse";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";

package/src/keybindings.ts

@@ -1,4 +1,4 @@
-import { type KeyId, matchesKey, parseKey } from "./keys";
+import { type KeyId, parseKey } from "./keys";
 
 /**
  * Global keybinding registry.
@@ -100,11 +100,11 @@ export const TUI_KEYBINDINGS = {
 		description: "Delete character forward",
 	},
 	"tui.editor.deleteWordBackward": {
-		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"],
 		description: "Delete word backward",
 	},
 	"tui.editor.deleteWordForward": {
-		defaultKeys: ["alt+delete", "alt+d"],
+		defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"],
 		description: "Delete word forward",
 	},
 	"tui.editor.deleteToLineStart": {
@@ -118,7 +118,7 @@ export const TUI_KEYBINDINGS = {
 	"tui.editor.yank": { defaultKeys: "ctrl+y", description: "Yank" },
 	"tui.editor.yankPop": { defaultKeys: "alt+y", description: "Yank pop" },
 	"tui.editor.undo": { defaultKeys: ["ctrl+-", "ctrl+_"], description: "Undo" },
-	"tui.input.newLine": { defaultKeys: "shift+enter", description: "Insert newline" },
+	"tui.input.newLine": { defaultKeys: ["shift+enter", "ctrl+j"], description: "Insert newline" },
 	"tui.input.submit": { defaultKeys: "enter", description: "Submit input" },
 	"tui.input.tab": { defaultKeys: "tab", description: "Tab / autocomplete" },
 	"tui.input.copy": { defaultKeys: "ctrl+c", description: "Copy selection" },
@@ -164,6 +164,64 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 	"~",
 ]);
 
+const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
+
+function startsWithModifier(key: string, offset: number, modifier: string): boolean {
+	if (key.length <= offset + modifier.length || key.charCodeAt(offset + modifier.length) !== 43) return false;
+	for (let i = 0; i < modifier.length; i++) {
+		const actual = key.charCodeAt(offset + i);
+		const expected = modifier.charCodeAt(i);
+		if (actual !== expected && actual !== expected - 32) return false;
+	}
+	return true;
+}
+
+function isAsciiUppercaseLetter(key: string): boolean {
+	if (key.length !== 1) return false;
+	const code = key.charCodeAt(0);
+	return code >= 65 && code <= 90;
+}
+
+export function canonicalKeyId(key: string): string {
+	let offset = 0;
+	const modifiers: string[] = [];
+	let foundModifier = true;
+
+	while (foundModifier) {
+		foundModifier = false;
+		for (const modifier of MODIFIER_ORDER) {
+			if (startsWithModifier(key, offset, modifier)) {
+				modifiers.push(modifier);
+				offset += modifier.length + 1;
+				foundModifier = true;
+				break;
+			}
+		}
+	}
+	const rawBase = key.slice(offset);
+	const lowerBase = rawBase.toLowerCase();
+	const base = lowerBase === "esc" ? "escape" : lowerBase === "return" ? "enter" : lowerBase;
+	if (isAsciiUppercaseLetter(rawBase) && !modifiers.includes("shift")) {
+		modifiers.push("shift");
+	}
+
+	if (modifiers.length === 0) return base;
+	modifiers.sort(
+		(left, right) =>
+			MODIFIER_ORDER.indexOf(left as (typeof MODIFIER_ORDER)[number]) -
+			MODIFIER_ORDER.indexOf(right as (typeof MODIFIER_ORDER)[number]),
+	);
+	return `${modifiers.join("+")}+${base}`;
+}
+
+export function addKeyAliases(keys: Set<string>, key: KeyId): void {
+	const canonical = canonicalKeyId(key);
+	keys.add(canonical);
+	if (SHIFTED_SYMBOL_KEYS.has(canonical)) {
+		keys.add(`shift+${canonical}`);
+	}
+}
+
 const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
 
 function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
@@ -185,6 +243,7 @@ export class KeybindingsManager {
 	#definitions: KeybindingDefinitions;
 	#userBindings: KeybindingsConfig;
 	#keysById = new Map<Keybinding, KeyId[]>();
+	#matchKeysById = new Map<Keybinding, Set<string>>();
 	#conflicts: KeybindingConflict[] = [];
 
 	constructor(definitions: KeybindingDefinitions, userBindings: KeybindingsConfig = {}) {
@@ -195,6 +254,7 @@ export class KeybindingsManager {
 
 	#rebuild(): void {
 		this.#keysById.clear();
+		this.#matchKeysById.clear();
 		this.#conflicts = [];
 
 		const userClaims = new Map<KeyId, Set<Keybinding>>();
@@ -217,21 +277,19 @@ export class KeybindingsManager {
 			const userKeys = this.#userBindings[id];
 			const keys = userKeys === undefined ? normalizeKeys(definition.defaultKeys) : normalizeKeys(userKeys);
 			this.#keysById.set(id as Keybinding, keys);
+			const matchKeys = new Set<string>();
+			for (const key of keys) {
+				addKeyAliases(matchKeys, key);
+			}
+			this.#matchKeysById.set(id as Keybinding, matchKeys);
 		}
 	}
 
 	matches(data: string, keybinding: Keybinding): boolean {
-		const keys = this.#keysById.get(keybinding) ?? [];
-		for (const key of keys) {
-			if (matchesKey(data, key)) return true;
-		}
-
-		// Handle shifted symbol keys (e.g., shift+- produces _ on US layout)
 		const parsed = parseKey(data);
-		if (!parsed?.startsWith("shift+")) return false;
-		const keyName = parsed.slice("shift+".length);
-		if (!SHIFTED_SYMBOL_KEYS.has(keyName)) return false;
-		return keys.includes(keyName as KeyId);
+		if (parsed === undefined) return false;
+		const matchKeys = this.#matchKeysById.get(keybinding);
+		return matchKeys?.has(canonicalKeyId(parsed)) ?? false;
 	}
 
 	getKeys(keybinding: Keybinding): KeyId[] {

package/src/keys.ts

@@ -195,7 +195,7 @@ export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
  * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
  * is `"ctrl+c"`, not just `string`). This mirrors the upstream
  * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
- * scope alias (`@mariozechner`, `@earendil-works`, `@prometheus`) keep working
+ * scope alias (`@mariozechner`, `@earendil-works`, `@Prometheus`) keep working
  * once the specifier shim remaps them to this package.
  */
 export const Key = {

package/src/kill-ring.ts

@@ -5,6 +5,8 @@
  * into a single entry. Supports yank (paste most recent) and yank-pop
  * (cycle through older entries).
  */
+const MAX_ENTRIES = 60;
+
 export class KillRing {
 	#ring: string[] = [];
 
@@ -24,6 +26,9 @@ export class KillRing {
 			this.#ring.push(opts.prepend ? text + last : last + text);
 		} else {
 			this.#ring.push(text);
+			if (this.#ring.length > MAX_ENTRIES) {
+				this.#ring.shift();
+			}
 		}
 	}
 

package/src/kitty-graphics.ts

@@ -1,6 +1,6 @@
 /**
- * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE) and temp-file
- * (`t=t`) image transmission, with runtime feature state and env overrides.
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
  *
  * Unicode placeholders let a transmitted image be displayed by writing ordinary
  * text cells — the placeholder char U+10EEEE plus row/column combining
@@ -14,10 +14,6 @@
  * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
  * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
  */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { $env, logger } from "@prometheus-ai/utils";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export const KITTY_PLACEHOLDER = "\u{10eeee}";
@@ -55,25 +51,9 @@ const ROWCOLUMN_DIACRITICS: readonly number[] = [
 /** Largest row/column index expressible with the diacritic table (one cell each). */
 export const KITTY_PLACEHOLDER_MAX_CELLS = ROWCOLUMN_DIACRITICS.length;
 
-/** A minimal opaque 1x1 PNG (base64) used for the temp-file support probe. */
-const PROBE_PNG_BASE64 =
-	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-
-export type KittyTransmissionMedium = "direct" | "temp-file";
-
 export interface KittyGraphicsFeatures {
 	/** Display images via Unicode placeholders instead of direct `a=p` placement. */
 	unicodePlaceholders: boolean;
-	/** How image data reaches the terminal: in-band base64 or a temp file. */
-	transmissionMedium: KittyTransmissionMedium;
-}
-
-/** Explicit transmission medium from `PROMETHEUS_KITTY_IMAGE_TRANSMISSION`, else "auto". */
-function transmissionOverride(): KittyTransmissionMedium | "auto" {
-	const raw = $env.PROMETHEUS_KITTY_IMAGE_TRANSMISSION?.trim().toLowerCase();
-	if (raw === "temp-file") return "temp-file";
-	if (raw === "direct") return "direct";
-	return "auto";
 }
 
 /**
@@ -106,8 +86,6 @@ let features: KittyGraphicsFeatures = {
 	// Off until `terminal-capabilities` seeds it from the detected terminal id —
 	// the default-on path corrupts wezterm and tmux-passthrough sessions.
 	unicodePlaceholders: false,
-	// Start direct; a successful probe (or explicit `temp-file` override) promotes.
-	transmissionMedium: transmissionOverride() === "temp-file" ? "temp-file" : "direct",
 };
 
 export function getKittyGraphics(): Readonly<KittyGraphicsFeatures> {
@@ -118,29 +96,11 @@ export function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void
 	features = { ...features, ...partial };
 }
 
-/**
- * Whether temp-file transmission may be promoted at runtime: forced via env,
- * disabled via env, otherwise auto (local sessions only — a temp file written
- * locally is not readable by a terminal on the far side of an SSH link).
- */
-export function kittyTempFileAllowed(): boolean {
-	const override = transmissionOverride();
-	if (override === "temp-file") return true;
-	if (override === "direct") return false;
-	// Auto: local sessions only — a temp file written here is not on the SSH peer.
-	return !$env.SSH_CONNECTION && !$env.SSH_CLIENT && !$env.SSH_TTY;
-}
-
 /** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
 export function kittyPlaceholdersFit(columns: number, rows: number): boolean {
 	return columns >= 1 && rows >= 1 && columns <= KITTY_PLACEHOLDER_MAX_CELLS && rows <= KITTY_PLACEHOLDER_MAX_CELLS;
 }
 
-/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
-export function isPngBase64(base64Data: string): boolean {
-	return base64Data.startsWith("iVBORw0KGgo");
-}
-
 function diacritic(index: number): string {
 	const cp = ROWCOLUMN_DIACRITICS[index];
 	return cp === undefined ? "" : String.fromCodePoint(cp);
@@ -209,62 +169,3 @@ export function renderKittyPlaceholderLines(opts: {
 	}
 	return grid;
 }
-
-/**
- * Path for a temp-file transmission. Kitty deletes a `t=t` file after reading it
- * **only** when the path contains the substring `tty-graphics-protocol`, so it is
- * embedded in the filename to keep the temp dir self-cleaning.
- */
-function tempGraphicsPath(tag: string): string {
-	return path.join(os.tmpdir(), `tty-graphics-protocol-${tag}-${process.pid}-${Date.now()}.png`);
-}
-
-/**
- * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
- * them to a temp file, and send the base64-encoded file path as payload. Returns
- * the APC string, or `null` on any failure (caller falls back to direct base64).
- *
- * Synchronous filesystem writes are mandated by the synchronous render pipeline
- * (`Image.render` → `renderImage` are sync); there is no async seam here.
- */
-export function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null {
-	try {
-		const bytes = Buffer.from(base64Png, "base64");
-		if (bytes.length === 0) return null;
-		const file = tempGraphicsPath(`i${imageId}`);
-		fs.writeFileSync(file, bytes);
-		const encodedPath = Buffer.from(file, "utf8").toString("base64");
-		return `\x1b_Ga=t,f=100,t=t,S=${bytes.length},q=2,i=${imageId};${encodedPath}\x1b\\`;
-	} catch (err) {
-		logger.debug("Kitty temp-file transmit failed; using direct base64", { err: String(err) });
-		return null;
-	}
-}
-
-/**
- * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
- * terminal to query it (`a=q,t=t`). A conforming terminal replies
- * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
- * removes the probe file (best-effort; kitty self-deletes the magic-named file).
- * Returns `null` if the temp file cannot be written.
- */
-export function encodeKittyTempFileProbe(probeId: number): { sequence: string; cleanup: () => void } | null {
-	try {
-		const bytes = Buffer.from(PROBE_PNG_BASE64, "base64");
-		const file = tempGraphicsPath(`probe${probeId}`);
-		fs.writeFileSync(file, bytes);
-		const encodedPath = Buffer.from(file, "utf8").toString("base64");
-		const sequence = `\x1b_Ga=q,t=t,f=100,S=${bytes.length},q=2,i=${probeId};${encodedPath}\x1b\\`;
-		const cleanup = () => {
-			try {
-				fs.rmSync(file, { force: true });
-			} catch {
-				// Best effort; kitty deletes tty-graphics-protocol files itself.
-			}
-		};
-		return { sequence, cleanup };
-	} catch (err) {
-		logger.debug("Kitty temp-file probe setup failed", { err: String(err) });
-		return null;
-	}
-}

package/src/loop-watchdog.ts

@@ -0,0 +1,106 @@
+import { performance } from "node:perf_hooks";
+import { logger, takeRecentLoopPhase } from "@prometheus-ai/utils";
+
+export interface LoopWatchdogOptions {
+	/** How far ahead each probe tick is scheduled, in ms. Default 250. */
+	intervalMs?: number;
+	/** A tick later than this past its deadline counts as a block. Default 250. */
+	thresholdMs?: number;
+	/** Monotonic clock source; injectable for tests. Default `performance.now`. */
+	now?: () => number;
+	/** Timer source; injectable for tests. Default `setTimeout`. */
+	schedule?: (cb: () => void, ms: number) => LoopWatchdogTimer;
+}
+
+/**
+ * Timer handle the watchdog arms. `cancel`, when present, is invoked on stop()
+ * so a stopped watchdog leaves no armed timer to wake the loop even once.
+ */
+interface LoopWatchdogTimer {
+	unref?(): void;
+	cancel?(): void;
+}
+
+/**
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
+ * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
+ * the loop was blocked that long. The overshoot is logged once on the rising
+ * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
+ * active during the elapsed interval via {@link takeRecentLoopPhase} — which
+ * survives the synchronous push/pop the instrumented hot paths do before this
+ * delayed tick can run — so the stall names its cause instead of "unknown".
+ *
+ * The handle is `unref`'d so the probe never keeps the process alive, and stop()
+ * cancels the armed timer when the handle exposes `cancel` (the default
+ * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
+ * as a fallback for injected handles that cannot cancel.
+ */
+export class LoopWatchdog {
+	#intervalMs: number;
+	#thresholdMs: number;
+	#now: () => number;
+	#schedule: (cb: () => void, ms: number) => LoopWatchdogTimer;
+	#expected = 0;
+	#wasBlocked = false;
+	#running = false;
+	// Bumped by stop(); each scheduled tick captures the generation it was armed
+	// under and no-ops if it no longer matches, so a start()→stop()→start() cycle
+	// cannot leave the pre-stop timer chain rescheduling itself in parallel.
+	#generation = 0;
+	#handle: LoopWatchdogTimer | undefined;
+
+	constructor(options: LoopWatchdogOptions = {}) {
+		this.#intervalMs = options.intervalMs ?? 250;
+		this.#thresholdMs = options.thresholdMs ?? 250;
+		this.#now = options.now ?? (() => performance.now());
+		this.#schedule =
+			options.schedule ??
+			((cb, ms) => {
+				const timer = setTimeout(cb, ms);
+				return { unref: () => timer.unref?.(), cancel: () => clearTimeout(timer) };
+			});
+	}
+
+	start(): void {
+		if (this.#running) return;
+		this.#running = true;
+		this.#wasBlocked = false;
+		this.#armTick();
+	}
+
+	stop(): void {
+		this.#running = false;
+		this.#wasBlocked = false;
+		this.#generation++;
+		this.#handle?.cancel?.();
+		this.#handle = undefined;
+	}
+
+	#armTick(): void {
+		const generation = this.#generation;
+		this.#expected = this.#now() + this.#intervalMs;
+		this.#handle = this.#schedule(() => this.#tick(generation), this.#intervalMs);
+		this.#handle.unref?.();
+	}
+
+	#tick(generation: number): void {
+		if (!this.#running || generation !== this.#generation) return;
+		const blockedMs = this.#now() - this.#expected;
+		// Consume the recent phase every tick (block or not) so attribution is
+		// scoped to the just-elapsed interval and never carries a stale phase
+		// forward to a later, phase-less block.
+		const phase = takeRecentLoopPhase();
+		if (blockedMs > this.#thresholdMs) {
+			if (!this.#wasBlocked) {
+				this.#wasBlocked = true;
+				logger.warn("ui.loop-blocked", {
+					blockedMs: Math.round(blockedMs),
+					phase: phase ?? "unknown",
+				});
+			}
+		} else {
+			this.#wasBlocked = false;
+		}
+		this.#armTick();
+	}
+}

package/src/mouse.ts

@@ -0,0 +1,55 @@
+/**
+ * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
+ *
+ * Mouse tracking is enabled only while a fullscreen overlay holds the
+ * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
+ * fullscreen components hit-testing against their own rendered frame:
+ * the frame paints from screen row 0, hence `row`/`col` are exposed
+ * 0-based for direct indexing into rendered lines.
+ */
+
+/** A decoded SGR mouse report. */
+export interface SgrMouseEvent {
+	/** Raw button code (bit 32 = motion, bit 64 = wheel, low bits = button). */
+	button: number;
+	/** 0-based column of the event. */
+	col: number;
+	/** 0-based row of the event. */
+	row: number;
+	/** True for a release report (`m` suffix). */
+	release: boolean;
+	/** Wheel direction: -1 up, 1 down, null when not a wheel event. */
+	wheel: -1 | 1 | null;
+	/** True when the pointer moved (hover or drag) rather than clicked. */
+	motion: boolean;
+	/** True for a left-button press (not motion, not release, not wheel). */
+	leftClick: boolean;
+}
+
+/**
+ * Decode an SGR mouse report, or return null when `data` is not one.
+ * Callers on hot keypress paths should pre-check `data.startsWith("\x1b[<")`
+ * before paying for the regex.
+ */
+export function parseSgrMouse(data: string): SgrMouseEvent | null {
+	const match = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(data);
+	if (!match) return null;
+	const button = Number(match[1]);
+	const col = Number(match[2]) - 1;
+	const row = Number(match[3]) - 1;
+	const release = match[4] === "m";
+	const wheel = button & 64 ? ((button & 1 ? 1 : -1) as 1 | -1) : null;
+	const motion = (button & 32) !== 0 && wheel === null;
+	const leftClick = !release && wheel === null && !motion && (button & 3) === 0;
+	return { button, col, row, release, wheel, motion, leftClick };
+}
+
+/**
+ * Implemented by components that accept routed mouse events at frame-local
+ * coordinates. Hosts translate screen coordinates to the component's own
+ * rendered lines before forwarding.
+ */
+export interface MouseRoutable {
+	/** `line`/`col` are 0-based within the component's rendered output. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}