pi-bro 0.23.1 → 0.24.0

package/src/btw.ts

@@ -1,8 +1,7 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { copyToClipboard, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Input, Markdown, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Focusable } from "@earendil-works/pi-tui";
+import { Input, Markdown, matchesKey, wrapTextWithAnsi, type Focusable } from "@earendil-works/pi-tui";
 import { execute as executeBackend, type BackendProgress, type BackendSelection } from "./backend.ts";
-import type { Theme, TuiLike } from "./config-ui.ts";
 import { buildBtwPrompt } from "./prompt.ts";
 import {
 	type BackendName,
@@ -14,15 +13,8 @@ import {
 	selectionLabel,
 } from "./settings.ts";
 import { captureShowTranscript } from "./show.ts";
-import {
-	broModalRows,
-	canBroInsertIntoEditor,
-	insertBroDesktopText,
-	setRegularMouseReporting,
-	wheelDelta,
-	type BroMouseEvent,
-	type BroMouseResult,
-} from "./ui-capabilities.ts";
+import { BRO_OVERLAY, broOverlayArea, formatNotice, modalHeight, openBroOverlay, renderFrame, Scroller, type Area, type NoticeTone, type Theme, type TuiLike } from "./modal-kit.ts";
+import { canBroInsertIntoEditor, insertBroDesktopText, type BroMouseEvent, type BroMouseResult } from "./ui-capabilities.ts";
 import { errorMessage } from "./util.ts";
 
 export const BTW_CONTEXT_TURNS = 8;
@@ -42,6 +34,7 @@ export type BtwThread = {
 	context?: string;
 	sessionFull?: boolean;
 	sessionPreferences?: string;
+	draft?: string;
 };
 
 export function parseBtwArguments(value: string): { question: string; invalid?: string } {
@@ -182,16 +175,22 @@ export class BtwModal implements Focusable {
 	private _focused = false;
 	private readonly markdown = new Markdown("", 0, 0, getMarkdownTheme());
 	private readonly input = new Input();
-	private notice = "";
-	private offset = 0;
-	// Pinned to the newest text until the reader scrolls up; scrolling back to the end re-pins.
-	private follow = false;
-	private maxOffset = 0;
-	private bodyHeight = 1;
+	private noticeText = "";
+	private noticeTone: NoticeTone = "info";
+	private rawArea: Area | undefined;
+	// Follows the newest text until the reader scrolls up; scrolling back to the end follows again.
+	private readonly scroller = new Scroller(
+		() => {
+			this.noticeText = "";
+			this.tui.requestRender();
+		},
+		{ followEnd: true },
+	);
 	private running = false;
 	private full = false;
 	private model = "";
 	private disposed = false;
+	onInput?: () => void;
 
 	get focused(): boolean {
 		return this._focused;
@@ -209,13 +208,12 @@ export class BtwModal implements Focusable {
 		private readonly onSubmit: (value: string) => void,
 		private readonly onDispose: () => void,
 	) {
-		setRegularMouseReporting(this.tui, true);
 		this.input.onSubmit = (value) => {
 			if (!this.running) this.onSubmit(value);
 		};
 	}
 
-	// Keeps the reader's place; render clamps the offset when the text shrinks (e.g. /clear).
+	// Keeps the reader's place; the scroller clamps when the text shrinks (e.g. /clear).
 	setText(text: string): void {
 		this.markdown.setText(text);
 		this.tui.requestRender();
@@ -223,13 +221,22 @@ export class BtwModal implements Focusable {
 
 	/** Show the newest text and keep following it while a reply streams. */
 	scrollToEnd(): void {
-		this.follow = true;
+		this.scroller.toEnd();
 		this.tui.requestRender();
 	}
 
-	setNotice(notice: string): void {
+	get notice(): string {
+		return this.noticeText;
+	}
+
+	set notice(notice: string) {
+		this.setNotice(notice);
+	}
+
+	setNotice(notice: string, tone: NoticeTone = "info"): void {
 		if (this.disposed) return;
-		this.notice = notice;
+		this.noticeText = notice;
+		this.noticeTone = tone;
 		this.tui.requestRender();
 	}
 
@@ -253,24 +260,23 @@ export class BtwModal implements Focusable {
 		this.tui.requestRender();
 	}
 
+	getComposerText(): string {
+		return this.input.getValue();
+	}
+
+	setComposerText(text: string): void {
+		this.input.setValue(text);
+		(this.input as unknown as { cursor: number }).cursor = text.length;
+		this.tui.requestRender();
+	}
+
 	invalidate(): void {
 		this.markdown.invalidate();
 		this.input.invalidate();
 	}
 
-	// Pi 1.2+ fullscreen delivers the wheel here and no longer forwards raw wheel input to handleInput.
 	handleMouse(event: BroMouseEvent): BroMouseResult {
-		if (event.type !== "wheel") return;
-		const delta = Math.trunc(event.wheelDelta ?? 0);
-		if (delta) this.scroll(delta);
-		return { handled: true, render: false };
-	}
-
-	private scroll(delta: number): void {
-		this.offset = Math.max(0, Math.min(this.offset + delta, this.maxOffset));
-		this.follow = this.offset >= this.maxOffset;
-		this.notice = "";
-		this.tui.requestRender();
+		return this.scroller.handleMouse(event);
 	}
 
 	handleInput(data: string): void {
@@ -278,74 +284,38 @@ export class BtwModal implements Focusable {
 			this.onClose();
 			return;
 		}
-		const delta = wheelDelta(data) || (matchesKey(data, "up") ? -1 : matchesKey(data, "down") ? 1 : 0);
-		if (delta) {
-			this.scroll(delta);
-			return;
-		}
+		if (this.scroller.handleKey(data, this.rawArea)) return;
 		this.input.handleInput(data);
+		this.onInput?.();
 		this.tui.requestRender();
 	}
 
-	private frameLine(content: string, innerWidth: number): string {
-		const truncated = truncateToWidth(content, innerWidth, "");
-		const padding = Math.max(0, innerWidth - visibleWidth(truncated));
-		return `${this.theme.fg("border", "│")}${truncated}${" ".repeat(padding)}${this.theme.fg("border", "│")}`;
-	}
-
-	private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
-		const left = edge === "top" ? "┌" : "└";
-		const right = edge === "top" ? "┐" : "┘";
-		return this.theme.fg("border", `${left}${"─".repeat(innerWidth)}${right}`);
-	}
-
-	private ruleLine(innerWidth: number): string {
-		return this.theme.fg("border", `├${"─".repeat(innerWidth)}┤`);
-	}
-
 	render(width: number): string[] {
-		const dialogWidth = Math.max(24, width);
-		const innerWidth = Math.max(22, dialogWidth - 2);
-		const terminalRows = broModalRows(this.tui, process.stdout.rows);
-		const dialogHeight = Math.min(34, Math.max(8, Math.floor(terminalRows * 0.82)));
-		const footer = [
-			...wrapTextWithAnsi(this.theme.fg("accent", this.theme.bold("Your message to Bro")), innerWidth),
-			this.input.render(innerWidth)[0] ?? "",
-			...wrapTextWithAnsi(this.running ? "Bro is thinking… · Esc: close (stops reply)" : "Enter: send message · Esc: close panel", innerWidth),
-			...wrapTextWithAnsi("Commands: /mode · /copy · /copy-all · /insert · /insert-all · /clear · /retry", innerWidth),
-			...(this.notice ? wrapTextWithAnsi(this.theme.fg("accent", this.notice), innerWidth) : []),
-		];
-		this.bodyHeight = Math.max(1, dialogHeight - 5 - footer.length);
-
-		const rendered = this.markdown.render(innerWidth);
-		this.maxOffset = Math.max(0, rendered.length - this.bodyHeight);
-		if (this.follow) this.offset = this.maxOffset;
-		this.offset = Math.max(0, Math.min(this.offset, this.maxOffset));
-		const visible = rendered.slice(this.offset, this.offset + this.bodyHeight);
-		const hiddenBelow = Math.max(0, this.maxOffset - this.offset);
-		const scroll = this.maxOffset > 0 ? ` · ↑${this.offset} ↓${hiddenBelow}` : "";
-
-		const model = this.model ? this.theme.fg("dim", ` · ${this.model}`) : "";
-		const mode = this.theme.fg("dim", " · ") + (this.full ? this.theme.fg("accent", this.theme.bold(btwModeLabel(true))) : this.theme.fg("dim", btwModeLabel(false)));
-		const header = this.theme.fg("accent", this.theme.bold("Bro · btw")) + model + mode + this.theme.fg("dim", scroll);
-
-		const lines = [
-			this.borderLine(innerWidth, "top"),
-			this.frameLine(header, innerWidth),
-			this.ruleLine(innerWidth),
-		];
-		for (const line of visible) lines.push(this.frameLine(line, innerWidth));
-		for (let i = visible.length; i < this.bodyHeight; i++) lines.push(this.frameLine("", innerWidth));
-		lines.push(this.ruleLine(innerWidth));
-		for (const line of footer) lines.push(this.frameLine(line, innerWidth));
-		lines.push(this.borderLine(innerWidth, "bottom"));
-		return lines;
+		const inner = Math.max(1, width - 2);
+		const height = modalHeight(this.tui, BRO_OVERLAY, 34);
+		this.rawArea = broOverlayArea(this.tui, width, height);
+		return renderFrame(this.theme, width, height, {
+			header: () => {
+				const scroll = this.scroller.indicator();
+				const model = this.model ? this.theme.fg("dim", ` · ${this.model}`) : "";
+				const mode = this.theme.fg("dim", " · ") + (this.full ? this.theme.fg("accent", this.theme.bold(btwModeLabel(true))) : this.theme.fg("dim", btwModeLabel(false)));
+				return this.theme.fg("accent", this.theme.bold("Bro · btw")) + model + mode + this.theme.fg("dim", scroll ? ` · ${scroll}` : "");
+			},
+			body: (rows, innerWidth) => this.scroller.view(this.markdown.render(innerWidth), rows),
+			// The frame drops lines from the top when space runs out, so the composer goes last.
+			footer: [
+				...wrapTextWithAnsi("Commands: /mode · /copy · /copy-all · /insert · /insert-all · /clear · /retry", inner),
+				this.theme.fg("accent", this.theme.bold("Your message to Bro")),
+				this.input.render(inner)[0] ?? "",
+			],
+			notice: this.noticeText ? formatNotice(this.theme, this.noticeText, this.noticeTone) : undefined,
+			hints: this.running ? "Bro is thinking… · Esc close (stops reply)" : "Enter send · Esc close",
+		});
 	}
 
 	dispose(): void {
 		if (this.disposed) return;
 		this.disposed = true;
-		setRegularMouseReporting(this.tui, false);
 		this.onDispose();
 	}
 }
@@ -356,24 +326,41 @@ export async function openBtwModal(
 ): Promise<void> {
 	const thread = options.thread;
 
-	await ctx.ui.custom<void>(
+	await openBroOverlay<void>(
+		ctx,
 		(tui, theme, _keybindings, done) => {
 			let closed = false;
 			let controller: AbortController | undefined;
 
 			const transcript = () => formatBtwTranscript(thread.turns);
 
+			let composerTouched = false;
+			const saveDraft = () => {
+				const draft = modal.getComposerText();
+				if (draft.trim()) {
+					thread.draft = draft;
+				} else if (!options.initialQuestion || composerTouched) {
+					delete thread.draft;
+				}
+			};
+
 			const close = () => {
 				if (closed) return;
 				closed = true;
+				saveDraft();
 				controller?.abort();
 				done(undefined);
 			};
 
 			const modal = new BtwModal(tui, theme, close, submit, () => {
 				closed = true;
+				saveDraft();
 				controller?.abort();
 			});
+			modal.onInput = () => {
+				composerTouched = true;
+			};
+			if (thread.draft && !options.initialQuestion) modal.setComposerText(thread.draft);
 
 			// `replaced` is the turn /retry removed; it is put back if the turn never starts.
 			const runTurn = async (question: string, replaced?: BtwTurn) => {
@@ -381,7 +368,6 @@ export async function openBtwModal(
 				const turnController = new AbortController();
 				controller = turnController;
 				modal.setRunning(true);
-				modal.clearComposer();
 
 				let settings: BroSettings;
 				let preferences: string;
@@ -390,17 +376,19 @@ export async function openBtwModal(
 					preferences = await readPreferences();
 				} catch (error) {
 					if (replaced) thread.turns.push(replaced);
+					if (!replaced && !options.initialQuestion) modal.setComposerText(question);
 					if (controller === turnController) controller = undefined;
-					if (!closed) { modal.setRunning(false); modal.setNotice(errorMessage(error)); }
+					if (!closed) { modal.setRunning(false); modal.setNotice(errorMessage(error), "error"); }
 					return;
 				}
 				// Closing (or reopening) during the reads above must not touch the shared thread.
 				if (closed || turnController.signal.aborted) {
 					if (replaced) thread.turns.push(replaced);
+					if (!replaced && !options.initialQuestion) modal.setComposerText(question);
 					if (controller === turnController) controller = undefined;
 					return;
 				}
-				if (bindBtwBackend(thread, capabilityBackend(settings, "btw"))) modal.setNotice("Backend changed — started a fresh side thread.");
+				if (bindBtwBackend(thread, capabilityBackend(settings, "btw"))) modal.setNotice("Backend changed — started a fresh side thread.", "warning");
 				if (thread.turns.length === 0) {
 					thread.conversationId = undefined;
 					const context = captureShowTranscript(ctx, BTW_CONTEXT_TURNS, BTW_CONTEXT_MAX)?.text;
@@ -443,7 +431,7 @@ export async function openBtwModal(
 				} catch (error) {
 					if (turnController.signal.aborted || closed) return;
 					thread.turns[thread.turns.length - 1]!.answer = `_${errorMessage(error)}_`;
-					modal.setNotice(errorMessage(error));
+					modal.setNotice(errorMessage(error), "error");
 				} finally {
 					if (controller === turnController) controller = undefined;
 					if (!closed) {
@@ -456,7 +444,7 @@ export async function openBtwModal(
 			const toggleMode = () => {
 				toggleBtwMode(thread);
 				modal.setFull(thread.full);
-				modal.setNotice(`Mode: ${btwModeLabel(thread.full)}`);
+				modal.setNotice(`Mode: ${btwModeLabel(thread.full)}`, "info");
 			};
 
 			const clear = () => {
@@ -465,6 +453,7 @@ export async function openBtwModal(
 				thread.context = undefined;
 				thread.sessionFull = undefined;
 				thread.sessionPreferences = undefined;
+				delete thread.draft;
 				modal.clearComposer();
 				modal.setNotice("");
 				modal.setText("");
@@ -474,7 +463,7 @@ export async function openBtwModal(
 				if (controller) return;
 				const last = thread.turns.at(-1);
 				if (!last) {
-					modal.setNotice("Nothing to retry yet.");
+					modal.setNotice("Nothing to retry yet.", "warning");
 					return;
 				}
 				thread.turns.pop();
@@ -484,34 +473,34 @@ export async function openBtwModal(
 			const copyOut = async (all: boolean) => {
 				const text = all ? transcript() : (thread.turns.at(-1)?.answer ?? "");
 				if (!text.trim()) {
-					modal.setNotice("Nothing to copy yet.");
+					modal.setNotice("Nothing to copy yet.", "warning");
 					return;
 				}
 				try {
 					await copyToClipboard(text);
-					modal.setNotice(all ? "Copied the full thread to the clipboard." : "Copied the latest answer to the clipboard.");
+					modal.setNotice(all ? "Copied the full thread to the clipboard." : "Copied the latest answer to the clipboard.", "success");
 				} catch (error) {
-					modal.setNotice(`Copy failed: ${errorMessage(error)}`);
+					modal.setNotice(`Copy failed: ${errorMessage(error)}`, "error");
 				}
 			};
 
 			const insert = async (all: boolean) => {
 				const text = all ? transcript() : (thread.turns.at(-1)?.answer ?? "");
 				if (!text.trim()) {
-					modal.setNotice("Nothing to insert yet.");
+					modal.setNotice("Nothing to insert yet.", "warning");
 					return;
 				}
 				if (!canBroInsertIntoEditor(ctx)) {
 					const result = await insertBroDesktopText(ctx, text);
-					modal.setNotice(result === "inserted" ? "Inserted into the main editor. Review it before sending." : result === "not_empty" ? "Main editor has a draft or attachment. Clear it first, then insert again." : "Could not confirm insertion. Check the main editor before trying again.");
+					modal.setNotice(result === "inserted" ? "Inserted into the main editor. Review it before sending." : result === "not_empty" ? "Main editor has a draft or attachment. Clear it first, then insert again." : "Could not confirm insertion. Check the main editor before trying again.", result === "inserted" ? "success" : result === "not_empty" ? "warning" : "error");
 					return;
 				}
 				if (ctx.ui.getEditorText().trim()) {
-					modal.setNotice("Main editor has a draft. Edit or clear it first, then insert again.");
+					modal.setNotice("Main editor has a draft. Edit or clear it first, then insert again.", "warning");
 					return;
 				}
 				ctx.ui.setEditorText(text);
-				modal.setNotice(all ? "Inserted the full thread into the main editor." : "Inserted the latest answer into the main editor.");
+				modal.setNotice(all ? "Inserted the full thread into the main editor." : "Inserted the latest answer into the main editor.", "success");
 			};
 
 			function submit(value: string): void {
@@ -542,10 +531,14 @@ export async function openBtwModal(
 					return;
 				}
 				if (action.kind === "retry") {
+					composerTouched = true;
 					modal.clearComposer();
 					retry();
 					return;
 				}
+				composerTouched = true;
+				delete thread.draft;
+				modal.clearComposer();
 				void runTurn(action.text);
 			}
 
@@ -558,15 +551,6 @@ export async function openBtwModal(
 
 			return modal;
 		},
-		{
-			overlay: true,
-			overlayOptions: {
-				width: "78%",
-				minWidth: 48,
-				maxHeight: "82%",
-				anchor: "top-center",
-				margin: { top: 1, left: 2, right: 2 },
-			},
-		},
+		{ mouse: true },
 	);
 }

package/src/config-ui.ts

@@ -2,21 +2,13 @@ import {
 	type Component,
 	type SelectItem,
 	type SettingItem,
-	Container,
 	Input,
 	SelectList,
 	SettingsList,
-	Text,
-	TruncatedText,
 	matchesKey,
 	truncateToWidth,
-	visibleWidth,
 } from "@earendil-works/pi-tui";
-import {
-	type ExtensionCommandContext,
-	getSelectListTheme,
-	getSettingsListTheme,
-} from "@earendil-works/pi-coding-agent";
+import { getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import {
 	type AgyModelFamily,
 	type BroSettings,
@@ -35,16 +27,10 @@ import {
 	withCapabilityOverride,
 } from "./settings.ts";
 import { BRO_MODES, parseBroMode } from "./prompt.ts";
-import { broModalRows, consumeWheel } from "./ui-capabilities.ts";
+import { delegateMouse, formatNotice, modalHeight, renderFrame, type Area, type Theme, type TuiLike } from "./modal-kit.ts";
+import type { BroMouseEvent } from "./ui-capabilities.ts";
 import { errorMessage } from "./util.ts";
 
-export type Theme = ExtensionCommandContext["ui"]["theme"];
-export type TuiLike = {
-	readonly mode: "regular" | "fullscreen";
-	readonly terminal?: { rows?: number; columns?: number; write?: (data: string) => void };
-	requestRender(): void;
-};
-
 const SHOW_TURNS_PRESETS = [1, 2, 3, 5, 8];
 
 function showTurnsValues(current: number): string[] {
@@ -60,10 +46,9 @@ export function createConfigModal(
 	persistSettings: (settings: BroSettings) => Promise<void>,
 ): (tui: TuiLike, theme: Theme, keybindings: unknown, done: (value?: void) => void) => Component & { dispose?(): void } {
 	return (tui, theme, _keybindings, done) => {
-		// The overlay (maxHeight 78%) clips from the bottom: leave room for the borders, title,
-		// subtitle, a two-line notice and SettingsList's own scroll, blank and hint rows.
-		// shortcut: sized once at open, not on resize; fine while config stays short-lived.
-		const listRows = Math.max(3, Math.floor(broModalRows(tui, process.stdout.rows) * 0.78) - 9);
+		// Size the host list once, then stop interaction if a later resize cannot show the whole
+		// component. SettingsList has no public resize API; clipping it would hide selection/actions.
+		const listRows = Math.max(1, modalHeight(tui) - 11);
 		let settings = initialSettings;
 		// The last settings actually confirmed on disk. A failed save reverts `settings` (and the
 		// whole displayed row set) back to this, so the screen never shows state that doesn't exist.
@@ -79,6 +64,12 @@ export function createConfigModal(
 		// that only actually happens once the in-flight (and any coalesced) save has settled, and
 		// only if it succeeded — a failure cancels the pending close so its notice stays visible.
 		let closeRequested = false;
+		let closed = false;
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			done(undefined);
+		};
 
 		const modelPicker = (current: string, pickerDone: (value?: string) => void, capability?: Capability) => {
 			const defaultResolved = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
@@ -120,9 +111,16 @@ export function createConfigModal(
 			return {
 				// SettingsList draws an open submenu instead of its own list and hints, so the picker brings its own.
 				render: (width: number) => enteringBackend
-					? [`${customLabel()} model ID (Enter saves, Esc cancels)`, ...input.render(width)]
+					? [
+						`${customLabel()} model ID:`,
+						...input.render(width),
+						"",
+						truncateToWidth(theme.fg("dim", "  Enter save · Esc back"), width),
+					]
 					: [...picker.render(width), "", truncateToWidth(theme.fg("dim", "  ↑/↓ choose · Enter select · Esc back"), width)],
 				invalidate: () => { picker.invalidate(); input.invalidate(); },
+				// SettingsList hands an open submenu its own events unchanged.
+				handleMouse: (event: BroMouseEvent) => (enteringBackend ? delegateMouse(input, event, { top: 1, left: 0, width: tui.terminal?.columns ?? 80, height: 1 }) : delegateMouse(picker, event)),
 				handleInput: (data: string) => {
 					if (enteringBackend && matchesKey(data, "escape")) pickerDone();
 					else if (enteringBackend) input.handleInput(data);
@@ -206,14 +204,17 @@ export function createConfigModal(
 			...CAPABILITIES.flatMap((capability) => [capabilityItems[capability].model, capabilityItems[capability].effort]),
 		];
 
-		const noticeText = new Text("", 1, 0);
+		let notice = "";
+		let interactive = true;
+		// Where the complete list was last drawn inside the overlay, for click forwarding.
+		let listArea: Area = { top: 0, left: 0, width: 0, height: 0 };
 
 		function runSave(toSave: BroSettings): void {
 			saving = true;
 			void persistSettings(toSave)
 				.then(() => {
 					savedSettings = toSave;
-					noticeText.setText("");
+					notice = "";
 				})
 				.catch((error: unknown) => {
 					// Restore the last state that is actually on disk: showing the failed, unsaved
@@ -222,7 +223,8 @@ export function createConfigModal(
 					queued = undefined;
 					closeRequested = false;
 					refresh();
-					noticeText.setText(theme.fg("warning", `Could not save settings: ${errorMessage(error)}. Reverted to the last saved settings.`));
+					// Outcome first: long notices are cut after three lines.
+					notice = formatNotice(theme, `Reverted to the last saved settings. Could not save settings: ${errorMessage(error)}`, "error");
 				})
 				.finally(() => {
 					saving = false;
@@ -233,7 +235,7 @@ export function createConfigModal(
 						runSave(next);
 					} else if (closeRequested) {
 						closeRequested = false;
-						done(undefined);
+						close();
 					}
 				});
 		}
@@ -304,31 +306,56 @@ export function createConfigModal(
 				closeRequested = true;
 				return;
 			}
-			done(undefined);
+			close();
 		};
 
 		const settingsList = new SettingsList(items, Math.min(items.length, listRows), getSettingsListTheme(), onChange, requestClose);
-		const container = new Container();
-		container.addChild(new Text(theme.fg("accent", theme.bold("Bro · config")), 1, 0));
-		container.addChild(new TruncatedText(theme.fg("dim", "Shared defaults, with optional overrides per capability"), 1, 0));
-		// SettingsList prints its own key hints, so Bro adds none.
-		container.addChild(settingsList);
-		container.addChild(noticeText);
-
 		return {
-			render: (w: number) => {
-				const inner = Math.max(1, w - 4);
-				const border = (left: string, right: string) => theme.fg("border", left + "─".repeat(inner + 2) + right);
-				return [border("┌", "┐"), ...container.render(inner).map(line => {
-					const text = truncateToWidth(line, inner, "");
-					return theme.fg("border", "│") + " " + text + " ".repeat(Math.max(0, inner - visibleWidth(text))) + " " + theme.fg("border", "│");
-				}), border("└", "┘")];
+			render: (width: number) => {
+				listArea = { top: 0, left: 0, width: 0, height: 0 };
+				const height = modalHeight(tui);
+				const innerWidth = Math.max(1, width - 2);
+				const list = settingsList.render(innerWidth);
+				// renderFrame shrinks a notice to one line before taking minBody rows.
+				interactive = list.length <= Math.max(0, height - 5 - (notice ? 1 : 0));
+				return renderFrame(theme, width, height, {
+					header: () => theme.fg(
+						interactive ? "accent" : "warning",
+						theme.bold(interactive ? "Bro · config" : "Bro · config · enlarge terminal"),
+					),
+					body: (rows) => {
+						if (!interactive) return [theme.fg("warning", "Enlarge the terminal to configure settings safely.")];
+						// The subtitle gives way before SettingsList's selection, scroll state and key hints.
+						const subtitle = rows > list.length
+							? [truncateToWidth(theme.fg("dim", "Shared defaults, with optional overrides per capability"), innerWidth)]
+							: [];
+						// Clicks only reach list rows that were actually drawn.
+						listArea = { top: 3 + subtitle.length, left: 1, width: innerWidth, height: Math.min(list.length, rows - subtitle.length) };
+						return [...subtitle, ...list];
+					},
+					notice,
+					hints: interactive ? undefined : "Esc close",
+					fill: false,
+					minBody: interactive ? list.length : 1,
+				});
 			},
-			invalidate: () => container.invalidate(),
-			handleMouse: consumeWheel,
+			invalidate: () => settingsList.invalidate(),
+			handleMouse: (event: BroMouseEvent) => delegateMouse(settingsList, event, listArea),
 			handleInput: (data: string) => {
+				if (!interactive) {
+					// No picker is visible here: Esc closes config, still waiting for pending saves.
+					if (matchesKey(data, "escape")) {
+						requestClose();
+						return;
+					}
+					if (notice) {
+						notice = "";
+						tui.requestRender();
+					}
+					return;
+				}
 				settingsList.handleInput?.(data);
-				tui.requestRender();
+				if (!closed) tui.requestRender();
 			},
 		};
 	};