gentle-pi 2.3.0 → 2.5.0

package/lib/shell-changes-view.ts

@@ -0,0 +1,205 @@
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { CHANGE_STATUS, changesSummary, type ChangedFile, type ChangesModel } from "./shell-changes.ts";
+
+// Gentle Shell changes overlay: a framed two-pane view with the working
+// tree's changed files on the left and the selected file's diff on the right.
+// Git access is injected so the component renders without a repository.
+
+export interface ChangesViewTheme {
+	fg(color: string, text: string): string;
+}
+
+export interface ChangesViewDeps {
+	theme: ChangesViewTheme;
+	rows: number;
+	loadDiff(file: ChangedFile): Promise<string>;
+	onOpen(file: ChangedFile): void;
+	onClose(): void;
+	requestRender(): void;
+}
+
+const ROLE = {
+	FRAME: "border",
+	TITLE: "customMessageLabel",
+	SELECTED: "accent",
+	PATH: "text",
+	PATH_IDLE: "muted",
+	ADDED: "success",
+	REMOVED: "error",
+	NEW: "success",
+	HUNK: "customMessageLabel",
+	KEY: "accent",
+	KEY_TEXT: "dim",
+	EMPTY: "dim",
+} as const;
+
+const HEADER_PREFIXES = ["diff --git", "index ", "--- ", "+++ ", "new file mode", "deleted file mode", "similarity index", "rename from", "rename to", "Binary files"];
+const LIST_MAX_WIDTH = 36;
+const LIST_RATIO = 0.35;
+const CHROME_ROWS = 3;
+const MIN_BODY_ROWS = 1;
+const EMPTY_DIFF = "no diff for this file";
+const CLEAN_TREE = "working tree is clean";
+const KEYS = [
+	["j/k", "file"],
+	["ctrl+j/k", "scroll"],
+	["o", "open in editor"],
+	["esc", "close"],
+] as const;
+
+function rule(length: number): string {
+	return "─".repeat(Math.max(0, length));
+}
+
+export function colorDiff(text: string, theme: ChangesViewTheme): string[] {
+	const lines: string[] = [];
+	for (const line of text.split("\n")) {
+		if (line === "" || HEADER_PREFIXES.some((prefix) => line.startsWith(prefix))) continue;
+		if (line.startsWith("@@")) lines.push(theme.fg(ROLE.HUNK, line));
+		else if (line.startsWith("+")) lines.push(theme.fg("toolDiffAdded", line));
+		else if (line.startsWith("-")) lines.push(theme.fg("toolDiffRemoved", line));
+		else lines.push(theme.fg("toolDiffContext", line));
+	}
+	return lines;
+}
+
+function fileCounts(file: ChangedFile, theme: ChangesViewTheme): string {
+	if (file.status === CHANGE_STATUS.UNTRACKED || file.status === CHANGE_STATUS.ADDED) {
+		return `${theme.fg(ROLE.ADDED, `+${file.added}`)} ${theme.fg(ROLE.NEW, "new")}`;
+	}
+	return `${theme.fg(ROLE.ADDED, `+${file.added}`)} ${theme.fg(ROLE.REMOVED, `−${file.deleted}`)}`;
+}
+
+function fit(text: string, width: number): string {
+	const clipped = truncateToWidth(text, width, "…");
+	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+function fingerprint(file: ChangedFile): string {
+	return `${file.status}:${file.added}:${file.deleted}`;
+}
+
+export class ChangesView {
+	private model: ChangesModel;
+	private readonly deps: ChangesViewDeps;
+	private selected = 0;
+	private scroll = 0;
+	private readonly diffs = new Map<string, string[]>();
+
+	constructor(model: ChangesModel, deps: ChangesViewDeps) {
+		this.model = model;
+		this.deps = deps;
+		this.loadSelected();
+	}
+
+	// Replace the model while open: keep the selection by path and drop cached
+	// diffs for files whose counts moved so they reload.
+	update(model: ChangesModel): void {
+		const selectedPath = this.model.files[this.selected]?.path;
+		const before = new Map(this.model.files.map((file) => [file.path, fingerprint(file)]));
+		for (const file of model.files) {
+			if (before.get(file.path) !== fingerprint(file)) this.diffs.delete(file.path);
+		}
+		for (const path of this.diffs.keys()) {
+			if (!model.files.some((file) => file.path === path)) this.diffs.delete(path);
+		}
+		this.model = model;
+		const index = model.files.findIndex((file) => file.path === selectedPath);
+		this.selected = index === -1 ? Math.max(0, Math.min(this.selected, model.files.length - 1)) : index;
+		this.loadSelected();
+		this.deps.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape) || data === "q") {
+			this.deps.onClose();
+			return;
+		}
+		// ctrl+j arrives as a bare line feed, which pi also reads as enter, so
+		// the scroll keys are checked before the open key; a real Enter is CR.
+		if (data === "j" || matchesKey(data, Key.down)) this.select(this.selected + 1);
+		else if (data === "k" || matchesKey(data, Key.up)) this.select(this.selected - 1);
+		else if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("j"))) this.scrollBy(this.bodyRows());
+		else if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("k"))) this.scrollBy(-this.bodyRows());
+		else if (data === "o" || matchesKey(data, Key.enter)) {
+			const file = this.model.files[this.selected];
+			if (file) this.deps.onOpen(file);
+		}
+	}
+
+	render(width: number): string[] {
+		const theme = this.deps.theme;
+		const inner = width - 2;
+		const listWidth = Math.min(LIST_MAX_WIDTH, Math.floor(inner * LIST_RATIO));
+		const diffWidth = inner - listWidth - 4;
+		const titleText = `✎ Changes · ${changesSummary(this.model)}`;
+		const top = theme.fg(ROLE.FRAME, "╭─ ") + theme.fg(ROLE.TITLE, titleText) + theme.fg(ROLE.FRAME, ` ${rule(inner - visibleWidth(titleText) - 3)}╮`);
+		const rows = this.bodyRows();
+		const diff = this.visibleDiff(rows);
+		const body: string[] = [];
+		for (let row = 0; row < rows; row += 1) {
+			const left = fit(this.fileLine(row), listWidth);
+			const right = fit(diff[row] ?? "", diffWidth);
+			body.push(`${theme.fg(ROLE.FRAME, "│")} ${left} ${theme.fg(ROLE.FRAME, "│")} ${right}${theme.fg(ROLE.FRAME, "│")}`);
+		}
+		const keys = KEYS.map(([key, label]) => `${theme.fg(ROLE.KEY, key)} ${theme.fg(ROLE.KEY_TEXT, label)}`).join("   ");
+		const keysLine = `${theme.fg(ROLE.FRAME, "│")} ${fit(keys, inner - 2)} ${theme.fg(ROLE.FRAME, "│")}`;
+		const bottom = theme.fg(ROLE.FRAME, `╰${rule(inner)}╯`);
+		return [top, ...body, keysLine, bottom];
+	}
+
+	invalidate(): void {}
+
+	private bodyRows(): number {
+		return Math.max(MIN_BODY_ROWS, this.deps.rows - CHROME_ROWS);
+	}
+
+	private fileLine(row: number): string {
+		const file = this.model.files[row];
+		if (!file) return "";
+		const theme = this.deps.theme;
+		const marker = row === this.selected ? theme.fg(ROLE.SELECTED, "▸") : " ";
+		const path = theme.fg(row === this.selected ? ROLE.PATH : ROLE.PATH_IDLE, file.path);
+		return `${marker} ${path}  ${fileCounts(file, theme)}`;
+	}
+
+	private visibleDiff(rows: number): string[] {
+		const file = this.model.files[this.selected];
+		if (!file) return [this.deps.theme.fg(ROLE.EMPTY, CLEAN_TREE)];
+		const lines = this.diffs.get(file.path);
+		if (!lines) return [];
+		if (lines.length === 0) return [this.deps.theme.fg(ROLE.EMPTY, EMPTY_DIFF)];
+		const maxScroll = Math.max(0, lines.length - rows);
+		this.scroll = Math.min(this.scroll, maxScroll);
+		return lines.slice(this.scroll, this.scroll + rows);
+	}
+
+	private select(index: number): void {
+		const next = Math.max(0, Math.min(this.model.files.length - 1, index));
+		if (next === this.selected) return;
+		this.selected = next;
+		this.scroll = 0;
+		this.loadSelected();
+		this.deps.requestRender();
+	}
+
+	private scrollBy(delta: number): void {
+		this.scroll = Math.max(0, this.scroll + delta);
+		this.deps.requestRender();
+	}
+
+	private loadSelected(): void {
+		const file = this.model.files[this.selected];
+		if (!file || this.diffs.has(file.path)) return;
+		void this.deps.loadDiff(file).then(
+			(text) => {
+				this.diffs.set(file.path, colorDiff(text, this.deps.theme));
+				this.deps.requestRender();
+			},
+			() => {
+				this.diffs.set(file.path, []);
+				this.deps.requestRender();
+			},
+		);
+	}
+}

package/lib/shell-changes.ts

@@ -0,0 +1,210 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+// Gentle Shell changes: the working tree against HEAD, new files included.
+// Git is the source of truth; this module turns raw `git diff --numstat` and
+// `git status --porcelain -z` output into a model and renders the widget.
+
+export const CHANGE_STATUS = {
+	MODIFIED: "modified",
+	ADDED: "added",
+	DELETED: "deleted",
+	RENAMED: "renamed",
+	UNTRACKED: "untracked",
+} as const;
+
+export type ChangeStatus = (typeof CHANGE_STATUS)[keyof typeof CHANGE_STATUS];
+
+export interface ChangedFile {
+	path: string;
+	added: number;
+	deleted: number;
+	status: ChangeStatus;
+}
+
+export interface ChangesModel {
+	files: ChangedFile[];
+	added: number;
+	deleted: number;
+}
+
+export interface ChangesSnapshot {
+	numstat: string;
+	porcelain: string;
+}
+
+export interface ChangesTheme {
+	fg(color: string, text: string): string;
+}
+
+interface NumstatEntry {
+	path: string;
+	added: number;
+	deleted: number;
+}
+
+export const CHANGES_COMMAND = "/gentle:changes";
+const WIDGET_GLYPH = "✎";
+const STATUS_BY_CODE: Record<string, ChangeStatus> = {
+	A: CHANGE_STATUS.ADDED,
+	D: CHANGE_STATUS.DELETED,
+	R: CHANGE_STATUS.RENAMED,
+	C: CHANGE_STATUS.ADDED,
+	"?": CHANGE_STATUS.UNTRACKED,
+};
+const RENAME_BRACES = /\{([^{}]*) => ([^{}]*)\}/g;
+const HAS_RENAME_BRACES = /\{[^{}]* => [^{}]*\}/;
+const RENAME_ARROW = " => ";
+
+export function emptyChanges(): ChangesModel {
+	return { files: [], added: 0, deleted: 0 };
+}
+
+function renamedPath(path: string): string {
+	if (HAS_RENAME_BRACES.test(path)) return path.replace(RENAME_BRACES, "$2").replace(/\/\//g, "/");
+	const arrow = path.indexOf(RENAME_ARROW);
+	return arrow === -1 ? path : path.slice(arrow + RENAME_ARROW.length);
+}
+
+function count(value: string): number {
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function parseNumstat(text: string): NumstatEntry[] {
+	const entries: NumstatEntry[] = [];
+	for (const line of text.split("\n")) {
+		const [added, deleted, ...rest] = line.split("\t");
+		if (added === undefined || deleted === undefined || rest.length === 0) continue;
+		entries.push({ path: renamedPath(rest.join("\t")), added: count(added), deleted: count(deleted) });
+	}
+	return entries;
+}
+
+export function parsePorcelain(text: string): Map<string, ChangeStatus> {
+	const statuses = new Map<string, ChangeStatus>();
+	const records = text.split("\0").filter((record) => record.length > 0);
+	for (let index = 0; index < records.length; index += 1) {
+		const record = records[index];
+		const code = record.slice(0, 2);
+		const path = record.slice(3);
+		const status = STATUS_BY_CODE[code[0]] ?? STATUS_BY_CODE[code[1]] ?? CHANGE_STATUS.MODIFIED;
+		statuses.set(path, status);
+		if (code[0] === "R" || code[0] === "C") index += 1;
+	}
+	return statuses;
+}
+
+export function snapshotChanges(snapshot: ChangesSnapshot): ChangedFile[] {
+	const counts = new Map(parseNumstat(snapshot.numstat).map((entry) => [entry.path, entry]));
+	const files: ChangedFile[] = [];
+	for (const [path, status] of parsePorcelain(snapshot.porcelain)) {
+		const entry = counts.get(path);
+		files.push({ path, added: entry?.added ?? 0, deleted: entry?.deleted ?? 0, status });
+	}
+	return files;
+}
+
+export function changesModel(changed: ChangedFile[]): ChangesModel {
+	const files = [...changed].sort((a, b) => a.path.localeCompare(b.path));
+	return {
+		files,
+		added: files.reduce((total, file) => total + file.added, 0),
+		deleted: files.reduce((total, file) => total + file.deleted, 0),
+	};
+}
+
+export function changesSummary(model: ChangesModel): string {
+	const noun = model.files.length === 1 ? "file" : "files";
+	return `${model.files.length} ${noun} · +${model.added} −${model.deleted}`;
+}
+
+// One line: summary, the files joined by dots, and the command pushed to
+// the right edge. The file list goes first when the terminal is narrow.
+export function renderChangesWidget(model: ChangesModel, theme: ChangesTheme, width: number): string[] {
+	if (model.files.length === 0) return [];
+	const noun = model.files.length === 1 ? "file" : "files";
+	const dot = theme.fg("muted", "·");
+	const head = `${theme.fg("accent", WIDGET_GLYPH)} ${theme.fg("text", `${model.files.length} ${noun}`)} ${dot} ${theme.fg("success", `+${model.added}`)} ${theme.fg("error", `−${model.deleted}`)}`;
+	const hint = theme.fg("dim", CHANGES_COMMAND);
+	const list = model.files.map((file) => theme.fg("muted", file.path)).join(` ${dot} `);
+	const left = `${head} ${dot} ${list}`;
+	const gap = width - visibleWidth(left) - visibleWidth(hint);
+	if (gap >= 2) return [`${left}${" ".repeat(gap)}${hint}`];
+	const headGap = width - visibleWidth(head) - visibleWidth(hint);
+	if (headGap >= 2) return [`${head}${" ".repeat(headGap)}${hint}`];
+	return [truncateToWidth(head, width, "…")];
+}
+
+export interface GitResult {
+	stdout: string;
+	code: number;
+}
+
+export type GitRunner = (args: string[]) => Promise<GitResult>;
+export type LineCounter = (path: string) => Promise<number>;
+
+const noLines: LineCounter = async () => 0;
+
+const NUMSTAT_ARGS = ["diff", "--numstat", "HEAD"];
+const PORCELAIN_ARGS = ["status", "--porcelain=v1", "--untracked-files=all", "-z"];
+
+// Tracks working-tree changes. Concurrent refreshes coalesce: one git
+// round-trip runs at a time and a refresh requested meanwhile triggers
+// exactly one more.
+export class ChangesTracker {
+	private readonly git: GitRunner;
+	private readonly countLines: LineCounter;
+	private current: ChangesModel = emptyChanges();
+	private available = false;
+	private inFlight: Promise<ChangesModel> | undefined;
+	private queued = false;
+
+	constructor(git: GitRunner, countLines: LineCounter = noLines) {
+		this.git = git;
+		this.countLines = countLines;
+	}
+
+	get model(): ChangesModel {
+		return this.current;
+	}
+
+	async start(): Promise<void> {
+		const files = await this.capture();
+		this.available = files !== undefined;
+		this.current = files ? changesModel(files) : emptyChanges();
+	}
+
+	async refresh(): Promise<ChangesModel> {
+		if (!this.available) return this.current;
+		if (this.inFlight) {
+			this.queued = true;
+			return this.inFlight;
+		}
+		this.inFlight = this.runRefresh();
+		try {
+			return await this.inFlight;
+		} finally {
+			this.inFlight = undefined;
+		}
+	}
+
+	private async runRefresh(): Promise<ChangesModel> {
+		do {
+			this.queued = false;
+			const files = await this.capture();
+			if (files) this.current = changesModel(files);
+		} while (this.queued);
+		return this.current;
+	}
+
+	private async capture(): Promise<ChangedFile[] | undefined> {
+		const [numstat, porcelain] = await Promise.all([this.git(NUMSTAT_ARGS), this.git(PORCELAIN_ARGS)]);
+		if (numstat.code !== 0 || porcelain.code !== 0) return undefined;
+		const files = snapshotChanges({ numstat: numstat.stdout, porcelain: porcelain.stdout });
+		// Untracked files never appear in numstat; count their lines directly.
+		for (const file of files) {
+			if (file.status === CHANGE_STATUS.UNTRACKED) file.added = await this.countLines(file.path).catch(() => 0);
+		}
+		return files;
+	}
+}

package/lib/shell-gauge.ts

@@ -0,0 +1,40 @@
+// Shared gauge primitives for the Gentle Shell bar and panels.
+
+const GAUGE_TONE = {
+	ACCENT: "accent",
+	WARNING: "warning",
+	ERROR: "error",
+	DIM: "dim",
+} as const;
+
+export type GaugeTone = (typeof GAUGE_TONE)[keyof typeof GAUGE_TONE];
+
+export interface GaugeTheme {
+	fg(color: string, text: string): string;
+}
+
+export const GAUGE_CELLS = 8;
+const GAUGE_FILLED = "▰";
+const GAUGE_EMPTY = "▱";
+const GAUGE_EMPTY_ROLE = "border";
+const WARNING_THRESHOLD = 80;
+const ERROR_THRESHOLD = 95;
+
+export function renderGauge(percent: number | null, cells: number = GAUGE_CELLS): string {
+	const clamped = Math.max(0, Math.min(100, percent ?? 0));
+	const filled = Math.round((clamped / 100) * cells);
+	return GAUGE_FILLED.repeat(filled) + GAUGE_EMPTY.repeat(cells - filled);
+}
+
+export function gaugeTone(percent: number | null): GaugeTone {
+	if (percent === null) return GAUGE_TONE.DIM;
+	if (percent >= ERROR_THRESHOLD) return GAUGE_TONE.ERROR;
+	if (percent >= WARNING_THRESHOLD) return GAUGE_TONE.WARNING;
+	return GAUGE_TONE.ACCENT;
+}
+
+export function paintGauge(percent: number | null, theme: GaugeTheme, cells: number = GAUGE_CELLS): string {
+	const gauge = renderGauge(percent, cells);
+	const filled = gauge.replace(new RegExp(`${GAUGE_EMPTY}+$`), "");
+	return theme.fg(gaugeTone(percent), filled) + theme.fg(GAUGE_EMPTY_ROLE, gauge.slice(filled.length));
+}

package/lib/shell-prompt.ts

@@ -0,0 +1,119 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { stripAnsi } from "./terminal-theme.ts";
+
+// Gentle Shell prompt frame. pi's editor renders a top rule, padded content
+// lines, and a bottom rule; this module wraps those lines in a rounded frame
+// with a petal that shows what the agent is doing. Everything here is pure.
+
+export const PROMPT_STATE = {
+	IDLE: "idle",
+	WORKING: "working",
+	QUEUED: "queued",
+} as const;
+
+export type PromptState = (typeof PROMPT_STATE)[keyof typeof PROMPT_STATE];
+
+const PETAL_TONE = {
+	BRIGHT: "borderAccent",
+	ROSE: "accent",
+	SOFT: "thinkingHigh",
+	DEEP: "mdQuoteBorder",
+	WARNING: "warning",
+} as const;
+
+export type PetalTone = (typeof PETAL_TONE)[keyof typeof PETAL_TONE];
+
+// The Gentle themes map these to the rose ramp: active pink, rose, soft
+// rose, deep pink. The spin walks the ramp one shade per frame.
+const PETAL_TONE_FRAMES = [PETAL_TONE.BRIGHT, PETAL_TONE.ROSE, PETAL_TONE.SOFT, PETAL_TONE.DEEP] as const;
+
+export interface PromptFrameOptions {
+	state: PromptState;
+	tick: number;
+	borderColor: (text: string) => string;
+	fg: (color: string, text: string) => string;
+	bold?: (text: string) => string;
+	/** Paints a finished line, e.g. with the panel background. */
+	paint?: (line: string) => string;
+}
+
+// A terminal cell cannot grow, so the petal earns presence with weight and
+// the brightest rose in the theme. Working spins through four flowers.
+export const PROMPT_PETAL = "✿";
+const PETAL_FRAMES = ["✿", "❀", "❁", "✾"] as const;
+export const PROMPT_HINT = "type, or / for commands";
+const LABEL_ROLE = "muted";
+const HINT_ROLE = "dim";
+const FAKE_CURSOR = "\x1b[7m \x1b[0m";
+const SCROLL_INDICATOR = /[↑↓] \d+ more/;
+const STATE_LABEL: Record<PromptState, string | undefined> = {
+	[PROMPT_STATE.IDLE]: undefined,
+	[PROMPT_STATE.WORKING]: "working",
+	[PROMPT_STATE.QUEUED]: "queued",
+};
+
+export function petalTone(state: PromptState, tick: number): PetalTone {
+	if (state === PROMPT_STATE.QUEUED) return PETAL_TONE.WARNING;
+	if (state === PROMPT_STATE.WORKING) return PETAL_TONE_FRAMES[tick % PETAL_TONE_FRAMES.length];
+	return PETAL_TONE.BRIGHT;
+}
+
+export function petalGlyph(state: PromptState, tick: number): string {
+	if (state === PROMPT_STATE.IDLE) return PROMPT_PETAL;
+	return PETAL_FRAMES[tick % PETAL_FRAMES.length];
+}
+
+function scrollIndicator(rule: string): string | undefined {
+	return stripAnsi(rule).match(SCROLL_INDICATOR)?.[0];
+}
+
+function rule(length: number): string {
+	return "─".repeat(Math.max(0, length));
+}
+
+function topRule(width: number, options: PromptFrameOptions, indicator: string | undefined): string {
+	const label = indicator ?? STATE_LABEL[options.state];
+	const glyph = petalGlyph(options.state, options.tick);
+	const petal = options.fg(petalTone(options.state, options.tick), options.bold ? options.bold(glyph) : glyph);
+	const labelText = label ? ` ${options.fg(LABEL_ROLE, label)}` : "";
+	const labelWidth = label ? label.length + 1 : 0;
+	const fill = width - 3 - visibleWidth(glyph) - labelWidth - 1 - 1;
+	return options.borderColor("╭─ ") + petal + labelText + options.borderColor(` ${rule(fill)}╮`);
+}
+
+function bottomRule(width: number, options: PromptFrameOptions, indicator: string | undefined): string {
+	if (!indicator) return options.borderColor(`╰${rule(width - 2)}╯`);
+	const fill = width - 3 - indicator.length - 1 - 1;
+	return options.borderColor("╰─ ") + options.fg(LABEL_ROLE, indicator) + options.borderColor(` ${rule(fill)}╯`);
+}
+
+function sideRules(line: string, innerWidth: number, options: PromptFrameOptions): string {
+	const padding = " ".repeat(Math.max(0, innerWidth - visibleWidth(line)));
+	return options.borderColor("│") + line + padding + options.borderColor("│");
+}
+
+export function framePromptLines(lines: string[], width: number, options: PromptFrameOptions): string[] {
+	if (lines.length < 2) return lines;
+	const innerWidth = width - 2;
+	const top = lines[0];
+	const bottom = lines[lines.length - 1];
+	const content = lines.slice(1, -1).map((line) => sideRules(line, innerWidth, options));
+	const paint = options.paint ?? ((line: string) => line);
+	return [topRule(width, options, scrollIndicator(top)), ...content, bottomRule(width, options, scrollIndicator(bottom))].map(paint);
+}
+
+export function withPromptHint(line: string, hint: string, fg: PromptFrameOptions["fg"]): string {
+	const cursorAt = line.indexOf(FAKE_CURSOR);
+	if (cursorAt === -1) return line;
+	const afterCursor = cursorAt + FAKE_CURSOR.length;
+	const trailing = line.slice(afterCursor);
+	if (trailing.trim() !== "" || trailing.length < hint.length + 1) return line;
+	return `${line.slice(0, afterCursor)} ${fg(HINT_ROLE, hint)}${" ".repeat(trailing.length - hint.length - 1)}`;
+}
+
+// Paints a line with a background that survives the resets pi's editor
+// emits around the cursor, so the panel color runs edge to edge.
+export function panelPainter(bgAnsi: string): (line: string) => string {
+	const RESET = "\x1b[0m";
+	return (line) => `${bgAnsi}${line.split(RESET).join(`${RESET}${bgAnsi}`)}\x1b[49m`;
+}