@oh-my-pi/pi-tui 16.2.2 → 16.2.4

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [16.2.3] - 2026-06-28
+
+### Added
+
+- Added a desktop notification fallback for Linux terminals using D-Bus (via notify-send or gdbus), enabling completion and prompt notifications in VTE-family terminals (such as GNOME Terminal, Ptyxis, Tilix), Alacritty, and xterm. This is automatically skipped for terminals with native notification support (like VS Code and Warp) and can be disabled using the PI_NO_DESKTOP_NOTIFY=1 environment variable.
+
+### Fixed
+
+- Fixed slash skill autocomplete not opening when there is existing prompt text, ensuring mid-prompt slash lookups correctly display and insert skill commands.
+- Fixed modified Enter and keyboard shortcuts in fullscreen overlays for terminals using the xterm modifyOtherKeys fallback (such as iTerm2 when Kitty keyboard negotiation is unavailable).
+
 ## [16.2.0] - 2026-06-27
 
 ### Added

package/dist/types/autocomplete.d.ts

@@ -5,6 +5,7 @@
  * agree on which prefixes count.
  */
 export declare function findLeadingSlashCommandStart(text: string): number | null;
+export declare function findTrailingSlashCommandStart(text: string): number | null;
 export interface AutocompleteItem {
     value: string;
     label: string;
@@ -57,6 +58,17 @@ export interface AutocompleteProvider {
         replaceLen: number;
         insert: string;
     } | null;
+    /**
+     * Force file-path completion (called on Tab). Returns matched items plus the
+     * full prefix, or null when no path token sits before the cursor. Present on
+     * file-aware providers; absent on slash-only ones.
+     */
+    getForceFileSuggestions?(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    /** Whether a Tab press should attempt file completion at the cursor. */
+    shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;
 }
 type CommandEntry = SlashCommand | AutocompleteItem;
 export declare class CombinedAutocompleteProvider implements AutocompleteProvider {

package/dist/types/desktop-notify.d.ts

@@ -0,0 +1,51 @@
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities";
+/** 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 + a session bus address in env. Caller is still responsible
+ * for resolving a delivery binary via {@link resolveDesktopNotifier}.
+ */
+export declare function hasLinuxDesktopSession(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function shouldDeliverDesktopNotification(_terminalId: TerminalId, notifyProtocolIsBell: boolean, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
+/** Reset the cached notifier resolution. Tests only. */
+export declare function resetDesktopNotifierCache(): void;
+/**
+ * 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 declare function resolveDesktopNotifier(): DesktopNotifier | null;
+/**
+ * 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 declare function buildDesktopNotifyCommand(notifier: DesktopNotifier, message: string | TerminalNotification): string[];
+/**
+ * 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 declare function sendDesktopNotification(message: string | TerminalNotification): void;

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./components/tab-bar";
 export * from "./components/text";
 export * from "./components/truncated-text";
 export * from "./deccara";
+export * from "./desktop-notify";
 export type * from "./editor-component";
 export * from "./fuzzy";
 export * from "./keybindings";

package/dist/types/terminal.d.ts

@@ -45,6 +45,8 @@ export interface Terminal {
     get rows(): number;
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
+    readonly keyboardEnhancementEnterSequence?: string | null;
+    readonly keyboardEnhancementExitSequence?: string | null;
     moveBy(lines: number): void;
     hideCursor(): void;
     showCursor(): void;
@@ -83,6 +85,8 @@ export declare class ProcessTerminal implements Terminal {
     #private;
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
+    get keyboardEnhancementEnterSequence(): string | null;
+    get keyboardEnhancementExitSequence(): string | null;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.2.2",
+	"version": "16.2.4",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.2.2",
-		"@oh-my-pi/pi-utils": "16.2.2",
+		"@oh-my-pi/pi-natives": "16.2.4",
+		"@oh-my-pi/pi-utils": "16.2.4",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/autocomplete.ts

@@ -68,6 +68,13 @@ export function findLeadingSlashCommandStart(text: string): number | null {
 	return text.length - trimmed.length;
 }
 
+export function findTrailingSlashCommandStart(text: string): number | null {
+	const match = /(?:^|\s)\/([^\s/]*)$/.exec(text);
+	if (!match || match.index === undefined) return null;
+	const slashOffset = match[0].indexOf("/");
+	return match.index + slashOffset;
+}
+
 function extractQuotedPrefix(text: string): string | null {
 	const quoteStart = findUnclosedQuoteStart(text);
 	if (quoteStart === null) {
@@ -223,6 +230,20 @@ export interface AutocompleteProvider {
 	 * buffer untouched.
 	 */
 	trySyncInlineReplace?(textBeforeCursor: string): { replaceLen: number; insert: string } | null;
+
+	/**
+	 * Force file-path completion (called on Tab). Returns matched items plus the
+	 * full prefix, or null when no path token sits before the cursor. Present on
+	 * file-aware providers; absent on slash-only ones.
+	 */
+	getForceFileSuggestions?(
+		lines: string[],
+		cursorLine: number,
+		cursorCol: number,
+	): Promise<{ items: AutocompleteItem[]; prefix: string } | null>;
+
+	/** Whether a Tab press should attempt file completion at the cursor. */
+	shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;
 }
 
 type CommandEntry = SlashCommand | AutocompleteItem;
@@ -324,6 +345,25 @@ function buildSlashCommandCompletions(commands: CommandEntry[], lowerPrefix: str
 		.map(({ score: _, ...rest }) => rest);
 }
 
+function hasPromptTextBeforeSlash(
+	lines: string[],
+	cursorLine: number,
+	textBeforeCursor: string,
+	slashStart: number,
+): boolean {
+	for (let i = 0; i < cursorLine; i += 1) {
+		if ((lines[i] || "").trim() !== "") return true;
+	}
+	return textBeforeCursor.slice(0, slashStart).trim() !== "";
+}
+
+function buildMidPromptSkillCompletions(commands: CommandEntry[], lowerPrefix: string): AutocompleteItem[] {
+	return buildSlashCommandCompletions(
+		commands.filter(cmd => getCommandName(cmd)?.startsWith("skill:")),
+		lowerPrefix,
+	);
+}
+
 // Combined provider that handles both slash commands and file paths.
 export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	#commands: CommandEntry[];
@@ -379,29 +419,40 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			};
 		}
 
-		const slashStart = findLeadingSlashCommandStart(textBeforeCursor);
+		const leadingSlashStart = findLeadingSlashCommandStart(textBeforeCursor);
+		const trailingSlashStart = findTrailingSlashCommandStart(textBeforeCursor);
+		const hasPromptTextBeforeTrailingSlash =
+			trailingSlashStart !== null &&
+			hasPromptTextBeforeSlash(lines, cursorLine, textBeforeCursor, trailingSlashStart);
+		const slashStart = hasPromptTextBeforeTrailingSlash ? trailingSlashStart : leadingSlashStart;
 		if (slashStart !== null) {
 			const commandText = textBeforeCursor.slice(slashStart);
 			const spaceIndex = commandText.indexOf(" ");
+			const isMidPromptSkillLookup = hasPromptTextBeforeTrailingSlash;
 
 			if (spaceIndex === -1) {
 				// No space yet - complete command names
 				const prefix = commandText.slice(1); // Remove the "/"
 				const lowerPrefix = prefix.toLowerCase();
 
-				const matches = buildSlashCommandCompletions(this.#commands, lowerPrefix);
-
-				if (matches.length === 0) return null;
-
-				return {
-					items: matches,
-					// Preserve the full text-before-cursor (incl. leading
-					// whitespace) so the editor's Enter-staleness check
-					// (`autocompletePrefix !== currentTextBeforeCursor`)
-					// still applies the completion for `  /sk`.
-					prefix: textBeforeCursor,
-				};
-			} else {
+				const matches = isMidPromptSkillLookup
+					? buildMidPromptSkillCompletions(this.#commands, lowerPrefix)
+					: buildSlashCommandCompletions(this.#commands, lowerPrefix);
+
+				if (matches.length > 0) {
+					return {
+						items: matches,
+						// Preserve the full text-before-cursor for submitted slash
+						// commands so the editor's Enter-staleness check still applies
+						// completion for `  /sk`. Mid-prompt skill lookup keeps only
+						// the slash token because accepting it replaces the whole draft.
+						prefix: isMidPromptSkillLookup ? commandText : textBeforeCursor,
+					};
+				}
+				if (!isMidPromptSkillLookup) return null;
+				// A mid-prompt slash token with no matching skill may still be an
+				// absolute path (`see /tmp`); fall through to file-path completion.
+			} else if (!isMidPromptSkillLookup) {
 				// Space found - complete command arguments
 				const commandName = commandText.slice(1, spaceIndex); // Command without "/"
 				const argumentText = commandText.slice(spaceIndex + 1); // Text after space
@@ -421,6 +472,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 					prefix: argumentText,
 				};
 			}
+			if (!isMidPromptSkillLookup) return null;
 		}
 
 		// Check for file paths - triggered by Tab or if we detect a path pattern
@@ -462,15 +514,30 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const textBeforeCursor = currentLine.slice(0, cursorCol);
 		const afterCursor = currentLine.slice(cursorCol);
 
-		const slashStart = findLeadingSlashCommandStart(textBeforeCursor);
+		const leadingSlashStart = findLeadingSlashCommandStart(textBeforeCursor);
+		const trailingSlashStart = findTrailingSlashCommandStart(textBeforeCursor);
+		const isMidPromptSkillLookup =
+			item.value.startsWith("skill:") &&
+			trailingSlashStart !== null &&
+			hasPromptTextBeforeSlash(lines, cursorLine, textBeforeCursor, trailingSlashStart) &&
+			findTrailingSlashCommandStart(prefix) !== null;
+
+		if (isMidPromptSkillLookup) {
+			const newLine = `/${item.value}`;
+			return {
+				lines: [newLine],
+				cursorLine: 0,
+				cursorCol: newLine.length,
+			};
+		}
 
 		// Slash command suggestions can be accepted before the debounced refresh
 		// catches up to newly typed characters. Replace the live command token,
 		// not only the prefix captured when the suggestion list was rendered.
-		if (findLeadingSlashCommandStart(prefix) !== null && slashStart !== null) {
-			const slashPrefix = textBeforeCursor.slice(slashStart);
+		if (findLeadingSlashCommandStart(prefix) !== null && leadingSlashStart !== null) {
+			const slashPrefix = textBeforeCursor.slice(leadingSlashStart);
 			if (!slashPrefix.includes(" ") && !slashPrefix.slice(1).includes("/")) {
-				const beforeSlash = currentLine.slice(0, slashStart);
+				const beforeSlash = currentLine.slice(0, leadingSlashStart);
 				const newLine = `${beforeSlash}/${item.value} ${afterCursor}`;
 				const newLines = [...lines];
 				newLines[cursorLine] = newLine;

package/src/components/editor.ts

@@ -1,8 +1,8 @@
 import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
 import {
 	type AutocompleteProvider,
-	type CombinedAutocompleteProvider,
 	findLeadingSlashCommandStart,
+	findTrailingSlashCommandStart,
 } from "../autocomplete";
 import { BracketedPasteHandler, decodeReencodedPasteControls } from "../bracketed-paste";
 import { getKeybindings, type KeybindingsManager } from "../keybindings";
@@ -1131,7 +1131,7 @@ export class Editor implements Component, Focusable {
 					// Check for stale autocomplete state due to debounce
 					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
 					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (currentTextBeforeCursor !== this.#autocompletePrefix) {
+					if (!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor)) {
 						// Autocomplete is stale - cancel and fall through to normal submission
 						this.#cancelAutocomplete();
 					} else {
@@ -1755,8 +1755,8 @@ export class Editor implements Component, Focusable {
 
 		// Check if we should trigger or update autocomplete
 		if (!this.#autocompleteState) {
-			// Auto-trigger for "/" at the start of a line (slash commands)
-			if (char === "/" && this.#isAtStartOfSubmittedMessage()) {
+			// Auto-trigger for "/" at the start of a submitted command or a mid-prompt skill lookup.
+			if (char === "/" && (this.#isAtStartOfSubmittedMessage() || this.#isInMidPromptSkillSlashContext())) {
 				this.#tryTriggerAutocomplete();
 			}
 			// Auto-trigger for "@" file reference (fuzzy search)
@@ -1777,8 +1777,8 @@ export class Editor implements Component, Focusable {
 			else if (/[a-zA-Z0-9.\-_/]/.test(char)) {
 				const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 				const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-				// Check if we're in a slash command (with or without space for arguments)
-				if (this.#isInSubmittedSlashCommandContext()) {
+				// Check if we're in a slash command or mid-prompt skill lookup.
+				if (this.#isInSlashAutocompleteContext()) {
 					this.#tryTriggerAutocomplete();
 				}
 				// Check if we're in an @ file reference context
@@ -1901,7 +1901,7 @@ export class Editor implements Component, Focusable {
 		}
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 		const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-		if (this.#isInSubmittedSlashCommandContext()) {
+		if (this.#isInSlashAutocompleteContext()) {
 			this.#tryTriggerAutocomplete();
 		} else if (textBeforeCursor.match(/(?:^|[\s])@[^\s]*$/)) {
 			this.#tryTriggerAutocomplete();
@@ -2067,8 +2067,8 @@ export class Editor implements Component, Focusable {
 			// If autocomplete was cancelled (no matches), re-trigger if we're in a completable context
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			// Slash command context
-			if (this.#isInSubmittedSlashCommandContext()) {
+			// Slash command or mid-prompt skill lookup context
+			if (this.#isInSlashAutocompleteContext()) {
 				this.#tryTriggerAutocomplete();
 			}
 			// @ file reference context
@@ -2236,7 +2236,7 @@ export class Editor implements Component, Focusable {
 		} else {
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			if (this.#isInSubmittedSlashCommandContext()) {
+			if (this.#isInSlashAutocompleteContext()) {
 				this.#tryTriggerAutocomplete();
 			} else if (textBeforeCursor.match(/(?:^|[\s])@[^\s]*$/)) {
 				this.#tryTriggerAutocomplete();
@@ -2568,8 +2568,8 @@ export class Editor implements Component, Focusable {
 		} else {
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			// Slash command context
-			if (this.#isInSubmittedSlashCommandContext()) {
+			// Slash command or mid-prompt skill lookup context
+			if (this.#isInSlashAutocompleteContext()) {
 				this.#tryTriggerAutocomplete();
 			}
 			// @ file reference context
@@ -2799,6 +2799,27 @@ export class Editor implements Component, Focusable {
 		return this.#hasOnlyWhitespaceBeforeCursorLine() && beforeCursor.trimStart().startsWith("/");
 	}
 
+	#isInMidPromptSkillSlashContext(): boolean {
+		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
+		const slashStart = findTrailingSlashCommandStart(beforeCursor);
+		if (slashStart === null) return false;
+		if (this.#hasOnlyWhitespaceBeforeCursorLine() && findLeadingSlashCommandStart(beforeCursor) !== null)
+			return false;
+		return !this.#hasOnlyWhitespaceBeforeCursorLine() || beforeCursor.slice(0, slashStart).trim() !== "";
+	}
+
+	#isInSlashAutocompleteContext(): boolean {
+		return this.#isInSubmittedSlashCommandContext() || this.#isInMidPromptSkillSlashContext();
+	}
+
+	#autocompletePrefixMatchesCursorText(currentTextBeforeCursor: string): boolean {
+		if (currentTextBeforeCursor === this.#autocompletePrefix) return true;
+		if (findTrailingSlashCommandStart(this.#autocompletePrefix) !== 0) return false;
+		const slashStart = findTrailingSlashCommandStart(currentTextBeforeCursor);
+		return slashStart !== null && currentTextBeforeCursor.slice(slashStart) === this.#autocompletePrefix;
+	}
+
 	#isSlashCommandNameAutocompleteSelection(): boolean {
 		if (this.#autocompleteState !== "regular") {
 			return false;
@@ -2837,10 +2858,13 @@ export class Editor implements Component, Focusable {
 		if (!this.#autocompleteProvider) return;
 		// Check if we should trigger file completion on Tab
 		if (explicitTab) {
-			const provider = this.#autocompleteProvider as CombinedAutocompleteProvider;
 			const shouldTrigger =
-				!provider.shouldTriggerFileCompletion ||
-				provider.shouldTriggerFileCompletion(this.#state.lines, this.#state.cursorLine, this.#state.cursorCol);
+				!this.#autocompleteProvider.shouldTriggerFileCompletion ||
+				this.#autocompleteProvider.shouldTriggerFileCompletion(
+					this.#state.lines,
+					this.#state.cursorLine,
+					this.#state.cursorCol,
+				);
 			if (!shouldTrigger) {
 				return;
 			}
@@ -2873,22 +2897,25 @@ export class Editor implements Component, Focusable {
 		return new SelectList(items, this.#autocompleteMaxVisible, this.#theme.selectList, layout);
 	}
 
-	#handleTabCompletion(): void {
+	async #handleTabCompletion(): Promise<void> {
 		if (!this.#autocompleteProvider) return;
 
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
 
-		// Check if we're in a slash command context
 		if (this.#isInSubmittedSlashCommandContext() && !beforeCursor.trimStart().includes(" ")) {
-			this.#handleSlashCommandCompletion();
+			await this.#handleSlashCommandCompletion();
+		} else if (this.#isInMidPromptSkillSlashContext()) {
+			await this.#handleSlashCommandCompletion();
+			if (!this.#autocompleteState) {
+				await this.#forceFileAutocomplete(true);
+			}
 		} else {
-			this.#forceFileAutocomplete(true);
+			await this.#forceFileAutocomplete(true);
 		}
 	}
-
-	#handleSlashCommandCompletion(): void {
-		this.#tryTriggerAutocomplete(true);
+	async #handleSlashCommandCompletion(): Promise<void> {
+		await this.#tryTriggerAutocomplete();
 	}
 
 	/*
@@ -2899,17 +2926,16 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 	async #forceFileAutocomplete(explicitTab: boolean = false): Promise<void> {
 		if (!this.#autocompleteProvider) return;
 
-		// Check if provider supports force file suggestions via runtime check
-		const provider = this.#autocompleteProvider as {
-			getForceFileSuggestions?: CombinedAutocompleteProvider["getForceFileSuggestions"];
-		};
-		if (typeof provider.getForceFileSuggestions !== "function") {
+		// File-aware providers expose getForceFileSuggestions; slash-only ones fall back to regular completion.
+		const getForceFileSuggestions = this.#autocompleteProvider.getForceFileSuggestions;
+		if (typeof getForceFileSuggestions !== "function") {
 			await this.#tryTriggerAutocomplete(true);
 			return;
 		}
 
 		const requestId = ++this.#autocompleteRequestId;
-		const suggestions = await provider.getForceFileSuggestions(
+		const suggestions = await getForceFileSuggestions.call(
+			this.#autocompleteProvider,
 			this.#state.lines,
 			this.#state.cursorLine,
 			this.#state.cursorCol,

package/src/desktop-notify.ts

@@ -0,0 +1,186 @@
+// 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 { $which } from "@oh-my-pi/pi-utils";
+import type { TerminalId, TerminalNotification } from "./terminal-capabilities";
+
+/** Application name surfaced as the notification source. */
+const APP_NAME = "Oh My Pi";
+
+/** 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 + a session bus address in env. 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,
+): boolean {
+	if (platform !== "linux") return false;
+	return Boolean(env.DBUS_SESSION_BUS_ADDRESS);
+}
+
+/**
+ * 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/index.ts

@@ -19,6 +19,8 @@ export * from "./components/text";
 export * from "./components/truncated-text";
 // DECCARA rectangular-SGR background-fill optimizer
 export * from "./deccara";
+// Desktop notifications via D-Bus (Linux freedesktop notifications)
+export * from "./desktop-notify";
 // Editor component interface (for custom editors)
 export type * from "./editor-component";
 // Fuzzy matching

package/src/terminal-capabilities.ts

@@ -1,5 +1,6 @@
 import { encodeSixel } from "@oh-my-pi/pi-natives";
 import { $env, isBunTestRuntime, isTerminalHeadless } from "@oh-my-pi/pi-utils";
+import { sendDesktopNotification, shouldDeliverDesktopNotification } from "./desktop-notify";
 import {
 	detectKittyUnicodePlaceholdersSupport,
 	getKittyGraphics,
@@ -122,6 +123,15 @@ export class TerminalInfo {
 			return;
 		}
 		process.stdout.write(formatted);
+		// VTE-family terminals (Ptyxis, GNOME Terminal, Tilix, …) plus Alacritty
+		// and bare xterm-on-Wayland have no in-band escape that surfaces an
+		// arbitrary desktop toast (#3685). When the chosen `notifyProtocol` is
+		// BEL on a Linux session bus, also fan the notification out via
+		// libnotify so users see the toast and the BEL still fires for tmux
+		// `monitor-bell` / X11 urgency hints / audible bell.
+		if (this.notifyProtocol === NotifyProtocol.Bell && shouldDeliverDesktopNotification(this.id, true)) {
+			sendDesktopNotification(message);
+		}
 	}
 }
 
@@ -399,7 +409,7 @@ export function resolveWarpImageProtocol(
 }
 
 function getWarpTerminalInfo(platform: NodeJS.Platform, env: NodeJS.ProcessEnv = Bun.env): TerminalInfo {
-	return new TerminalInfo("warp", resolveWarpImageProtocol(platform, env), true, false, NotifyProtocol.Bell);
+	return new TerminalInfo("warp", resolveWarpImageProtocol(platform, env), true, false, NotifyProtocol.Osc9);
 }
 const KNOWN_TERMINALS = Object.freeze({
 	// Fallback terminals
@@ -415,8 +425,9 @@ const KNOWN_TERMINALS = Object.freeze({
 	// Warp identifies via TERM_PROGRAM=WarpTerminal and ships the Kitty graphics
 	// protocol on macOS/Linux (direct placement only — no Unicode placeholders, so
 	// detectKittyUnicodePlaceholdersSupport correctly excludes it). It does not
-	// honor OSC 8 yet (the escape renders as visible text), so hyperlinks stay off.
-	warp: new TerminalInfo("warp", ImageProtocol.Kitty, true, false, NotifyProtocol.Bell),
+	// honor OSC 8 yet (the escape renders as visible text), so hyperlinks stay off,
+	// but it does support OSC 9 notifications.
+	warp: new TerminalInfo("warp", ImageProtocol.Kitty, true, false, NotifyProtocol.Osc9),
 });
 
 /** Resolve terminal identity from environment markers used by common emulators. */

package/src/terminal.ts

@@ -336,6 +336,16 @@ export interface Terminal {
 	// so the TUI re-pushes this after entering the alternate screen.
 	get kittyEnableSequence(): string | null;
 
+	// The active modified-key reporting sequence to reassert on alternate-screen
+	// entry, or null when no enhanced keyboard mode is active. Optional so custom
+	// Terminals built against older pi-tui versions keep working.
+	readonly keyboardEnhancementEnterSequence?: string | null;
+
+	// The sequence that cleanly disables the active enhanced keyboard mode on
+	// alternate-screen exit, or null when no exit handshake is required. Optional
+	// so custom Terminals built against older pi-tui versions keep working.
+	readonly keyboardEnhancementExitSequence?: string | null;
+
 	// Cursor positioning (relative to current position)
 	moveBy(lines: number): void; // Move cursor up (negative) or down (positive) by N lines
 
@@ -472,6 +482,20 @@ export class ProcessTerminal implements Terminal {
 		return this.#kittyProtocolActive ? this.#kittyEnableSeq : null;
 	}
 
+	get keyboardEnhancementEnterSequence(): string | null {
+		if (this.#kittyProtocolActive) return this.#kittyEnableSeq;
+		return this.#modifyOtherKeysActive ? "\x1b[>4;2m" : null;
+	}
+
+	get keyboardEnhancementExitSequence(): string | null {
+		// kitty is a stack push (per-screen), so the matching pop balances alt-screen
+		// entry. xterm modifyOtherKeys is a single global flag with no per-screen
+		// stack — emitting `>4;0m` here would clear it on the normal screen too,
+		// breaking the composer between overlays. terminal.stop() still disables it
+		// globally on graceful exit; the emergency-restore path mirrors that.
+		return this.#kittyProtocolActive ? "\x1b[<u" : null;
+	}
+
 	get appearance(): TerminalAppearance | undefined {
 		return this.#appearance;
 	}

package/src/tui.ts

@@ -1745,8 +1745,8 @@ export class TUI extends Container {
 			this.terminal.write(this.#leaveResizeAltSequence());
 		}
 		if (this.#altActive) {
-			const kittyPop = this.terminal.kittyEnableSequence ? "\x1b[<u" : "";
-			this.terminal.write(`${MOUSE_TRACKING_OFF}${kittyPop}\x1b[?1049l`);
+			const enhancementExit = this.#keyboardEnhancementExit();
+			this.terminal.write(`${MOUSE_TRACKING_OFF}${enhancementExit}\x1b[?1049l`);
 			setAltScreenActive(false);
 			this.#altActive = false;
 			this.#altPreviousLines = [];
@@ -2488,11 +2488,11 @@ export class TUI extends Container {
 		// modal there; the normal screen and all accounting stay untouched.
 		const wantAlt = this.#wantsAltScreen();
 		if (wantAlt && !this.#altActive) {
-			// Kitty keyboard flags are per-screen: re-push our level on the freshly
-			// entered alternate screen, or Esc/modified keys revert to legacy
-			// encoding inside fullscreen overlays (Ghostty/kitty). See kitty
-			// keyboard-protocol docs: the mode stack is separate per screen.
-			this.terminal.write(`\x1b[?1049h${this.terminal.kittyEnableSequence ?? ""}${MOUSE_TRACKING_ON}`);
+			// Enhanced keyboard modes can be buffer-local: re-push the active
+			// modified-key reporting sequence on the freshly entered alternate
+			// screen, or Esc/modified keys revert to legacy encoding inside
+			// fullscreen overlays (Ghostty/kitty/iTerm2).
+			this.terminal.write(`\x1b[?1049h${this.#keyboardEnhancementEnter()}${MOUSE_TRACKING_ON}`);
 			setAltScreenActive(true);
 			this.terminal.hideCursor();
 			this.#forgetHardwareCursorState();
@@ -2502,8 +2502,8 @@ export class TUI extends Container {
 			this.#altEnterWidth = width;
 			this.#altEnterHeight = height;
 		} else if (!wantAlt && this.#altActive) {
-			const kittyPop = this.terminal.kittyEnableSequence ? "\x1b[<u" : "";
-			this.terminal.write(`${MOUSE_TRACKING_OFF}${kittyPop}\x1b[?1049l`);
+			const enhancementExit = this.#keyboardEnhancementExit();
+			this.terminal.write(`${MOUSE_TRACKING_OFF}${enhancementExit}\x1b[?1049l`);
 			setAltScreenActive(false);
 			this.#forgetHardwareCursorState();
 			this.#altActive = false;
@@ -3339,23 +3339,42 @@ export class TUI extends Container {
 		return { window: this.#prepareLinesArray(window, width), contentRows: count };
 	}
 
-	/** Enter or leave the alternate screen borrowed for transient resize frames. */
+	/**
+	 * Resolve the active keyboard-enhancement enter sequence. Falls back to the
+	 * legacy `kittyEnableSequence` when a custom Terminal predates the
+	 * `keyboardEnhancementEnterSequence` property.
+	 */
+	#keyboardEnhancementEnter(): string {
+		return this.terminal.keyboardEnhancementEnterSequence ?? this.terminal.kittyEnableSequence ?? "";
+	}
+
+	/**
+	 * Resolve the active keyboard-enhancement exit sequence. Falls back to popping
+	 * kitty whenever a custom Terminal exposes its push sequence but predates the
+	 * `keyboardEnhancementExitSequence` property.
+	 */
+	#keyboardEnhancementExit(): string {
+		const exit = this.terminal.keyboardEnhancementExitSequence;
+		if (exit !== undefined) return exit ?? "";
+		return this.terminal.kittyEnableSequence ? "\x1b[<u" : "";
+	}
+
 	#enterResizeAltSequence(): string {
 		if (this.#resizeAltActive || this.#altActive) return "";
 		this.#resizeAltActive = true;
 		setAltScreenActive(true);
 		this.#forgetHardwareCursorState();
 		this.#recordHardwareCursorHidden();
-		return `${ALT_SCREEN_ENTER}${this.terminal.kittyEnableSequence ?? ""}`;
+		return `${ALT_SCREEN_ENTER}${this.#keyboardEnhancementEnter()}`;
 	}
 
 	#leaveResizeAltSequence(): string {
 		if (!this.#resizeAltActive) return "";
-		const kittyPop = this.terminal.kittyEnableSequence ? "\x1b[<u" : "";
+		const enhancementExit = this.#keyboardEnhancementExit();
 		this.#resizeAltActive = false;
 		setAltScreenActive(false);
 		this.#forgetHardwareCursorState();
-		return `${kittyPop}${ALT_SCREEN_EXIT}`;
+		return `${enhancementExit}${ALT_SCREEN_EXIT}`;
 	}
 
 	/**