@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/overlays/error-banner.ts

@@ -3,6 +3,10 @@ import { WidthAwareText } from "../render/index";
 import { theme } from "../theme/theme";
 import { DynamicBorder } from "../chrome/dynamic-border";
 import { formatErrorBlock } from "../chrome/error-block";
+import type { NativeNode, NativeUiEvent } from "../native/node";
+import { node, span, text } from "../native/describe";
+import { actionButton } from "../native/overlay";
+import { plainText } from "../native/spans";
 
 /** Max wrapped rows of the error message shown in the pinned banner. */
 const MAX_BANNER_ROWS = 4;
@@ -17,8 +21,14 @@ const MAX_BANNER_ROWS = 4;
  * overflow row reveals the full body inline in the transcript.
  */
 export class ErrorBannerComponent extends Container {
+	readonly #message: string;
+	/** Natively the strip shows the headline; Details unfolds the whole message in place. */
+	#expanded = false;
+	#native: NativeNode | undefined;
+
 	constructor(message: string) {
 		super();
+		this.#message = plainText(message).trim();
 		this.addChild(new Spacer(1));
 		this.addChild(new DynamicBorder(str => theme.fg("error", str)));
 		this.addChild(
@@ -36,4 +46,38 @@ export class ErrorBannerComponent extends Container {
 		this.addChild(new Text(theme.fg("dim", "Dismissed when you send your next message."), 1, 0));
 		this.addChild(new DynamicBorder(str => theme.fg("error", str)));
 	}
+
+	/**
+	 * An error-tinted strip pinned above the composer: the message's first line
+	 * (the transcript's error frame keeps the full message and its actions)
+	 * and a Details button that unfolds the rest here.
+	 */
+	override describe(): NativeNode {
+		if (this.#native) return this.#native;
+		const headline =
+			this.#message
+				.split("\n")
+				.find(line => line.trim() !== "")
+				?.trim() || "Error";
+		const multiline = this.#message !== headline;
+		const message = this.#expanded
+			? text([span(this.#message, "error")], { wrap: "word", grow: 1 })
+			: text([span(headline, "error")], { truncate: "end", lines: 1, grow: 1, title: this.#message });
+		const children: NativeNode[] = [message];
+		if (multiline || headline.length > 80) {
+			children.push(actionButton(this.#expanded ? "Less" : "Details", "details"));
+		}
+		this.#native = node(
+			"row",
+			{ role: "omp.errorBanner", tone: "error", gap: "sm", align: this.#expanded ? "start" : "center" },
+			children,
+		);
+		return this.#native;
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type !== "action" || event.act !== "details") return;
+		this.#expanded = !this.#expanded;
+		this.#native = undefined;
+	}
 }

package/src/overlays/extensions/extension-list.ts

@@ -10,7 +10,8 @@ import { matchesKey } from "../../keys";
 import { padding, truncateToWidth, visibleWidth } from "../../utils";
 import { theme } from "../../theme";
 import { matchesSelectDown, matchesSelectUp } from "../../keybinding-matchers";
-import { contentRowWidth, renderScrollableList, searchableChar } from "../../chrome/selector-helpers";
+import { contentRowWidth, renderScrollableList } from "../../chrome/selector-helpers";
+import { Input } from "../../components/input";
 import { MenuSelection } from "../../components/menu-selection";
 import { scrollOffsetForRow, viewportRange } from "../../components/scroll-viewport";
 import { sanitizeDisplayLine } from "./display-text";
@@ -102,6 +103,8 @@ export class ExtensionList implements Component {
 
 	#extensions: Extension[];
 	readonly #callbacks: ExtensionListCallbacks;
+	/** Search field; its value is pushed into the menu query whenever it changes. */
+	readonly #search = new Input();
 
 	constructor(extensions: Extension[], callbacks: ExtensionListCallbacks = {}, maxVisible?: number) {
 		this.#extensions = extensions;
@@ -110,6 +113,7 @@ export class ExtensionList implements Component {
 		this.#mcpSource = callbacks.mcpSource;
 		this.#toolSource = callbacks.toolSource;
 		this.#maxVisible = maxVisible ?? DEFAULT_MAX_VISIBLE;
+		this.#search.prompt = "";
 		this.#menu = new MenuSelection<ListItem>(this.#buildListItems(""), {
 			getKey: getListItemKey,
 			getSearchText: getListItemSearchText,
@@ -169,7 +173,9 @@ export class ExtensionList implements Component {
 		return item?.type === "kind-header" ? item.kind : null;
 	}
 
+	/** Replace the search text (caret to end) and refilter. */
 	setSearchQuery(query: string): void {
+		if (this.#search.getValue() !== query) this.#search.setValue(query);
 		this.#menu.setQuery(query, false);
 		this.#scrollOffset = 0;
 		this.#notifySelectionChange();
@@ -188,10 +194,14 @@ export class ExtensionList implements Component {
 
 		// Search bar
 		const searchPrefix = theme.fg("muted", "Search: ");
-		const query = this.#menu.query;
-		const searchText = query || (this.#focused ? "" : theme.fg("dim", "type to filter"));
-		const cursor = this.#focused ? theme.fg("accent", "_") : "";
-		lines.push(searchPrefix + searchText + cursor);
+		const query = this.#search.getValue();
+		if (this.#focused) {
+			const fieldWidth = Math.max(1, width - visibleWidth(searchPrefix));
+			const [field = ""] = this.#search.render(Math.min(fieldWidth, visibleWidth(query) + 1));
+			lines.push(searchPrefix + field);
+		} else {
+			lines.push(searchPrefix + (query || theme.fg("dim", "type to filter")));
+		}
 		lines.push("");
 
 		const items = this.#menu.visibleItems;
@@ -631,18 +641,14 @@ export class ExtensionList implements Component {
 			return;
 		}
 
-		// Backspace: Delete from search query
-		if (matchesKey(data, "backspace")) {
-			if (this.#menu.query.length > 0) {
-				this.setSearchQuery(this.#menu.query.slice(0, -1));
-			}
-			return;
-		}
-
-		// Printable characters -> search
-		const char = searchableChar(data);
-		if (char !== null) {
-			this.setSearchQuery(this.#menu.query + char);
+		// Everything else edits the search field; refilter only when the text changed.
+		const before = this.#search.getValue();
+		this.#search.handleInput(data);
+		const after = this.#search.getValue();
+		if (after !== before) {
+			this.#menu.setQuery(after, false);
+			this.#scrollOffset = 0;
+			this.#notifySelectionChange();
 		}
 	}
 

package/src/overlays/history-search.ts

@@ -21,6 +21,8 @@ import {
 export interface HistorySearchEntry {
 	prompt: string;
 	created_at: number;
+	/** Project folder the prompt was typed in. */
+	cwd?: string;
 }
 
 /** Searchable prompt history supplied by the host. */
@@ -28,11 +30,37 @@ export interface HistorySource {
 	search(query: string, limit: number): HistorySearchEntry[];
 	getRecent(limit: number): HistorySearchEntry[];
 }
-import { editorKeys, keyHint, rawKeyHint } from "../chrome/keybinding-hints";
+import { boundKeys, editorKeys, keyHint, rawKeyHint } from "../chrome/keybinding-hints";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { contentRowWidth, renderScrollableList } from "../chrome/selector-helpers";
 import { MenuSelection } from "../components/menu-selection";
 import { centeredViewportRange } from "../components/scroll-viewport";
+import type { KeyName } from "../key-hint-format";
+import type { TspPickerItem } from "@oh-my-pi/pi-wire";
+import { col, keyed, node, span } from "../native/describe";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node";
+import { actionHint, hintsRow, overlayCard } from "../native/overlay";
+import { picker, pickerAction, pickerAge, pickerDate, pickerEvent, pickerHits, pickerQuery } from "../native/picker";
+import { shortenPath } from "../render/render-utils";
+
+const ENTER_KEYS: readonly KeyName[] = ["enter"];
+
+/** Native item key of a history entry: key-path safe (prompts may hold `/` and newlines), stable across queries. */
+function nativeEntryKey(entry: HistorySearchEntry): string {
+	return `${entry.created_at}-${Bun.hash(entry.prompt).toString(36)}`;
+}
+
+interface HistoryNativeMemo {
+	picker: boolean;
+	items: readonly HistorySearchEntry[];
+	selected: HistorySearchEntry | undefined;
+	query: string;
+	cursor: number;
+	node: NativeNode;
+}
+
+/** Key of the `picker` child a dock-mounted history search describes (hoisted into `layer`). */
+const PICKER_KEY = "picker";
 
 /** Visible result rows; also the jump distance for PageUp/PageDown. */
 const MAX_VISIBLE = 10;
@@ -47,46 +75,31 @@ function queryTokens(query: string): string[] {
 
 /** Wrap every case-insensitive occurrence of any token in `text` with the accent color. */
 function highlightTokens(text: string, tokens: string[]): string {
-	if (tokens.length === 0) return text;
-
-	const lower = text.toLowerCase();
-	const ranges: Array<[number, number]> = [];
-	for (const tok of tokens) {
-		let from = lower.indexOf(tok);
-		while (from !== -1) {
-			ranges.push([from, from + tok.length]);
-			from = lower.indexOf(tok, from + tok.length);
-		}
-	}
+	const ranges = pickerHits(text, tokens);
 	if (ranges.length === 0) return text;
-
-	ranges.sort((a, b) => a[0] - b[0]);
 	let out = "";
 	let pos = 0;
 	for (const [start, end] of ranges) {
-		if (end <= pos) continue; // fully covered by a previous (merged) range
-		const from = Math.max(start, pos);
-		if (from > pos) out += text.slice(pos, from);
-		out += theme.fg("accent", text.slice(from, end));
+		if (start > pos) out += text.slice(pos, start);
+		out += theme.fg("accent", text.slice(start, end));
 		pos = end;
 	}
 	if (pos < text.length) out += text.slice(pos);
 	return out;
 }
 
-/** Compact "time since" label (e.g. `now`, `5m`, `2h`, `3d`, `2w`, `6mo`, `1y`) from epoch seconds. */
-function relativeTime(epochSeconds: number): string {
-	const seconds = Math.max(0, Math.floor(Date.now() / 1000) - epochSeconds);
-	if (seconds < 60) return "now";
-	const minutes = Math.floor(seconds / 60);
-	if (minutes < 60) return `${minutes}m`;
-	const hours = Math.floor(minutes / 60);
-	if (hours < 24) return `${hours}h`;
-	const days = Math.floor(hours / 24);
-	if (days < 7) return `${days}d`;
-	if (days < 30) return `${Math.floor(days / 7)}w`;
-	if (days < 365) return `${Math.floor(days / 30)}mo`;
-	return `${Math.floor(days / 365)}y`;
+/** A past prompt as a picker row: its first line (with query hits), age and project folder. */
+function historyPickerItem(entry: HistorySearchEntry, tokens: readonly string[]): TspPickerItem {
+	const label = entry.prompt.trim().split("\n", 1)[0]!.replace(/\s+/g, " ").trim();
+	const hits = pickerHits(label, tokens);
+	return {
+		id: nativeEntryKey(entry),
+		label,
+		...(entry.cwd ? { detail: shortenPath(entry.cwd) } : {}),
+		facts: { when: pickerAge(entry.created_at * 1000) },
+		...(hits.length > 0 ? { hits } : {}),
+		title: pickerDate(entry.created_at * 1000),
+	};
 }
 
 class HistoryResultsList implements Component {
@@ -133,7 +146,7 @@ class HistoryResultsList implements Component {
 			if (!entry) continue;
 			const isSelected = i === this.#menu.selectedIndex;
 
-			const timeStr = relativeTime(entry.created_at);
+			const timeStr = pickerAge(entry.created_at * 1000);
 			const timeWidth = visibleWidth(timeStr);
 			const showTime = rowWidth >= gutterWidth + 12 + timeWidth;
 
@@ -170,9 +183,12 @@ export class HistorySearchComponent extends OverlayPanel {
 	#onSelect: (prompt: string) => void;
 	#onCancel: () => void;
 	#resultLimit = 100;
+	#nativeHints: NativeNode | undefined;
+	#nativeMemo: HistoryNativeMemo | undefined;
+	#pickerItems: { items: readonly HistorySearchEntry[]; rows: readonly TspPickerItem[] } | undefined;
 
 	constructor(historyStorage: HistorySource, onSelect: (prompt: string) => void, onCancel: () => void) {
-		super("History");
+		super("History", "omp.overlay.history");
 		this.#historyStorage = historyStorage;
 		this.#onSelect = onSelect;
 		this.#onCancel = onCancel;
@@ -257,6 +273,132 @@ export class HistorySearchComponent extends OverlayPanel {
 		this.#updateResults();
 	}
 
+	/**
+	 * With the `picker` kind: a `size:"md"` sheet of past prompts (first line
+	 * with hits, age, folder) as a keyed child the reconciler hoists into
+	 * `layer`, since the selector replaces the editor in the dock. Otherwise
+	 * the query field (the `Input`, which describes itself as `input`), the
+	 * results as a `list` keyed by entry (filter = query, age as the item
+	 * value), and the key hints.
+	 */
+	override describe(cx: DescribeContext): NativeNode {
+		const items = this.#menu.visibleItems;
+		const selected = this.#menu.selectedItem;
+		const usePicker = cx.supports("picker");
+		const query = usePicker ? this.#searchInput.getValue() : this.#searchInput.getValue().trim();
+		const cursor = this.#searchInput.getCursor();
+		const memo = this.#nativeMemo;
+		if (
+			memo &&
+			memo.picker === usePicker &&
+			memo.items === items &&
+			memo.selected === selected &&
+			memo.query === query &&
+			memo.cursor === cursor
+		) {
+			return memo.node;
+		}
+		if (usePicker) {
+			const root = col([keyed(this.#describePicker(items, selected, query), PICKER_KEY)]);
+			this.#nativeMemo = { picker: true, items, selected, query, cursor, node: root };
+			return root;
+		}
+
+		const rows = items.map(entry =>
+			node(
+				"item",
+				{
+					label: entry.prompt.replace(/\s+/g, " ").trim(),
+					value: [span(pickerAge(entry.created_at * 1000), "dim")],
+				},
+				undefined,
+				nativeEntryKey(entry),
+			),
+		);
+		const list = node(
+			"list",
+			{
+				selected: selected ? nativeEntryKey(selected) : null,
+				filter: query || undefined,
+				empty: query ? "No matching history" : "No history yet",
+				max: { lines: MAX_VISIBLE },
+				virtual: true,
+			},
+			rows,
+			"list",
+		);
+		this.#nativeHints ??= hintsRow([
+			actionHint(["tui.select.up", "tui.select.down"], "navigate"),
+			{ keys: ENTER_KEYS, label: "select" },
+			actionHint("tui.select.cancel", "cancel"),
+		]);
+		const root = overlayCard(this.nativeRole, this.title, [this.#searchInput, list, this.#nativeHints]);
+		this.#nativeMemo = { picker: false, items, selected, query, cursor, node: root };
+		return root;
+	}
+
+	#describePicker(
+		items: readonly HistorySearchEntry[],
+		selected: HistorySearchEntry | undefined,
+		query: string,
+	): NativeNode {
+		let rows = this.#pickerItems;
+		if (rows?.items !== items) {
+			const tokens = queryTokens(query.trim());
+			rows = { items, rows: items.map(entry => historyPickerItem(entry, tokens)) };
+			this.#pickerItems = rows;
+		}
+		return picker({
+			title: this.title,
+			icon: "history",
+			noun: "prompts",
+			size: "md",
+			layout: "rows",
+			preview: "none",
+			...pickerQuery(this.#searchInput),
+			placeholder: "Search prompts…",
+			columns: [{ id: "when", format: "time" }],
+			items: rows.rows,
+			selected: selected ? nativeEntryKey(selected) : null,
+			empty: "No history yet",
+			actions: [
+				pickerAction("insert", "Insert", "enter", { primary: true }),
+				pickerAction("close", "Close", boundKeys("app.interrupt", ["escape"])[0] ?? "escape", { end: true }),
+			],
+		});
+	}
+
+	/**
+	 * Picker: a row click highlights, a second click or `Insert` inserts it
+	 * (Enter), `Close` cancels (Esc), `Clear search` empties the query.
+	 * List: picking a result does what highlighting it and pressing Enter does.
+	 */
+	handleNativeEvent(event: NativeUiEvent): void {
+		const ev = pickerEvent(event, PICKER_KEY);
+		if (ev) {
+			if (ev.kind === "action") {
+				if (ev.act === "close") this.#onCancel();
+				else if (ev.act === "insert") this.handleInput("\r");
+				else if (ev.act === "clear") {
+					this.#searchInput.setValue("");
+					this.#updateResults();
+				}
+				return;
+			}
+			const index = this.#menu.visibleItems.findIndex(entry => nativeEntryKey(entry) === ev.item);
+			if (index < 0) return;
+			this.#menu.setSelectedIndex(index);
+			if (ev.kind === "activate") this.#onSelect(this.#menu.visibleItems[index]!.prompt);
+			return;
+		}
+		if ((event.type !== "select" && event.type !== "activate") || event.key !== "list") return;
+		const index = this.#menu.visibleItems.findIndex(entry => nativeEntryKey(entry) === event.item);
+		const target = this.#menu.visibleItems[index];
+		if (!target) return;
+		this.#menu.setSelectedIndex(index);
+		this.#onSelect(target.prompt);
+	}
+
 	#updateResults(): void {
 		const query = this.#searchInput.getValue().trim();
 		const results = query

package/src/overlays/hook-editor.ts

@@ -7,6 +7,9 @@
  *   (Ctrl+Q / Ctrl+Enter) submits, bordered popup
  * - Prompt-style (ask): Enter submits, Shift+Enter inserts newline, legacy ask chrome
  */
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { compactImageMarkers, formatVisionMarker, PLACEHOLDER_REGEX } from "../prompt/composer-attachments";
+import { extractImagePastePathsFromText } from "../prompt/custom-editor";
 import { Editor, type Focusable, matchesKey, Spacer, Text, type TUI } from "../index";
 import { BracketedPasteHandler } from "../bracketed-paste";
 import { getEditorTheme, theme } from "../theme/theme";
@@ -16,12 +19,32 @@ import { OverlayPanel } from "../chrome/overlay-box";
 import { FormField } from "../components/form";
 import { formatKeyHint, formatKeyHints } from "../app-keybindings";
 import { boundKeys, editorKey, interruptKey } from "../chrome/keybinding-hints";
+import { node, span } from "../native/describe";
+import type { DescribeContext, NativeChild, NativeNode } from "../native/node";
+import { hintsRow, type NativeHint, overlayCard } from "../native/overlay";
+import { plainText } from "../native/spans";
 
 export interface HookEditorOptions {
 	/** Edit text with the host's configured external editor. */
 	externalEditor?: (text: string) => Promise<string | null>;
 	/** When true, use prompt-style keybindings with the legacy ask prompt chrome. */
 	promptStyle?: boolean;
+	/** Allow clipboard images to be attached to this prompt. */
+	acceptImages?: boolean;
+	/** Images already represented by markers in the prefilled text. */
+	images?: readonly ImageContent[];
+	/**
+	 * With `acceptImages`, called for an empty bracketed paste, which is how terminals that own
+	 * the paste key send an image-only clipboard (#3601). Same signature as
+	 * `CustomEditor.onPasteImage`; the host calls `beginPaste` before its first await.
+	 */
+	onPasteImage?: () => Promise<boolean>;
+	/**
+	 * With `acceptImages`, called for each path of a bracketed paste made only of image paths.
+	 * Same signature as `CustomEditor.onPasteImagePath`; calls are not awaited in turn, so images
+	 * attach as they finish loading and are renumbered in text order on submit.
+	 */
+	onPasteImagePath?: (path: string) => void | Promise<void>;
 	/**
 	 * Max rows the inner Editor may occupy. When omitted, the editor is
 	 * bounded to the current terminal height minus the component's chrome
@@ -35,15 +58,21 @@ export interface HookEditorOptions {
 export class HookEditorComponent extends OverlayPanel implements Focusable {
 	#editor: Editor;
 	#field: FormField;
-	#onSubmitCallback: (value: string) => void;
+	#onSubmitCallback: (value: string, images?: ImageContent[]) => void;
 	#onCancelCallback: () => void;
 	#tui: TUI;
 	#promptStyle: boolean;
+	#acceptImages: boolean;
+	#images: ImageContent[];
 	#externalEditor: HookEditorOptions["externalEditor"];
+	#onPasteImage: HookEditorOptions["onPasteImage"];
+	#onPasteImagePath: HookEditorOptions["onPasteImagePath"];
 	#pasteHandler = new BracketedPasteHandler();
 	#pendingPastes: { settled: boolean; text: string | undefined }[] = [];
 	#submitQueued = false;
 	#disposed = false;
+	/** Detail lines, hints and the editor under the title; every part is fixed, so it is built once. */
+	#nativeRoot: NativeNode;
 	/** Focus state mirrored to the nested editor during rendering. */
 	focused = false;
 
@@ -51,7 +80,7 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 		tui: TUI,
 		title: string,
 		prefill: string | undefined,
-		onSubmit: (value: string) => void,
+		onSubmit: (value: string, images?: ImageContent[]) => void,
 		onCancel: () => void,
 		options?: HookEditorOptions,
 	) {
@@ -59,13 +88,17 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 		// bounded ask question under "◆ Other (type your own)") stay as body rows
 		// so they are never truncated into the one-row border.
 		const [titleLine = "", ...detailLines] = title.split("\n");
-		super(titleLine);
+		super(titleLine, "omp.overlay.hook-editor");
 
 		this.#tui = tui;
 		this.#onSubmitCallback = onSubmit;
 		this.#onCancelCallback = onCancel;
 		this.#promptStyle = options?.promptStyle ?? false;
+		this.#acceptImages = options?.acceptImages ?? false;
+		this.#images = this.#acceptImages ? [...(options?.images ?? [])] : [];
 		this.#externalEditor = options?.externalEditor;
+		this.#onPasteImage = options?.onPasteImage;
+		this.#onPasteImagePath = options?.onPasteImagePath;
 
 		// Editor
 		this.#editor = new Editor(getEditorTheme());
@@ -74,6 +107,8 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 			this.#editor.setPromptGutter("> ");
 			this.#editor.disableSubmit = true;
 		}
+		// Image markers delete as a unit, like the main editor's attachment tokens.
+		if (options?.acceptImages) this.#editor.atomicTokenPattern = PLACEHOLDER_REGEX;
 		// Bound the editor so long content scrolls instead of pushing the
 		// submit hint off-screen. Caller may override via options.maxHeight.
 		const termRows = this.#tui.terminal?.rows ?? process.stdout.rows ?? 40;
@@ -99,6 +134,41 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 		});
 		this.addChild(this.#field);
 		this.addChild(new Spacer(1));
+
+		const externalHint: NativeHint = {
+			keys: boundKeys("app.editor.external", ["ctrl+g"]).slice(0, 1),
+			label: "external editor",
+		};
+		const nativeHints: NativeHint[] = this.#promptStyle
+			? [
+					{ keys: ["enter", primaryFollowUpKey], label: "submit" },
+					{ keys: ["escape"], label: "cancel" },
+					externalHint,
+				]
+			: [
+					{ keys: followUpKeys, label: "submit" },
+					{ keys: boundKeys("app.interrupt", ["escape"]).slice(0, 1), label: "cancel" },
+					externalHint,
+				];
+		const nativeChildren: NativeChild[] = [];
+		if (detailLines.length > 0) {
+			nativeChildren.push(
+				node(
+					"text",
+					{ spans: [span(plainText(detailLines.join("\n")), "accent")], wrap: "word" },
+					undefined,
+					"detail",
+				),
+			);
+		}
+		nativeChildren.push(this.#editor, hintsRow(nativeHints));
+		this.#nativeRoot = overlayCard(this.nativeRole, plainText(titleLine), nativeChildren);
+	}
+
+	/** The editor (which describes itself) under the title and detail lines, with the key hints below. */
+	override describe(_cx: DescribeContext): NativeNode {
+		this.#field.focused = this.focused;
+		return this.#nativeRoot;
 	}
 
 	/** Keep the nested editor's software/hardware cursor mode aligned with the dialog focus target. */
@@ -117,7 +187,20 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 		const paste = this.#pasteHandler.process(keyData);
 		if (paste.handled) {
 			if (paste.pasteContent === undefined) return;
-			this.pasteText(paste.pasteContent);
+			// Hosts reserve ordered delivery synchronously inside these callbacks, so input
+			// that followed the paste in this chunk (e.g. Enter) still waits for the image.
+			const content = paste.pasteContent;
+			const acceptsImages = this.acceptsImages;
+			if (acceptsImages && content.length === 0 && this.#onPasteImage) {
+				void this.#onPasteImage();
+			} else {
+				const imagePaths = acceptsImages ? extractImagePastePathsFromText(content) : undefined;
+				if (imagePaths && this.#onPasteImagePath) {
+					for (const path of imagePaths) void this.#onPasteImagePath(path);
+				} else {
+					this.pasteText(content);
+				}
+			}
 			if (paste.remaining.length > 0) this.handleInput(paste.remaining);
 			return;
 		}
@@ -134,10 +217,34 @@ export class HookEditorComponent extends OverlayPanel implements Focusable {
 			this.#submitQueued = true;
 			return;
 		}
-		const text = this.#editor.getExpandedText();
+		let text = this.#editor.getExpandedText();
 		if (requireText && text.trim().length === 0) return;
+		let images: ImageContent[] | undefined;
+		if (this.#images.length > 0) {
+			// Path pastes attach as they finish loading; submit numbers images in text order.
+			const compacted = compactImageMarkers(text, this.#images.length, { byAppearance: true });
+			if (compacted) {
+				text = compacted.text;
+				images = compacted.keep.map(index => this.#images[index]);
+			} else {
+				images = this.#images;
+			}
+		}
 		this.dispose();
-		this.#onSubmitCallback(text);
+		if (images?.length) this.#onSubmitCallback(text, images);
+		else this.#onSubmitCallback(text);
+	}
+
+	/** Whether this prompt opted into clipboard image attachments. */
+	get acceptsImages(): boolean {
+		return this.#acceptImages && !this.#disposed;
+	}
+
+	/** Attach an image; returns its `[Image #N, WxH]` marker for the caller to deliver. */
+	attachImage(image: ImageContent, dims?: { width: number; height: number }): string | undefined {
+		if (!this.acceptsImages) return undefined;
+		this.#images.push(image);
+		return formatVisionMarker("image", this.#images.length, dims);
 	}
 
 	/** Reserve ordered clipboard delivery. Completion accepts nonempty text once, or releases on undefined. */

package/src/overlays/hook-input.ts

@@ -8,6 +8,10 @@ import { formTheme } from "../chrome/form-theme";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { Form, TextFormField } from "../components/form";
 import { editorKey, interruptKey } from "../chrome/keybinding-hints";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
+import { overlayCard } from "../native/overlay";
+import { plainText } from "../native/spans";
 
 export interface HookInputOptions {
 	tui?: TUI;
@@ -22,6 +26,7 @@ export class HookInputComponent extends OverlayPanel {
 	#onCancelCallback: () => void;
 	#baseTitle: string;
 	#countdown: CountdownTimer | undefined;
+	#nativeMemo: { countdown: NativeNode | undefined; node: NativeNode } | undefined;
 
 	constructor(
 		title: string,
@@ -30,7 +35,7 @@ export class HookInputComponent extends OverlayPanel {
 		onCancel: () => void,
 		opts?: HookInputOptions,
 	) {
-		super(title);
+		super(title, "omp.overlay.hook-input");
 
 		this.#onSubmitCallback = onSubmit;
 		this.#onCancelCallback = onCancel;
@@ -82,4 +87,20 @@ export class HookInputComponent extends OverlayPanel {
 		this.#countdown?.dispose();
 		super.dispose();
 	}
+
+	/** A card over the form, headed by the title plus the countdown `elapsed` while a timeout runs. */
+	override describe(_cx: DescribeContext): NativeNode {
+		const countdown = this.#countdown?.describe();
+		const memo = this.#nativeMemo;
+		if (memo && memo.countdown === countdown) return memo.node;
+		const title = plainText(this.#baseTitle);
+		const root = countdown
+			? overlayCard(this.nativeRole, undefined, [
+					node("row", { gap: "sm", align: "baseline" }, [node("text", { text: title }), countdown], "head"),
+					this.#form,
+				])
+			: overlayCard(this.nativeRole, title, [this.#form]);
+		this.#nativeMemo = { countdown, node: root };
+		return root;
+	}
 }