pi-context-view 0.2.0

package/src/ui/injections-model.ts

@@ -0,0 +1,239 @@
+/**
+ * Pure presentation model for the Injections view: flattened rows and
+ * list navigation/scrolling state. No pi or TUI access — unit-testable.
+ */
+import type { InitialSnapshot, InjectionItem } from "../model.ts";
+
+const TERMINAL_STRING_SEQUENCE =
+	/(?:\u001B[\]PX^_]|[\u0090\u0098\u009D\u009E\u009F])[\s\S]*?(?:\u0007|\u001B\\|\u009C)/g;
+const TERMINAL_CSI_SEQUENCE = /(?:\u001B\[|\u009B)[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]/g;
+const TERMINAL_ESCAPE_SEQUENCE = /\u001B[\u0020-\u002F]*[\u0030-\u007E]/g;
+const TERMINAL_CONTROL_CHARACTER = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+
+/** One flattened list row derived from the snapshot hierarchy. */
+export type InjectionRow =
+	| {
+		readonly kind: "group";
+		readonly label: string;
+		readonly tokens: number;
+		readonly depth: 0;
+	}
+	| {
+		readonly kind: "item";
+		readonly label: string;
+		readonly tokens: number;
+		/** One for items and two for constituent sub-items. */
+		readonly depth: 1 | 2;
+		/** Stable preview target id from the snapshot. */
+		readonly itemId: string;
+	}
+	| {
+		readonly kind: "separator";
+		readonly label: "";
+		readonly tokens: 0;
+		readonly depth: 0;
+	}
+	| {
+		readonly kind: "total";
+		readonly label: "TOTAL";
+		readonly tokens: number;
+		readonly depth: 0;
+	};
+
+/** Index snapshot items (including sub-items) by id for preview lookup. */
+export function collectItemsById(snapshot: InitialSnapshot): Map<string, InjectionItem> {
+	const items = new Map<string, InjectionItem>();
+	for (const group of snapshot.groups) {
+		for (const item of group.items) {
+			items.set(item.id, item);
+			for (const child of item.children ?? []) items.set(child.id, child);
+		}
+	}
+	return items;
+}
+
+/** Normalize whitespace and remove terminal control sequences from raw preview text. */
+export function normalizePreviewText(text: string): string {
+	return text
+		.replaceAll("\r\n", "\n")
+		.replaceAll("\r", "\n")
+		.replaceAll("\t", "    ")
+		.replace(TERMINAL_STRING_SEQUENCE, "")
+		.replace(TERMINAL_CSI_SEQUENCE, "")
+		.replace(TERMINAL_ESCAPE_SEQUENCE, "")
+		.replace(TERMINAL_CONTROL_CHARACTER, "");
+}
+
+/** Sanitize dynamic text for one terminal line and collapse embedded whitespace. */
+export function normalizeInlineText(text: string): string {
+	return normalizePreviewText(text).replace(/\s+/g, " ").trim();
+}
+
+/** Flatten snapshot groups into rows separated from the non-selectable Initial total. */
+export function buildInjectionRows(snapshot: InitialSnapshot): InjectionRow[] {
+	const rows: InjectionRow[] = [];
+	for (const group of snapshot.groups) {
+		rows.push({
+			kind: "group",
+			label: group.source.label,
+			tokens: group.totalTokens,
+			depth: 0,
+		});
+		for (const item of group.items) {
+			rows.push({
+				kind: "item",
+				label: item.label,
+				tokens: item.tokens,
+				depth: 1,
+				itemId: item.id,
+			});
+			for (const child of item.children ?? []) {
+				rows.push({
+					kind: "item",
+					label: child.label,
+					tokens: child.tokens,
+					depth: 2,
+					itemId: child.id,
+				});
+			}
+		}
+	}
+	rows.push({ kind: "separator", label: "", tokens: 0, depth: 0 });
+	rows.push({ kind: "total", label: "TOTAL", tokens: snapshot.totalTokens, depth: 0 });
+	return rows;
+}
+
+/**
+ * Selection and scroll-window state over fixed rows. A trailing summary can
+ * participate in scrolling without being included in selection navigation.
+ */
+export class ListNavigator {
+	private readonly rowCount: number;
+	private readonly selectableRowCount: number;
+	private visibleCount: number;
+	private selectedIndex = 0;
+	private scrollOffset = 0;
+
+	public constructor(rowCount: number, visibleCount: number, selectableRowCount = rowCount) {
+		this.rowCount = Math.max(0, rowCount);
+		this.selectableRowCount = Math.min(this.rowCount, Math.max(0, selectableRowCount));
+		this.visibleCount = Math.max(1, visibleCount);
+	}
+
+	public get selected(): number {
+		return this.selectedIndex;
+	}
+
+	public get selectedOrdinal(): number {
+		return this.selectedIndex;
+	}
+
+	public get selectableCount(): number {
+		return this.selectableRowCount;
+	}
+
+	public get offset(): number {
+		return this.scrollOffset;
+	}
+
+	public get windowSize(): number {
+		return Math.min(this.visibleCount, this.rowCount);
+	}
+
+	public get hasOverflow(): boolean {
+		return this.rowCount > this.visibleCount;
+	}
+
+	public setVisibleCount(count: number): void {
+		this.visibleCount = Math.max(1, count);
+		this.ensureVisible();
+	}
+
+	public moveBy(delta: number): boolean {
+		return this.moveTo(this.selectedIndex + delta);
+	}
+
+	public moveTo(index: number): boolean {
+		if (this.selectableRowCount === 0) return false;
+		const next = Math.min(this.selectableRowCount - 1, Math.max(0, index));
+		if (next === this.selectedIndex) return false;
+		this.selectedIndex = next;
+		this.ensureVisible();
+		return true;
+	}
+
+	public page(direction: -1 | 1): boolean {
+		return this.moveBy(direction * Math.max(1, this.visibleCount - 1));
+	}
+
+	private ensureVisible(): void {
+		const maxOffset = Math.max(0, this.rowCount - this.visibleCount);
+		if (this.selectedIndex < this.scrollOffset) {
+			this.scrollOffset = this.selectedIndex;
+		} else if (this.selectedIndex >= this.scrollOffset + this.visibleCount) {
+			this.scrollOffset = this.selectedIndex - this.visibleCount + 1;
+		}
+
+		const trailingRows = this.rowCount - this.selectedIndex - 1;
+		if (this.selectedIndex === this.selectableRowCount - 1 && trailingRows < this.visibleCount) {
+			this.scrollOffset = maxOffset;
+		}
+		this.scrollOffset = Math.min(maxOffset, Math.max(0, this.scrollOffset));
+	}
+}
+
+/**
+ * Scroll-only window over wrapped preview lines. Extent is re-declared each
+ * render (wrapping depends on width); the offset is clamped to stay valid.
+ */
+export class PreviewScroller {
+	private lineCount = 0;
+	private visibleCount = 1;
+	private offsetValue = 0;
+
+	public get offset(): number {
+		return this.offsetValue;
+	}
+
+	public get windowSize(): number {
+		return Math.min(this.visibleCount, this.lineCount);
+	}
+
+	/** One-based final line currently visible, suitable for a progress counter. */
+	public get visibleEnd(): number {
+		return Math.min(this.lineCount, this.offsetValue + this.windowSize);
+	}
+
+	public get hasOverflow(): boolean {
+		return this.lineCount > this.visibleCount;
+	}
+
+	public get maxOffset(): number {
+		return Math.max(0, this.lineCount - this.visibleCount);
+	}
+
+	public setExtent(lineCount: number, visibleCount: number): void {
+		this.lineCount = Math.max(0, lineCount);
+		this.visibleCount = Math.max(1, visibleCount);
+		this.offsetValue = Math.min(this.maxOffset, this.offsetValue);
+	}
+
+	public scrollBy(delta: number): boolean {
+		return this.scrollTo(this.offsetValue + delta);
+	}
+
+	public scrollTo(offset: number): boolean {
+		const next = Math.min(this.maxOffset, Math.max(0, offset));
+		if (next === this.offsetValue) return false;
+		this.offsetValue = next;
+		return true;
+	}
+
+	public page(direction: -1 | 1): boolean {
+		return this.scrollBy(direction * Math.max(1, this.visibleCount - 1));
+	}
+
+	public reset(): void {
+		this.offsetValue = 0;
+	}
+}

package/src/ui/injections-view.ts

@@ -0,0 +1,369 @@
+/**
+ * Focused `/context injections` view: hierarchical Initial snapshot rows and
+ * a disabled Runtime roadmap label.
+ */
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+import type { InitialSnapshot, InjectionItem } from "../model.ts";
+import {
+	buildInjectionRows,
+	collectItemsById,
+	type InjectionRow,
+	ListNavigator,
+	normalizeInlineText,
+	normalizePreviewText,
+	PreviewScroller,
+} from "./injections-model.ts";
+import {
+	BODY_INDENT,
+	calculateViewport,
+	DEFAULT_TERMINAL_ROWS,
+	fitLine,
+	fitToTerminalHeight,
+	hintRow,
+	normalizeTerminalRows,
+	spreadLine,
+} from "./layout.ts";
+
+const LIST_FIXED_LINE_COUNT = 10;
+const PREVIEW_FIXED_LINE_COUNT = 8;
+const LIST_DESCRIPTION = "Injections into the model context for the first turn, with token estimates.";
+
+/** Everything the Injections view renders. */
+export interface InjectionsViewInput {
+	readonly snapshot: InitialSnapshot;
+	readonly degradedReason?: string;
+}
+
+/** Open the Injections view as a fullscreen overlay. */
+export async function showInjectionsView(
+	context: ExtensionCommandContext,
+	input: InjectionsViewInput,
+): Promise<void> {
+	await context.ui.custom<void>(
+		(tui, theme, _keybindings, done) => {
+			const view = new InjectionsView(theme, input, done, () => tui.terminal.rows);
+			return {
+				render: (width: number) => view.render(width),
+				invalidate: () => view.invalidate(),
+				handleInput: (data: string) => {
+					view.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: { width: "100%", maxHeight: "100%", margin: 0 },
+		},
+	);
+}
+
+/** Exported for direct render/input tests; use showInjectionsView from pi code. */
+export class InjectionsView {
+	private readonly theme: Theme;
+	private readonly input: InjectionsViewInput;
+	private readonly done: (result: undefined) => void;
+	private readonly getTerminalRows: () => number;
+	private readonly rows: InjectionRow[];
+	private readonly navigator: ListNavigator;
+	private readonly itemsById: Map<string, InjectionItem>;
+	private readonly previewScroller = new PreviewScroller();
+	private previewItem: InjectionItem | undefined;
+	private previewLines: string[] | undefined;
+	private previewWrapWidth: number | undefined;
+	private cachedWidth: number | undefined;
+	private cachedTerminalRows: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	public constructor(
+		theme: Theme,
+		input: InjectionsViewInput,
+		done: (result: undefined) => void,
+		getTerminalRows: () => number = () => process.stdout.rows ?? DEFAULT_TERMINAL_ROWS,
+	) {
+		this.theme = theme;
+		this.input = input;
+		this.done = done;
+		this.getTerminalRows = getTerminalRows;
+		this.rows = buildInjectionRows(input.snapshot);
+		this.navigator = new ListNavigator(this.rows.length, 1, this.rows.length - 2);
+		this.itemsById = collectItemsById(input.snapshot);
+	}
+
+	public handleInput(data: string): void {
+		if (this.previewItem !== undefined) {
+			this.handlePreviewInput(data);
+			return;
+		}
+		if (matchesKey(data, Key.escape) || data === "q") {
+			this.done(undefined);
+			return;
+		}
+		if (matchesKey(data, Key.enter)) {
+			this.openPreview();
+		} else if (matchesKey(data, Key.up)) {
+			if (this.navigator.moveBy(-1)) this.clearCache();
+		} else if (matchesKey(data, Key.down)) {
+			if (this.navigator.moveBy(1)) this.clearCache();
+		} else if (matchesKey(data, Key.pageUp)) {
+			if (this.navigator.page(-1)) this.clearCache();
+		} else if (matchesKey(data, Key.pageDown)) {
+			if (this.navigator.page(1)) this.clearCache();
+		} else if (matchesKey(data, Key.home)) {
+			if (this.navigator.moveTo(0)) this.clearCache();
+		} else if (matchesKey(data, Key.end)) {
+			if (this.navigator.moveTo(this.rows.length - 1)) this.clearCache();
+		}
+	}
+
+	public render(width: number): string[] {
+		const terminalRows = normalizeTerminalRows(this.getTerminalRows());
+		if (
+			this.cachedLines !== undefined &&
+			this.cachedWidth === width &&
+			this.cachedTerminalRows === terminalRows
+		) {
+			return this.cachedLines;
+		}
+		if (this.previewItem !== undefined) {
+			const lines = this.renderPreview(width, terminalRows, this.previewItem);
+			this.cachedWidth = width;
+			this.cachedTerminalRows = terminalRows;
+			this.cachedLines = lines;
+			return lines;
+		}
+		const theme = this.theme;
+		const border = theme.fg("border", "─".repeat(Math.max(1, width)));
+		const warningLines = this.degradedWarningLines(width);
+		const degradedDescriptionLine = this.degradedDescriptionLine(width);
+		const extraLineCount = warningLines.length + (degradedDescriptionLine === undefined ? 0 : 1);
+		const viewport = calculateViewport(this.rows.length, terminalRows, LIST_FIXED_LINE_COUNT, extraLineCount);
+		this.navigator.setVisibleCount(viewport.visibleCount);
+		const lines: string[] = [border, ""];
+
+		lines.push(this.headerLine(width));
+		lines.push("");
+		lines.push(...warningLines);
+		const listLines = this.listLines(width);
+		lines.push(...listLines);
+		if (viewport.showScroll) lines.push(this.scrollLine(width));
+		const paddingCount = viewport.visibleCount - listLines.length;
+		for (let pad = 0; pad < paddingCount; pad++) lines.push("");
+		lines.push("");
+		lines.push(this.fit(theme.fg("muted", `${BODY_INDENT}${LIST_DESCRIPTION}`), width));
+		if (degradedDescriptionLine !== undefined) lines.push(degradedDescriptionLine);
+		lines.push("");
+		lines.push(
+			this.fit(
+				hintRow(this.theme, [
+					["↑↓", "Navigate"],
+					["Enter", "Preview"],
+					["Esc", "Close"],
+				]),
+				width,
+			),
+		);
+		lines.push("", border);
+
+		const fittedLines = fitToTerminalHeight(lines, terminalRows, border);
+		this.cachedWidth = width;
+		this.cachedTerminalRows = terminalRows;
+		this.cachedLines = fittedLines;
+		return fittedLines;
+	}
+
+	public invalidate(): void {
+		this.clearCache();
+	}
+
+	// === Preview mode ===
+
+	private handlePreviewInput(data: string): void {
+		if (matchesKey(data, Key.escape) || data === "q") {
+			this.closePreview();
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			if (this.previewScroller.scrollBy(-1)) this.clearCache();
+		} else if (matchesKey(data, Key.down)) {
+			if (this.previewScroller.scrollBy(1)) this.clearCache();
+		} else if (matchesKey(data, Key.pageUp)) {
+			if (this.previewScroller.page(-1)) this.clearCache();
+		} else if (matchesKey(data, Key.pageDown)) {
+			if (this.previewScroller.page(1)) this.clearCache();
+		} else if (matchesKey(data, Key.home)) {
+			if (this.previewScroller.scrollTo(0)) this.clearCache();
+		} else if (matchesKey(data, Key.end)) {
+			if (this.previewScroller.scrollTo(this.previewScroller.maxOffset)) this.clearCache();
+		}
+	}
+
+	private openPreview(): void {
+		const row = this.rows[this.navigator.selected];
+		if (row?.kind !== "item") return;
+		const item = this.itemsById.get(row.itemId);
+		if (item === undefined) return;
+		this.previewItem = item;
+		this.previewLines = undefined;
+		this.previewWrapWidth = undefined;
+		this.previewScroller.reset();
+		this.clearCache();
+	}
+
+	private closePreview(): void {
+		this.previewItem = undefined;
+		this.previewLines = undefined;
+		this.previewWrapWidth = undefined;
+		this.clearCache();
+	}
+
+	private renderPreview(width: number, terminalRows: number, item: InjectionItem): string[] {
+		const theme = this.theme;
+		const border = theme.fg("border", "─".repeat(Math.max(1, width)));
+		const wrapped = this.getPreviewLines(width, item);
+		const viewport = calculateViewport(wrapped.length, terminalRows, PREVIEW_FIXED_LINE_COUNT);
+		this.previewScroller.setExtent(wrapped.length, viewport.visibleCount);
+
+		const lines: string[] = [border, ""];
+		const title = theme.fg("accent", theme.bold(normalizeInlineText(item.label)));
+		const source = normalizeInlineText(item.source.label);
+		const meta = theme.fg("muted", `${source} · ${item.tokens.toLocaleString("en-US")} tokens `);
+		lines.push(this.spread(title, meta, width));
+		lines.push("");
+
+		const start = this.previewScroller.offset;
+		for (let index = start; index < start + viewport.visibleCount; index++) {
+			lines.push(wrapped[index] ?? "");
+		}
+
+		if (viewport.showScroll) lines.push(this.previewScrollLine(width, wrapped.length));
+		lines.push("");
+		lines.push(
+			this.fit(
+				hintRow(this.theme, [
+					["↑↓", "Scroll"],
+					["PgUp/PgDn", "Page"],
+					["Esc", "Back"],
+				]),
+				width,
+			),
+		);
+		lines.push("", border);
+		return fitToTerminalHeight(lines, terminalRows, border);
+	}
+
+	private getPreviewLines(width: number, item: InjectionItem): string[] {
+		const wrapWidth = Math.max(10, width - BODY_INDENT.length - 1);
+		if (this.previewLines !== undefined && this.previewWrapWidth === wrapWidth) return this.previewLines;
+		const text = normalizePreviewText(item.text);
+		const lines: string[] = [];
+		for (const paragraph of text.split("\n")) {
+			const wrapped = wrapTextWithAnsi(paragraph, wrapWidth);
+			if (wrapped.length === 0) {
+				lines.push("");
+				continue;
+			}
+			for (const line of wrapped) lines.push(`${BODY_INDENT}${line}`);
+		}
+		this.previewLines = lines;
+		this.previewWrapWidth = wrapWidth;
+		return lines;
+	}
+
+	private previewScrollLine(width: number, totalLines: number): string {
+		if (!this.previewScroller.hasOverflow) return this.fit("", width);
+		return this.fit(
+			this.theme.fg("dim", `${BODY_INDENT}(${this.previewScroller.visibleEnd}/${totalLines})`),
+			width,
+		);
+	}
+
+	private headerLine(width: number): string {
+		const theme = this.theme;
+		const title = theme.fg("accent", theme.bold("Context Injections"));
+		const separator = theme.fg("dim", " · ");
+		const initial = theme.fg("mdHeading", theme.bold("[INITIAL]"));
+		const runtime = theme.fg("dim", "RUNTIME");
+		return this.fit(`${title}${separator}${initial}  ${runtime}`, width);
+	}
+
+	private listLines(width: number): string[] {
+		const theme = this.theme;
+		const lines: string[] = [];
+		const start = this.navigator.offset;
+		const end = start + this.navigator.windowSize;
+		for (let index = start; index < end; index++) {
+			const row = this.rows[index];
+			if (row === undefined) break;
+			if (row.kind === "separator") {
+				lines.push("");
+				continue;
+			}
+			const selected = row.kind !== "total" && index === this.navigator.selected;
+			// The cursor stays in one fixed column; hierarchy indents after it.
+			const marker = selected ? theme.fg("accent", "→ ") : BODY_INDENT;
+			const indent = BODY_INDENT.repeat(row.depth);
+			const value = row.tokens.toLocaleString("en-US");
+			const tokens = row.kind === "total"
+				? theme.bold(theme.fg("text", value))
+				: theme.fg(selected ? "accent" : "muted", value);
+			const labelWidth = Math.max(8, width - indent.length - visibleWidth(tokens) - 6);
+			const label = truncateToWidth(normalizeInlineText(row.label), labelWidth, "…");
+			lines.push(this.spread(`${marker}${indent}${this.rowLabel(row, label, selected)}`, `${tokens}  `, width));
+		}
+		return lines;
+	}
+
+	private rowLabel(row: InjectionRow, label: string, selected: boolean): string {
+		const theme = this.theme;
+		if (selected) return theme.fg("accent", label);
+		if (row.kind === "group" || row.kind === "total") return theme.bold(theme.fg("text", label));
+		return theme.fg(row.depth > 1 ? "dim" : "muted", label);
+	}
+
+	private scrollLine(width: number): string {
+		if (!this.navigator.hasOverflow) return this.fit("", width);
+		return this.fit(
+			this.theme.fg(
+				"dim",
+				`${BODY_INDENT}(${this.navigator.selectedOrdinal + 1}/${this.navigator.selectableCount})`,
+			),
+			width,
+		);
+	}
+
+	/** Wrapped degraded-capture reason placed below the dialog header. */
+	private degradedWarningLines(width: number): string[] {
+		if (this.input.degradedReason === undefined) return [];
+		const reason = this.theme.fg(
+			"warning",
+			`${BODY_INDENT}${normalizeInlineText(this.input.degradedReason)}`,
+		);
+		return wrapTextWithAnsi(reason, width);
+	}
+
+	/** Degraded-capture indicator shown as part of the dialog description. */
+	private degradedDescriptionLine(width: number): string | undefined {
+		if (this.input.degradedReason === undefined) return undefined;
+		return this.fit(
+			this.theme.fg("warning", `${BODY_INDENT}[Degraded: pi-native fallback used]`),
+			width,
+		);
+	}
+
+	private spread(left: string, right: string, width: number): string {
+		return spreadLine(left, right, width);
+	}
+
+	private fit(line: string, width: number): string {
+		return fitLine(line, width);
+	}
+
+	private clearCache(): void {
+		this.cachedWidth = undefined;
+		this.cachedTerminalRows = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/src/ui/layout.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared pi-native fullscreen-view layout helpers: indentation constants,
+ * terminal-height viewport math, width fitting, and hint-row formatting used
+ * by the Usage and Injections views. Pure string/number logic — no pi access.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** Two-space indent for descriptions, counters, hints, and body content. */
+export const BODY_INDENT = "  ";
+export const DEFAULT_TERMINAL_ROWS = 24;
+
+/** How many content rows fit and whether an overflow indicator is needed. */
+export interface Viewport {
+	visibleCount: number;
+	showScroll: boolean;
+}
+
+/** Divide terminal rows between content and an overflow indicator. */
+export function calculateViewport(
+	itemCount: number,
+	terminalRows: number,
+	fixedLineCount: number,
+	extraLineCount = 0,
+): Viewport {
+	const available = Math.max(1, terminalRows - fixedLineCount - extraLineCount);
+	const showScroll = itemCount > available && available > 1;
+	return {
+		visibleCount: Math.max(1, available - (showScroll ? 1 : 0)),
+		showScroll,
+	};
+}
+
+/** Keep emergency short-terminal output bounded while preserving both borders. */
+export function fitToTerminalHeight(lines: string[], terminalRows: number, border: string): string[] {
+	if (lines.length <= terminalRows) return lines;
+	if (terminalRows === 1) return [border];
+	return [...lines.slice(0, terminalRows - 1), border];
+}
+
+/** Normalize an injected terminal-height reading to a usable positive integer. */
+export function normalizeTerminalRows(rows: number): number {
+	return Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : DEFAULT_TERMINAL_ROWS;
+}
+
+/** Truncate one rendered line to the supplied width. */
+export function fitLine(line: string, width: number): string {
+	return truncateToWidth(line, width, "…");
+}
+
+/** Spread left and right content across the width, truncating the left side on overlap. */
+export function spreadLine(left: string, right: string, width: number): string {
+	const gap = width - visibleWidth(left) - visibleWidth(right);
+	if (gap < 1) {
+		return fitLine(`${truncateToWidth(left, Math.max(1, width - visibleWidth(right) - 2), "…")} ${right}`, width);
+	}
+	return `${left}${" ".repeat(gap)}${right}`;
+}
+
+/** Pi-style hint row: two-space indent, `key description` pairs joined by ` · `. */
+export function hintRow(theme: Theme, hints: ReadonlyArray<readonly [string, string]>): string {
+	const separator = theme.fg("dim", " · ");
+	return `${BODY_INDENT}${hints.map(([key, description]) => hint(theme, key, description)).join(separator)}`;
+}
+
+/** Pi-style hint: dim key, slightly brighter (muted) description. */
+function hint(theme: Theme, key: string, description: string): string {
+	return theme.fg("dim", key) + theme.fg("muted", ` ${description}`);
+}