magus-cli 7.3.1 → 7.4.0

package/src/ui/keymap.ts

@@ -0,0 +1,898 @@
+/**
+ * Every key magus binds, in one place.
+ *
+ * The footer hints, the help overlay AND the key handling all read this file.
+ * They used to be three hand-kept copies: the help text said `u` updated a
+ * plugin while the Plugins handler bound `u` to a scope toggle, the help
+ * covered four tabs of ten, and footers advertised keys the screen had renamed.
+ *
+ * A binding's `keys` are what the user sees and also what is matched: `"U"` is
+ * Shift+U, `"u/p/l"` is three keys in one hint, `"^U"` is Ctrl+U, and `"Enter"`,
+ * `"Space"`, `"Esc"`, `"Tab"`, `"⇧Tab"`, `"PgUp"`, `"PgDn"` and the arrows are
+ * named keys. A screen hands `useScreenKeys` one handler per binding id, typed
+ * as `ScreenHandlers<S>`, so a binding with no handler does not compile — and a
+ * key with no binding cannot be handled, because the handler is only ever
+ * reached through a binding.
+ *
+ * The rules the tests hold this file to are also checked when it loads (see
+ * `assertKeymap` at the bottom): within a screen no key is claimed twice, and no
+ * screen claims a digit, `q`, `?` or a scroll key.
+ */
+
+import { TABS } from "./components/TabBar.js";
+import type { KeyPress } from "./input/key-dispatch.js";
+import type { Screen } from "./state/types.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface KeyBinding {
+	/** Unique within its screen (or within the global / scroll lists). */
+	id: string;
+	/**
+	 * As displayed: "u", "U", "Enter", "Space", "/", "?", "^U". An entry may
+	 * group alternatives with a slash — "u/p/l", "PgUp/PgDn" — which reads as one
+	 * hint and matches each key. The lone "/" is the slash key itself.
+	 */
+	keys: readonly string[];
+	/** Short footer label, e.g. "update". */
+	label: string;
+	/** Help text: one line, what the key does and where. */
+	description: string;
+	/**
+	 * Higher is kept first when the footer is narrow. 0 (`HELP_ONLY`) keeps the
+	 * binding out of footers altogether — it is listed in help only.
+	 */
+	priority: number;
+}
+
+export interface LegendEntry {
+	symbol: string;
+	meaning: string;
+}
+
+export interface HelpSection {
+	title: string;
+	/** Set on a screen's own section; global, scroll and search-box sections have none. */
+	screen?: Screen;
+	bindings: readonly KeyBinding[];
+	/** What the symbols on this screen mean. */
+	legend?: readonly LegendEntry[];
+}
+
+/**
+ * What a binding does when its key arrives. Return `false` to decline — the key
+ * then carries on to the layers below, as if the binding were not there (Esc
+ * clears a committed filter, and only when there is one; otherwise it goes on to
+ * the global "back"). Anything else, including nothing, consumes the key.
+ */
+export type KeyHandler = (key: KeyPress) => unknown;
+
+/** A binding whose id is known to the type system. */
+type Bound<Id extends string> = KeyBinding & { readonly id: Id };
+
+function bind<const Id extends string>(
+	id: Id,
+	keys: readonly string[],
+	label: string,
+	description: string,
+	priority: number,
+): Bound<Id> {
+	return { id, keys, label, description, priority };
+}
+
+/** Listed in help, never in a footer. */
+const HELP_ONLY = 0;
+
+// ─── Shared bindings ────────────────────────────────────────────────────────
+
+const MOVE = bind(
+	"move",
+	["↑", "↓", "j", "k"],
+	"move",
+	"Move the selection",
+	20,
+);
+
+/** The direction a `move` key asks for: -1 for ↑ or k, +1 for ↓ or j. */
+export function moveDirection(key: KeyPress): -1 | 1 {
+	return key.name === "up" || key.name === "k" ? -1 : 1;
+}
+
+const CLEAR_FILTER = bind(
+	"clear-filter",
+	["Esc"],
+	"clear filter",
+	"Clear a filter kept with Enter (only while one is set)",
+	95,
+);
+
+function search(description: string) {
+	return bind("search", ["/"], "search", description, 75);
+}
+
+function refresh(description: string) {
+	return bind("refresh", ["r"], "refresh", description, 40);
+}
+
+// ─── Per screen ─────────────────────────────────────────────────────────────
+
+const PLUGINS = [
+	bind(
+		"scope",
+		["u/p/l"],
+		"toggle",
+		"Install or uninstall at user (u), project (p) or local (l) scope",
+		90,
+	),
+	bind(
+		"update",
+		["U"],
+		"update",
+		"Update the plugin, or repair it when stale or broken",
+		85,
+	),
+	bind(
+		"update-all",
+		["a"],
+		"all",
+		"Update or repair every plugin that needs it",
+		80,
+	),
+	bind(
+		"open",
+		["Enter"],
+		"scopes",
+		"Pick a scope to toggle; on a marketplace, expand or collapse it",
+		55,
+	),
+	bind(
+		"expand",
+		["←", "→", "<", ">"],
+		"expand",
+		"Expand or collapse a marketplace, or a plugin's contents",
+		25,
+	),
+	bind(
+		"save-profile",
+		["s"],
+		"profile",
+		"Save the enabled plugins as a profile",
+		60,
+	),
+	bind(
+		"remove",
+		["d"],
+		"remove",
+		"Remove a deprecated plugin from every scope",
+		30,
+	),
+	bind("add-marketplace", ["n"], "add marketplace", "Add a marketplace", 30),
+	bind("team-help", ["t"], "team", "How to share marketplaces with a team", 10),
+	refresh("Refresh the local marketplace caches"),
+	search("Filter plugins by name"),
+	CLEAR_FILTER,
+	MOVE,
+] as const;
+
+const SKILLS = [
+	bind(
+		"scope",
+		["u/p"],
+		"toggle",
+		"Install or remove at user (u) or project (p) scope; on a set, install it all",
+		90,
+	),
+	bind(
+		"open",
+		["Enter"],
+		"install",
+		"Install the skill in this project; on a set, expand or collapse it",
+		60,
+	),
+	bind("browse", ["o"], "open", "Open the skill or set on GitHub", 50),
+	refresh("Reload the skills catalog"),
+	search("Filter skills; two or more characters also search the registry"),
+	CLEAR_FILTER,
+	MOVE,
+] as const;
+
+const STYLES = [
+	bind(
+		"toggle",
+		["Space"],
+		"toggle",
+		"Tick or untick the style; on a registry entry, fetch it",
+		90,
+	),
+	bind("apply", ["a"], "apply", "Apply the ticked styles to this project", 88),
+	bind(
+		"fill",
+		["t"],
+		"fill",
+		"Fill a template from the codebase (runs for minutes)",
+		62,
+	),
+	bind("clear", ["c"], "clear", "Turn the active output style off", 60),
+	bind(
+		"edit",
+		["Enter", "e"],
+		"edit",
+		"Open the style's file in its default app",
+		55,
+	),
+	bind(
+		"fetch",
+		["f"],
+		"fetch",
+		"Fetch a community style, or accept its downloaded update",
+		54,
+	),
+	bind(
+		"new",
+		["n"],
+		"new",
+		"Create a team style in .claude/output-styles/",
+		50,
+	),
+	bind(
+		"check",
+		["u"],
+		"check",
+		"Check the selected community style for an update",
+		45,
+	),
+	bind(
+		"check-all",
+		["U"],
+		"check all",
+		"Check every fetched community style for updates",
+		35,
+	),
+	bind("reset", ["x"], "reset", "Reset the ticks to what is live", 30),
+	refresh("Re-read the styles"),
+	search("Filter styles"),
+	CLEAR_FILTER,
+	MOVE,
+] as const;
+
+const MODELS = [
+	bind(
+		"apply",
+		["Enter", "a"],
+		"apply",
+		"Route this project through the selected preset",
+		90,
+	),
+	bind("off", ["c"], "off", "Turn model tiers off", 70),
+	bind("reload", ["r"], "reload", "Re-read the model routing", 40),
+	search("Filter presets"),
+	CLEAR_FILTER,
+	MOVE,
+] as const;
+
+const MCP = [
+	bind(
+		"toggle",
+		["Enter"],
+		"add/remove",
+		"Add the server to this project, or remove it",
+		90,
+	),
+	search("Search the MCP registry"),
+	bind("registry", ["r"], "registry", "Browse the MCP registry", 60),
+	MOVE,
+] as const;
+
+const MCP_REGISTRY = [
+	bind("install", ["Enter"], "install", "Add the server to this project", 90),
+	search("Search the registry; the list reloads as you type"),
+	bind("local", ["l"], "local", "Back to this project's MCP servers", 50),
+	bind("reload", ["R"], "reload", "Reload the results", 40),
+	CLEAR_FILTER,
+	MOVE,
+] as const;
+
+const SETTINGS = [
+	bind(
+		"user",
+		["u"],
+		"user",
+		"Change the setting at user scope (~/.claude/settings.json)",
+		90,
+	),
+	bind(
+		"project",
+		["Enter", "p"],
+		"project",
+		"Change the setting at project scope (.claude/settings.json)",
+		88,
+	),
+	MOVE,
+] as const;
+
+const CLI_TOOLS = [
+	bind(
+		"install",
+		["Enter"],
+		"install",
+		"Install, update or reinstall the selected tool",
+		90,
+	),
+	bind(
+		"update-all",
+		["a"],
+		"update all",
+		"Update every tool known to be behind",
+		80,
+	),
+	bind(
+		"conflict",
+		["c"],
+		"fix conflict",
+		"Keep one install of a tool installed more than one way",
+		60,
+	),
+	refresh("Check every tool again"),
+	MOVE,
+] as const;
+
+const PROFILES = [
+	bind(
+		"apply",
+		["Enter", "a"],
+		"apply",
+		"Apply the selected profile to this project",
+		90,
+	),
+	bind("rename", ["r"], "rename", "Rename a saved profile", 60),
+	bind("delete", ["d"], "delete", "Delete a saved profile", 55),
+	bind("copy", ["c"], "copy", "Copy a saved profile to the clipboard", 50),
+	bind("import", ["i"], "import", "Import a profile from the clipboard", 45),
+	MOVE,
+] as const;
+
+const GITIGNORE = [
+	bind("fix", ["f"], "fix", "Fix the selected row", 90),
+	bind("fix-all", ["F"], "fix all", "Fix every row that needs it", 85),
+	bind("edit", ["e"], "edit", "Open .claude/gitignore.json in $EDITOR", 55),
+	bind(
+		"template",
+		["t"],
+		"template",
+		"Merge a built-in template into .claude/gitignore.json",
+		50,
+	),
+	bind("reload", ["r"], "reload", "Re-read the git state", 40),
+	MOVE,
+] as const;
+
+const ALIAS = [
+	bind(
+		"toggle",
+		["Space", "Enter"],
+		"toggle",
+		"Turn the flag on or off; in the flag editor, the row",
+		90,
+	),
+	bind("write", ["w"], "write", "Write the alias to your shell's rc file", 85),
+	bind("edit", ["e"], "edit", "Edit the flag's value", 80),
+	bind("reset", ["r"], "reset", "Reset the row to its default", 50),
+	bind("add", ["a"], "add", "Flag editor: add a value", 80),
+	bind("delete", ["d"], "delete", "Flag editor: remove the selected value", 70),
+	bind("back", ["h", "Esc"], "back", "Flag editor: back to the flag list", 75),
+	MOVE,
+] as const;
+
+const SCREEN_KEYMAP = {
+	plugins: PLUGINS,
+	mcp: MCP,
+	"mcp-registry": MCP_REGISTRY,
+	settings: SETTINGS,
+	"cli-tools": CLI_TOOLS,
+	profiles: PROFILES,
+	skills: SKILLS,
+	styles: STYLES,
+	gitignore: GITIGNORE,
+	alias: ALIAS,
+	models: MODELS,
+} as const satisfies Record<Screen, readonly KeyBinding[]>;
+
+export const SCREEN_BINDINGS: Readonly<Record<Screen, readonly KeyBinding[]>> =
+	SCREEN_KEYMAP;
+
+/** The binding ids one screen declares. */
+export type BindingId<S extends Screen> =
+	(typeof SCREEN_KEYMAP)[S][number]["id"];
+
+/** One handler per binding of screen `S` — none missing, none extra. */
+export type ScreenHandlers<S extends Screen> = Record<BindingId<S>, KeyHandler>;
+
+// ─── Global and scroll ──────────────────────────────────────────────────────
+
+const HELP = bind("help", ["?"], "help", "Show every key (this list)", 100);
+
+const FIXED_GLOBAL = [
+	HELP,
+	bind(
+		"quit",
+		["q"],
+		"quit",
+		"Quit magus (Ctrl+C quits from anywhere, even a dialog)",
+		30,
+	),
+	bind(
+		"cycle-tab",
+		["Tab", "⇧Tab"],
+		"tabs",
+		"Next tab; Shift+Tab goes to the previous one",
+		15,
+	),
+	bind(
+		"back",
+		["Esc"],
+		"back",
+		"To Plugins (from the MCP registry, to MCP); on Plugins, quit",
+		10,
+	),
+] as const;
+
+/** One help entry per tab, keyed from TABS so the digits are never retyped. */
+const TAB_BINDINGS = TABS.map((tab) =>
+	bind(
+		`tab-${tab.screen}`,
+		[tab.key],
+		tab.label,
+		`Go to ${tab.label}`,
+		HELP_ONLY,
+	),
+);
+
+const TAB_SCREEN_BY_BINDING = new Map<string, Screen>(
+	TABS.map((tab) => [`tab-${tab.screen}`, tab.screen]),
+);
+
+export const GLOBAL_BINDINGS: readonly KeyBinding[] = [
+	...FIXED_GLOBAL,
+	...TAB_BINDINGS,
+];
+
+/**
+ * The global handlers: one per fixed binding, plus `tab`, which every digit
+ * binding calls with its screen.
+ */
+export type GlobalHandlers = Record<
+	(typeof FIXED_GLOBAL)[number]["id"],
+	KeyHandler
+> & { tab: (screen: Screen) => void };
+
+const SCROLL = [
+	bind(
+		"scroll-half",
+		["^U/^D"],
+		"scroll",
+		"Scroll the right-hand panel half a page up / down",
+		70,
+	),
+	bind(
+		"scroll-page",
+		["PgUp/PgDn"],
+		"page",
+		"Scroll the right-hand panel a page up / down",
+		15,
+	),
+] as const;
+
+export const SCROLL_BINDINGS: readonly KeyBinding[] = SCROLL;
+
+export type ScrollHandlers = Record<(typeof SCROLL)[number]["id"], KeyHandler>;
+
+/**
+ * What a focused search box does with keys. Not matched like the lists above —
+ * the input layer decides by `inputLayerConsumes` — but listed so its footer
+ * and its help section come from the same file as everything else.
+ */
+export const INPUT_BINDINGS: readonly KeyBinding[] = [
+	bind(
+		"type",
+		["type"],
+		"filter",
+		"Typed text goes into the box, digits, q and ? included",
+		90,
+	),
+	bind("done", ["Enter"], "done", "Keep the filter and leave the box", 85),
+	bind(
+		"clear",
+		["Esc"],
+		"clear",
+		"Clear the text; on an empty box, leave it",
+		80,
+	),
+	bind(
+		"move",
+		["↑", "↓"],
+		"move",
+		"Move the selection without leaving the box",
+		60,
+	),
+	bind("erase", ["Backspace"], "erase", "Delete the last character", HELP_ONLY),
+];
+
+// ─── Matching ───────────────────────────────────────────────────────────────
+
+type KeyMatcher = (key: KeyPress) => boolean;
+
+const plain = (key: KeyPress) => !key.ctrl && !key.meta;
+
+const NAMED_KEYS: Readonly<Record<string, KeyMatcher>> = {
+	Enter: (k) => plain(k) && (k.name === "return" || k.name === "enter"),
+	Space: (k) => plain(k) && k.name === "space",
+	Esc: (k) => plain(k) && k.name === "escape",
+	Tab: (k) => plain(k) && k.name === "tab" && !k.shift,
+	"⇧Tab": (k) => plain(k) && k.name === "tab" && k.shift,
+	PgUp: (k) => plain(k) && k.name === "pageup",
+	PgDn: (k) => plain(k) && k.name === "pagedown",
+	Backspace: (k) => plain(k) && k.name === "backspace",
+	"↑": (k) => plain(k) && k.name === "up",
+	"↓": (k) => plain(k) && k.name === "down",
+	"←": (k) => plain(k) && k.name === "left",
+	"→": (k) => plain(k) && k.name === "right",
+};
+
+/** The individual keys one displayed entry stands for: "u/p/l" → u, p, l. */
+function tokensOf(entry: string): string[] {
+	return entry === "/" ? ["/"] : entry.split("/");
+}
+
+function parseToken(token: string): KeyMatcher {
+	const named = NAMED_KEYS[token];
+	if (named) return named;
+
+	const ctrl = /^\^([A-Z])$/.exec(token);
+	if (ctrl) {
+		const name = (ctrl[1] as string).toLowerCase();
+		return (k) => k.ctrl && !k.meta && k.name === name;
+	}
+
+	if ([...token].length === 1) {
+		// Letters arrive lowercase with `shift` separate, so "U" is Shift+u and
+		// "u" must NOT also fire on Shift+u.
+		if (/^[a-z]$/.test(token)) {
+			return (k) => plain(k) && k.name === token && !k.shift;
+		}
+		if (/^[A-Z]$/.test(token)) {
+			const name = token.toLowerCase();
+			return (k) => plain(k) && k.name === name && k.shift;
+		}
+		// Digits and punctuation: shift is how some of them are typed at all.
+		return (k) => plain(k) && (k.name === token || k.sequence === token);
+	}
+
+	throw new Error(`keymap: "${token}" is not a key this keymap can match`);
+}
+
+const MATCHERS = new WeakMap<KeyBinding, KeyMatcher[]>();
+
+function matchersOf(binding: KeyBinding): KeyMatcher[] {
+	let matchers = MATCHERS.get(binding);
+	if (!matchers) {
+		matchers = binding.keys.flatMap(tokensOf).map(parseToken);
+		MATCHERS.set(binding, matchers);
+	}
+	return matchers;
+}
+
+/** The first binding in `bindings` whose keys include `key`. */
+export function matchBinding(
+	bindings: readonly KeyBinding[],
+	key: KeyPress,
+): KeyBinding | undefined {
+	return bindings.find((binding) =>
+		matchersOf(binding).some((matches) => matches(key)),
+	);
+}
+
+/**
+ * Run the handler of the binding `key` belongs to. True when a binding matched
+ * and its handler did not decline.
+ */
+export function runBindings(
+	bindings: readonly KeyBinding[],
+	handlers: Readonly<Record<string, KeyHandler>>,
+	key: KeyPress,
+): boolean {
+	const binding = matchBinding(bindings, key);
+	if (!binding) return false;
+	const handler = handlers[binding.id];
+	if (!handler) return false;
+	return handler(key) !== false;
+}
+
+/** The global layer's version of `runBindings`: digits go to `handlers.tab`. */
+export function runGlobalBindings(
+	handlers: GlobalHandlers,
+	key: KeyPress,
+): boolean {
+	const binding = matchBinding(GLOBAL_BINDINGS, key);
+	if (!binding) return false;
+	const screen = TAB_SCREEN_BY_BINDING.get(binding.id);
+	if (screen) {
+		handlers.tab(screen);
+		return true;
+	}
+	const handler = (handlers as unknown as Record<string, KeyHandler>)[
+		binding.id
+	];
+	return handler ? handler(key) !== false : false;
+}
+
+// ─── Tabs ───────────────────────────────────────────────────────────────────
+
+/** The digit that opens `screen`, from TABS; null for the MCP registry. */
+export function tabKey(screen: Screen): string | null {
+	return TABS.find((tab) => tab.screen === screen)?.key ?? null;
+}
+
+/** Every screen, in tab order, with the MCP registry after MCP. */
+const ALL_SCREENS: readonly Screen[] = TABS.flatMap((tab): Screen[] =>
+	tab.screen === "mcp" ? ["mcp", "mcp-registry"] : [tab.screen],
+);
+
+function screenTitle(screen: Screen): string {
+	if (screen === "mcp-registry") return "MCP registry";
+	const tab = TABS.find((t) => t.screen === screen);
+	return tab ? `${tab.key} ${tab.label}` : screen;
+}
+
+// ─── Footer ─────────────────────────────────────────────────────────────────
+
+/** The space between two footer hints. */
+export const FOOTER_GAP = "  ";
+
+/** Terminal cells a string takes. Every glyph this keymap uses is one cell. */
+function cells(text: string): number {
+	return [...text].length;
+}
+
+/**
+ * A key group as one chip's text.
+ *
+ * Single-character keys butt together, because `↑↓` is how an arrow pair is
+ * written everywhere. Anything longer needs a gap, or the names run into each
+ * other and read as one key that does not exist — MEASURED on screen:
+ * `["Enter", "a"]` rendered as `Entera`. A space rather than a slash, because
+ * an entry such as "u/p/l" or "PgUp/PgDn" already contains one.
+ */
+export function joinKeys(keys: readonly string[]): string {
+	return keys.every((k) => cells(k) === 1) ? keys.join("") : keys.join(" ");
+}
+
+/**
+ * Cells one hint takes: the key chip and the label chip, each padded by a space
+ * on both sides — exactly what `FooterHints` draws.
+ */
+function hintWidth(hint: Pick<KeyBinding, "keys" | "label">): number {
+	return cells(joinKeys(hint.keys)) + 2 + cells(hint.label) + 2;
+}
+
+/** Cells the footer row needs for `hints`, gaps included. */
+export function footerWidth(
+	hints: readonly Pick<KeyBinding, "keys" | "label">[],
+): number {
+	if (hints.length === 0) return 0;
+	const chips = hints.reduce((sum, hint) => sum + hintWidth(hint), 0);
+	return chips + FOOTER_GAP.length * (hints.length - 1);
+}
+
+export interface FooterOptions<S extends Screen = Screen> {
+	/**
+	 * Who owns the keys right now.
+	 * - "screen" (default): the screen's bindings, then scroll and global keys.
+	 * - "input": a focused search box. `?`, digits and `q` are typed, so no
+	 *   global hint is shown — advertising one would be a lie.
+	 * - "none": the screen failed to draw; only scroll and global keys still work.
+	 */
+	owner?: "screen" | "input" | "none";
+	/**
+	 * Binding ids of screen `S` not worth advertising on the current row. They
+	 * still work, and help still lists them. Typed per screen, so a misspelt id
+	 * does not compile rather than silently hiding nothing.
+	 */
+	hide?: readonly BindingId<S>[];
+	/**
+	 * What a binding does on the current row, when that differs by row — Enter
+	 * on CLI Tools is "install", "update" or "reinstall". Replaces the footer
+	 * label only; help keeps the binding's own description, which covers every
+	 * case. Typed per screen, like `hide`.
+	 */
+	labels?: Readonly<Partial<Record<BindingId<S>, string>>>;
+}
+
+/**
+ * The hints that fit a footer `width` cells wide.
+ *
+ * `? help` is pinned whenever it fits. The rest are taken in descending
+ * priority and the first one that does not fit ends the list, so a narrower
+ * footer is always a subset of a wider one and never keeps a lower-priority
+ * hint while dropping a higher one. They are shown in declaration order —
+ * screen, scroll, global — with `? help` last.
+ */
+export function footerHints(
+	screen: Screen,
+	width: number,
+	options: FooterOptions = {},
+): KeyBinding[] {
+	const owner = options.owner ?? "screen";
+	const hidden = new Set<string>(options.hide ?? []);
+	const labels: Readonly<Record<string, string | undefined>> =
+		options.labels ?? {};
+
+	const own =
+		owner === "screen"
+			? SCREEN_BINDINGS[screen]
+					.filter((b) => !hidden.has(b.id))
+					// Relabelled BEFORE fitting, so the width budget measures the
+					// words actually drawn.
+					.map((b) => {
+						const label = labels[b.id];
+						return label ? { ...b, label } : b;
+					})
+			: owner === "input"
+				? INPUT_BINDINGS
+				: [];
+	const global =
+		owner === "input" ? [] : GLOBAL_BINDINGS.filter((b) => b !== HELP);
+	const pool = [...own, ...SCROLL_BINDINGS, ...global].filter(
+		(b) => b.priority > HELP_ONLY,
+	);
+
+	const pinned: KeyBinding[] = owner === "input" ? [] : [HELP];
+	if (footerWidth(pinned) > width) return [];
+
+	const kept = new Set<KeyBinding>(pinned);
+	// A stable sort keeps declaration order among equal priorities.
+	for (const binding of [...pool].sort((a, b) => b.priority - a.priority)) {
+		if (footerWidth([...kept, binding]) > width) break;
+		kept.add(binding);
+	}
+	return [...pool.filter((b) => kept.has(b)), ...pinned];
+}
+
+// ─── Help ───────────────────────────────────────────────────────────────────
+
+/**
+ * What the symbols on each screen mean — every glyph a row draws, in the words
+ * a reader needs, so a state never depends on telling two colours apart.
+ * `■`/`□` are `SCOPE_ON`/`SCOPE_OFF` (ScopeSquares), `▌` is `SELECTED_MARK`
+ * (SelectableRow), `[–]` the Styles template glyph — each drawn exactly as
+ * written here.
+ */
+const LEGENDS: Partial<Record<Screen, readonly LegendEntry[]>> = {
+	plugins: [
+		{
+			symbol: "■",
+			meaning: "installed at that scope; the squares are user, project, local",
+		},
+		{ symbol: "□", meaning: "not installed at that scope" },
+		{ symbol: "✗", meaning: "listed by no marketplace magus read" },
+		{ symbol: "●", meaning: "added / installed" },
+		{ symbol: "○", meaning: "not added / not installed" },
+		{ symbol: "★", meaning: "an official marketplace" },
+		{ symbol: "▌", meaning: "the selected row" },
+	],
+	skills: [
+		{
+			symbol: "■",
+			meaning: "installed at that scope; the squares are user, project",
+		},
+		{ symbol: "□", meaning: "not installed at that scope" },
+		{ symbol: "★", meaning: "GitHub stars of a repo about skills" },
+		{
+			symbol: "☆",
+			meaning: "stars of a large mixed repo; they say little about the skill",
+		},
+		{ symbol: "●", meaning: "installed at that scope" },
+		{ symbol: "○", meaning: "not installed at that scope" },
+	],
+	styles: [
+		{ symbol: "[x]", meaning: "ticked and live" },
+		{ symbol: "[+]", meaning: "ticked; a to apply" },
+		{ symbol: "[~]", meaning: "live but unticked; apply removes it" },
+		{ symbol: "[ ]", meaning: "not ticked" },
+		{
+			symbol: "[–]",
+			meaning: "a template; fill it (t) before it can be ticked",
+		},
+		{
+			symbol: "[↓]",
+			meaning: "in the registry, not fetched yet; f fetches it",
+		},
+	],
+	mcp: [
+		{ symbol: "⚙", meaning: "needs configuration before it runs" },
+		{ symbol: "●", meaning: "installed" },
+		{ symbol: "○", meaning: "not installed" },
+		{ symbol: "⬢", meaning: "an MCP server" },
+	],
+	settings: [
+		{ symbol: "★", meaning: "recommended settings" },
+		{ symbol: "●", meaning: "set in a settings file" },
+		{ symbol: "○", meaning: "not set; the default applies" },
+	],
+	"cli-tools": [
+		{ symbol: "●", meaning: "installed and current" },
+		{ symbol: "○", meaning: "not installed" },
+		{ symbol: "*", meaning: "an update is available" },
+		{
+			symbol: "?",
+			meaning: "installed; magus cannot tell whether it is current",
+		},
+		{ symbol: "!", meaning: "installed more than one way; c fixes it" },
+	],
+};
+
+/**
+ * The help overlay's contents: `current` first, then every other screen in tab
+ * order, then the search box, the global keys and the scroll keys.
+ */
+export function helpSections(current: Screen): HelpSection[] {
+	const screens = [current, ...ALL_SCREENS.filter((s) => s !== current)];
+	return [
+		...screens.map((screen): HelpSection => {
+			const legend = LEGENDS[screen];
+			return {
+				title: screenTitle(screen),
+				screen,
+				bindings: SCREEN_BINDINGS[screen],
+				...(legend ? { legend } : {}),
+			};
+		}),
+		{ title: "In a search box", bindings: INPUT_BINDINGS },
+		{ title: "Everywhere", bindings: GLOBAL_BINDINGS },
+		{ title: "Scrolling the right-hand panel", bindings: SCROLL_BINDINGS },
+	];
+}
+
+// ─── Load-time checks ───────────────────────────────────────────────────────
+
+/**
+ * Refuse a keymap that breaks its own rules. Runs once, when the module loads,
+ * so a bad edit fails the first test or launch rather than a keypress.
+ */
+function assertKeymap(): void {
+	const scrollKeys = new Set(
+		SCROLL_BINDINGS.flatMap((b) => b.keys.flatMap(tokensOf)),
+	);
+	for (const binding of [...GLOBAL_BINDINGS, ...SCROLL_BINDINGS]) {
+		matchersOf(binding);
+	}
+	for (const screen of ALL_SCREENS) {
+		const seen = new Map<string, string>();
+		for (const binding of SCREEN_BINDINGS[screen]) {
+			matchersOf(binding);
+			for (const token of binding.keys.flatMap(tokensOf)) {
+				const owner = seen.get(token);
+				if (owner) {
+					throw new Error(
+						`keymap: ${screen} binds "${token}" twice (${owner}, ${binding.id})`,
+					);
+				}
+				seen.set(token, binding.id);
+				if (/^[0-9]$/.test(token) || token === "q" || token === "?") {
+					throw new Error(
+						`keymap: ${screen}.${binding.id} claims "${token}", a global key`,
+					);
+				}
+				if (scrollKeys.has(token)) {
+					throw new Error(
+						`keymap: ${screen}.${binding.id} claims "${token}", a scroll key`,
+					);
+				}
+			}
+		}
+	}
+	if (ALL_SCREENS.length !== Object.keys(SCREEN_BINDINGS).length) {
+		throw new Error("keymap: a screen has bindings but no place in TABS");
+	}
+}
+
+assertKeymap();