@linxiraos/pi-tui 1.0.0

package/src/deccara.ts

@@ -0,0 +1,314 @@
+/**
+ * DECCARA rectangular-SGR background-fill optimizer.
+ *
+ * Kitty extends VT510 DECCARA ("Change Attributes in Rectangular Area") to all
+ * SGR attributes, including background color, so a solid background panel can be
+ * painted as a single rectangle escape instead of a full-width run of
+ * background-styled spaces on every row (see kitty `docs/deccara.rst`):
+ *
+ *   <ESC>[2*x                 DECSACE: select rectangle change extent
+ *   <ESC>[Pt;Pl;Pb;Pr;<sgr>$r DECCARA: apply <sgr> to rows Pt..Pb, cols Pl..Pr
+ *   <ESC>[*x                  DECSACE: restore default extent
+ *
+ * Coordinates are 1-based and inclusive. This module is a pure, renderer-level
+ * planner: it consumes the *final* ANSI strings the renderer would otherwise
+ * write, strips the trailing background-padded spaces it can prove are safe to
+ * drop, and returns the rectangles to emit in their place. It never mutates
+ * component output and never decides which rows are scrollback-bound — those
+ * concerns belong to the caller in `tui.ts`.
+ */
+import { visibleWidth } from "./utils";
+
+/** Reset every attribute (SGR 0). Mirrors `tui.ts`'s per-line terminator. */
+const SEGMENT_RESET = "\x1b[0m";
+
+/** DECSACE — select the rectangle change extent so DECCARA fills a rectangle. */
+export const DECSACE_RECT = "\x1b[2*x";
+/** DECSACE — restore the default (stream) change extent. */
+export const DECSACE_DEFAULT = "\x1b[*x";
+
+/**
+ * Byte cost of the per-frame DECSACE wrapper ({@link DECSACE_RECT} +
+ * {@link DECSACE_DEFAULT}) that brackets every rectangle batch. Charged once per
+ * frame: a plan is emitted only when the trailing-space bytes it removes exceed
+ * the rectangles' own bytes by more than this, so the optimizer never inflates.
+ */
+const DECSACE_WRAPPER_BYTES = DECSACE_RECT.length + DECSACE_DEFAULT.length;
+
+/**
+ * Encode a single DECCARA rectangle. `top`/`bottom` are 1-based inclusive screen
+ * rows, `left`/`right` 1-based inclusive columns, `sgr` the raw SGR parameter
+ * list to apply (e.g. `48;2;10;20;30`, `48;5;4`, `41`).
+ */
+export function encodeDeccara(top: number, left: number, bottom: number, right: number, sgr: string): string {
+	return `\x1b[${top};${left};${bottom};${right};${sgr}$r`;
+}
+
+/** Sentinel for a background form this optimizer refuses to reason about. */
+const BAIL = Symbol("deccara-bail");
+type BgState = string | null;
+
+/**
+ * Fold one SGR parameter list into the active background-color parameter string.
+ * Returns the new background (`null` = default/no background) or {@link BAIL}
+ * when the sequence contains a background form this optimizer will not reason
+ * about (colon-form extended color, malformed params). Foreground and style
+ * parameters are skipped; only background state is tracked.
+ */
+function nextBackground(bg: BgState, params: string): BgState | typeof BAIL {
+	// CSI m with no parameters is SGR 0 (reset everything).
+	if (params.length === 0) return null;
+	const tokens = params.split(";");
+	let result: BgState = bg;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		// An empty parameter defaults to 0 (reset), matching terminal behavior.
+		const n = token.length === 0 ? 0 : Number(token);
+		if (!Number.isInteger(n)) return BAIL;
+		if (n === 0 || n === 49) {
+			result = null;
+			continue;
+		}
+		if ((n >= 40 && n <= 47) || (n >= 100 && n <= 107)) {
+			result = token;
+			continue;
+		}
+		if (n === 48) {
+			const mode = tokens[i + 1];
+			if (mode === "5") {
+				const idx = tokens[i + 2];
+				if (idx === undefined) return BAIL;
+				result = `48;5;${idx}`;
+				i += 2;
+				continue;
+			}
+			if (mode === "2") {
+				const r = tokens[i + 2];
+				const g = tokens[i + 3];
+				const b = tokens[i + 4];
+				if (r === undefined || g === undefined || b === undefined) return BAIL;
+				result = `48;2;${r};${g};${b}`;
+				i += 4;
+				continue;
+			}
+			// Colon-form (`48:2:...`) collapses to a single non-integer token and is
+			// rejected above; anything else following 48 is unexpected — bail.
+			return BAIL;
+		}
+		if (n === 38) {
+			// Foreground extended color: skip its sub-parameters, leave bg alone.
+			const mode = tokens[i + 1];
+			if (mode === "5") {
+				i += 2;
+				continue;
+			}
+			if (mode === "2") {
+				i += 4;
+				continue;
+			}
+			return BAIL;
+		}
+		// Every other parameter (foreground 30-39/90-97, styles) leaves bg alone.
+	}
+	return result;
+}
+
+/** Where to cut a fillable line and the background to paint over the remainder. */
+export interface BgFillAnalysis {
+	/** Byte index where droppable trailing background padding begins (0 = whole line). */
+	cut: number;
+	/** 0-based column where the trailing padding begins (DECCARA left = leftCol + 1). */
+	leftCol: number;
+	/** SGR parameter list of the background covering the trailing region. */
+	bg: string;
+}
+
+/**
+ * Decide whether `line` (a final, width-fit, reset-terminated ANSI string) is a
+ * full-width background fill whose trailing padding can be replaced by a DECCARA
+ * rectangle. Returns `null` unless it can *prove* the dropped bytes are literal
+ * trailing spaces under a single, constant, non-default background span (or the
+ * entire row is background-styled spaces).
+ *
+ * Conservative by construction: any OSC sequence (hyperlinks/images), any
+ * non-SGR CSI, a partial row, an inconsistent or default trailing background, or
+ * a malformed escape all yield `null` so the caller keeps the exact original.
+ */
+export function analyzeBgFillLine(line: string, width: number): BgFillAnalysis | null {
+	if (width <= 0 || line.length === 0) return null;
+	let i = 0;
+	let col = 0;
+	let bg: BgState = null;
+	// Byte index / column immediately after the last non-space printable glyph.
+	let nonSpaceEndByte = 0;
+	let nonSpaceEndCol = 0;
+	// Background covering the current trailing run of spaces, and whether that
+	// trailing run has started. `null` is a real "default background" value, so
+	// it cannot double as the uninitialized sentinel.
+	let trailBg: BgState = null;
+	let trailStarted = false;
+	let trailConsistent = true;
+
+	while (i < line.length) {
+		if (line.charCodeAt(i) === 0x1b) {
+			// Only CSI SGR (`\x1b[ ... m`) is tolerated. OSC, APC, and any other
+			// CSI mean styled hyperlinks/images/cursor markers — refuse to touch.
+			if (line.charCodeAt(i + 1) !== 0x5b) return null;
+			let j = i + 2;
+			while (j < line.length) {
+				const c = line.charCodeAt(j);
+				if (c >= 0x40 && c <= 0x7e) break;
+				j++;
+			}
+			if (j >= line.length) return null; // unterminated CSI
+			if (line.charCodeAt(j) !== 0x6d) return null; // non-SGR CSI (final byte != 'm')
+			const next = nextBackground(bg, line.slice(i + 2, j));
+			if (next === BAIL) return null;
+			bg = next;
+			i = j + 1;
+			continue;
+		}
+
+		// Printable run up to the next escape.
+		let j = i;
+		while (j < line.length && line.charCodeAt(j) !== 0x1b) j++;
+		const text = line.slice(i, j);
+		let nonSpaceLen = text.length;
+		while (nonSpaceLen > 0 && text.charCodeAt(nonSpaceLen - 1) === 0x20) nonSpaceLen--;
+
+		if (nonSpaceLen > 0) {
+			// Run carries a non-space glyph: the trailing region restarts after it.
+			const nonSpaceWidth = visibleWidth(text.slice(0, nonSpaceLen));
+			nonSpaceEndByte = i + nonSpaceLen;
+			nonSpaceEndCol = col + nonSpaceWidth;
+			// Spaces after the last non-space glyph in this same printable run sit
+			// under the current bg. If there are none, the trailing region has not
+			// started yet; a later SGR can still begin a uniform fill safely.
+			if (nonSpaceLen < text.length) {
+				trailBg = bg;
+				trailStarted = true;
+			} else {
+				trailBg = null;
+				trailStarted = false;
+			}
+			trailConsistent = true;
+		} else if (text.length > 0) {
+			// Whole run is spaces: it extends the trailing region. Track bg drift.
+			if (!trailStarted) {
+				trailBg = bg;
+				trailStarted = true;
+			} else if (bg !== trailBg) {
+				trailConsistent = false;
+			}
+		}
+		col += visibleWidth(text);
+		i = j;
+	}
+
+	if (col !== width) return null; // not a full-width fill
+	if (nonSpaceEndCol >= width) return null; // no trailing padding to drop
+	if (!trailStarted || trailBg === null || !trailConsistent) return null; // default/mixed bg — nothing safe to paint
+	return { cut: nonSpaceEndByte, leftCol: nonSpaceEndCol, bg: trailBg };
+}
+
+interface FillCandidate {
+	left: number;
+	right: number;
+	bg: string;
+	short: string;
+	origLen: number;
+}
+
+/** Per-frame plan: the (possibly shortened) row strings and the DECCARA batch. */
+export interface DeccaraPlan {
+	/** Row strings to write, parallel to the input. Optimized rows are shortened. */
+	texts: string[];
+	/** DECSACE-wrapped rectangle batch to emit after the rows, or `""` if none. */
+	sequence: string;
+}
+
+/**
+ * Plan DECCARA rectangles for a contiguous block of visible rows.
+ *
+ * `lines[k]` is the final ANSI string for screen row `firstScreenRow + k`
+ * (0-based). For each fillable row the trailing background padding is removed
+ * (the row's cells are cleared/erased by the caller, then repainted by the
+ * rectangle), and vertically adjacent rows with an identical left/right/bg span
+ * coalesce into one rectangle. Rectangles are emitted only when they save more
+ * bytes than they cost, so the result never exceeds the original byte count.
+ */
+export function planDeccaraFills(lines: string[], width: number, firstScreenRow = 0): DeccaraPlan {
+	const n = lines.length;
+	const texts: string[] = new Array(n);
+	const candidates: (FillCandidate | null)[] = new Array(n);
+
+	for (let k = 0; k < n; k++) {
+		const line = lines[k];
+		texts[k] = line;
+		const analysis = analyzeBgFillLine(line, width);
+		if (!analysis) {
+			candidates[k] = null;
+			continue;
+		}
+		// Cut at the last non-space glyph and re-close attributes. An all-space row
+		// (cut 0) needs no styled text at all — the caller's erase plus the
+		// rectangle paint it. A content row keeps its prefix and a fresh reset so
+		// the inline background never bleeds past the row.
+		const short = analysis.cut === 0 ? "" : line.slice(0, analysis.cut) + SEGMENT_RESET;
+		candidates[k] = { left: analysis.leftCol + 1, right: width, bg: analysis.bg, short, origLen: line.length };
+	}
+
+	// Collect coalesced groups whose rectangle at least pays for its own bytes.
+	// The DECSACE wrapper is a single per-frame cost, so it is charged once below
+	// rather than amortized into each group (which would over-reject lone rows).
+	interface Group {
+		start: number;
+		end: number;
+		rect: string;
+	}
+	const groups: Group[] = [];
+	let removedTotal = 0;
+	let rectBytesTotal = 0;
+	let k = 0;
+	while (k < n) {
+		const head = candidates[k];
+		if (!head) {
+			k++;
+			continue;
+		}
+		// Extend the group over adjacent rows sharing the same fill span.
+		let end = k;
+		while (end + 1 < n) {
+			const next = candidates[end + 1];
+			if (!next || next.left !== head.left || next.right !== head.right || next.bg !== head.bg) break;
+			end++;
+		}
+		const rect = encodeDeccara(firstScreenRow + k + 1, head.left, firstScreenRow + end + 1, head.right, head.bg);
+		let removed = 0;
+		for (let r = k; r <= end; r++) {
+			const c = candidates[r];
+			if (c) removed += c.origLen - c.short.length;
+		}
+		if (removed > rect.length) {
+			groups.push({ start: k, end, rect });
+			removedTotal += removed;
+			rectBytesTotal += rect.length;
+		}
+		k = end + 1;
+	}
+
+	// Emit nothing unless the batch beats the original by more than the wrapper.
+	if (groups.length === 0 || removedTotal - rectBytesTotal <= DECSACE_WRAPPER_BYTES) {
+		return { texts, sequence: "" };
+	}
+	let sequence = DECSACE_RECT;
+	for (const group of groups) {
+		for (let r = group.start; r <= group.end; r++) {
+			const c = candidates[r];
+			if (c) texts[r] = c.short;
+		}
+		sequence += group.rect;
+	}
+	sequence += DECSACE_DEFAULT;
+	return { texts, sequence };
+}

package/src/desktop-notify.ts

@@ -0,0 +1,192 @@
+// Linux desktop notification delivery via D-Bus.
+//
+// Several terminal families — most notably the VTE-based stack (Ptyxis,
+// GNOME Terminal, Tilix, Terminator) but also Alacritty and bare xterm — have
+// `notifyProtocol === Bell`, which means `formatNotification()` emits only a
+// raw BEL. BEL alone never surfaces an arbitrary-text toast on those hosts
+// (see #3685): Ptyxis hooks BEL to a CSS visual-bell flash, GNOME Terminal
+// rings the audible bell. None of OSC 9 (ConEmu progress in VTE), OSC 99
+// (unimplemented), or OSC 777 (only `notify;Command completed` → unused
+// shell-postexec termprop in current VTE) produce a desktop notification.
+//
+// The freedesktop `org.freedesktop.Notifications` D-Bus service is the only
+// path that consistently delivers toasts on those terminals across Wayland
+// and X11. We invoke it out-of-process via `notify-send` (the canonical
+// libnotify CLI present on every modern Linux desktop) and fall back to
+// `gdbus call` when libnotify is absent but GLib is installed.
+//
+// Delivery is fire-and-forget: a failed spawn or missing binary is treated as
+// a silent no-op so terminals that already deliver toasts in-band (Kitty,
+// iTerm2, WezTerm, …) keep working unchanged and the BEL emission still fires
+// for tmux `monitor-bell`, X11 urgency hints, and audible-bell handlers.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $which } from "@linxiraos/pi-utils";
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities";
+
+/** Application name surfaced as the notification source. */
+const APP_NAME = "Zeta";
+
+/** Resolved notifier binary used to fan a notification out to D-Bus. */
+export type DesktopNotifierKind = "notify-send" | "gdbus";
+
+export interface DesktopNotifier {
+	kind: DesktopNotifierKind;
+	path: string;
+}
+
+/**
+ * Whether the current process can reach a freedesktop notification daemon:
+ * Linux platform plus either a session bus address in env or the
+ * systemd user-bus socket at `$XDG_RUNTIME_DIR/bus`. Caller is still responsible for
+ * resolving a delivery binary via {@link resolveDesktopNotifier}.
+ */
+export function hasLinuxDesktopSession(
+	platform: NodeJS.Platform = process.platform,
+	env: NodeJS.ProcessEnv = Bun.env,
+	fileExists: (path: string) => boolean = fs.existsSync,
+): boolean {
+	if (platform !== "linux") return false;
+	if (env.DBUS_SESSION_BUS_ADDRESS) return true;
+	const runtimeDir = env.XDG_RUNTIME_DIR;
+	return Boolean(runtimeDir && fileExists(path.join(runtimeDir, "bus")));
+}
+
+/**
+ * Whether `sendNotification` should also dispatch a D-Bus toast for this
+ * terminal. Returns true only when (1) the chosen `notifyProtocol` is BEL,
+ * which cannot carry arbitrary toast text, (2) the host exposes a Linux desktop
+ * session, and (3) the user has not opted out via `PI_NO_DESKTOP_NOTIFY=1`.
+ * Terminals that genuinely speak OSC 9 / OSC 99 pass
+ * `notifyProtocolIsBell=false` and are filtered before the D-Bus fallback can
+ * run. Pure helper for tests and the singleton path.
+ */
+export function shouldDeliverDesktopNotification(
+	_terminalId: TerminalId,
+	notifyProtocolIsBell: boolean,
+	platform: NodeJS.Platform = process.platform,
+	env: NodeJS.ProcessEnv = Bun.env,
+): boolean {
+	if (!notifyProtocolIsBell) return false;
+	if (!hasLinuxDesktopSession(platform, env)) return false;
+	if (env.PI_NO_DESKTOP_NOTIFY === "1") return false;
+	return true;
+}
+
+let cachedNotifier: DesktopNotifier | null | undefined;
+
+/** Reset the cached notifier resolution. Tests only. */
+export function resetDesktopNotifierCache(): void {
+	cachedNotifier = undefined;
+}
+
+/**
+ * Locate a libnotify-compatible delivery binary on `PATH`, preferring
+ * `notify-send` (one-shot, no marshalling) and falling back to `gdbus call`
+ * for hosts where libnotify is not installed but GLib is. Result is cached so
+ * repeated notifications do not hit `$which` again.
+ */
+export function resolveDesktopNotifier(): DesktopNotifier | null {
+	if (cachedNotifier !== undefined) return cachedNotifier;
+	const notifySend = $which("notify-send");
+	if (notifySend) {
+		cachedNotifier = { kind: "notify-send", path: notifySend };
+		return cachedNotifier;
+	}
+	const gdbus = $which("gdbus");
+	if (gdbus) {
+		cachedNotifier = { kind: "gdbus", path: gdbus };
+		return cachedNotifier;
+	}
+	cachedNotifier = null;
+	return null;
+}
+
+interface ResolvedNotificationFields {
+	title: string;
+	body: string;
+	urgency: "low" | "normal" | "critical";
+}
+
+function resolveFields(message: string | TerminalNotification): ResolvedNotificationFields {
+	if (typeof message === "string") {
+		return { title: APP_NAME, body: message, urgency: "normal" };
+	}
+	const title = message.title?.trim() || APP_NAME;
+	const body = message.body ?? "";
+	const urgency = message.urgency === "critical" || message.urgency === "low" ? message.urgency : "normal";
+	return { title, body, urgency };
+}
+
+const URGENCY_BYTE: Record<ResolvedNotificationFields["urgency"], number> = {
+	low: 0,
+	normal: 1,
+	critical: 2,
+};
+
+/**
+ * Build the argv that delivers `message` through the resolved notifier. Pure
+ * helper so tests assert exact wire shape without spawning a child. Notes:
+ * - `notify-send` accepts title + body positionally and a numeric expire
+ *   timeout (`-t`); urgency is a flag.
+ * - `gdbus call ... Notify` takes the freedesktop signature
+ *   `s u s s s as a{sv} i`: app_name, replaces_id, app_icon, summary, body,
+ *   actions, hints, expire_timeout. We feed hints with the urgency byte so
+ *   the daemon classifies the toast identically to `notify-send`.
+ */
+export function buildDesktopNotifyCommand(notifier: DesktopNotifier, message: string | TerminalNotification): string[] {
+	const { title, body, urgency } = resolveFields(message);
+	if (notifier.kind === "notify-send") {
+		return [notifier.path, "--app-name", APP_NAME, `--urgency=${urgency}`, "--expire-time=5000", title, body];
+	}
+	const hints = `{"urgency": <byte ${URGENCY_BYTE[urgency]}>}`;
+	return [
+		notifier.path,
+		"call",
+		"--session",
+		"--dest",
+		"org.freedesktop.Notifications",
+		"--object-path",
+		"/org/freedesktop/Notifications",
+		"--method",
+		"org.freedesktop.Notifications.Notify",
+		APP_NAME,
+		"0",
+		"",
+		title,
+		body,
+		"[]",
+		hints,
+		"5000",
+	];
+}
+
+/**
+ * Fire-and-forget D-Bus desktop notification. Resolves a notifier, spawns it
+ * with stdio fully detached, and never throws — terminal notifications are
+ * best-effort and must not block the renderer or interleave bytes onto
+ * stdout. Caller is responsible for the gating check
+ * ({@link shouldDeliverDesktopNotification}).
+ */
+export function sendDesktopNotification(message: string | TerminalNotification): void {
+	const notifier = resolveDesktopNotifier();
+	if (!notifier) return;
+	try {
+		// `.unref()` lets the event loop exit while the notifier is still running.
+		// Without it, an unresponsive D-Bus activation (slow `notify-send`, hung
+		// `gdbus` waiting on a stalled session bus) would keep `omp` alive past
+		// the renderer's shutdown — a completion toast must never delay process
+		// exit. Ignored stdio alone does not detach the child from the parent's
+		// reference count.
+		const child = Bun.spawn({
+			cmd: buildDesktopNotifyCommand(notifier, message),
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		child.unref();
+	} catch {
+		// Best-effort: a failed spawn is silent.
+	}
+}

package/src/editor-component.ts

@@ -0,0 +1,74 @@
+import type { AutocompleteProvider } from "./autocomplete";
+import type { Component } from "./tui";
+
+/**
+ * Interface for custom editor components.
+ *
+ * This allows extensions to provide their own editor implementation
+ * (e.g., vim mode, emacs mode, custom keybindings) while maintaining
+ * compatibility with the core application.
+ */
+export interface EditorComponent extends Component {
+	// =========================================================================
+	// Core text access (required)
+	// =========================================================================
+
+	/** Get the current text content */
+	getText(): string;
+
+	/** Set the text content */
+	setText(text: string): void;
+
+	/** Handle raw terminal input (key presses, paste sequences, etc.) */
+	handleInput(data: string): void;
+
+	// =========================================================================
+	// Callbacks (required)
+	// =========================================================================
+
+	/** Called when user submits (e.g., Enter key) */
+	onSubmit?: (text: string) => void;
+
+	/** Programmatically trigger submission (optional, e.g. for voice submit). */
+	submit?(): void;
+
+	/** Called when text changes */
+	onChange?: (text: string) => void;
+
+	// =========================================================================
+	// History support (optional)
+	// =========================================================================
+
+	/** Add text to history for up/down navigation */
+	addToHistory?(text: string): void;
+
+	// =========================================================================
+	// Advanced text manipulation (optional)
+	// =========================================================================
+
+	/** Insert text at current cursor position */
+	insertTextAtCursor?(text: string): void;
+
+	/**
+	 * Get text with any markers expanded (e.g., paste markers).
+	 * Falls back to getText() if not implemented.
+	 */
+	getExpandedText?(): string;
+
+	// =========================================================================
+	// Autocomplete support (optional)
+	// =========================================================================
+
+	/** Set the autocomplete provider */
+	setAutocompleteProvider?(provider: AutocompleteProvider): void;
+
+	// =========================================================================
+	// Appearance (optional)
+	// =========================================================================
+
+	/** Border color function */
+	borderColor?: (str: string) => string;
+
+	/** Set horizontal padding */
+	setPaddingX?(padding: number): void;
+}