@gavin-hu/my-pi-agent 0.19.0 → 0.20.0

package/extensions/bytefly/panel/tui/frame.ts

@@ -1,13 +1,17 @@
 /**
- * The chrome around the panel's body: the layout constants, the section bar with
- * its counts, a group heading, the hint row that a transient notice replaces, and
- * the frame the two sections share.
+ * The chrome around the panel's body: the header rule with the screen's
+ * attention, the section tabs with their counts and the write scope, a group
+ * heading, the hint row that a transient notice replaces, and the frame all three
+ * sections share.
  *
- * Every section draws its body through these, so the two views cannot drift on
- * spacing, roles, or the width arithmetic.
+ * Every section draws its body through {@link panelFrame}, so the three cannot
+ * drift on spacing, roles, width arithmetic, or height: the body is padded to one
+ * target measured across all three sections, which is what keeps the dock from
+ * resizing when the tabs change.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../../../lib/format.ts";
 import {
 	detailBlockRows,
@@ -17,51 +21,86 @@ import {
 	type ViewportRowsSource,
 } from "../../../../lib/tui/chrome.ts";
 import { clip, fitCells, splitRow } from "../../../../lib/tui/columns.ts";
-import { fitRows, formatRange, type ListCursor } from "../../../../lib/tui/cursor.ts";
+import { formatRange, type ListCursor } from "../../../../lib/tui/cursor.ts";
+import { SEPARATORS } from "../../../../lib/tui/glyphs.ts";
 import { BODY_INDENT } from "../../../../lib/tui/indent.ts";
 import { emptyState } from "../../../../lib/tui/rows.ts";
+import { titleRule } from "../../../../lib/tui/rules.ts";
 import { paint } from "../../../../lib/tui/tokens.ts";
-import { sectionSegments, type SummarySegment } from "../format.ts";
+import { sectionLabel, type SummarySegment } from "../format.ts";
 import type { PanelSection } from "../types.ts";
 import { selectableRange, type PanelEntry } from "./entries.ts";
+import { composeRows } from "./panes.ts";
 
 /** Body rows when the terminal height is unknown. */
 export const SCREEN_DEFAULT_ROWS = 16;
-/** Fixed rows around the body: header, summary, blank, blank, hint, closing rule. */
+/** Fixed rows around the body: header, tabs, blank, blank, hint, closing rule. */
 export const FRAME_ROWS = 6;
-/** Detail rows reserved for the focused row: its head, one description line, and its origin. */
+/** Detail rows reserved for the focused row in the single-column layout. */
 export const DETAIL_ROWS = 3;
-/** Body rows that must survive before the detail pane collapses to its title. */
+/** Body rows that must survive before the bottom pane collapses to nothing. */
 export const MIN_BODY_ROWS = 3;
 /** Detail rows when the terminal height is unknown and the focused row is expanded. */
 export const EXPANDED_DETAIL_FALLBACK = 8;
-/** Fixed body offset in the frame: header, summary, blank line. */
+/** Fixed body offset in the frame: header, tabs, blank line. */
 export const BODY_START = 3;
 
-/** The body indent, shared by the note and the detail pane. */
+/** The body indent, shared by the note and any focused-row block. */
 export const INDENT = " ".repeat(BODY_INDENT);
 
-/** The themed section bar: both section names, the active one accented. */
-export function sectionBar(theme: Theme, width: number, active: PanelSection, counts: string): string {
-	const separator = paint(theme, "faint", " · ");
-	const left = `  ${sectionSegments(active)
-		.map((segment) => paint(theme, segment.color, segment.text))
-		.join(separator)}`;
-	return clip(splitRow(left, counts, width), width);
+/**
+ * The header rule: the screen's name first, the attention it found at the right
+ * edge. The right side is dropped whole on a narrow terminal rather than clipped
+ * into half a word; the tabs below carry the same facts.
+ */
+export function headerLine(theme: Theme, width: number, title: string, right: readonly SummarySegment[]): string {
+	const w = Math.max(1, width);
+	const separator = paint(theme, "faint", SEPARATORS.item);
+	const text = right.map((segment) => paint(theme, segment.color, segment.text)).join(separator);
+	const rightWidth = visibleWidth(text);
+	if (text === "" || rightWidth + title.length + 4 > w) return titleRule(theme, w, title);
+	return `${titleRule(theme, w - rightWidth - 1, title)} ${text}`;
+}
+
+/**
+ * The tab row: every section with how many rows it holds, then any filter chips,
+ * and the scope a change is written to at the right edge. The active tab takes the
+ * accent; the counts stay faint so the names read first.
+ */
+export function tabsLine(
+	theme: Theme,
+	width: number,
+	active: PanelSection,
+	counts: Record<PanelSection, number>,
+	options: { chips?: readonly SummarySegment[]; scope?: string } = {},
+): string {
+	const separator = paint(theme, "faint", SEPARATORS.item);
+	const tabs = (["extensions", "skills", "settings"] as const).map(
+		(section) =>
+			paint(theme, section === active ? "accent" : "faint", sectionLabel(section)) +
+			paint(theme, "faint", ` ${counts[section]}`),
+	);
+	const chips = options.chips ?? [];
+	const left = [
+		`  ${tabs.join(separator)}`,
+		...(chips.length > 0 ? [`  ${chips.map((chip) => paint(theme, chip.color, chip.text)).join(separator)}`] : []),
+	].join("");
+	const right = options.scope === undefined ? "" : paint(theme, "meta", `writes ${options.scope}`);
+	return clip(splitRow(left, right, width), width);
 }
 
 /** One section's counts as whole segments, so a narrow screen drops a count. */
 export function countsLine(theme: Theme, width: number, segments: readonly SummarySegment[]): string {
-	const separator = paint(theme, "faint", " · ");
+	const separator = paint(theme, "faint", SEPARATORS.item);
 	const styled = segments.map((segment) => paint(theme, segment.color, segment.text));
 	return fitCells(styled, Math.max(1, width - 2), separator);
 }
 
-/** One group heading: its label and how many rows sit under it. */
+/** One group heading: its label, and how many rows sit under it. */
 export function groupLine(theme: Theme, width: number, entry: { label: string; count: number }): string {
 	const label = paint(theme, "meta", sanitizeLine(entry.label));
-	const count = paint(theme, "faint", `(${entry.count})`);
-	return clip(`  ${label} ${count}`, width);
+	const count = entry.count > 0 ? paint(theme, "faint", ` (${entry.count})`) : "";
+	return clip(`  ${label}${count}`, width);
 }
 
 /** The key-hint row, or a section's notice that replaces it. */
@@ -74,7 +113,7 @@ export function noticeLine(theme: Theme, width: number, notice: string): string
 	return clip(`${INDENT}${paint(theme, "meta", sanitizeLine(notice))}`, width);
 }
 
-/** The saved-then-reload marker, shared by both detail panes. */
+/** The saved-then-reload marker, shared by every focused-row block. */
 export function savedLine(theme: Theme, width: number, dirty: boolean): string[] {
 	if (!dirty) return [];
 	return [clip(`${INDENT}${paint(theme, "warn", "Saved · reload to apply")}`, width)];
@@ -87,50 +126,18 @@ export function totalRows(source: ViewportRowsSource | undefined): number | unde
 }
 
 /**
- * Detail rows the focused row gets: the fixed pane, or the free height when
- * expanded. Zero when there is no free row for a pane at all, so a short
- * terminal keeps its body; the caller then drops optional rows if needed.
+ * The rows the bottom pane gets in the single-column layout: the fixed pane, or
+ * the free height when expanded. Zero when there is no free row for a pane at all,
+ * so a short terminal keeps its body.
  */
 export function detailRows(expanded: boolean, viewportRows: ViewportRowsSource | undefined): number {
 	const total = totalRows(viewportRows);
 	if (total === undefined) return expanded ? EXPANDED_DETAIL_FALLBACK : DETAIL_ROWS;
-	// One row pays for the blank line the frame puts above the pane.
 	const available = total - FRAME_ROWS - MIN_BODY_ROWS - 1;
 	if (available < 1) return 0;
 	return expanded ? available : Math.min(DETAIL_ROWS, available);
 }
 
-/**
- * Drop optional rows until the frame fits the viewport: the range row first,
- * then the project note, then the blank above the detail pane, then the pane.
- * The header, summary, one body row, and the hint always survive; a terminal
- * shorter than those is left to the host.
- */
-export function fitOptionalLines(options: {
-	viewportRows: ViewportRowsSource | undefined;
-	body: string[];
-	note: string | undefined;
-	range: string | undefined;
-	detail: string[];
-}): { body: string[]; range: string | undefined; detail: string[]; noteShown: boolean; detailBlank: boolean } {
-	const total = totalRows(options.viewportRows);
-	let { body, range, detail } = options;
-	let noteShown = options.note !== undefined && body[0] === options.note;
-	if (total === undefined) return { body, range, detail, noteShown, detailBlank: true };
-	const fits = (blank: boolean): boolean =>
-		FRAME_ROWS + body.length + (range === undefined ? 0 : 1) + detailBlockRows(detail, blank) <= total;
-	if (!fits(true)) range = undefined;
-	if (!fits(true) && noteShown) {
-		body = body.slice(1);
-		noteShown = false;
-	}
-	// The separator goes before the pane does: the focused row's findings are
-	// worth more than the blank above them.
-	const detailBlank = fits(true) || !fits(false);
-	if (!fits(false)) detail = [];
-	return { body, range, detail, noteShown, detailBlank };
-}
-
 /** What {@link panelFrame} draws: the window, the body, and the chrome around it. */
 export interface PanelFrameInput {
 	theme: Theme;
@@ -138,59 +145,89 @@ export interface PanelFrameInput {
 	cursor: ListCursor;
 	width: number;
 	header: string;
-	summary: string;
+	tabs: string;
 	entries: readonly PanelEntry[];
 	note?: string;
+	/** The focused row's block, drawn under the list below the pane breakpoint. */
 	detail: string[];
 	hint: string;
 	/** The line a section shows in place of its body when it has no entries. */
 	emptyLabel?: string;
+	/**
+	 * The tallest section's row count. The body is padded to it (bounded by the
+	 * viewport), so every section draws the same height.
+	 */
+	tallest: number;
+	/** The side pane's rows, in the wide layout only. */
+	side?: (rows: number) => string[];
 	draw: (entry: PanelEntry, index: number) => string | undefined;
 }
 
+/** The frame both sections share, and the state the caller has to remember. */
+export interface PanelFrameResult {
+	lines: string[];
+	/** Whether the project note survived the row budget, for the click mapping. */
+	noteShown: boolean;
+	/** Body rows drawn, so a caller can map a click to a row. */
+	bodyRows: number;
+}
+
 /**
- * The frame both sections share: the cursor window, the visible body rows, the
- * range row, the optional rows that give way on a short terminal, and the
- * chrome around them. Each section supplies its summary, its detail pane, its
- * hint row, and how one entry is drawn.
+ * The frame every section draws: the cursor window, the padded body, the range
+ * row when the list scrolls, the optional rows that give way on a short terminal,
+ * and the chrome around them.
+ *
+ * The height comes from one place. With a side pane the body is the whole free
+ * height, capped by the tallest section; without one the bottom pane is paid for
+ * first and the body gets what is left. Either way `target` is the same for all
+ * three sections at a given terminal size.
  */
-export function panelFrame(input: PanelFrameInput): { lines: string[]; noteShown: boolean } {
-	const { theme, viewportRows, cursor, width, entries, note, detail, hint, draw } = input;
-	cursor.visible = fitRows(
-		viewportRows,
-		entries.length,
-		FRAME_ROWS + detailBlockRows(detail) + (note ? 1 : 0),
-		SCREEN_DEFAULT_ROWS,
-	);
+export function panelFrame(input: PanelFrameInput): PanelFrameResult {
+	const { theme, viewportRows, cursor, width, entries, note, hint } = input;
+	const total = totalRows(viewportRows);
+	const wide = input.side !== undefined;
+
+	// Costs that a short terminal can shed, in the order they go: the bottom pane
+	// first (its facts move nowhere, but the list matters more), then the note.
+	let detail = wide ? [] : input.detail;
+	let noteShown = note !== undefined;
+	const budgetFor = (): number => {
+		if (total === undefined) return Math.max(MIN_BODY_ROWS, input.tallest);
+		return total - FRAME_ROWS - detailBlockRows(wide ? [] : detail) - (noteShown ? 1 : 0);
+	};
+	if (budgetFor() < MIN_BODY_ROWS && !wide) detail = [];
+	if (budgetFor() < MIN_BODY_ROWS && noteShown) noteShown = false;
+
+	const target = Math.max(1, Math.min(budgetFor(), Math.max(1, input.tallest)));
+	const capacity = Math.max(1, target - (noteShown && note !== undefined ? 1 : 0));
+	const scrolling = entries.length > capacity;
+	cursor.visible = Math.max(1, capacity - (scrolling ? 1 : 0));
 	cursor.sync(entries.length);
 	const { start, end } = cursor.window(entries.length);
 
 	const body: string[] = [];
-	if (note) body.push(note);
+	if (note !== undefined && noteShown) body.push(note);
 	if (entries.length === 0 && input.emptyLabel !== undefined) {
 		body.push(...emptyState(theme, width, { label: input.emptyLabel }));
 	}
 	for (let index = start; index < end; index += 1) {
-		const line = draw(entries[index], index);
+		const line = input.draw(entries[index], index);
 		if (line !== undefined) body.push(line);
 	}
-
-	const range = cursor.clipped(entries.length)
-		? formatRange(theme, width, selectableRange(entries, { start, end }))
-		: undefined;
-	const fitted = fitOptionalLines({ viewportRows, body, note, range, detail });
-	return {
-		lines: dockListFrame({
-			theme,
-			width,
-			header: input.header,
-			summary: input.summary,
-			body: fitted.body,
-			range: fitted.range,
-			detail: fitted.detail.length > 0 ? fitted.detail : undefined,
-			detailBlank: fitted.detailBlank,
-			hint,
-		}),
-		noteShown: fitted.noteShown,
-	};
+	if (scrolling) {
+		body.push(formatRange(theme, width, selectableRange(entries, { start, end })));
+	}
+	while (body.length < target) body.push("");
+
+	const side = input.side === undefined ? undefined : input.side(target);
+	const lines = dockListFrame({
+		theme,
+		width,
+		header: input.header,
+		summary: input.tabs,
+		body: side === undefined ? body : composeRows(theme, width, body, side),
+		detail: detail.length > 0 ? detail : undefined,
+		hint,
+	});
+	return { lines, noteShown, bodyRows: target };
 }

package/extensions/bytefly/panel/tui/keys.ts

@@ -0,0 +1,352 @@
+/**
+ * The control center's key table: the binding, the hint row it appears in, and
+ * the help block `?` prints.
+ *
+ * One table, so a help line cannot drift from a binding: the component dispatches
+ * through {@link keyFor}, the hint row is {@link hintsFor}, and the help block is
+ * {@link helpRows}. Movement is not here — `lib/tui/cursor.ts` owns the arrows,
+ * `j`/`k`, PgUp/PgDn and Home/End for every screen in the package — so the help
+ * block names movement in its own row and the table stays the actions this screen
+ * alone defines.
+ *
+ * Value-only: pure functions, the theme passed in.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import type { ScreenHint } from "../../../../lib/tui/chrome.ts";
+import { clip, padTo } from "../../../../lib/tui/columns.ts";
+import { isCloseKey } from "../../../../lib/tui/cursor.ts";
+import { BODY_INDENT } from "../../../../lib/tui/indent.ts";
+import { paint } from "../../../../lib/tui/tokens.ts";
+import type { PanelSection } from "../types.ts";
+import { hintLine, noticeLine } from "./frame.ts";
+import { editHints } from "./settings-view.ts";
+
+/** One action the screen binds. */
+export type PanelKeyId =
+	| "close"
+	| "previousSection"
+	| "nextSection"
+	| "toggle"
+	| "change"
+	| "detail"
+	| "scope"
+	| "filter"
+	| "attention"
+	| "refresh"
+	| "reload"
+	| "reset"
+	| "json"
+	| "inherit"
+	| "help";
+
+/** One binding, its hint label, and what the help block says about it. */
+export interface PanelKey {
+	id: PanelKeyId;
+	/** The keys as the hint row and the help block print them. */
+	label: string;
+	/** The sections that offer it. A key absent from a section is not hinted there. */
+	sections: readonly PanelSection[];
+	/** One plain sentence for the help block. */
+	help: string;
+	/** Whether `data` is this key. */
+	match(data: string): boolean;
+}
+
+/** Every section, and the two resource lists that share a set of keys. */
+const ALL: readonly PanelSection[] = ["extensions", "skills", "settings"];
+const LISTS: readonly PanelSection[] = ["extensions", "skills"];
+
+/** Shift+Tab arrives as this sequence on terminals without the Kitty protocol. */
+const SHIFT_TAB = "\u001b[Z";
+
+/** The screen's keys, in help order. */
+export const PANEL_KEYS: readonly PanelKey[] = [
+	{
+		id: "close",
+		label: "Esc",
+		sections: ALL,
+		help: "Close the screen",
+		match: (data) => isCloseKey(data),
+	},
+	{
+		id: "previousSection",
+		label: "←",
+		sections: ALL,
+		help: "Previous section",
+		match: (data) =>
+			matchesKey(data, Key.left) || data === "h" || matchesKey(data, Key.shift("tab")) || data === SHIFT_TAB,
+	},
+	{
+		id: "nextSection",
+		label: "→",
+		sections: ALL,
+		help: "Next section",
+		match: (data) => matchesKey(data, Key.right) || data === "l" || matchesKey(data, Key.tab),
+	},
+	{
+		id: "toggle",
+		label: "Space",
+		sections: LISTS,
+		help: "Enable or disable, and re-probe when it changes",
+		match: (data) => matchesKey(data, Key.space),
+	},
+	{
+		id: "detail",
+		label: "Enter",
+		sections: LISTS,
+		help: "Show or hide the focused row's findings",
+		match: (data) => matchesKey(data, Key.enter),
+	},
+	{
+		id: "change",
+		label: "Space",
+		sections: ["settings"],
+		help: "Change the focused value",
+		match: (data) => matchesKey(data, Key.space) || matchesKey(data, Key.enter),
+	},
+	{
+		id: "reset",
+		label: "u",
+		sections: ["settings"],
+		help: "Reset the focused value to its default",
+		match: (data) => data === "u",
+	},
+	{
+		id: "json",
+		label: "J",
+		sections: ["settings"],
+		help: "Show the whole `bytefly.json` section the value lives in",
+		match: (data) => data === "J",
+	},
+	{
+		id: "scope",
+		label: "s",
+		sections: ALL,
+		help: "Switch where a change is written: Global or Project",
+		match: (data) => data === "s",
+	},
+	{
+		id: "filter",
+		label: "/",
+		sections: ALL,
+		help: "Filter the rows by text; Esc clears it",
+		match: (data) => matchesKey(data, Key.slash),
+	},
+	{
+		id: "attention",
+		label: "!",
+		sections: ALL,
+		help: "Show only the rows that need attention",
+		match: (data) => matchesKey(data, Key.exclamation),
+	},
+	{
+		id: "refresh",
+		label: "r",
+		sections: ["extensions"],
+		help: "Re-probe every extension's requirements",
+		match: (data) => data === "r",
+	},
+	{
+		id: "inherit",
+		label: "x",
+		sections: LISTS,
+		help: "Drop the Project override, so Global applies again",
+		match: (data) => data === "x",
+	},
+	{
+		id: "reload",
+		label: "R",
+		sections: ALL,
+		help: "Reload now, to apply what you changed",
+		match: (data) => data === "R",
+	},
+	{
+		id: "help",
+		label: "?",
+		sections: ALL,
+		help: "Show every key, in place of the focused row's facts",
+		match: (data) => matchesKey(data, Key.question),
+	},
+];
+
+/** The binding for `id`; a table with no row would be a bug, not a key state. */
+export function keyOf(id: PanelKeyId): PanelKey {
+	const key = PANEL_KEYS.find((entry) => entry.id === id);
+	if (key === undefined) throw new Error(`No panel key "${id}"`);
+	return key;
+}
+
+/** The action `data` asks for in `section`, or `undefined` for anything else. */
+export function keyFor(data: string, section: PanelSection): PanelKeyId | undefined {
+	for (const key of PANEL_KEYS) {
+		if (key.sections.includes(section) && key.match(data)) return key.id;
+	}
+	return undefined;
+}
+
+/** What the hint row needs to know about the screen's state. */
+export interface HintState {
+	/** The focused row's findings are expanded (lists only). */
+	expanded: boolean;
+	/** A probe is in flight, so the refresh key is not offered. */
+	refreshing: boolean;
+	/** Project scope can hold an override, Global cannot (lists only). */
+	projectScope: boolean;
+	/** Something was changed this session, so the reload key applies. */
+	dirty: boolean;
+	/** The help block is open. */
+	help: boolean;
+}
+
+/** One pale, dim hint, or an accented primary one. */
+function hint(text: string, primary = false): ScreenHint {
+	return primary ? { text, color: "accent" } : text;
+}
+
+/**
+ * The hint row for a section, most useful first: whole hints drop from the right
+ * as the width runs out, so the close and section keys survive on a narrow
+ * terminal and `?` is the one that leaves first.
+ */
+export function hintsFor(section: PanelSection, state: HintState): ScreenHint[] {
+	const hints: ScreenHint[] = [
+		hint("Esc close"),
+		hint("←/→ section"),
+		section === "settings" ? hint("Space change", true) : hint("Space toggle", true),
+		...(section === "settings" ? [] : [hint(state.expanded ? "Enter collapse" : "Enter detail", true)]),
+		hint("/ filter"),
+	];
+	if (section === "settings") {
+		hints.push(hint("u reset"), hint(state.help ? "? hide" : "? keys"));
+		return hints;
+	}
+	hints.push(hint(state.help ? "? hide" : "? keys"));
+	if (section === "extensions") hints.push(hint(state.refreshing ? "refreshing…" : "r refresh"));
+	if (state.dirty) hints.push(hint("R reload", true));
+	hints.push(hint("s scope"));
+	if (state.projectScope) hints.push(hint("x inherit"));
+	hints.push(hint("↑/↓ select"));
+	return hints;
+}
+
+/**
+ * The hint row a section shows: an editor's own keys while one is open, else the
+ * transient notice, else the section's hints. The three cases are exclusive, so a
+ * notice never shares the row with a hint that could not work.
+ */
+export function hintRow(options: {
+	theme: Theme;
+	width: number;
+	section: PanelSection;
+	state: HintState;
+	/** A settings row or the filter is being typed into. */
+	editing: boolean;
+	/** The last refusal or failure, shown until the next key. */
+	notice?: string;
+}): string {
+	const { theme, width, section, state, editing, notice } = options;
+	if (editing) return hintLine(theme, width, editHints());
+	if (notice !== undefined) return noticeLine(theme, width, notice);
+	return hintLine(theme, width, hintsFor(section, state));
+}
+
+/**
+ * One help row: the keys it names, and what they do.
+ *
+ * A row naming one binding takes that binding's own sentence, so the two cannot
+ * disagree; a row that explains a verb for this section — `!` narrows settings to
+ * what changed, not to what is broken — states its own.
+ */
+interface HelpRow {
+	/** Table bindings this row documents; empty for a row over shared movement keys. */
+	ids: readonly PanelKeyId[];
+	/** The keys as printed; joined from the bindings unless the row sets its own. */
+	label?: string;
+	/** What the keys do here; the single binding's own sentence when omitted. */
+	help?: string;
+}
+
+/** Rows over the movement keys, which `lib/tui/cursor.ts` owns for every screen. */
+const MOVEMENT: readonly HelpRow[] = [
+	{ ids: [], label: "↑/↓ j/k", help: "Move to the next or previous row" },
+	{ ids: [], label: "g G", help: "Jump to the first or last row" },
+	{ ids: [], label: "[ ]", help: "Jump to the next or previous group" },
+];
+
+/** The help block per section: the table's own rows, plus movement and the close pair. */
+const HELP: Record<PanelSection, readonly HelpRow[]> = {
+	extensions: [
+		{ ids: ["close", "previousSection", "nextSection"], help: "Close, or change section" },
+		...MOVEMENT,
+		{ ids: ["toggle"], help: "Enable or disable the focused extension" },
+		{ ids: ["detail"], help: "Show or hide its findings" },
+		{ ids: ["attention"], help: "Show only the rows that need attention" },
+		{ ids: ["filter"], help: "Filter the rows by text; Esc clears it" },
+		{ ids: ["scope"], help: "Switch where a change is written" },
+		{ ids: ["refresh"], help: "Re-probe every extension's requirements" },
+		{ ids: ["inherit"], help: "Drop the Project override" },
+		{ ids: ["reload"], help: "Reload to apply what you changed" },
+		{ ids: ["help"], help: "Show or hide this key list" },
+	],
+	skills: [
+		{ ids: ["close", "previousSection", "nextSection"], help: "Close, or change section" },
+		...MOVEMENT,
+		{ ids: ["toggle"], help: "Enable or disable the focused skill" },
+		{ ids: ["detail"], help: "Show or hide what its `SKILL.md` declares" },
+		{ ids: ["attention"], help: "Show only the rows that need attention" },
+		{ ids: ["filter"], help: "Filter the rows by text; Esc clears it" },
+		{ ids: ["scope"], help: "Switch where a change is written" },
+		{ ids: ["inherit"], help: "Drop the Project override" },
+		{ ids: ["reload"], help: "Reload to apply what you changed" },
+		{ ids: ["help"], help: "Show or hide this key list" },
+	],
+	settings: [
+		{ ids: ["close", "previousSection", "nextSection"], help: "Close, or change section" },
+		...MOVEMENT,
+		{ ids: ["change"], help: "Change the focused value" },
+		{ ids: ["reset"], help: "Reset it to its default" },
+		{ ids: ["json"], help: "Show the section it lives in" },
+		{ ids: ["attention"], help: "Show only the values you changed" },
+		{ ids: ["filter"], help: "Filter the rows by text; Esc clears it" },
+		{ ids: ["scope"], help: "Switch where a change is written" },
+		{ ids: ["reload"], help: "Reload to apply what you changed" },
+		{ ids: ["help"], help: "Show or hide this key list" },
+	],
+};
+
+/** The bindings a section's help block documents, for the drift test. */
+export function helpKeyIds(section: PanelSection): PanelKeyId[] {
+	return HELP[section].flatMap((row) => [...row.ids]);
+}
+
+/** The keys a help row prints, from the bindings it names. */
+function helpLabel(row: HelpRow): string {
+	if (row.label !== undefined) return row.label;
+	return row.ids.map((id) => keyOf(id).label).join(" ");
+}
+
+/** What a help row says: its own sentence, or the single binding's. */
+function helpText(row: HelpRow): string {
+	if (row.help !== undefined) return row.help;
+	return row.ids.map((id) => keyOf(id).help).join("; ");
+}
+
+/**
+ * The help block for a section: one `keys  action` line per row, the key column
+ * padded to the widest label so the sentences line up. Every binding the section
+ * offers has a row, and every row names a binding the section offers —
+ * `keys.test.ts` holds both directions.
+ */
+export function helpRows(theme: Theme, width: number, section: PanelSection): string[] {
+	const rows = HELP[section].map((row) => ({ label: helpLabel(row), help: helpText(row) }));
+	const column = Math.max(...rows.map((row) => row.label.length)) + 2;
+	const indent = " ".repeat(BODY_INDENT);
+	return rows.map((row) =>
+		clip(
+			`${indent}${paint(theme, "faint", padTo(row.label, column))}${paint(theme, "meta", row.help)}`,
+			Math.max(1, width),
+		),
+	);
+}