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

package/src/overlays/omfg-panel.ts

@@ -3,7 +3,10 @@ import { replaceTabs } from "../render/render-utils";
 import { getMarkdownTheme, theme } from "../theme/theme";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { StreamingPanelContent } from "../chrome/streaming-panel";
-import { interruptKey } from "../chrome/keybinding-hints";
+import { boundKeys, interruptKey } from "../chrome/keybinding-hints";
+import type { NativeNode } from "../native/node";
+import { col, md, node, span, text } from "../native/describe";
+import { hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
 
 export type OmfgPanelState =
 	| "generating"
@@ -15,6 +18,18 @@ export type OmfgPanelState =
 	| "aborted"
 	| "error";
 
+/** States with work still in flight (the sheet head shows the live spinner). */
+const LIVE_STATES: Record<OmfgPanelState, boolean> = {
+	generating: true,
+	validating: true,
+	confirming: true,
+	saving: true,
+	saved: false,
+	rejected: false,
+	aborted: false,
+	error: false,
+};
+
 interface OmfgPanelComponentOptions {
 	complaint: string;
 	tui: TUI;
@@ -28,11 +43,14 @@ export class OmfgPanelComponent extends OverlayPanel {
 	#savedPath: string | undefined;
 	#errorMessage: string | undefined;
 	#closed = false;
+	readonly #complaint: string;
 	readonly #content: StreamingPanelContent;
+	#native: NativeNode | undefined;
 
 	constructor(options: OmfgPanelComponentOptions) {
-		super(`/omfg ${replaceTabs(options.complaint)}`);
+		super(`/omfg ${replaceTabs(options.complaint)}`, "omp.overlay.omfg");
 		this.#tui = options.tui;
+		this.#complaint = replaceTabs(options.complaint);
 		this.#content = new StreamingPanelContent(() => ({
 			sections: [new Text(theme.fg("muted", replaceTabs(this.#status)), 0, 0), this.#contentComponent()],
 			footer: this.#footerLine(),
@@ -98,7 +116,73 @@ export class OmfgPanelComponent extends OverlayPanel {
 		this.#closed = true;
 	}
 
+	override invalidate(): void {
+		this.#native = undefined;
+		super.invalidate();
+	}
+
+	override describe(): NativeNode {
+		if (this.#native) return this.#native;
+		const tone =
+			this.#state === "error"
+				? "error"
+				: this.#state === "rejected" || this.#state === "aborted"
+					? "warning"
+					: undefined;
+		// Inline in the dock, styled as a sheet by role: a borderless column headed by the complaint.
+		const head = node("row", { role: "omp.sheet.head", gap: "sm", align: "center" }, [
+			...(LIVE_STATES[this.#state] ? [node("spinner", {})] : []),
+			text([span("/omfg", "accent"), span(` ${this.#complaint}`)], { truncate: "end", lines: 1 }),
+		]);
+		this.#native = col(
+			[
+				head,
+				text([span(replaceTabs(this.#status), "muted")], { wrap: "word" }),
+				this.#describeBody(),
+				this.#describeFooter(),
+			],
+			{ role: this.nativeRole, gap: "sm", tone },
+		);
+		return this.#native;
+	}
+
+	#describeBody(): NativeNode {
+		if (this.#state === "error") {
+			return text([span(replaceTabs(this.#errorMessage ?? "Unknown error"), "error")], { wrap: "word" });
+		}
+		const preview = replaceTabs(this.#preview).trim();
+		if (preview) return md(preview, { stream: this.#state === "generating" });
+		return text([span(`${theme.status.pending} Waiting for candidate rule…`, "dim")]);
+	}
+
+	#describeFooter(): NativeNode {
+		const esc: NativeHint = { keys: boundKeys("app.interrupt", ["escape"]).slice(0, 1), label: "dismiss" };
+		switch (this.#state) {
+			case "generating":
+			case "validating":
+			case "confirming":
+			case "saving":
+				return hintsRow([{ ...esc, label: "cancel /omfg" }]);
+			case "saved":
+				return statusHintsRow(
+					[
+						span(`${theme.status.success} Registered live`, "success"),
+						span(" · ", "muted"),
+						span(replaceTabs(this.#savedPath ?? "saved"), "path"),
+					],
+					[esc],
+				);
+			case "rejected":
+				return statusHintsRow([span(`${theme.status.warning} Not saved`, "warning")], [esc]);
+			case "aborted":
+				return statusHintsRow([span(`${theme.status.warning} Cancelled`, "warning")], [esc]);
+			case "error":
+				return statusHintsRow([span(`${theme.status.error} Error`, "error")], [esc]);
+		}
+	}
+
 	#rebuild(): void {
+		this.#native = undefined;
 		this.#content.refresh();
 		this.#tui.requestRender();
 	}

package/src/overlays/pause-screen.ts

@@ -18,7 +18,11 @@ import { centerLine } from "../utils";
 import { theme } from "../theme/theme";
 import { matchesAppInterrupt } from "../keybinding-matchers";
 import { formatKeyHint } from "../app-keybindings";
-import { interruptKey } from "../chrome/keybinding-hints";
+import { boundKeys, interruptKey } from "../chrome/keybinding-hints";
+import type { NativeNode, NativeUiEvent } from "../native/node";
+import { col, node, row, span, text } from "../native/describe";
+import { actionBar, actionButton } from "../native/overlay";
+import { isNativeRendering } from "../native/state";
 
 /**
  * Slice of `InteractiveModeContext` the pause screen drives. Narrow so tests
@@ -120,15 +124,20 @@ export class PauseScreenComponent implements Component, OverlayFocusOwner {
 	#done = Promise.withResolvers<void>();
 	#disposed = false;
 	#startedAt = Date.now();
+	#native: NativeNode | undefined;
 
 	constructor(readonly host: PauseScreenHost) {}
 
 	/** Start the clock; resolves once the user asks to resume. */
 	run(): Promise<void> {
 		this.#startedAt = agentPauseGate.pausedAt ?? Date.now();
-		this.#timer ??= setInterval(() => {
-			if (!this.#disposed) this.host.ui.requestRender();
-		}, TICK_MS);
+		this.#native = undefined;
+		// The tick only repaints the hold clock; natively the `elapsed` node counts on its own.
+		if (!isNativeRendering()) {
+			this.#timer ??= setInterval(() => {
+				if (!this.#disposed) this.host.ui.requestRender();
+			}, TICK_MS);
+		}
 		this.host.ui.requestRender();
 		return this.#done.promise;
 	}
@@ -160,6 +169,48 @@ export class PauseScreenComponent implements Component, OverlayFocusOwner {
 		}
 	}
 
+	invalidate(): void {
+		this.#native = undefined;
+	}
+
+	/** A glass sheet titled "Paused" (not the whole pane: the transcript stays visible, frozen). */
+	readonly nativeOverlay = { role: "omp.overlay.pause", size: "md", anchor: "center", head: "Paused" } as const;
+
+	describe(): NativeNode {
+		if (this.#native) return this.#native;
+		const children: NativeNode[] = [];
+		if (this.host.sessionName) children.push(text([span(this.host.sessionName, "strong")]));
+		const resumeKey = boundKeys("app.interrupt", ["escape"])[0] ?? "escape";
+		children.push(
+			text(
+				BODY_LINES.map((line, index) => span(index === 0 ? line : `\n${line}`, "muted")),
+				{ wrap: "word" },
+			),
+			row(
+				[
+					text([span("Paused for", "dim")]),
+					node("elapsed", { age: Date.now() - this.#startedAt, format: "clock" }),
+				],
+				{ gap: "xs", align: "baseline" },
+			),
+			actionBar([
+				null,
+				actionButton("Resume", "resume", {
+					keys: resumeKey,
+					tone: "accent",
+					title: `Resume  ${resumeKey} · enter · space`,
+				}),
+			]),
+		);
+		this.#native = col(children, { gap: "md" });
+		return this.#native;
+	}
+
+	/** Resume runs what Esc/Enter/Space run. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "resume" && !this.#disposed) this.#done.resolve();
+	}
+
 	render(width: number): readonly string[] {
 		const elapsed = Date.now() - this.#startedAt;
 		return renderPauseScreen(

package/src/overlays/plan-review-overlay.ts

@@ -54,9 +54,16 @@ import { padToWidth } from "../render/utils";
 import { renderSegmentTrack } from "../chrome/segment-track";
 import { formatKeyHint, formatKeyHints } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
+import type { KeyName } from "../key-hint-format";
+import { col, item, keyed, md, node, row as rowNode, span, text } from "../native/describe";
+import { leafKey, type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
+import { actionButton, actionHint, hintsRow, itemIndex, type NativeHint, selectList } from "../native/overlay";
+import { getKeybindings } from "../keybindings";
 
 /** Title shown in the overlay's top border. */
 const OVERLAY_TITLE = "Plan Review";
+/** Native sheet title when the plan has no title heading of its own. */
+const NATIVE_TITLE = "Plan review";
 /** Minimum plan-body rows kept visible even on short terminals. */
 const MIN_BODY_ROWS = 3;
 /** Visible rows for the in-overlay annotation editor before it scrolls. */
@@ -107,6 +114,14 @@ interface AnnotationChooser {
 	selected: number;
 }
 
+/** Described plan body and Contents entries, rebuilt when sections or annotations change. */
+interface NativePlanContent {
+	sections: OverlaySection[];
+	rev: number;
+	body: NativeNode[];
+	toc: NativeNode[];
+}
+
 /** Serializable annotations retained by the plan-review owner between overlays. */
 export interface PlanReviewAnnotationState {
 	annotations: Array<{
@@ -173,6 +188,10 @@ export class PlanReviewOverlay implements Component {
 	#scrollView: ScrollView;
 	#sections: OverlaySection[] = [];
 	#toc: number[] = [];
+	/** Section holding the plan's title heading (dropped from the ToC; the native sheet title), or -1. */
+	#titleIndex = -1;
+	/** Memoized {@link nativeOverlay} for the current title. */
+	#nativeOverlay: { title: string; props: NonNullable<Component["nativeOverlay"]> } | undefined;
 	/** Shallowest level among ToC entries, used to flatten indentation. */
 	#tocBaseLevel = 1;
 	#sectionOffsets: number[] = [];
@@ -223,6 +242,14 @@ export class PlanReviewOverlay implements Component {
 	#editingAnnotation: AnnotationSelection | undefined;
 	#annotationChooser: AnnotationChooser | undefined;
 
+	/** Bumped on every section/annotation change (all of them funnel through {@link #recomputeFeedback}). */
+	#annotationRev = 0;
+	#nativeContent: NativePlanContent | undefined;
+	#nativeSig = "";
+	#nativeRoot: NativeNode | undefined;
+	/** Content the memoized root was built from. */
+	#nativeRootContent: NativePlanContent | undefined;
+
 	constructor(
 		planContent: string,
 		options: PlanReviewOverlayOptions,
@@ -443,6 +470,7 @@ export class PlanReviewOverlay implements Component {
 		for (const i of headings) minLevel = Math.min(minLevel, this.#sections[i]!.level);
 		const topLevel = headings.filter(i => this.#sections[i]!.level === minLevel);
 		const titleIndex = topLevel.length === 1 && headings[0] === topLevel[0] ? topLevel[0] : -1;
+		this.#titleIndex = titleIndex ?? -1;
 		this.#toc = headings.filter(i => i !== titleIndex);
 		this.#tocBaseLevel = this.#toc.length > 0 ? Math.min(...this.#toc.map(i => this.#sections[i]!.level)) : 1;
 	}
@@ -996,6 +1024,7 @@ export class PlanReviewOverlay implements Component {
 	}
 
 	#recomputeFeedback(): void {
+		this.#annotationRev++;
 		this.callbacks.onAnnotationStateChange?.(this.#annotationState());
 		const annotated = this.#sections.filter(section => section.annotations.length > 0);
 		if (annotated.length === 0 && this.#deleted.length === 0) {
@@ -1351,6 +1380,329 @@ export class PlanReviewOverlay implements Component {
 		return [theme.fg("dim", this.#buildHelp())];
 	}
 
+	/** The native sheet: large glass, titled by the plan's own title heading (the body never repeats it). */
+	get nativeOverlay(): NonNullable<Component["nativeOverlay"]> {
+		const heading = this.#sections[this.#titleIndex]?.title;
+		const title = heading ? sanitizeStatusText(heading) : NATIVE_TITLE;
+		if (this.#nativeOverlay?.title !== title) {
+			this.#nativeOverlay = {
+				title,
+				props: { role: "omp.overlay.planReview", size: "lg", anchor: "center", head: title },
+			};
+		}
+		return this.#nativeOverlay.props;
+	}
+
+	describe(): NativeNode {
+		// The terminal lays out the sidebar; it is shown whenever the Contents has
+		// enough entries, which is also what Tab cycling consults.
+		this.#sidebarShown = this.#toc.length >= SIDEBAR_MIN_HEADINGS;
+		if (this.#annotating) this.#editor.focused = true;
+		const content = this.#describeContent();
+		const chooser = this.#annotationChooser;
+		const target = this.#annotationTarget;
+		const sig = [
+			this.#focus,
+			this.#tocCursor,
+			this.#selectedIndex,
+			this.#sliderIndex,
+			this.#committed ? `committed:${this.#committedLabel ?? ""}` : "",
+			this.#annotating
+				? `annotating:${target?.sectionIndex}:${target?.row}:${target?.context}:${this.#editingAnnotation !== undefined}`
+				: "",
+			chooser
+				? `chooser:${chooser.selected}:${chooser.entries.map(e => `${e.sectionIndex}.${e.annotationIndex}`).join()}`
+				: "",
+		].join("|");
+		if (this.#nativeRoot && sig === this.#nativeSig && content === this.#nativeRootContent) return this.#nativeRoot;
+
+		const children: NativeChild[] = [];
+		const tools = this.#describeTools();
+		if (tools) children.push(tools);
+		const bodyCol = node(
+			"col",
+			{ role: "omp.plan.body", grow: 1, gap: "md", tone: this.#focus === "body" ? "accent" : undefined },
+			content.body,
+			"body",
+		);
+		if (this.#sidebarShown) {
+			const tocSection = this.#toc[this.#tocCursor];
+			const toc = selectList("toc", content.toc, {
+				selected: tocSection === undefined ? null : `h${tocSection}`,
+				role: "omp.plan.toc",
+				tone: this.#focus === "toc" ? "accent" : undefined,
+			});
+			const sidebar = node("col", { max: { w: "32ch" }, shrink: 0 }, [toc], "sidebar");
+			children.push(keyed(rowNode([sidebar, bodyCol], { gap: "lg", align: "start" }), "split"));
+		} else {
+			children.push(bodyCol);
+		}
+		if (this.#promptTitle) {
+			children.push(keyed(text([span(this.#promptTitle, "muted")], { role: "omp.plan.prompt" }), "prompt"));
+		}
+		if (this.#committed) {
+			const label = this.#committedLabel ? `${this.#committedLabel} — submitting…` : "Submitting…";
+			children.push(node("spinner", { label: [span(label, "accent strong")] }, undefined, "options"));
+			children.push(
+				keyed(
+					text([span("Applying your selection — this can take a moment while context is prepared.", "dim")], {
+						wrap: "word",
+					}),
+					"footer",
+				),
+			);
+		} else {
+			children.push(...this.#describeSlider());
+			// The decision bar: Tern lays the list out as buttons, the first one the hero.
+			const optionItems = this.#options.map((label, i) =>
+				item(`o${i}`, {
+					label,
+					disabled: this.#disabled.has(i) || undefined,
+					hint: i === this.#selectedIndex ? ["enter"] : undefined,
+				}),
+			);
+			children.push(
+				selectList("options", optionItems, {
+					selected: this.#selectedIndex >= 0 ? `o${this.#selectedIndex}` : null,
+					role: "omp.plan.options",
+					tone: this.#focus === "actions" ? "accent" : undefined,
+				}),
+			);
+			children.push(...this.#describeFooter());
+		}
+
+		this.#nativeSig = sig;
+		this.#nativeRootContent = content;
+		// The sheet is the frame: a borderless column, titled by `nativeOverlay`.
+		this.#nativeRoot = col(children, { gap: "md" });
+		return this.#nativeRoot;
+	}
+
+	/** Head tools: Copy `c` and the external editor, mirroring their keys. */
+	#describeTools(): NativeNode | undefined {
+		if (this.#committed) return undefined;
+		const buttons: NativeNode[] = [];
+		if (this.callbacks.onCopyPlan)
+			buttons.push(actionButton("Copy", "copyPlan", { keys: "c", title: "Copy plan  c" }));
+		// Unbound: the button still mirrors the callback, without a keycap.
+		const editorKeyId = getKeybindings().getKeys("app.editor.external")[0];
+		if (this.callbacks.onExternalEditor) {
+			buttons.push(actionButton("Edit in $EDITOR", "externalEditor", editorKeyId ? { keys: editorKeyId } : {}));
+		}
+		if (buttons.length === 0) return undefined;
+		return node("row", { role: "omp.plan.tools", gap: "sm", align: "center", justify: "end" }, buttons, "tools");
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (this.#committed) return;
+		if (event.type === "action") {
+			// Head tools run exactly what `c` and the external-editor key run.
+			if (this.#annotating || this.#annotationChooser) return;
+			if (event.act === "copyPlan" && this.callbacks.onCopyPlan) {
+				void this.callbacks.onCopyPlan(joinPlanSections(this.#sections));
+			} else if (event.act === "externalEditor") {
+				this.callbacks.onExternalEditor?.();
+			}
+			return;
+		}
+		if (event.type !== "select" && event.type !== "activate") return;
+		const activate = event.type === "activate";
+		switch (leafKey(event.key)) {
+			case "toc": {
+				const pos = this.#toc.indexOf(itemIndex(event.item, "h"));
+				if (pos < 0) return;
+				this.#focus = "toc";
+				this.#tocCursor = pos;
+				this.#scrubBodyToToc();
+				if (activate) this.#setFocus("body");
+				return;
+			}
+			case "options": {
+				const index = itemIndex(event.item, "o");
+				if (index < 0 || index >= this.#options.length || this.#disabled.has(index)) return;
+				this.#focus = "actions";
+				this.#selectedIndex = index;
+				if (activate) this.#confirmSelection();
+				return;
+			}
+			case "tabs": {
+				const index = itemIndex(event.item, "t");
+				if (index >= 0) this.#moveSlider(index - this.#sliderIndex);
+				return;
+			}
+			case "chooser": {
+				const chooser = this.#annotationChooser;
+				const index = itemIndex(event.item, "c");
+				if (!chooser || index < 0 || index >= chooser.entries.length) return;
+				chooser.selected = index;
+				if (activate) {
+					this.#annotationChooser = undefined;
+					this.#startExistingAnnotation(chooser.entries[index]!);
+				}
+				return;
+			}
+		}
+	}
+
+	/** Plan body (one `md` per section, annotation callouts after it) and Contents items. */
+	#describeContent(): NativePlanContent {
+		const cached = this.#nativeContent;
+		if (cached && cached.sections === this.#sections && cached.rev === this.#annotationRev) return cached;
+		const body: NativeNode[] = [];
+		for (const [sectionIndex, section] of this.#sections.entries()) {
+			const key = `s${sectionIndex}`;
+			// The title heading is the sheet's title; the body keeps only what follows it.
+			const newline = section.raw.indexOf("\n");
+			const source =
+				sectionIndex !== this.#titleIndex ? section.raw : newline < 0 ? "" : section.raw.slice(newline + 1);
+			const hasText = sectionIndex !== this.#titleIndex || source.trim() !== "";
+			if (section.annotations.length === 0) {
+				if (hasText) body.push(keyed(md(source), key));
+				continue;
+			}
+			const children: NativeNode[] = hasText ? [keyed(md(source), "md")] : [];
+			for (const [n, annotation] of section.annotations.entries()) {
+				// A margin note: the anchored line quoted, then the note, on one ink-pen bar.
+				const note: NativeNode[] = [];
+				if (annotation.target.kind === "line") {
+					note.push(text([span(annotation.target.context, "muted")], { truncate: "end", lines: 1 }));
+				}
+				note.push(text(sanitizeText(annotation.note), { wrap: "word" }));
+				children.push(node("col", { role: "omp.plan.note", gap: "xs" }, note, `n${n}`));
+			}
+			body.push(keyed(col(children, { gap: "sm" }), key));
+		}
+		const toc = this.#toc.map(sectionIndex => {
+			const section = this.#sections[sectionIndex]!;
+			const count = section.annotations.length;
+			return item(`h${sectionIndex}`, {
+				label: section.title || "(untitled)",
+				value: count > 0 ? [span(`✎${count}`, "warning")] : undefined,
+				role: `omp.plan.toc.depth${section.level - this.#tocBaseLevel}`,
+			});
+		});
+		this.#nativeContent = { sections: this.#sections, rev: this.#annotationRev, body, toc };
+		return this.#nativeContent;
+	}
+
+	#describeSlider(): NativeNode[] {
+		const slider = this.#slider;
+		if (!slider) return [];
+		const tabs = node(
+			"tabs",
+			{
+				items: slider.segments.map((segment, i) => ({ id: `t${i}`, label: segment.label })),
+				active: `t${this.#sliderIndex}`,
+				actions: { click: "select" },
+				role: "omp.plan.strategy",
+			},
+			undefined,
+			"tabs",
+		);
+		const track: NativeChild[] = slider.caption ? [text([span(slider.caption, "dim")]), tabs] : [tabs];
+		const out = [keyed(rowNode(track, { gap: "sm", align: "center" }), "slider")];
+		const detail = slider.segments[this.#sliderIndex]?.detail;
+		if (detail) out.push(keyed(text([span("↳ ", "dim"), span(detail, "muted")], { wrap: "word" }), "sliderDetail"));
+		return out;
+	}
+
+	#describeFooter(): NativeChild[] {
+		const chooser = this.#annotationChooser;
+		if (chooser) {
+			const entries = chooser.entries.map((selection, i) => {
+				const section = this.#sections[selection.sectionIndex];
+				const annotation = section?.annotations[selection.annotationIndex];
+				const where = annotation?.target.kind === "line" ? `line ${annotation.target.context}` : "section";
+				return item(`c${i}`, {
+					label: sanitizeStatusText(annotation?.note ?? ""),
+					detail: `${sanitizeStatusText(section?.title || "Plan preamble")} · ${where}`,
+				});
+			});
+			return [
+				keyed(text([span("Edit annotation", "accent strong")]), "chooserHead"),
+				selectList("chooser", entries, { selected: `c${chooser.selected}` }),
+				hintsRow(
+					[
+						actionHint(["tui.select.up", "tui.select.down"], "choose"),
+						{ keys: ["enter"], label: "edit" },
+						actionHint("tui.select.cancel", "cancel"),
+					],
+					"chooserHints",
+				),
+			];
+		}
+		if (this.#annotating) {
+			const target = this.#annotationTarget;
+			const title = sanitizeStatusText(this.#sections[target?.sectionIndex ?? -1]?.title || "Plan preamble");
+			const location = target?.row === null ? `‹${title}›` : `‹${title}› · ${target?.context ?? ""}`;
+			const hints: (NativeHint | undefined)[] = [
+				actionHint("tui.input.submit", "save"),
+				actionHint("tui.input.newLine", "newline"),
+				actionHint("tui.select.cancel", "cancel"),
+			];
+			if (this.#editingAnnotation) hints.push({ keys: [], label: "empty deletes" });
+			if (this.#externalEditorLabel) hints.push({ keys: [], label: `${this.#externalEditorLabel} editor` });
+			// The feedback field, inline under the plan: its caption names the anchor, omp's editor holds the text.
+			return [
+				node(
+					"col",
+					{ role: "omp.plan.feedback", gap: "xs" },
+					[
+						keyed(
+							text([span("Note on ", "muted"), span(location, "accent")], { truncate: "end" }),
+							"annotateHead",
+						),
+						this.#editor,
+						hintsRow(hints, "annotateHints"),
+					],
+					"feedback",
+				),
+			];
+		}
+		return [hintsRow(this.#nativeHelpHints())];
+	}
+
+	/** {@link #buildHelp} as keycap hints. */
+	#nativeHelpHints(): (NativeHint | undefined)[] {
+		const upDown = (label: string) => actionHint(["tui.select.up", "tui.select.down"], label);
+		const key = (keys: KeyName | readonly KeyName[], label: string): NativeHint => ({
+			keys: typeof keys === "string" ? [keys] : keys,
+			label,
+		});
+		const hints: (NativeHint | undefined)[] = [];
+		switch (this.#focus) {
+			case "actions":
+				hints.push(upDown("select"), key("enter", "confirm"));
+				if (this.#slider) hints.push(key(["left", "right"], "model"));
+				break;
+			case "toc":
+				hints.push(
+					upDown("section"),
+					key("enter", "open"),
+					key("a", "annotate"),
+					key("e", "edit"),
+					key("d", "delete"),
+					key("u", "undo"),
+				);
+				break;
+			case "body":
+				hints.push(
+					upDown("scroll"),
+					key("shift", "faster"),
+					key(["pageUp", "pageDown"], "page"),
+					key(["g", "shift+g"], "ends"),
+					key("a", "annotate"),
+					key("e", "edit"),
+					key("u", "undo"),
+				);
+				break;
+		}
+		// Copy and the external editor are head buttons with their keycaps; the hints skip them.
+		hints.push(key("tab", "regions"));
+		hints.push(this.#helpSuffix ? { keys: [], label: this.#helpSuffix } : actionHint("tui.select.cancel", "cancel"));
+		return hints;
+	}
+
 	render(width: number): readonly string[] {
 		const termHeight = process.stdout.rows || 40;
 		const sidebarShown = this.#sidebarVisible(width);

package/src/overlays/plan-save-overlay.ts

@@ -2,6 +2,10 @@ import { type Component, CURSOR_MARKER, type Focusable, Input, truncateToWidth,
 import { theme } from "../theme/theme";
 import { OverlayPanel, PanelRows } from "../chrome/overlay-box";
 import { editorKey } from "../chrome/keybinding-hints";
+import { col, keyed, span, text } from "../native/describe";
+import type { NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { actionBar, actionButton } from "../native/overlay";
+import { getKeybindings } from "../keybindings";
 
 /** A confirmed destination chosen from {@link PlanSaveOverlay}. */
 export interface PlanSaveOverlayResult {
@@ -16,6 +20,8 @@ export class PlanSaveOverlay implements Component, Focusable {
 	#focused = false;
 	readonly #panel: OverlayPanel;
 	readonly #body: PanelRows;
+	#nativeSig = "";
+	#nativeRoot: NativeNode | undefined;
 
 	constructor(suggestedPath: string, done: (result: PlanSaveOverlayResult | undefined) => void) {
 		this.#suggestedPath = suggestedPath;
@@ -64,6 +70,45 @@ export class PlanSaveOverlay implements Component, Focusable {
 		return this.#panel.render(width);
 	}
 
+	/** A small glass sheet titled "Save and quit". */
+	readonly nativeOverlay = { role: "omp.overlay.planSave", size: "sm", head: "Save and quit" } as const;
+
+	describe(): NativeNode {
+		this.#input.focused = this.#focused;
+		const showDefault = this.#input.getValue().length === 0;
+		const bindings = getKeybindings();
+		const submitKey = bindings.getKeys("tui.input.submit")[0];
+		const cancelKey = bindings.getKeys("tui.select.cancel")[0];
+		const sig = `${showDefault}|${this.#suggestedPath}|${submitKey}|${cancelKey}`;
+		if (this.#nativeRoot && sig === this.#nativeSig) return this.#nativeRoot;
+		const children: NativeChild[] = [this.#input];
+		if (showDefault) {
+			children.push(
+				keyed(
+					text([span("Empty saves to ", "dim"), span(this.#suggestedPath, "path")], { truncate: "middle" }),
+					"default",
+				),
+			);
+		}
+		children.push(
+			actionBar([
+				null,
+				actionButton("Cancel", "cancel", cancelKey ? { keys: cancelKey } : {}),
+				actionButton("Save and quit", "save", { tone: "accent", ...(submitKey ? { keys: submitKey } : {}) }),
+			]),
+		);
+		this.#nativeSig = sig;
+		this.#nativeRoot = col(children, { gap: "md" });
+		return this.#nativeRoot;
+	}
+
+	/** Save and Cancel run what the submit and cancel keys run. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type !== "action") return;
+		if (event.act === "save") this.#input.onSubmit?.(this.#input.getValue());
+		else if (event.act === "cancel") this.#input.onEscape?.();
+	}
+
 	#renderInput(width: number): string {
 		if (this.#input.getValue().length > 0) return this.#input.render(width)[0] ?? "";
 		const prompt = this.#input.prompt;