magus-cli 7.3.1 → 7.4.1

package/src/ui/input/KeyRouter.tsx

@@ -0,0 +1,304 @@
+/**
+ * The one keyboard subscriber in the React tree — and the one paste subscriber.
+ *
+ * Components do not call `useKeyboard`, and no screen listens for a paste of
+ * its own. They register a LAYER — modal, input, screen, scroll or global — and
+ * this router offers each key to the live layers through `dispatchKey`, top
+ * first, so exactly one of them acts on it. The system layer (Ctrl+C) is not
+ * here: `src/tui.tsx` takes that key on the renderer before this subscriber
+ * runs and stops it there.
+ *
+ * Each key is dispatched inside `flushSync`, so everything a key changes is
+ * committed — and every layer's `active` flag and handler refreshed — before the
+ * next key is looked at. A fast typist delivers several keys in one stdin read;
+ * without this, `/abc` would open the search box and then send `a`, `b` and `c`
+ * to the screen underneath, whose handlers still believed the box was closed.
+ *
+ * A PASTE is NOT that burst of keys. Bracketed paste is on (OpenTUI's native
+ * core writes `ESC[?2004h`), so the terminal wraps the clipboard in
+ * `ESC[200~ … ESC[201~` and the renderer emits ONE `paste` event carrying the
+ * whole text — and no `keypress` at all. That is why a search term pasted into
+ * a filter box used to vanish without a trace: every layer here listened for
+ * keys that were never sent. `dispatchPaste` runs the same layer order over the
+ * layers that registered a paste handler.
+ *
+ * The paste event is deliberately NOT stopped: OpenTUI hands it to the focused
+ * renderable afterwards, which is how the input modal's `<input>` still takes a
+ * paste of its own — exactly the arrangement the modal layer relies on for keys.
+ */
+
+import { appendFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { KeyEvent, PasteEvent } from "@opentui/core";
+import { decodePasteBytes, stripAnsiSequences } from "@opentui/core";
+import { flushSync, useKeyboard, useRenderer } from "@opentui/react";
+import {
+	type ReactNode,
+	createContext,
+	useContext,
+	useEffect,
+	useLayoutEffect,
+	useState,
+} from "react";
+import {
+	SCREEN_BINDINGS,
+	type ScreenHandlers,
+	runBindings,
+} from "../keymap.js";
+import type { Screen } from "../state/types.js";
+import {
+	type KeyLayer,
+	type KeyLayerId,
+	type KeyPress,
+	type PasteLayer,
+	dispatchKey,
+	dispatchPaste,
+	inputLayerConsumes,
+	typedCharacter,
+} from "./key-dispatch.js";
+
+/** The two registries the router dispatches over. */
+interface LayerRegistry {
+	keys: Set<KeyLayer>;
+	pastes: Set<PasteLayer>;
+}
+
+const LayersContext = createContext<LayerRegistry | null>(null);
+
+/** OpenTUI's key event, reduced to the fields the dispatcher reads. */
+export function toKeyPress(event: KeyEvent): KeyPress {
+	return {
+		name: event.name ?? "",
+		sequence: event.sequence ?? "",
+		ctrl: event.ctrl === true,
+		meta: event.meta === true,
+		shift: event.shift === true,
+	};
+}
+
+/**
+ * The text a paste event carries, as a single-line search term.
+ *
+ * Three things are stripped, in this order. The bytes are decoded as UTF-8
+ * (`decodePasteBytes`). Any ANSI escape the clipboard carried is removed — a
+ * terminal forwards the clipboard verbatim inside the brackets, so copying
+ * coloured output pastes its escape sequences too, and they are not a search
+ * term. Then every remaining control character goes: a newline or a tab becomes
+ * one space, so a multi-line clipboard reads as words rather than running the
+ * lines together, and the rest are dropped outright.
+ *
+ * The ends are trimmed last, because a copied line almost always carries its
+ * trailing newline and a query ending in a space matches nothing.
+ */
+export function pastedText(event: PasteEvent): string {
+	const decoded = stripAnsiSequences(decodePasteBytes(event.bytes));
+	let out = "";
+	for (const ch of decoded) {
+		const cp = ch.codePointAt(0) ?? 0;
+		// Newline, carriage return, tab: one space — and a RUN of them one space
+		// too, so a CRLF clipboard does not double-space every line break.
+		if (cp === 0x0a || cp === 0x0d || cp === 0x09) {
+			if (!out.endsWith(" ")) out += " ";
+			continue;
+		}
+		// The rest of C0 and C1, dropped. Written as codepoint bounds rather
+		// than a regex character class because the formatter rewrites a
+		// `\u0000` escape inside a regex literal into the raw byte it stands
+		// for — which puts literal control characters in this source file.
+		if (cp < 0x20 || (cp >= 0x7f && cp <= 0x9f)) continue;
+		out += ch;
+	}
+	return out.trim();
+}
+
+/**
+ * `MAGUS_DEBUG_KEYS=1` appends every key and the layer that took it to
+ * `magus-keys.log` in the temp directory — the first thing to look at when a
+ * key "does nothing". A paste is logged the same way, as `paste`.
+ */
+function logKey(what: string, consumer: KeyLayerId | null): void {
+	if (process.env.MAGUS_DEBUG_KEYS !== "1") return;
+	try {
+		appendFileSync(
+			path.join(os.tmpdir(), "magus-keys.log"),
+			`${new Date().toISOString()} ${what} -> ${consumer ?? "nobody"}\n`,
+		);
+	} catch {
+		// Best-effort logging: never let it break a keypress.
+	}
+}
+
+function describeKey(key: KeyPress): string {
+	return `name=${JSON.stringify(key.name)} seq=${JSON.stringify(key.sequence)} ctrl=${key.ctrl} meta=${key.meta} shift=${key.shift}`;
+}
+
+export function KeyRouter({ children }: { children: ReactNode }) {
+	const [layers] = useState<LayerRegistry>(() => ({
+		keys: new Set<KeyLayer>(),
+		pastes: new Set<PasteLayer>(),
+	}));
+	const renderer = useRenderer();
+
+	useKeyboard((event) => {
+		const key = toKeyPress(event);
+		let consumer: KeyLayerId | null = null;
+		flushSync(() => {
+			consumer = dispatchKey([...layers.keys], key);
+		});
+		logKey(describeKey(key), consumer);
+	});
+
+	// The ONE paste subscriber. `useKeyboard` has no paste counterpart in
+	// @opentui/react, so this listens on the renderer's key input directly —
+	// once, here, rather than once per screen.
+	useEffect(() => {
+		const onPaste = (event: PasteEvent): void => {
+			const text = pastedText(event);
+			let consumer: KeyLayerId | null = null;
+			flushSync(() => {
+				consumer = dispatchPaste([...layers.pastes], text);
+			});
+			logKey(`paste=${JSON.stringify(text)}`, consumer);
+		};
+		renderer.keyInput.on("paste", onPaste);
+		return () => {
+			renderer.keyInput.off("paste", onPaste);
+		};
+	}, [renderer, layers]);
+
+	return (
+		<LayersContext.Provider value={layers}>{children}</LayersContext.Provider>
+	);
+}
+
+/**
+ * Register a key layer for as long as the calling component is mounted.
+ *
+ * `active` and `handle` are refreshed on every commit, so the router always
+ * calls the handler from the latest render — never a stale closure.
+ */
+export function useKeyLayer(
+	id: KeyLayerId,
+	active: boolean,
+	handle: (key: KeyPress) => boolean,
+): void {
+	const layers = useContext(LayersContext);
+	if (!layers) throw new Error("useKeyLayer needs a <KeyRouter> above it");
+	const [entry] = useState<KeyLayer>(() => ({ id, active, handle }));
+
+	useLayoutEffect(() => {
+		entry.id = id;
+		entry.active = active;
+		entry.handle = handle;
+	});
+
+	useLayoutEffect(() => {
+		layers.keys.add(entry);
+		return () => {
+			layers.keys.delete(entry);
+		};
+	}, [layers, entry]);
+}
+
+/**
+ * Register a PASTE layer for as long as the calling component is mounted.
+ *
+ * The counterpart of {@link useKeyLayer}, and refreshed on every commit the
+ * same way. A component registers this only when a paste means something to it:
+ * a layer that does not is simply absent from the order, and the paste falls
+ * through it.
+ */
+export function usePasteLayer(
+	id: KeyLayerId,
+	active: boolean,
+	handlePaste: (text: string) => boolean,
+): void {
+	const layers = useContext(LayersContext);
+	if (!layers) throw new Error("usePasteLayer needs a <KeyRouter> above it");
+	const [entry] = useState<PasteLayer>(() => ({ id, active, handlePaste }));
+
+	useLayoutEffect(() => {
+		entry.id = id;
+		entry.active = active;
+		entry.handlePaste = handlePaste;
+	});
+
+	useLayoutEffect(() => {
+		layers.pastes.add(entry);
+		return () => {
+			layers.pastes.delete(entry);
+		};
+	}, [layers, entry]);
+}
+
+/**
+ * The screen layer: one handler per binding the keymap declares for `screen`.
+ * `active: false` stands the layer down without unmounting it.
+ */
+export function useScreenKeys<S extends Screen>(
+	screen: S,
+	handlers: ScreenHandlers<S>,
+	active = true,
+): void {
+	useKeyLayer("screen", active, (key) =>
+		runBindings(SCREEN_BINDINGS[screen], handlers, key),
+	);
+}
+
+/** A screen's search box, as the input layer drives it. */
+export interface SearchBox {
+	/** The box has focus: what the user types goes into it. */
+	focused: boolean;
+	query: string;
+	/** Add text: one typed character, or a whole pasted term. */
+	append(text: string): void;
+	/** Delete the last character. */
+	erase(): void;
+	/** Empty the box and stay in it. */
+	clear(): void;
+	/** Leave the box. The filter stays as typed. */
+	blur(): void;
+}
+
+/**
+ * The input layer for a search box.
+ *
+ * While focused it takes every printable key — digits, `j`, `k`, `q`, `?` and
+ * space are typed, not acted on — plus Backspace, Enter (keep the filter, leave
+ * the box) and Esc (clear the text; on an empty box, leave). Up/Down, Tab and the
+ * scroll keys pass through: the list still moves, tabs still cycle, the panel
+ * still scrolls.
+ *
+ * It is the input layer for a PASTE too, and the only layer that takes one:
+ * pasted text is appended to the query exactly as typing it would be. With no
+ * box focused nothing consumes a paste — it must never reach the screen or the
+ * global keys, where a clipboard holding `q` would quit the app.
+ */
+export function useSearchInput(box: SearchBox): void {
+	usePasteLayer("input", box.focused, (text) => {
+		box.append(text);
+		return true;
+	});
+
+	useKeyLayer("input", box.focused, (key) => {
+		if (!inputLayerConsumes(key)) return false;
+		switch (key.name) {
+			case "return":
+			case "enter":
+				box.blur();
+				return true;
+			case "escape":
+				if (box.query.length > 0) box.clear();
+				else box.blur();
+				return true;
+			case "backspace":
+			case "delete":
+				box.erase();
+				return true;
+		}
+		const char = typedCharacter(key);
+		if (char !== null) box.append(char);
+		return true;
+	});
+}

package/src/ui/input/key-dispatch.ts

@@ -0,0 +1,197 @@
+/**
+ * One keypress, one handler.
+ *
+ * OpenTUI's `useKeyboard` is a broadcast: every subscriber receives every key,
+ * with no way for one to stop the next. magus used to have a dozen subscribers
+ * — the global keys, the panel scroll keys, each screen, each modal — and each
+ * one guessed from render-time flags (`modal`, `isSearching`, `detailActive`)
+ * whether the key was meant for it. The guesses disagreed: Esc that cleared a
+ * filter also ran the global Esc and quit, Enter in a confirm dialog also acted
+ * on the row underneath, and `j`/`k` moved the cursor before a search box could
+ * type them.
+ *
+ * This module replaces the guessing with an order. Every key is offered to the
+ * layers top first, and the first layer that consumes it is the only one that
+ * acts:
+ *
+ *   system → modal → input → screen → scroll → global
+ *
+ * - system: Ctrl+C. Taken in `src/tui.tsx` on the renderer itself, before the
+ *   React tree sees any key, so it quits even under a modal or a crashed screen.
+ * - modal:  an open dialog (or the help overlay) takes every key.
+ * - input:  a focused search box takes what it types — see `inputLayerConsumes`.
+ * - screen: the current screen's bindings, from `ui/keymap.ts`.
+ * - scroll: PgUp / PgDn / Ctrl+U / Ctrl+D scroll the detail panel.
+ * - global: tab digits, Tab, `q`, `?`, Esc.
+ *
+ * A PASTE follows the same order through `dispatchPaste`, over the layers that
+ * registered a paste handler. It is a separate entry point because a paste is a
+ * separate terminal event, not a burst of keys — see {@link PasteLayer}.
+ *
+ * Pure: no React, no OpenTUI. `KeyRouter.tsx` feeds it the live layers.
+ */
+
+/**
+ * A keypress, named the way OpenTUI names it: "a", "1", "?", "space",
+ * "return", "escape", "backspace", "up", "down", "pageup", "pagedown", "tab".
+ * A shifted letter keeps its lowercase name with `shift` set (Shift+U is
+ * `{ name: "u", shift: true, sequence: "U" }`); Ctrl+U is `{ name: "u", ctrl: true }`.
+ */
+export interface KeyPress {
+	name: string;
+	sequence: string;
+	ctrl: boolean;
+	meta: boolean;
+	shift: boolean;
+}
+
+export type KeyLayerId =
+	| "system"
+	| "modal"
+	| "input"
+	| "screen"
+	| "scroll"
+	| "global";
+
+/** Top first. A layer only sees a key every layer above it declined. */
+export const LAYER_ORDER: readonly KeyLayerId[] = [
+	"system",
+	"modal",
+	"input",
+	"screen",
+	"scroll",
+	"global",
+];
+
+export interface KeyLayer {
+	id: KeyLayerId;
+	/** An inactive layer is skipped without its handler being called. */
+	active: boolean;
+	/** True when the layer consumed the key; nothing below it will see it. */
+	handle(key: KeyPress): boolean;
+}
+
+/**
+ * Offer `key` to the active layers in LAYER_ORDER — whatever order the array is
+ * in — and stop at the first that consumes it. Returns that layer's id, or null
+ * when no layer wanted the key. Layers below the consumer are never called.
+ *
+ * Several layers may share an id (two components can each register a screen
+ * layer); within one id they are asked in array order.
+ */
+export function dispatchKey(
+	layers: readonly KeyLayer[],
+	key: KeyPress,
+): KeyLayerId | null {
+	for (const id of LAYER_ORDER) {
+		for (const layer of layers) {
+			if (layer.id !== id || !layer.active) continue;
+			if (layer.handle(key)) return id;
+		}
+	}
+	return null;
+}
+
+/**
+ * A layer that can take a PASTE.
+ *
+ * A terminal does not deliver a paste as keys. With bracketed paste on — and
+ * OpenTUI's native core turns it on — the whole clipboard arrives wrapped in
+ * `ESC[200~ … ESC[201~` and reaches the renderer as ONE `paste` event; no
+ * `keypress` is emitted for any of its characters. So a layer that only
+ * implements `handle()` never sees a pasted search term at all.
+ *
+ * Separate from {@link KeyLayer} because most layers have nothing to do with a
+ * paste: a tab digit, `q` or a scroll key is a keystroke, and pasting "q" must
+ * not quit.
+ */
+export interface PasteLayer {
+	id: KeyLayerId;
+	/** An inactive layer is skipped without its handler being called. */
+	active: boolean;
+	/** True when the layer consumed the text; nothing below it will see it. */
+	handlePaste(text: string): boolean;
+}
+
+/**
+ * Offer pasted `text` to the active layers in LAYER_ORDER and stop at the first
+ * that consumes it — the same rule {@link dispatchKey} follows, so a paste
+ * lands where a keystroke would: a focused search box takes it, a modal above
+ * it takes it first, and with neither open nothing consumes it.
+ *
+ * Empty text is offered to nobody: there is nothing to insert, and a layer that
+ * consumed it would only report a phantom edit.
+ */
+export function dispatchPaste(
+	layers: readonly PasteLayer[],
+	text: string,
+): KeyLayerId | null {
+	if (text.length === 0) return null;
+	for (const id of LAYER_ORDER) {
+		for (const layer of layers) {
+			if (layer.id !== id || !layer.active) continue;
+			if (layer.handlePaste(text)) return id;
+		}
+	}
+	return null;
+}
+
+/** PgUp, PgDn, Ctrl+U, Ctrl+D — the keys that scroll the detail panel. */
+export function isScrollKey(key: KeyPress): boolean {
+	if (key.meta) return false;
+	if (key.name === "pageup" || key.name === "pagedown") return true;
+	return key.ctrl && (key.name === "u" || key.name === "d");
+}
+
+/** True for a single printable character: no control bytes, no escape sequences. */
+function isPrintable(text: string): boolean {
+	const chars = [...text];
+	if (chars.length !== 1) return false;
+	const code = chars[0]?.codePointAt(0) ?? 0;
+	return code >= 0x20 && code !== 0x7f;
+}
+
+/**
+ * The character a keypress types, or null when it types nothing.
+ *
+ * `sequence` first: it is the literal text for a plain key, and under the kitty
+ * keyboard protocol OpenTUI puts the produced text there too. `name` is the
+ * fallback for a printable key whose sequence is an escape (kitty's Space).
+ */
+export function typedCharacter(key: KeyPress): string | null {
+	if (key.ctrl || key.meta) return null;
+	if (isPrintable(key.sequence)) return key.sequence;
+	if (key.name === "space") return " ";
+	if (isPrintable(key.name)) {
+		return key.shift && /^[a-z]$/.test(key.name)
+			? key.name.toUpperCase()
+			: key.name;
+	}
+	return null;
+}
+
+/** The editing keys a focused box owns besides the characters it types. */
+const INPUT_EDIT_KEYS = new Set([
+	"backspace",
+	"delete",
+	"return",
+	"enter",
+	"escape",
+]);
+
+/**
+ * Does a focused search/edit box take this key?
+ *
+ * Yes: any printable character — letters, digits, punctuation including `?`,
+ * space — plus Backspace, Enter and Esc. They are typed or edit the box; they
+ * do not switch tab, move the selection, quit or open help.
+ *
+ * No: Up/Down (the screen moves the selection), Tab (the global layer cycles
+ * tabs), the scroll keys (the panel keeps scrolling while you type), Ctrl+C,
+ * and any other Ctrl or Meta chord.
+ */
+export function inputLayerConsumes(key: KeyPress): boolean {
+	if (key.ctrl || key.meta) return false;
+	if (INPUT_EDIT_KEYS.has(key.name)) return true;
+	return typedCharacter(key) !== null;
+}