feat(tui): add popups for prompt autocomplete triggers

docs/settings.md

@@ -750,9 +750,16 @@ tui:
 | `images.blockImages`        | boolean | `false`          | Never send images to providers.                                           |
 | `tui.hyperlinks`            | enum    | `auto`           | `off`, `auto`, `always`.                                                  |
 | `tui.mouse`                 | boolean | `false`          | Capture mouse clicks in the main session so live subagent cards and HUD rows focus on click, with a hover highlight on the target. Native text selection becomes Shift+drag and wheel scroll becomes Shift+wheel while on. |
+| `display.commandSuggestionsPopup` | boolean | `false` | Show slash-command and argument suggestions in a bordered popup without adding conversation rows. Under Appearance → Display. Native selection and scrolling remain unchanged. |
+| `display.autocompleteSuggestionsPopup` | boolean | `false` | Show `@` file mentions, `#` prompt actions/references, and `:` emoji suggestions in the bordered popup without moving conversation rows. Model mentions remain controlled by `display.inlineModelPicker`. |
+| `display.popupFill` | boolean | `false` | Opt in to the message-colored background fill for bordered command and argument suggestion popups. |
 | `display.pinnedAgents`      | enum    | `collapsed`      | Pinned live-agent jump list above the editor: `off` hides it, `collapsed` shows a few rows with an expander, `full` lists all. |
 | `tui.resizeScrollback`      | enum    | `rebuild`        | How a settled width resize refreshes transcript rows kept in terminal scrollback: `append` replays the transcript at the new width below retained history, `rebuild` erases pane scrollback then replays one current-width copy, `preserve` repaints only the viewport. |
 
+Command popup interactions do not rebuild scrollback. After a resize, popup backing that remains addressable is restored in place. If covered rows have left the viewport or reflow has changed their physical extent, recovery rebuilds the application's complete history. This exceptional recovery also applies in `preserve`/`append` mode and can remove pre-existing shell or pane scrollback that the application does not own.
+
+Popup fill is intentionally opt-in. With fill disabled, Kitty images can remain visible through unfilled popup cells; enable `display.popupFill` when opaque image occlusion is needed. Popup interaction never deletes image placements, including through tmux: deleting a partially archived placement would also remove its scrollback cells. A terminal-default background reset alone does not hide Kitty images.
+
 For a custom status line, set `statusLine.preset: custom` and configure `statusLine.leftSegments`, `statusLine.rightSegments`, and `statusLine.segmentOptions`. Include `status` in either segment list to render extension statuses registered through `ctx.ui.setStatus()`, ordered by key and joined inline. Set `statusLine.showHookStatus: false` to suppress the same statuses in the footer.
 
 The `cost` segment shows recorded session costs. For an active provider/model with scheduled pricing, it appends `↑` during peak hours or `↓` off-peak, refreshing at boundaries even while idle. The arrow reflects the current tariff, not past spending; flat-price models and explicit cost overrides have no arrow. See [usage costs and time-based pricing](models.md#usage-costs-and-time-based-pricing) for the UTC schedule and estimation semantics.

packages/coding-agent/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added an optional Autocomplete Suggestions Popup for `@` file mentions, `#` actions/references, and `:` emoji suggestions without moving the chat ([#12671](https://github.com/can1357/oh-my-pi/pull/12671) by [@DarkPhilosophy](https://github.com/DarkPhilosophy)).
+
 ## [18.2.7] - 2026-09-21
 
 ### Breaking Changes
@@ -610,6 +614,13 @@
 - Browser startup reuses a successful system-Chrome fallback instead of retrying an unavailable download during the same open.
 - Browser clicks and other interactions no longer stall when OMP-owned tabs are in the background, including after worker timeout recovery.
 
+### Added
+
+- Added an opt-in Popup Background Fill setting; command popups keep their unfilled appearance by default ([#11946](https://github.com/can1357/oh-my-pi/pull/11946) by [@DarkPhilosophy](https://github.com/DarkPhilosophy)).
+
+- Added an optional Command Suggestions Popup in Appearance → Display that keeps the chat stationary while suggestions open, filter, and close ([#11946](https://github.com/can1357/oh-my-pi/pull/11946) by [@DarkPhilosophy](https://github.com/DarkPhilosophy)).
+
+### Changed
 ## [18.1.20] - 2026-09-13
 
 ### Added

packages/coding-agent/src/config/settings-schema.ts

@@ -1154,6 +1154,40 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"display.popupFill": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			group: "Display",
+			label: "Popup Background Fill",
+			description: "Fill bordered command and argument suggestion popups with the message surface color",
+		},
+	},
+
+	"display.commandSuggestionsPopup": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			group: "Display",
+			label: "Command Suggestions Popup",
+			description:
+				"Show slash-command and argument suggestions in a bordered popup without moving the chat or changing native scrolling",
+		},
+	},
+
+	"display.autocompleteSuggestionsPopup": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			group: "Display",
+			label: "Autocomplete Suggestions Popup",
+			description: "Show @, #, and : autocomplete suggestions in the bordered popup",
+		},
+	},
+
 	"display.shimmer": {
 		type: "enum",
 		values: ["classic", "kitt", "disabled"] as const,

packages/coding-agent/src/modes/controllers/input-controller.ts

@@ -754,7 +754,7 @@ export class InputController {
 	// empty (resize transactions) or the row falls outside it: routing stale
 	// spans would highlight or focus an unrelated agent from old rows.
 	#viewportCandidates(screenRow: number): string[] {
-		const viewport = this.ctx.ui.getMutableViewport();
+		const viewport = this.ctx.ui.getMutableViewport(screenRow);
 		const local = screenRow - viewport.top;
 		if (viewport.length === 0 || local < 0 || local >= viewport.length) return [];
 		return this.ctx.resolveViewportClickCandidates(local);

packages/coding-agent/src/modes/controllers/selector-controller.ts

@@ -661,6 +661,18 @@ export class SelectorController {
 				this.ctx.eventController.refreshIdleCompactionTimer();
 				break;
 
+			case "display.popupFill":
+				this.ctx.editor.popupFill = value as boolean;
+				this.ctx.ui.requestRender();
+				break;
+			case "display.commandSuggestionsPopup":
+				this.ctx.editor.commandSuggestionsPopup = value as boolean;
+				this.ctx.ui.requestRender();
+				break;
+			case "display.autocompleteSuggestionsPopup":
+				this.ctx.editor.autocompleteSuggestionsPopup = value as boolean;
+				this.ctx.ui.requestRender();
+				break;
 			case "autocompleteMaxVisible":
 				this.ctx.editor.setAutocompleteMaxVisible(typeof value === "number" ? value : Number(value));
 				break;

packages/coding-agent/src/modes/interactive-mode.ts

@@ -1255,6 +1255,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.editor.setImeSafeCursorLayout(settings.get("tui.imeSafeCursor"));
 		this.#applyVimMode(this.editor);
 		this.editor.setAutocompleteMaxVisible(settings.get("autocompleteMaxVisible"));
+		this.editor.commandSuggestionsPopup = settings.get("display.commandSuggestionsPopup");
+		this.editor.autocompleteSuggestionsPopup = settings.get("display.autocompleteSuggestionsPopup");
+		this.editor.popupFill = settings.get("display.popupFill");
+		this.editor.onAutocompleteRender = (render, offset, rows) => this.ui.setCursorOverlay(render, offset, rows);
 		this.syncEditorSpelling();
 		this.editor.viewportRowsProvider = () => this.ui.terminal.rows;
 		this.editor.onAutocompleteCancel = () => {
@@ -5749,6 +5753,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		nextEditor.setImeSafeCursorLayout(this.settings.get("tui.imeSafeCursor"));
 		this.#applyVimMode(nextEditor);
 		nextEditor.setAutocompleteMaxVisible(this.settings.get("autocompleteMaxVisible"));
+		nextEditor.commandSuggestionsPopup = this.settings.get("display.commandSuggestionsPopup");
+		nextEditor.autocompleteSuggestionsPopup = this.settings.get("display.autocompleteSuggestionsPopup");
+		nextEditor.popupFill = this.settings.get("display.popupFill");
+		nextEditor.onAutocompleteRender = (render, offset, rows) => this.ui.setCursorOverlay(render, offset, rows);
 		nextEditor.setSpellingFeatures({
 			typoDetection: this.settings.get("spelling.typoDetection"),
 			autocomplete: this.settings.get("spelling.autocomplete"),