magus-cli 7.3.1 → 7.4.1

package/src/ui/components/modals/ModalContainer.tsx

@@ -1,26 +1,52 @@
-import React, { useState } from "react";
-import { useKeyboard } from "../../hooks/useKeyboard.js";
-import { useApp } from "../../state/AppContext.js";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import React, { useRef, useState } from "react";
+import { useKeyLayer, usePasteLayer } from "../../input/KeyRouter.js";
+import { type KeyPress, isScrollKey } from "../../input/key-dispatch.js";
+import { useApp, useModal } from "../../state/AppContext.js";
+import { useDimensions } from "../../state/DimensionsContext.js";
 import { ConfirmModal } from "./ConfirmModal.js";
+import { HelpOverlay, helpOverlaySize } from "./HelpOverlay.js";
 import { InputModal } from "./InputModal.js";
 import { LoadingModal } from "./LoadingModal.js";
 import { MessageModal } from "./MessageModal.js";
 import { SelectModal } from "./SelectModal.js";
 
+const isEnter = (key: KeyPress) =>
+	key.name === "return" || key.name === "enter";
+const isPlain = (key: KeyPress) => !key.ctrl && !key.meta;
+
 /**
- * Container that renders the active modal as an overlay
- * Handles ALL keyboard events when a modal is open to avoid
- * conflicts with multiple useKeyboard hooks in child components
+ * Renders the open modal as an overlay and is the modal KEY LAYER.
+ *
+ * While any modal is open this layer takes every key, so nothing reaches a
+ * search box, the screen, the panel scroll or the global keys underneath — the
+ * Enter that confirms a dialog confirms only the dialog. Ctrl+C still quits: it
+ * is taken above every layer, in src/tui.tsx.
  *
- * Input modal: Enter/Escape handled by OpenTUI <input> onSubmit + ModalContainer escape
- * Select modal: keyboard fully handled here (index tracking + Enter/arrows)
+ * It takes every PASTE for the same reason, and does nothing with it: a search
+ * box on the screen behind still has focus, and without this its query would
+ * grow from a paste aimed at the dialog in front of it. The event itself is not
+ * stopped, so the input modal's focused `<input>` still receives it — the
+ * arrangement the `input` case below already relies on for keys.
+ *
+ * - confirm: y / Enter confirm; n / Esc / q cancel.
+ * - select:  ↑↓ (j/k) move, Enter picks, Esc / q cancel (a no-op for a
+ *            question that must be answered).
+ * - input:   Esc cancels; everything else goes to the focused <input>, which
+ *            OpenTUI delivers after this layer and which submits on Enter.
+ * - message: any key dismisses.
+ * - loading: keys are swallowed until the work finishes.
+ * - help:    ↑↓ / PgUp / PgDn / Ctrl+U / Ctrl+D scroll; Esc or `?` close.
  */
 export function ModalContainer() {
 	const { state } = useApp();
 	const { modal } = state;
+	const { hideModal } = useModal();
+	const dimensions = useDimensions();
 
 	// Track select modal index here (lifted from SelectModal)
 	const [selectIndex, setSelectIndex] = useState(0);
+	const helpScrollRef = useRef<ScrollBoxRenderable | null>(null);
 
 	// Reset select index when modal changes
 	const modalRef = React.useRef(modal);
@@ -31,58 +57,84 @@ export function ModalContainer() {
 		}
 	}
 
-	// Handle keyboard events for modals
-	useKeyboard((key) => {
-		if (!modal) return;
-		if (modal.type === "loading") return;
-
-		// Escape — close any modal
-		if (key.name === "escape") {
-			if (modal.type === "confirm") modal.onCancel();
-			else if (modal.type === "input") modal.onCancel();
-			else if (modal.type === "select") modal.onCancel();
-			else if (modal.type === "message") modal.onDismiss();
+	const handleHelpKey = (key: KeyPress) => {
+		if (
+			key.name === "escape" ||
+			(isPlain(key) && (key.name === "?" || key.sequence === "?"))
+		) {
+			hideModal();
 			return;
 		}
-
-		// 'q' to close — but NOT for input modals (need to type 'q')
-		if (key.name === "q" && modal.type !== "input") {
-			if (modal.type === "confirm") modal.onCancel();
-			else if (modal.type === "select") modal.onCancel();
-			else if (modal.type === "message") modal.onDismiss();
-			return;
+		const scroll = helpScrollRef.current;
+		if (!scroll) return;
+		const page = helpOverlaySize(
+			dimensions.terminalWidth,
+			dimensions.terminalHeight,
+		).listHeight;
+		if (isScrollKey(key)) {
+			const step =
+				key.name === "pageup" || key.name === "pagedown"
+					? Math.max(1, page - 1)
+					: Math.max(1, Math.floor(page / 2));
+			const up = key.name === "pageup" || key.name === "u";
+			scroll.scrollBy(up ? -step : step);
+		} else if (isPlain(key) && (key.name === "up" || key.name === "k")) {
+			scroll.scrollBy(-1);
+		} else if (isPlain(key) && (key.name === "down" || key.name === "j")) {
+			scroll.scrollBy(1);
 		}
+	};
 
-		// Input modal — let OpenTUI <input> handle Enter via onSubmit
-		if (modal.type === "input") {
-			return;
-		}
+	usePasteLayer("modal", modal !== null, () => true);
 
-		// Select modal — handle navigation and selection
-		if (modal.type === "select") {
-			if (key.name === "return" || key.name === "enter") {
-				modal.onSelect(modal.options[selectIndex].value);
-			} else if (key.name === "up" || key.name === "k") {
-				setSelectIndex((prev) => Math.max(0, prev - 1));
-			} else if (key.name === "down" || key.name === "j") {
-				setSelectIndex((prev) => Math.min(modal.options.length - 1, prev + 1));
-			}
-			return;
-		}
+	useKeyLayer("modal", modal !== null, (key) => {
+		if (!modal) return false;
+
+		switch (modal.type) {
+			case "loading":
+				break;
+
+			case "help":
+				handleHelpKey(key);
+				break;
 
-		// Message modal — Enter to dismiss
-		if (modal.type === "message") {
-			if (key.name === "return" || key.name === "enter") {
+			case "message":
 				modal.onDismiss();
-			}
-		}
+				break;
+
+			case "confirm":
+				if (key.name === "y" || isEnter(key)) modal.onConfirm();
+				else if (
+					key.name === "n" ||
+					key.name === "q" ||
+					key.name === "escape"
+				) {
+					modal.onCancel();
+				}
+				break;
 
-		// Confirm modal — Enter to confirm
-		if (modal.type === "confirm") {
-			if (key.name === "return" || key.name === "enter") {
-				modal.onConfirm();
-			}
+			case "input":
+				// Not consumed by anything of ours below, and still delivered to
+				// the focused <input> afterwards: typing and Enter work there.
+				if (key.name === "escape") modal.onCancel();
+				break;
+
+			case "select":
+				if (isEnter(key)) {
+					const option = modal.options[selectIndex];
+					if (option) modal.onSelect(option.value);
+				} else if (key.name === "up" || key.name === "k") {
+					setSelectIndex((prev) => Math.max(0, prev - 1));
+				} else if (key.name === "down" || key.name === "j") {
+					setSelectIndex((prev) =>
+						Math.min(modal.options.length - 1, prev + 1),
+					);
+				} else if (key.name === "escape" || key.name === "q") {
+					modal.onCancel();
+				}
+				break;
 		}
+		return true;
 	});
 
 	if (!modal) {
@@ -92,14 +144,7 @@ export function ModalContainer() {
 	const renderModal = () => {
 		switch (modal.type) {
 			case "confirm":
-				return (
-					<ConfirmModal
-						title={modal.title}
-						message={modal.message}
-						onConfirm={modal.onConfirm}
-						onCancel={modal.onCancel}
-					/>
-				);
+				return <ConfirmModal title={modal.title} message={modal.message} />;
 
 			case "input":
 				return (
@@ -131,13 +176,15 @@ export function ModalContainer() {
 						title={modal.title}
 						message={modal.message}
 						variant={modal.variant}
-						onDismiss={modal.onDismiss}
 					/>
 				);
 
 			case "loading":
 				return <LoadingModal message={modal.message} />;
 
+			case "help":
+				return <HelpOverlay screen={modal.screen} scrollRef={helpScrollRef} />;
+
 			default:
 				return null;
 		}

package/src/ui/components/primitives/ErrorNotice.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { theme } from "../../theme.js";
+
+interface ErrorNoticeProps {
+	/** What could not be done, in words: "Could not read the MCP configuration." */
+	title: string;
+	/**
+	 * The error's own message. Shown verbatim, because for a settings file that
+	 * does not parse it is the message that names the file — a summary here
+	 * would drop the one fact the reader needs to fix it.
+	 */
+	detail: string;
+	/** Optional next step, e.g. "Fix the file, then press r." */
+	hint?: string;
+}
+
+/**
+ * A failure shown in place of content that could not be loaded.
+ *
+ * It exists so a failed read never renders as an empty list: an empty list
+ * says "nothing is configured", which for a settings file that merely failed
+ * to parse is false and invites the user to configure it again.
+ */
+export function ErrorNotice({ title, detail, hint }: ErrorNoticeProps) {
+	return (
+		<box flexDirection="column" paddingLeft={2} paddingRight={2}>
+			<text fg={theme.colors.danger}>{title}</text>
+			<box marginTop={1}>
+				<text fg={theme.colors.muted}>{detail}</text>
+			</box>
+			{hint && (
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>{hint}</text>
+				</box>
+			)}
+		</box>
+	);
+}

package/src/ui/components/primitives/ListCategoryRow.tsx

@@ -1,13 +1,14 @@
 import React from "react";
-import { theme } from "../../theme.js";
-import { SelectableRow } from "./SelectableRow.js";
+import { type BadgeTone, theme } from "../../theme.js";
+import { SelectableRow, rowLead } from "./SelectableRow.js";
 
 interface ListCategoryRowProps {
 	title: string;
 	expanded?: boolean;
 	count?: number;
 	badge?: string;
-	tone?: keyof typeof theme.category;
+	/** What the group is. `neutral` unless its name is a state — see `theme.badge`. */
+	tone?: BadgeTone;
 	selected: boolean;
 	/**
 	 * Whether the row can be opened and closed. Default true, which is what
@@ -23,22 +24,32 @@ export function ListCategoryRow({
 	expanded = false,
 	count,
 	badge,
-	tone = "gray",
+	tone = "neutral",
 	selected,
 	expandable = true,
 }: ListCategoryRowProps) {
-	const colors = theme.category[tone];
+	const colors = theme.badge[tone];
 	const marker = expandable ? (expanded ? "▼ " : "▶ ") : "";
 	const label = `${marker}${title}${count !== undefined ? ` (${count})` : ""}`;
 
+	// Both forms start with the row's lead cell — a blank inside the chip, the
+	// selection mark on the cursor — so the title never moves as it is selected.
 	return (
 		<SelectableRow selected={selected}>
 			{!selected && (
 				<span bg={colors.bg} fg={colors.fg}>
-					<strong> {label} </strong>
+					<strong>
+						{rowLead(false)}
+						{label}{" "}
+					</strong>
 				</span>
 			)}
-			{selected && <strong> {label} </strong>}
+			{selected && (
+				<strong>
+					{rowLead(true)}
+					{label}{" "}
+				</strong>
+			)}
 			{!selected && badge ? <span fg={colors.badgeFg}> {badge}</span> : null}
 		</SelectableRow>
 	);

package/src/ui/components/primitives/MetaText.tsx

@@ -3,7 +3,7 @@ import { theme } from "../../theme.js";
 
 interface MetaTextProps {
 	text: string;
-	tone?: "muted" | "warning" | "success" | "danger";
+	tone?: keyof typeof theme.meta;
 	/**
 	 * True when this sits inside a SELECTED row. Not cosmetic.
 	 *

package/src/ui/components/primitives/ScopeDetail.tsx

@@ -19,49 +19,54 @@ interface ScopeDetailProps {
 }
 
 /**
- * The u/p/l badges used in detail panels.
- * Renders each scope as: [bg=color] key [/bg] ● or ○ Label path
+ * The u/p/l lines used in detail panels:
+ * `[key] ● Label path` — the key chip, installed or not, the scope's name.
+ *
+ * The key chip is neutral: it names a key to press, which is chrome. The scopes
+ * no longer own a hue each (see theme.ts), so the dot carries the state — `●`
+ * in `success` when installed, `○` in `muted` when not — and the words carry
+ * which scope it is.
  */
 export function ScopeDetail({ scopes, paths }: ScopeDetailProps) {
 	const items = [
-		{
-			key: "u",
-			label: "User",
-			color: theme.scopes.user,
-			active: scopes.user,
-			path: paths?.user,
-		},
+		{ key: "u", label: "User", active: scopes.user, path: paths?.user },
 		{
 			key: "p",
 			label: "Project",
-			color: theme.scopes.project,
 			active: scopes.project,
 			path: paths?.project,
 		},
-		{
-			key: "l",
-			label: "Local",
-			color: theme.scopes.local,
-			active: scopes.local,
-			path: paths?.local,
-		},
+		{ key: "l", label: "Local", active: scopes.local, path: paths?.local },
 	].filter((i) => i.path !== undefined || i.active !== undefined);
 
 	return (
 		<box flexDirection="column">
 			{items.map((item) => (
-				<text key={item.key}>
-					<span bg={item.color} fg={theme.hints.fg}>
-						{" "}
-						{item.key}{" "}
-					</span>
-					<span fg={item.active ? item.color : theme.colors.muted}>
-						{item.active ? " ● " : " ○ "}
-					</span>
-					<span fg={item.color}>{item.label}</span>
+				<text key={item.key} fg={theme.colors.text}>
+					<ScopeKeyChip scopeKey={item.key} />
+					<ScopeDot installed={!!item.active} />
+					<span fg={theme.colors.text}>{item.label}</span>
 					{item.path && <span fg={theme.colors.muted}> {item.path}</span>}
 				</text>
 			))}
 		</box>
 	);
 }
+
+/** ` u ` — the key that toggles a scope, as a neutral chip. Inside a `<text>`. */
+export function ScopeKeyChip({ scopeKey }: { scopeKey: string }) {
+	return (
+		<span bg={theme.colors.dim} fg={theme.hints.fg}>
+			{` ${scopeKey} `}
+		</span>
+	);
+}
+
+/** ` ● ` installed, ` ○ ` not. Inside a `<text>`. */
+export function ScopeDot({ installed }: { installed: boolean }) {
+	return (
+		<span fg={installed ? theme.colors.success : theme.colors.muted}>
+			{installed ? " ● " : " ○ "}
+		</span>
+	);
+}

package/src/ui/components/primitives/ScopeSquares.tsx

@@ -1,5 +1,4 @@
 import type React from "react";
-import { scopeOffFill } from "../../theme-mode.js";
 import { theme } from "../../theme.js";
 
 interface ScopeSquaresProps {
@@ -9,22 +8,26 @@ interface ScopeSquaresProps {
 	selected?: boolean;
 }
 
-/** Every segment is a filled block; only the fill colour says lit or unlit. */
-const SEGMENT = "■";
+/** Installed at that scope. */
+export const SCOPE_ON = "■";
+/** Not installed at that scope. */
+export const SCOPE_OFF = "□";
 
 /**
- * Scope bar: three positional segments, user / project / local.
+ * Scope bar: three positional squares, user / project / local.
  *
- * Reads as a segmented indicator — each segment lit in its scope colour, or
- * unlit in a fill that recedes toward the page. Position identifies the scope;
- * the first segment is always user, the second project, the third local.
+ * POSITION names the scope — the first square is always user, the second
+ * project, the third local — and SHAPE says the state: `■` installed, `□` not.
+ * That reads with no colour at all, which the bar never used to: every square
+ * was the same filled block, lit in a scope hue or unlit in a fill near the
+ * page, so on a monochrome terminal, to a colour-blind reader, or on a theme
+ * that drew two hues alike, all three states were one shape.
  *
- * The unlit fill used to be `theme.colors.muted` (#6B7280), the same mid-dark
- * grey as de-emphasised body text. Against a light page that reads as a *dark*
- * block, giving an unlit segment the same visual weight as a lit one — "non
- * installed state is dark as well - confusing". The unlit fill now comes from
- * `scopeOffFill()`, which steps toward the page the resolved mode names; see
- * theme-mode.ts for why that one value cannot be fixed.
+ * Colour now only repeats what the shape says. A filled square wears `success`
+ * (installed is what it means, on every screen); a hollow one wears `muted`,
+ * which a thin outline needs to stay visible — the shape, not a pale fill, is
+ * what makes it recede. On a selected row the selection owns the colour
+ * channel: filled squares take its ink, hollow ones its dim ink.
  */
 export function ScopeSquares({
 	user,
@@ -32,25 +35,17 @@ export function ScopeSquares({
 	local,
 	selected = false,
 }: ScopeSquaresProps) {
-	// On a selected row the background is our own accent, so an unlit segment
-	// recedes toward that block rather than toward the page.
-	const off = selected ? theme.selection.bg : scopeOffFill();
-	const lit = (on: boolean, color: string) =>
-		on ? (selected ? theme.selection.fg : color) : off;
-
-	const segments = [
-		lit(user, theme.scopes.user),
-		lit(project, theme.scopes.project),
-		...(local !== undefined ? [lit(local, theme.scopes.local)] : []),
-	];
+	const on = selected ? theme.selection.fg : theme.colors.success;
+	const off = selected ? theme.selection.dim : theme.colors.muted;
+	const states = [user, project, ...(local !== undefined ? [local] : [])];
 
 	// Fragments of <span> — safe to embed inside a coloured <text> parent.
 	return (
 		<>
-			{segments.map((fg, i) => (
-				// biome-ignore lint/suspicious/noArrayIndexKey: fixed positional segments
-				<span key={i} fg={fg}>
-					{SEGMENT}
+			{states.map((installed, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: fixed positional squares
+				<span key={i} fg={installed ? on : off}>
+					{installed ? SCOPE_ON : SCOPE_OFF}
 				</span>
 			))}
 		</>

package/src/ui/components/primitives/SelectableRow.tsx

@@ -1,8 +1,29 @@
 import type React from "react";
 import { theme } from "../../theme.js";
 
+/**
+ * The glyph a selected row starts with.
+ *
+ * The selection used to be a background fill and nothing else, so it vanished
+ * wherever colour does — a monochrome terminal, a screenshot pasted as text, a
+ * reader who cannot tell the fill from the page. A left-edge bar is the cursor
+ * in shape as well as in colour, and it takes the row's first cell, which every
+ * list row already leaves blank, so no name moves as the cursor passes.
+ */
+export const SELECTED_MARK = "▌";
+
+/** A list row's first cell: the selection mark, or the blank it replaces. */
+export function rowLead(selected: boolean): string {
+	return selected ? SELECTED_MARK : " ";
+}
+
 interface SelectableRowProps {
 	selected: boolean;
+	/**
+	 * Leading cells before the children. The first of them is the lead cell,
+	 * which carries `SELECTED_MARK` on the selected row. At 0 the children own
+	 * their first cell and must draw `rowLead` themselves.
+	 */
 	indent?: number;
 	children: React.ReactNode;
 }
@@ -12,6 +33,8 @@ export function SelectableRow({
 	indent = 0,
 	children,
 }: SelectableRowProps) {
+	const lead =
+		indent > 0 ? `${rowLead(selected)}${" ".repeat(indent - 1)}` : "";
 	return (
 		<text
 			// Unselected: no background, so the row sits on the terminal's own page.
@@ -23,7 +46,7 @@ export function SelectableRow({
 			// reached by omission rather than by a wrong literal.
 			fg={selected ? theme.selection.fg : theme.colors.text}
 		>
-			{" ".repeat(indent)}
+			{lead}
 			{children}
 		</text>
 	);

package/src/ui/components/primitives/index.ts

@@ -1,9 +1,10 @@
-export { SelectableRow } from "./SelectableRow.js";
+export { SELECTED_MARK, SelectableRow, rowLead } from "./SelectableRow.js";
 export { ListCategoryRow } from "./ListCategoryRow.js";
-export { ScopeSquares } from "./ScopeSquares.js";
-export { ScopeDetail } from "./ScopeDetail.js";
+export { SCOPE_OFF, SCOPE_ON, ScopeSquares } from "./ScopeSquares.js";
+export { ScopeDetail, ScopeDot, ScopeKeyChip } from "./ScopeDetail.js";
 export { ActionHints } from "./ActionHints.js";
 export type { Hint } from "./ActionHints.js";
 export { MetaText } from "./MetaText.js";
 export { KeyValueLine } from "./KeyValueLine.js";
 export { DetailSection } from "./DetailSection.js";
+export { ErrorNotice } from "./ErrorNotice.js";

package/src/ui/hooks/useProfileStartupModal.ts

@@ -16,6 +16,7 @@
  */
 
 import { useCallback } from "react";
+import { getManifestPath } from "../../services/manifest.js";
 import {
 	type ProfileChoice,
 	applyProfileChoice,
@@ -26,7 +27,9 @@ import {
 	defaultOptionIndex,
 	describeNeed,
 	parseProfileChoice,
+	unparseableNeed,
 } from "../../services/profile-startup.js";
+import { SettingsParseError } from "../../services/settings-file.js";
 import type { DisplacedArtifact } from "../../services/symlink-manager.js";
 import { useApp, useNavigation } from "../state/AppContext.js";
 import type { ModalState } from "../state/types.js";
@@ -207,6 +210,15 @@ export function useProfileStartupModal(onQuit: () => void) {
 						});
 					})
 					.catch((error: unknown) => {
+						// The manifest stopped parsing between launch and this answer —
+						// someone is mid-edit — and saving refused to write over it.
+						// Asking the same question again would offer that save again, so
+						// the question becomes the one for a file that does not parse.
+						const next =
+							error instanceof SettingsParseError &&
+							error.path === getManifestPath(projectPath)
+								? unparseableNeed(error)
+								: need;
 						dispatch({
 							type: "SHOW_MODAL",
 							modal: {
@@ -226,17 +238,17 @@ export function useProfileStartupModal(onQuit: () => void) {
 								// dismissing returns to the question — including when the
 								// attempt was automatic, which is the one case where there
 								// was no question on screen yet.
-								onDismiss: ask,
+								onDismiss: () => ask(next),
 							},
 						});
 					});
 			};
 
-			function ask(): void {
+			function ask(current: ProfileStartupNeed = need): void {
 				dispatch({
 					type: "SHOW_MODAL",
 					modal: buildProfileStartupModal({
-						need,
+						need: current,
 						onChoose: (choice) => apply(choice, false),
 						onQuit,
 					}),