pi-bro 0.23.0 → 0.24.0

package/src/review-ui.ts

@@ -1,7 +1,5 @@
 import {
 	matchesKey,
-	truncateToWidth,
-	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import {
@@ -10,8 +8,8 @@ import {
 	type ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
-import { execute, reviewBackendError } from "./backend.ts";
-import { readSettings, selectionForCapability } from "./settings.ts";
+import { execute, reviewBackendNotice } from "./backend.ts";
+import { capabilityBackend, readSettings, selectionForCapability } from "./settings.ts";
 import {
 	replaceGuide,
 	guideEvidence,
@@ -24,18 +22,22 @@ import {
 	type ReviewRecord,
 } from "./review.ts";
 import { captureReview, readEvidence, resolveReviewTarget } from "./review-source.ts";
-import { ReviewModal, newReviewView, safeReviewText } from "./review-modal.ts";
+import { REVIEW_OVERLAY, ReviewModal, newReviewView, safeReviewText } from "./review-modal.ts";
+import { formatNotice, modalHeight, openBroOverlay, renderFrame } from "./modal-kit.ts";
+import { consumeWheel } from "./ui-capabilities.ts";
+
+export const REVIEW_ACQUIRE_OVERLAY = {
+	anchor: "center",
+	width: "70%",
+	minWidth: 44,
+	maxHeight: "60%",
+	margin: { top: 1, bottom: 1 },
+} as const;
 
 const activeReviews = new Map<string, AbortController | undefined>();
 export function stopGuidedReviews(): void {
 	for (const controller of activeReviews.values()) controller?.abort();
 }
-const overlayOptions = {
-	anchor: "center" as const,
-	width: "100%" as const,
-	maxHeight: "100%" as const,
-	margin: { top: 1, bottom: 1 },
-};
 
 export async function openGuidedReview(
 	ctx: ExtensionCommandContext,
@@ -73,10 +75,12 @@ export async function openGuidedReview(
 		if (!picked) return;
 		record = records[labels.indexOf(picked)];
 	} else {
-		record = await ctx.ui.custom<ReviewRecord | undefined>(
+		record = await openBroOverlay<ReviewRecord | undefined>(
+			ctx,
 			(tui, theme, _keys, done) => {
 				let controller = new AbortController();
 				let message = "Resolving PR identity…";
+				let advisory: string | undefined;
 				let failed = false;
 				let retryable = true;
 				let startedAt = Date.now();
@@ -94,11 +98,15 @@ export async function openGuidedReview(
 				const acquire = async () => {
 					failed = false;
 					retryable = true;
+					advisory = undefined;
 					startedAt = Date.now();
 					controller = new AbortController();
 					message = "Resolving PR identity…";
 					tui.requestRender();
 					try {
+						// Resolved before PR identity: the advisory is about the backend that will run the
+						// review, so it belongs on a resolution failure too, not only a capture failure.
+						advisory = reviewBackendNotice(capabilityBackend(await readSettings(), "review"));
 						const target = await resolveReviewTarget(value, ctx.cwd, controller.signal);
 						if (disposed) return;
 						const id = reviewKey(target);
@@ -124,12 +132,6 @@ export async function openGuidedReview(
 							if (!disposed) done(existing);
 							return;
 						}
-						const selection = selectionForCapability(await readSettings(), "review");
-						const backendError = reviewBackendError(selection.backend ?? "agy");
-						if (backendError) {
-							retryable = false;
-							throw Error(backendError);
-						}
 						message = `${target.repository} #${target.number} · ${target.head.slice(0, 8)}\nFetching captured source…`;
 						tui.requestRender();
 						const snapshot = await captureReview(target, root, controller.signal);
@@ -152,31 +154,25 @@ export async function openGuidedReview(
 				void acquire();
 				return {
 					render(width: number) {
-						const inner = Math.max(1, width - 2);
-						const height = Math.max(1, tui.terminal.rows - 2);
-						const border = "─".repeat(inner);
-						const row = (text: string) => {
-							const line = truncateToWidth(text, inner, "…");
-							return `│${line}${" ".repeat(Math.max(0, inner - visibleWidth(line)))}│`;
-						};
-						const body = wrapTextWithAnsi(safeReviewText(message), inner).slice(
-							0,
-							Math.max(1, height - 4),
-						);
-						const lines = [
-							`╭${border}╮`,
-							row(
-								`Bro · Review${failed ? "" : ` · ${Math.floor((Date.now() - startedAt) / 1000)}s`}`,
-							),
-							...body.map(row),
-							row(failed ? (retryable ? "Esc close · Enter retry" : "Esc close") : "Esc cancel"),
-							`╰${border}╯`,
-						];
-						return lines
-							.slice(0, height)
-							.map((line) => theme.fg("accent", truncateToWidth(line, width, "")));
+						const height = modalHeight(tui, REVIEW_ACQUIRE_OVERLAY);
+						const hints = failed ? (retryable ? "Enter retry · Esc close" : "Esc close") : "Esc cancel";
+						return renderFrame(theme, width, height, {
+							header: () =>
+								theme.fg("accent", theme.bold("Bro · Review")) +
+								(failed ? "" : theme.fg("dim", ` · ${Math.floor((Date.now() - startedAt) / 1000)}s`)),
+							body: (_rows, innerWidth) =>
+								wrapTextWithAnsi(safeReviewText(message), innerWidth).map((line) =>
+									failed ? theme.fg("error", line) : theme.fg("dim", line),
+								),
+							// An advisory is information, not a failure: keep it visible even when the fetch fails.
+							notice: advisory ? formatNotice(theme, advisory, "warning") : undefined,
+							hints,
+							fill: false,
+							minBody: 1,
+						});
 					},
 					invalidate() {},
+					handleMouse: consumeWheel,
 					handleInput(data: string) {
 						if (matchesKey(data, "escape")) {
 							disposed = true;
@@ -193,7 +189,7 @@ export async function openGuidedReview(
 					},
 				};
 			},
-			{ overlay: true, overlayOptions },
+			{ overlay: REVIEW_ACQUIRE_OVERLAY },
 		);
 	}
 	if (!record) return;
@@ -205,7 +201,8 @@ export async function openGuidedReview(
 	activeReviews.set(state.id, undefined);
 	let overlayHandle: { setHidden(hidden: boolean): void } | undefined;
 	try {
-		await ctx.ui.custom<void>(
+		await openBroOverlay<void>(
+			ctx,
 			(tui, theme, _keys, done) => {
 				let controller: AbortController | undefined;
 				let running: Promise<void> | undefined;
@@ -307,7 +304,9 @@ export async function openGuidedReview(
 						await persist();
 						const settings = await readSettings();
 						const selection = selectionForCapability(settings, "review");
-						panel.notice = `${question ? "Answering" : regenerate ? "Regenerating guide" : "Preparing guide"} · ${selection.backend ?? "agy"}`;
+						const backend = capabilityBackend(settings, "review");
+						panel.advisory = reviewBackendNotice(backend) ?? "";
+						panel.notice = `${question ? "Answering" : regenerate ? "Regenerating guide" : "Preparing guide"} · ${backend}`;
 						panel.stage = {
 							step: "investigate",
 							detail: question ? "Considering your question" : "Inspecting captured changes",
@@ -472,6 +471,14 @@ export async function openGuidedReview(
 					changed,
 				});
 				void hydrateEvidence();
+				// Also on reopen: the advisory is about the selected backend, not about a new turn.
+				void readSettings().then(
+					(settings) => {
+						panel.advisory = reviewBackendNotice(capabilityBackend(settings, "review")) ?? "";
+						if (!closed) tui.requestRender();
+					},
+					() => {},
+				);
 				if (fresh)
 					queueMicrotask(() => {
 						if (!closed && !closing) running = run("whole review");
@@ -495,18 +502,21 @@ export async function openGuidedReview(
 						panel.focused = value;
 					},
 					dispose() {
+						// close() sets `closed` only after its save succeeded; other teardown still saves here.
+						const savedByClose = closed;
 						closed = true;
 						panel.dispose();
 						evidenceAbort.abort();
 						controller?.abort();
 						if (saveTimer) clearTimeout(saveTimer);
-						void persist().catch(() => {});
+						if (!savedByClose) void persist().catch(() => {});
 					},
 				};
 			},
 			{
-				overlay: true,
-				overlayOptions,
+				overlay: REVIEW_OVERLAY,
+				// Regular-mode wheel scrolling; released while hidden behind the regenerate confirm.
+				mouse: true,
 				onHandle: (handle) => {
 					overlayHandle = handle;
 				},

package/src/settings.ts

@@ -1,6 +1,6 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import {
 	type BackendSelection,
@@ -10,8 +10,8 @@ import {
 	CODEX_EFFORTS,
 	MUSE_EFFORTS,
 } from "./backend.ts";
-import { type BroMode, DEFAULT_BRO_MODE, parseBroMode } from "./prompt.ts";
-import { isRecord } from "./util.ts";
+import { type BroMode, DEFAULT_BRO_MODE, MAX_PREFERENCES_CHARS, parseBroMode } from "./prompt.ts";
+import { errorMessage, isRecord } from "./util.ts";
 
 export const EFFORTS = ["default", "low", "medium", "high"] as const;
 export const BACKENDS = ["agy", "claude", "grok", "codex", "muse"] as const;
@@ -503,3 +503,45 @@ export async function writeSettings(settings: BroSettings): Promise<void> {
 		throw error;
 	}
 }
+
+export const PREFERENCES_FILE = join(getAgentDir(), "bro-preferences.md");
+// Larger files are rejected before reading, even by the editor; the prompt limit is MAX_PREFERENCES_CHARS.
+export const MAX_PREFERENCES_FILE_BYTES = 64 * 1024;
+
+// Raw file text for the editor, undefined when there is no file: never rejects for length, so an
+// oversize file can be opened and trimmed.
+export async function readPreferencesRaw(): Promise<string | undefined> {
+	let size: number;
+	try {
+		size = (await stat(PREFERENCES_FILE)).size;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw new Error(`Cannot read ${PREFERENCES_FILE}: ${errorMessage(error)}`);
+	}
+	if (size > MAX_PREFERENCES_FILE_BYTES) throw new Error(`${PREFERENCES_FILE} is larger than 64 KB. Edit or delete it directly.`);
+	try {
+		return (await readFile(PREFERENCES_FILE, "utf8")).replace(/^\uFEFF/, "");
+	} catch (error) {
+		throw new Error(`Cannot read ${PREFERENCES_FILE}: ${errorMessage(error)}`);
+	}
+}
+
+// Preferences for prompts: "" when absent or blank. Re-read on every request. An oversize file stops
+// the request before any backend call instead of being silently truncated.
+export async function readPreferences(): Promise<string> {
+	const text = ((await readPreferencesRaw()) ?? "").trim();
+	if (text.length > MAX_PREFERENCES_CHARS) {
+		throw new Error(`${PREFERENCES_FILE} is ${text.length.toLocaleString("en-US")} characters; keep it under ${MAX_PREFERENCES_CHARS.toLocaleString("en-US")} (it's sent with every request). Use /bro preferences to trim it.`);
+	}
+	return text;
+}
+
+// Saves and deletes run one at a time, even across a closed and reopened editor, so a slow delete
+// from an earlier editor can never remove a file saved by a later one.
+let preferencesWrites: Promise<void> = Promise.resolve();
+export function queuePreferencesWrite(write: () => Promise<void>): Promise<void> {
+	const next = preferencesWrites.then(write);
+	preferencesWrites = next.catch(() => {});
+	return next;
+}
+

package/src/show.ts

@@ -0,0 +1,243 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { runBackendText } from "./backend.ts";
+import { buildShowPrompt } from "./prompt.ts";
+import { type BroSettings, readPreferences, selectionForCapability, selectionLabel } from "./settings.ts";
+import { type BroSource, MAX_TEXT_LENGTH } from "./sources.ts";
+import { errorMessage, isRenderableSequence } from "./util.ts";
+
+const SHOW_HTML_FILE_PATTERN = /^bro-show-[0-9a-f]{8}\.html$/;
+
+// /bro show: capture only the user- and assistant-visible conversation text of
+// recent session turns and let the show prompt draw it as shapes. Tool calls,
+// tool results, reasoning, and images never leave the session -- this is a
+// structural role/content-type filter, not semantic or keyword-based. See
+// docs/plans/2026-09-07-bro-show-visual-design.md (predates this change).
+type ShowTurn = { entries: string[]; startsTurn: boolean };
+
+function showTextContent(content: unknown): string {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	let text = "";
+	for (const part of content) {
+		if (part && typeof part === "object" && (part as { type?: string }).type === "text") {
+			text += `${(part as { text?: string }).text ?? ""}\n`;
+		}
+	}
+	return text.trim();
+}
+
+export function showEntriesForMessage(message: { role?: string; content?: unknown }): string[] {
+	if (message.role === "user") {
+		const text = showTextContent(message.content);
+		return text ? [`## user\n${JSON.stringify(text)}`] : [];
+	}
+	if (message.role === "assistant") {
+		const text = showTextContent(message.content);
+		return text ? [`## assistant\n${JSON.stringify(text)}`] : [];
+	}
+	return [];
+}
+
+function serializeShowTurns(turns: readonly ShowTurn[]): string {
+	return turns.flatMap((turn) => turn.entries).join("\n\n");
+}
+
+export function captureShowTranscript(ctx: ExtensionCommandContext, turnsRequested: number, maxLength = MAX_TEXT_LENGTH): BroSource | undefined {
+	if (!Number.isSafeInteger(maxLength) || maxLength < 128) throw new Error("Transcript limit must be an integer of at least 128 characters.");
+	const turns: ShowTurn[] = [];
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "message") continue;
+		const message = entry.message as { role?: string; stopReason?: string };
+		// Aborted assistant text is a half-written claim, not a report.
+		if (message.role === "assistant" && message.stopReason === "abort") continue;
+		const entries = showEntriesForMessage(message);
+		// A user message always marks a turn boundary even when it has no
+		// capturable text (image-only, whitespace-only): the turn must still
+		// count, or /bro show 1 would silently over-capture earlier turns.
+		if (message.role === "user") turns.push({ entries, startsTurn: true });
+		else if (entries.length) turns.push({ entries, startsTurn: false });
+	}
+
+	let start = 0;
+	let seen = 0;
+	for (let index = turns.length - 1; index >= 0; index -= 1) {
+		if (!turns[index]!.startsTurn) continue;
+		seen += 1;
+		if (seen === turnsRequested) {
+			start = index;
+			break;
+		}
+	}
+	if (seen === 0) return undefined;
+
+	let text = serializeShowTurns(turns.slice(start));
+	while (text.length > maxLength && start < turns.length - 1) {
+		let next = turns.length;
+		for (let index = start + 1; index < turns.length; index += 1) {
+			if (turns[index]!.startsTurn) {
+				next = index;
+				break;
+			}
+		}
+		if (next >= turns.length) break;
+		start = next;
+		text = serializeShowTurns(turns.slice(start));
+	}
+	if (text.length > maxLength) {
+		// Prefer the newest complete messages even within an oversized single turn.
+		const entries = turns.slice(start).flatMap(turn => turn.entries);
+		const notice = "[… earlier messages truncated …]\n";
+		while (entries.length > 1 && entries.join("\n\n").length + notice.length > maxLength) entries.shift();
+		text = entries.join("\n\n");
+		if (text.length + notice.length > maxLength) {
+			const newline = text.indexOf("\n");
+			const header = text.slice(0, newline);
+			const content = JSON.parse(text.slice(newline + 1)) as string;
+			const marker = "[… earlier text truncated …] ";
+			let tail = content.slice(-(maxLength - header.length - marker.length - 8));
+			while (`${header}\n${JSON.stringify(marker + tail)}`.length > maxLength) tail = tail.slice(Math.max(1, Math.floor(tail.length / 10)));
+			text = `${header}\n${JSON.stringify(marker + tail)}`;
+		} else text = notice + text;
+	}
+	const kept = turns.slice(start).filter((turn) => turn.startsTurn).length;
+	return { text: text.trim(), label: `last ${Math.max(1, kept)} turn${kept > 1 ? "s" : ""} · conversation only` };
+}
+
+export interface ParsedShowArguments {
+	// undefined means "use the configured default"; invalid leading numeric tokens report `invalid` instead.
+	requested?: string;
+	steering: string;
+	invalid: boolean;
+}
+
+// A leading token is only ever treated as the turn count, never as the start of the query — so
+// "/bro show 1 404 handler" is count 1, query "404 handler", not an ambiguous double-numeric query.
+export function parseShowArguments(value: string): ParsedShowArguments {
+	const firstSpace = value.search(/\s/);
+	const firstToken = firstSpace === -1 ? value : value.slice(0, firstSpace);
+	const looksLikeCount = firstToken !== "" && /^-?\d+(?:\.\d+)?$/.test(firstToken);
+	if (!looksLikeCount) return { steering: value, invalid: false };
+
+	// Slicing the raw remainder (instead of split(/\s+/).join(" ")) keeps the query's original spacing intact.
+	const steering = firstSpace === -1 ? "" : value.slice(firstSpace).replace(/^\s+/, "");
+	const valid = /^[1-9]\d*$/.test(firstToken) && Number.isSafeInteger(Number(firstToken));
+	return { requested: valid ? firstToken : undefined, steering, invalid: !valid };
+}
+
+export type ShowDiagram = { kind: "html" | "mermaid"; source: string };
+const SHOW_DIAGRAM_FENCE = /^```(html|mermaid)[^\S\r\n]*\r?\n([\s\S]*?)^```[^\S\r\n]*$/gm;
+
+export function extractShowDiagram(text: string): ShowDiagram | undefined {
+	const last = [...text.matchAll(SHOW_DIAGRAM_FENCE)].at(-1);
+	if (!last) return undefined;
+	const diagram = { kind: last[1] as ShowDiagram["kind"], source: last[2]!.trim() };
+	// Any other Mermaid stays in the modal as a plain text block, visible rather than hidden.
+	return diagram.kind === "html" || isRenderableSequence(diagram.source) ? diagram : undefined;
+}
+
+export function stripShowDiagramFence(text: string): string {
+	const last = [...text.matchAll(SHOW_DIAGRAM_FENCE)].at(-1);
+	if (!last || last.index === undefined) return text;
+	const shown = last[1] === "mermaid" ? `${last[0]}\n[Diagram saved — press O to render]` : "[HTML diagram saved — press O to open]";
+	return text.slice(0, last.index) + shown + text.slice(last.index + last[0].length);
+}
+
+export function showHtmlDirectory(): string {
+	// ponytail: per-uid directory so keep-one cleanup never touches other
+	// users' files in a shared /tmp, and readdir stays small.
+	return join(tmpdir(), `pi-bro-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
+}
+
+function withShowCsp(html: string): string {
+	// Defense in depth: the prompt forbids external resources and scripts;
+	// a meta CSP blocks them anyway if the model slips. Always inserted: multiple
+	// policies are enforced together, so a model-supplied CSP can only tighten it.
+	// Skip only simple leading comments: browsers accept comment terminators that
+	// a general regex misses. Ambiguous markup gets the policy prepended instead.
+	const meta = '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; style-src \'unsafe-inline\'; img-src data:;">';
+	return html.replace(/^(\s*(?:<!--[^<>]*-->\s*)*(?:<!doctype[^>]*>\s*)?)/i, `$1\n${meta}\n`);
+}
+
+// Bro, not the model, owns every script on a Mermaid page: the CSP allows only these two exact
+// scripts by hash, and the model's source is inserted as escaped text that Mermaid parses itself.
+const MERMAID_INIT = 'mermaid.initialize({startOnLoad:true,securityLevel:"strict",htmlLabels:false,flowchart:{htmlLabels:false}});';
+
+async function vendoredMermaid(): Promise<string> {
+	const library = await readFile(new URL("./vendor/mermaid.min.js", import.meta.url), "utf8");
+	// Inlined in <script>: "<!--" or "<script" would change how HTML parses the element. Every
+	// occurrence sits inside a JS string or regex literal, where \x3C is the same character.
+	return library.replace(/<(?=!--|\/?script)/gi, "\\x3C");
+}
+
+function escapeHtml(text: string): string {
+	return text.replace(/[&<>"]/g, (character) => `&#${character.charCodeAt(0)};`);
+}
+
+export async function mermaidShowPage(source: string): Promise<string> {
+	const library = await vendoredMermaid();
+	const hash = (script: string) => `'sha256-${createHash("sha256").update(script).digest("base64")}'`;
+	const escaped = escapeHtml(source);
+	return `<!doctype html>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data:; script-src ${hash(library)} ${hash(MERMAID_INIT)}">
+<title>Bro diagram</title>
+<body style="margin:16px;font-family:system-ui,sans-serif">
+<style>pre.mermaid svg{max-height:calc(100vh - 64px)}</style>
+<pre class="mermaid">${escaped}</pre>
+<details><summary>Diagram source</summary><pre>${escaped}</pre></details>
+<script>${library}</script>
+<script>${MERMAID_INIT}</script>
+</body>`;
+}
+
+export async function writeShowDiagram(diagram: ShowDiagram): Promise<string> {
+	const page = diagram.kind === "mermaid" ? await mermaidShowPage(diagram.source) : withShowCsp(diagram.source);
+	const slug = createHash("sha256").update(page).digest("hex").slice(0, 8);
+	const directory = showHtmlDirectory();
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	for (const name of await readdir(directory)) {
+		if (SHOW_HTML_FILE_PATTERN.test(name)) await rm(join(directory, name), { force: true });
+	}
+	const path = join(directory, `bro-show-${slug}.html`);
+	await writeFile(path, `${page}\n`, "utf8");
+	return path;
+}
+
+// A diagram that cannot be written must not cost the reply: keep the text and warn instead.
+export async function showDiagramPath(text: string, warn: (message: string) => void): Promise<string | undefined> {
+	const diagram = extractShowDiagram(text);
+	if (!diagram) return undefined;
+	try { return await writeShowDiagram(diagram); }
+	catch (error) {
+		warn(`Diagram file unavailable: ${errorMessage(error)}`);
+		return undefined;
+	}
+}
+
+export function openShowHtml(path: string): boolean {
+	if (process.platform === "win32") {
+		const result = spawnSync("cmd", ["/c", "start", "", path], { stdio: "ignore", timeout: 5_000 });
+		return result.status === 0;
+	}
+	const opener = process.platform === "darwin" ? "open" : "xdg-open";
+	const result = spawnSync(opener, [path], { stdio: "ignore", timeout: 5_000 });
+	return result.status === 0;
+}
+
+export async function runShowExplanation(
+	transcript: string,
+	steering: string,
+	signal: AbortSignal,
+	settings: BroSettings,
+	onProgress?: (text: string) => void,
+): Promise<{ text: string; model: string; preferences: boolean }> {
+	const selection = selectionForCapability(settings, "show");
+	const preferences = await readPreferences();
+	const text = await runBackendText(buildShowPrompt(transcript, steering, preferences), selection, signal, onProgress, "show");
+	return { text, model: selectionLabel(selection), preferences: Boolean(preferences) };
+}

package/src/ui-capabilities.ts

@@ -33,3 +33,35 @@ export async function insertBroDesktopText(ctx: UiContext, text: string): Promis
 
 /** Only terminal mode uses synchronous insertion; Desktop uses insertBroDesktopText instead. */
 export function canBroInsertIntoEditor(ctx: UiContext): boolean { return ctx.mode === "tui"; }
+
+/** Any raw SGR mouse report; regular-mode reporting delivers these to handleInput. */
+export const SGR_MOUSE = /^\x1b\[<(\d+);(\d+);(\d+)[Mm]$/;
+
+/** A raw SGR wheel report (Pi 0.84 and regular mode): ±3 lines at a 1-based terminal cell. */
+export function rawWheel(data: string): { delta: number; column: number; row: number } | undefined {
+	const match = SGR_MOUSE.exec(data);
+	const button = match ? Number.parseInt(match[1]!, 10) : 0;
+	if ((button & 64) === 0 || (button & 3) > 1) return undefined;
+	return { delta: button & 1 ? 3 : -3, column: Number(match![2]), row: Number(match![3]) };
+}
+
+export function wheelDelta(data: string): number {
+	return rawWheel(data)?.delta ?? 0;
+}
+
+/** Structural subset of pi-tui's mouse event; Pi 0.84 declares no mouse types. */
+export type BroMouseEvent = { type: string; x?: number; y?: number; wheelDelta?: number };
+export type BroMouseResult = { handled: boolean; render: boolean } | undefined;
+
+/** Pi 1.2+ scrolls the chat behind an overlay whose handleMouse leaves a wheel unhandled. */
+export function consumeWheel(event: BroMouseEvent): BroMouseResult {
+	return event.type === "wheel" ? { handled: true, render: false } : undefined;
+}
+
+export function setRegularMouseReporting(
+	tui: { readonly mode: "regular" | "fullscreen"; readonly terminal?: { write?: (data: string) => void } },
+	enabled: boolean,
+): void {
+	if (tui.mode === "regular") tui.terminal?.write?.(`\x1b[?1000${enabled ? "h" : "l"}\x1b[?1006${enabled ? "h" : "l"}`);
+}
+