magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/screens/AliasScreen.tsx

@@ -0,0 +1,1558 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+	ALIAS_FLAGS,
+	type AliasFlag,
+	FLAG_GROUPS,
+} from "../../data/alias-flags.js";
+import { loadAliasName, saveAliasName } from "../../services/alias-settings.js";
+import {
+	type AdoptableAlias,
+	type FlagValidationIssue,
+	type Segment,
+	type ShellTarget,
+	detectShells,
+	findAdoptableAlias,
+	parseAliasFromRc,
+	renderArgs,
+	validateConfig,
+	writeAliasToShell,
+} from "../../services/alias-shell-writer.js";
+import {
+	type AliasConfig,
+	CHANNELS_FLAG_ID,
+	DEFAULT_ALIAS_NAME,
+	type FlagValue,
+	defaultAliasConfig,
+	defaultValueFor,
+	derivedChannelValues,
+	validateAliasName,
+	withoutDerivedChannel,
+} from "../../services/alias-store.js";
+import { FlagDetailEditor } from "../components/FlagDetailEditor.js";
+import { type FooterHint, ScreenLayout } from "../components/layout/index.js";
+import { useKeyboardHandler } from "../hooks/useKeyboardHandler.js";
+import { useApp, useModal } from "../state/AppContext.js";
+import { theme } from "../theme.js";
+
+interface FlagRow {
+	kind: "flag";
+	flag: AliasFlag;
+	value: FlagValue;
+	/** Pre-computed validation issue for this row, if any. */
+	issue?: FlagValidationIssue;
+	/**
+	 * Override for the checkbox's enabled state when the rendered alias would
+	 * carry this flag even though its OWN value is disabled. Used by --channels:
+	 * a dev-loaded channel forces `--channels` to emit (the render-time union),
+	 * so the row must show `[x]` to match what gets written — even when the
+	 * user's own channels list is off. Undefined → use the flag's own enabled.
+	 */
+	effectiveEnabled?: boolean;
+	/**
+	 * Override for the trailing detail (e.g. the --channels union count: own +
+	 * derived). Undefined → derive from the flag's own value. Empty string is a
+	 * valid override meaning "show nothing".
+	 */
+	effectiveDetail?: string;
+	/**
+	 * Override for the detail-pane `State:` line. For --channels this is the
+	 * effective channel-list summary (the union of own + derived), so the detail
+	 * agrees with the list count and the Preview. Undefined → summarizeValue.
+	 */
+	stateSummary?: string;
+}
+
+interface AliasNameRow {
+	kind: "alias-name";
+	value: string;
+}
+
+type Row = AliasNameRow | FlagRow;
+
+/**
+ * Flat-list items for the windowed `<ScrollableList>`. Selectable rows
+ * (`alias-name`, `flag`) accept the cursor; presentation rows (`header`)
+ * render in-line so groups scroll with their flags, but `j`/`k` skip them.
+ *
+ * The shells legend is NOT in this list — it lives outside the scroll area
+ * as a fixed footer so it's always visible. Keeping non-selectable items
+ * trailing the scrollable list would let `↓ N more` lie about reachable
+ * content.
+ */
+type Item =
+	| { kind: "alias-name"; row: AliasNameRow }
+	| { kind: "flag"; row: FlagRow }
+	| { kind: "header"; label: string };
+
+function isSelectableItem(item: Item): boolean {
+	return item.kind === "alias-name" || item.kind === "flag";
+}
+
+/**
+ * View modes for the Alias screen.
+ *
+ * - `main`: the default list of all flags grouped by section.
+ * - `flag-detail`: a dedicated sub-screen for editing a single `text-list` or
+ *   `multi-with-custom` flag's value. Has its own keybindings (`a` add, `d`
+ *   delete, `space`/`enter` toggle, `h` back to main) so each row's primary
+ *   action is unambiguous. Esc still exits the screen via the global handler.
+ *
+ * Other flag kinds (boolean, tri-state, select, text, optional-text) use
+ * modals because they're single-action — no benefit from a sub-screen.
+ */
+type ViewMode = { kind: "main" } | { kind: "flag-detail"; flagId: string };
+
+export function AliasScreen() {
+	const { state } = useApp();
+	const modal = useModal();
+
+	const [config, setConfig] = useState<AliasConfig | null>(null);
+	const [shells, setShells] = useState<ShellTarget[]>([]);
+	const [selectedIdx, setSelectedIdx] = useState(0);
+	const [error, setError] = useState<string | null>(null);
+	const [viewMode, setViewMode] = useState<ViewMode>({ kind: "main" });
+	// Snapshot of the rc file's flag values as parsed on mount / write. Used
+	// to compute the dirty indicator: in-memory != rcSnapshot ⇒ unsaved.
+	const [rcSnapshot, setRcSnapshot] = useState<Record<
+		string,
+		FlagValue
+	> | null>(null);
+	// Transient write feedback shown on the header status line (not a blocking
+	// modal). Auto-clears after a few seconds. Errors still use a modal since
+	// they need to be read and acknowledged.
+	const [writeStatus, setWriteStatus] = useState<string | null>(null);
+
+	// A hand-written `claude` alias found OUTSIDE any managed block on mount.
+	// Set when the rc file has no managed block but a stray alias we could
+	// adopt — drives the one-time "import it?" offer below. Cleared once the
+	// offer has been shown (whether accepted or declined).
+	const [adoptable, setAdoptable] = useState<AdoptableAlias | null>(null);
+	// When the user accepts a LOSSLESS adoption, we remember the line range of
+	// their original alias so the next write replaces it in place (no duplicate
+	// alias). Cleared after that write absorbs it into the managed block.
+	const [pendingAdoptRange, setPendingAdoptRange] = useState<
+		[number, number] | null
+	>(null);
+
+	// Clear the write status line a few seconds after it appears.
+	useEffect(() => {
+		if (!writeStatus) return;
+		const t = setTimeout(() => setWriteStatus(null), 4000);
+		return () => clearTimeout(t);
+	}, [writeStatus]);
+
+	// One-time "adopt a hand-written alias?" offer. Fires when the mount load
+	// found a stray `claude` alias outside any managed block. We import only the
+	// flags we recognized; whether we also TAKE OWNERSHIP (remove the original
+	// line on the next write) depends on `lossless`:
+	//   - lossless: every token round-trips → safe to absorb. We stash the line
+	//     range so the next write replaces it in place (no duplicate alias).
+	//   - not lossless: we couldn't parse some tokens (e.g. an uncatalogued
+	//     flag like --model) → import the known flags for convenience but LEAVE
+	//     the original line untouched. CRITICAL: we must NOT adopt its name here.
+	//     Shell alias resolution is last-definition-wins, so a managed block
+	//     sharing the name would shadow the surviving original at `source` time —
+	//     silently killing the very tokens that made it not-lossless. Keeping the
+	//     tool's own name lets both coexist: the original keeps working, the
+	//     managed block lives under a different name.
+	// True once we've shown the offer. A ref (not state) so it survives re-render
+	// without being a dependency — critical because this effect mutates its own
+	// `adoptable` dep, and tying "fire once" to state/deps would let the dep
+	// change abort the in-flight modal mid-await (the cleanup would fire before
+	// the user answered). The ref decouples one-shot from the dependency array.
+	const didOfferAdoptRef = useRef(false);
+	useEffect(() => {
+		if (!adoptable || !config || didOfferAdoptRef.current) return;
+		didOfferAdoptRef.current = true;
+		(async () => {
+			const a = adoptable;
+
+			const body = a.rawLine.trim();
+			const others =
+				a.others.length > 0
+					? `\n\n(Also found ${a.others.length} other claude alias${
+							a.others.length === 1 ? "" : "es"
+						} — leaving those alone.)`
+					: "";
+
+			// On a not-lossless adopt the managed block must NOT share the original's
+			// name — same name + last-wins shell resolution = the block shadows the
+			// surviving original, killing its uncatalogued tokens. Compute a managed
+			// name distinct from `a.name`: keep the tool's current name if it already
+			// differs, else derive a suffixed variant that's free in the rc file.
+			const managedName = a.lossless
+				? a.name
+				: pickDistinctName(config.aliasName, a.name, a.others);
+
+			const message = a.lossless
+				? `Found a hand-written alias:\n\n  ${body}\n\nImport its flags into the editor? On the next write it'll be absorbed into a managed block (your original line is replaced — no duplicate).${others}`
+				: `Found a hand-written alias:\n\n  ${body}\n\nI can import the flags I recognize, but it uses ${
+						a.leftovers.length
+					} token${a.leftovers.length === 1 ? "" : "s"} I don't manage (${a.leftovers
+						.map((t) => JSON.stringify(t))
+						.join(
+							", ",
+						)}). I'll import the known flags and LEAVE your original "${a.name}" line untouched so it keeps working. The managed alias will use the name "${managedName}" — distinct from "${a.name}" so it can't override it. Import the known flags?${others}`;
+
+			const accepted = await modal.confirm("Adopt existing alias?", message);
+			if (accepted) {
+				// Lossless: adopt the name AND take ownership (replace the line on
+				// write). Not-lossless: import flags under a distinct managed name and
+				// never touch the original line — so it survives AND keeps resolving.
+				setConfig((prev) =>
+					prev
+						? {
+								...prev,
+								aliasName: managedName,
+								flags: { ...prev.flags, ...a.flags },
+							}
+						: prev,
+				);
+				if (a.lossless) {
+					// Persist the adopted name and stash the line range so the next
+					// write replaces the original in place (no duplicate, no shadow).
+					void persistAliasName(a.name);
+					setPendingAdoptRange(a.lineRange);
+				} else {
+					// Persist the distinct managed name so it survives a reopen.
+					void persistAliasName(managedName);
+				}
+			}
+			// Clear the candidate now that the decision is made — after the await,
+			// never before (clearing before would abort this very async via the
+			// dep-change cleanup, the bug this effect previously had).
+			setAdoptable(null);
+		})();
+		// persistAliasName is stable (useCallback); excluded to keep this one-shot.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [adoptable, config, modal]);
+
+	// ── Load alias name + parse rc file + detect shells on mount ─────────
+	// The alias name is computer-wide and persisted in ~/.claude/settings.json.
+	// Flag values are read directly from the shell rc file's managed block —
+	// the rc file IS the source of truth so what the user sees matches what
+	// they're actually running.
+	useEffect(() => {
+		let cancelled = false;
+		(async () => {
+			try {
+				const [name, s] = await Promise.all([loadAliasName(), detectShells()]);
+				if (cancelled) return;
+
+				// Pick the same rc file we'd write to with `w` (default shell that
+				// exists; else first existing). If none exists, start from defaults.
+				const readTarget =
+					s.find((sh) => sh.isDefault && sh.exists) ??
+					s.find((sh) => sh.exists);
+
+				const base = defaultAliasConfig();
+				base.aliasName = name;
+
+				let parsedFlags: Record<string, FlagValue> | null = null;
+				let foundAdoptable: AdoptableAlias | null = null;
+				if (readTarget && existsSync(readTarget.path)) {
+					try {
+						const rcText = await readFile(readTarget.path, "utf8");
+						const parsed = parseAliasFromRc(rcText);
+						if (parsed) {
+							parsedFlags = { ...base.flags, ...parsed.flags };
+							base.flags = parsedFlags;
+							// Honour an existing alias name from the rc if settings is at default.
+							// But the user's stored preference wins when set explicitly.
+							// (No-op here — `name` already loaded above.)
+						} else {
+							// No managed block on disk. The user may still have a hand-written
+							// `claude` alias elsewhere — detect it so we can offer to adopt it
+							// instead of looking broken. Non-destructive: just a candidate.
+							foundAdoptable = findAdoptableAlias(rcText);
+						}
+					} catch {
+						// rc unreadable — fall back to defaults; not a hard error.
+					}
+				}
+
+				if (cancelled) return;
+				// No mirror normalization: channels.values holds OWN channels only;
+				// derived channels come from the dev-load flag at display/render time.
+				// The parser already subtracts derived values from the parsed channels
+				// list, so `base.flags` is correct as-is.
+				setConfig(base);
+				setShells(s);
+				setRcSnapshot(parsedFlags ?? { ...base.flags });
+				if (foundAdoptable) setAdoptable(foundAdoptable);
+			} catch (err) {
+				if (cancelled) return;
+				setError(err instanceof Error ? err.message : String(err));
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	// ── Build the flat list of items ──────────────────────────────────────
+	// Group headers and the shell legend live in the same flat array as
+	// alias-name + flag rows so that ScrollableList can window them together.
+	// Navigation skips non-selectable kinds.
+	const items: Item[] = useMemo(() => {
+		if (!config) return [];
+		const issues = validateConfig(config);
+		const issueMap = new Map(issues.map((i) => [i.flagId, i]));
+
+		const out: Item[] = [
+			{
+				kind: "alias-name",
+				row: { kind: "alias-name", value: config.aliasName },
+			},
+		];
+
+		for (const group of FLAG_GROUPS) {
+			const groupFlags = ALIAS_FLAGS.filter((f) => f.group === group.id);
+			if (groupFlags.length === 0) continue;
+			out.push({ kind: "header", label: group.label });
+			for (const flag of groupFlags) {
+				// --channels shows enabled when the rendered alias would emit it —
+				// i.e. own channels are on OR a dev-loaded channel is derived in. This
+				// keeps the checkbox honest about what gets written without mutating
+				// the own-channels enabled flag (which would silently re-emit own
+				// values the user disabled).
+				let effectiveEnabled: boolean | undefined;
+				let effectiveDetail: string | undefined;
+				let stateSummary: string | undefined;
+				if (flag.id === CHANNELS_FLAG_ID) {
+					const own = config.flags[flag.id];
+					const ownValues =
+						own && own.kind === "text-list" && own.enabled
+							? own.values.filter((v) => v.length > 0)
+							: [];
+					const derived = derivedChannelValues(config.flags);
+					// Deduped union — matches the writer's render-time union and the
+					// detail-pane summary, so the count is consistent everywhere.
+					const total = new Set([...ownValues, ...derived]).size;
+					effectiveEnabled = total > 0;
+					// Show the union count so the row matches what's written. When the
+					// count is purely derived, this reads e.g. `[x] --channels  1`.
+					effectiveDetail = total > 0 ? `${total}` : "";
+					// The detail-pane State line shows the same final channel list.
+					stateSummary = channelsStateSummary(config.flags);
+				}
+				out.push({
+					kind: "flag",
+					row: {
+						kind: "flag",
+						flag,
+						value: config.flags[flag.id] ?? defaultValueFor(flag),
+						issue: issueMap.get(flag.id),
+						effectiveEnabled,
+						effectiveDetail,
+						stateSummary,
+					},
+				});
+			}
+		}
+
+		return out;
+	}, [config]);
+
+	/** Indices in `items` that the cursor may land on. */
+	const selectableIndices = useMemo(
+		() => items.flatMap((it, i) => (isSelectableItem(it) ? [i] : [])),
+		[items],
+	);
+
+	// ── Flag-detail sub-screen items ──────────────────────────────────────
+	// Computed only when viewMode is flag-detail. Built off the flag's current
+	// The flag-detail sub-screen is now self-contained in <FlagDetailEditor>.
+	// We just resolve the flag + value pair here so the parent can render
+	// the editor and the right-pane preview.
+	const detailFlag: AliasFlag | null =
+		viewMode.kind === "flag-detail"
+			? (ALIAS_FLAGS.find((f) => f.id === viewMode.flagId) ?? null)
+			: null;
+	const detailValue: FlagValue | null =
+		detailFlag && config ? (config.flags[detailFlag.id] ?? null) : null;
+
+	// ── Helper: check whether a row is gated (requires unmet) ─────────────
+	const isGated = useCallback(
+		(flag: AliasFlag): boolean => {
+			if (!flag.requires || !config) return false;
+			return !isFlagEnabled(config.flags[flag.requires]);
+		},
+		[config],
+	);
+
+	const selectedItem = items[selectedIdx];
+	const selectedRow: Row | undefined =
+		selectedItem &&
+		(selectedItem.kind === "alias-name" || selectedItem.kind === "flag")
+			? selectedItem.row
+			: undefined;
+
+	// Clamp selection: snap to the nearest selectable index whenever items shift.
+	useEffect(() => {
+		if (selectableIndices.length === 0) return;
+		if (!isSelectableItem(items[selectedIdx])) {
+			// Find the nearest selectable index <= selectedIdx (or the first one)
+			const fallback =
+				[...selectableIndices].reverse().find((i) => i <= selectedIdx) ??
+				selectableIndices[0];
+			setSelectedIdx(fallback);
+		} else if (selectedIdx >= items.length) {
+			setSelectedIdx(selectableIndices[selectableIndices.length - 1]);
+		}
+	}, [items, selectableIndices, selectedIdx]);
+
+	// ── Mutators ──────────────────────────────────────────────────────────
+	// Flag mutations stay in memory. Only the alias name is persisted (to
+	// ~/.claude/settings.json) — flag values reach disk only when the user
+	// explicitly presses `w` to write the shell rc file.
+	const persistAliasName = useCallback(
+		async (name: string) => {
+			try {
+				await saveAliasName(name);
+			} catch (err) {
+				await modal.message(
+					"Save failed",
+					err instanceof Error ? err.message : String(err),
+					"error",
+				);
+			}
+		},
+		[modal],
+	);
+
+	// Cascade dependencies on every mutation:
+	//   - Enabling a flag → enable its `requires` chain (no modal nagging).
+	//   - Disabling a flag → disable anything whose `requires === this flag id`,
+	//     because the renderer would silently drop them otherwise and the UI
+	//     would lie about what's going to be written.
+	const updateFlag = useCallback((id: string, next: FlagValue) => {
+		setConfig((prev) => {
+			if (!prev) return prev;
+			const flags = { ...prev.flags, [id]: next };
+			const target = ALIAS_FLAGS.find((f) => f.id === id);
+			if (!target) return { ...prev, flags };
+
+			const becomingEnabled = isFlagEnabled(next);
+
+			if (becomingEnabled) {
+				// Walk `requires` chain and force-enable each ancestor to its
+				// catalog-default-enabled state if it's currently off.
+				let cursor = target.requires;
+				const seen = new Set<string>();
+				while (cursor && !seen.has(cursor)) {
+					seen.add(cursor);
+					const dep = ALIAS_FLAGS.find((f) => f.id === cursor);
+					if (!dep) break;
+					if (!isFlagEnabled(flags[dep.id])) {
+						flags[dep.id] = enableDefault(dep);
+					}
+					cursor = dep.requires;
+				}
+			} else {
+				// Cascade-disable any flag that requires this one (one level deep is
+				// enough today; recurse defensively in case a chain emerges).
+				const queue = [id];
+				const seen = new Set<string>();
+				for (let cur = queue.shift(); cur !== undefined; cur = queue.shift()) {
+					if (seen.has(cur)) continue;
+					seen.add(cur);
+					for (const dependent of ALIAS_FLAGS) {
+						if (dependent.requires !== cur) continue;
+						if (!isFlagEnabled(flags[dependent.id])) continue;
+						flags[dependent.id] = disableValue(flags[dependent.id]);
+						queue.push(dependent.id);
+					}
+				}
+			}
+
+			return { ...prev, flags };
+		});
+	}, []);
+
+	// Remove a value from the dev-load flag — invoked when the user deletes a
+	// "Dev-loaded channels" row inside the --channels editor. The derived
+	// section is sourced from this flag, so the deletion lands here, not in
+	// channels.values. updateFlag keeps enabled-state and cascades consistent.
+	const removeDevloadChannel = useCallback((val: string) => {
+		setConfig((prev) =>
+			prev ? { ...prev, flags: withoutDerivedChannel(prev.flags, val) } : prev,
+		);
+	}, []);
+
+	const editAliasName = useCallback(async () => {
+		if (!config) return;
+		const v = await modal.input(
+			"Alias name",
+			`Shell alias name (default: "${DEFAULT_ALIAS_NAME}"). Letters, digits, _ or - only.`,
+			config.aliasName,
+		);
+		if (v === null) return;
+		const reason = validateAliasName(v);
+		if (reason) {
+			await modal.message("Invalid alias name", reason, "error");
+			return;
+		}
+		setConfig((prev) => (prev ? { ...prev, aliasName: v } : prev));
+		void persistAliasName(v);
+	}, [config, modal, persistAliasName]);
+
+	const editSelected = useCallback(async () => {
+		if (!selectedRow) return;
+		if (selectedRow.kind === "alias-name") {
+			await editAliasName();
+			return;
+		}
+		// No more "Requires another flag" modal — `updateFlag` auto-enables the
+		// `requires` chain when the user activates a gated flag.
+		//
+		// Collection editors live in a dedicated sub-screen, not a modal —
+		// each row gets its own keybindings (space toggle, a add, d delete)
+		// so there's no "what does enter do here?" overloading.
+		const k = selectedRow.value.kind;
+		if (k === "text-list" || k === "multi-with-custom") {
+			// FlagDetailEditor manages its own cursor — parent just flips mode.
+			setViewMode({ kind: "flag-detail", flagId: selectedRow.flag.id });
+			return;
+		}
+		const next = await editFlagValue(
+			selectedRow.flag,
+			selectedRow.value,
+			modal,
+		);
+		if (next) updateFlag(selectedRow.flag.id, next);
+	}, [selectedRow, modal, updateFlag, editAliasName]);
+
+	const toggleSelected = useCallback(async () => {
+		if (!selectedRow) return;
+		if (selectedRow.kind === "alias-name") {
+			// No "toggle" semantic for the name — fall through to edit.
+			await editAliasName();
+			return;
+		}
+		// Only booleans and tri-states have a meaningful single-press cycle.
+		// Everything else (select, text, list, multi-with-custom) needs a value
+		// chooser; falling back to edit prevents the "I pressed space and got the
+		// first option without seeing the choices" footgun.
+		const k = selectedRow.value.kind;
+		if (k !== "boolean" && k !== "tri-state") {
+			await editSelected();
+			return;
+		}
+		const next = quickToggle(selectedRow.flag, selectedRow.value);
+		if (next) updateFlag(selectedRow.flag.id, next);
+	}, [selectedRow, updateFlag, editSelected, editAliasName]);
+
+	const handleWrite = useCallback(async () => {
+		if (!config) return;
+
+		// Pick the target shell automatically: default shell (matches $SHELL)
+		// if its rc file exists; otherwise the first existing rc file. Users
+		// who care about other shells edit them directly — the alias config
+		// itself is stored in ~/.claude and the user can run `w` again from
+		// a different $SHELL session if they want to mirror it.
+		const target =
+			shells.find((s) => s.isDefault && s.exists) ??
+			shells.find((s) => s.exists);
+
+		if (!target) {
+			await modal.message(
+				"No shells detected",
+				"No supported rc files found. Create ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish first.",
+				"info",
+			);
+			return;
+		}
+
+		try {
+			// If we adopted a lossless hand-written alias, pass its line range so
+			// the FIRST write replaces that line in place (absorbing it into the
+			// managed block) rather than appending a second alias. Once the block
+			// exists, the writer ignores the range and splices by markers.
+			const r = await writeAliasToShell(
+				config,
+				target,
+				pendingAdoptRange ? { adoptLineRange: pendingAdoptRange } : {},
+			);
+			// The adopted line is now gone (replaced by the block); drop the range
+			// so subsequent writes don't try to re-target a line that moved.
+			if (pendingAdoptRange) setPendingAdoptRange(null);
+			// Non-blocking confirmation on the status line — no "press any key".
+			const name = r.path.split("/").pop() || r.path;
+			setWriteStatus(
+				`✓ ${r.action === "created" ? "Created" : "Updated"} ${name} — source it or open a new shell`,
+			);
+			setShells(await detectShells());
+			// We just wrote the rc file with current in-memory flag values, so
+			// the snapshot now matches in-memory state. Dirty indicator clears.
+			setRcSnapshot(config.flags);
+		} catch (err) {
+			await modal.message(
+				"Write failed",
+				err instanceof Error ? err.message : String(err),
+				"error",
+			);
+		}
+	}, [config, shells, modal, pendingAdoptRange]);
+
+	// ── Keyboard ──────────────────────────────────────────────────────────
+	// j/k navigate the selectable subset, jumping over headers/legend lines.
+	const moveSelection = useCallback(
+		(dir: 1 | -1) => {
+			if (selectableIndices.length === 0) return;
+			const cursorPos = selectableIndices.indexOf(selectedIdx);
+			const nextPos =
+				cursorPos === -1
+					? // Currently parked on a non-selectable; move to first/last selectable.
+						dir === 1
+						? 0
+						: selectableIndices.length - 1
+					: Math.min(
+							selectableIndices.length - 1,
+							Math.max(0, cursorPos + dir),
+						);
+			setSelectedIdx(selectableIndices[nextPos]);
+		},
+		[selectableIndices, selectedIdx],
+	);
+
+	// The flag-detail sub-screen handles its own cursor + key + render
+	// (see FlagDetailEditor component). The parent only needs to know how
+	// to leave it.
+	const exitDetail = useCallback(() => {
+		setViewMode({ kind: "main" });
+	}, []);
+
+	// ── Keyboard handler ──────────────────────────────────────────────────
+	// When the sub-screen is mounted, FlagDetailEditor installs its own
+	// keyboard handler. Both handlers fire (OpenTUI's useKeyboard delivers
+	// to every subscriber), so this handler must SKIP the keys the child
+	// owns to avoid double-dispatch. We bail entirely while in detail mode.
+	useKeyboardHandler((input, key) => {
+		if (state.modal) return;
+		if (viewMode.kind === "flag-detail") return;
+
+		// Main mode.
+		if (input === "j" || key.downArrow) {
+			moveSelection(1);
+			return;
+		}
+		if (input === "k" || key.upArrow) {
+			moveSelection(-1);
+			return;
+		}
+		if (key.return || input === " " || key.name === "space") {
+			void toggleSelected();
+			return;
+		}
+		if (input === "e") {
+			void editSelected();
+			return;
+		}
+		if (input === "w") {
+			void handleWrite();
+			return;
+		}
+		if (input === "r") {
+			// Reset the selected row to its default.
+			if (!selectedRow) return;
+			if (selectedRow.kind === "alias-name") {
+				setConfig((prev) =>
+					prev ? { ...prev, aliasName: DEFAULT_ALIAS_NAME } : prev,
+				);
+				void persistAliasName(DEFAULT_ALIAS_NAME);
+				return;
+			}
+			// Flag reset stays in memory until `w`.
+			updateFlag(selectedRow.flag.id, defaultValueFor(selectedRow.flag));
+		}
+	});
+
+	// ── Render ────────────────────────────────────────────────────────────
+	const previewSegments = config ? renderArgs(config) : [];
+	const previewAliasName = config?.aliasName ?? "";
+
+	// Native OpenTUI scrollboxes own the scroll math. We render every item
+	// into the scrollbox's content area and ask the renderable to scroll the
+	// selected child into view whenever the cursor moves. The previous JS-
+	// windowed approach (ScrollableList) overstrike-rendered rows when its
+	// height computation drifted off the actual panel size.
+	const mainScrollRef = useRef<ScrollBoxRenderable | null>(null);
+
+	useEffect(() => {
+		const item = items[selectedIdx];
+		if (!item) return;
+		mainScrollRef.current?.scrollChildIntoView(`alias-row-${getItemKey(item)}`);
+	}, [items, selectedIdx]);
+
+	const inDetail = viewMode.kind === "flag-detail" && detailFlag && detailValue;
+	// FlagDetailEditor only handles text-list and multi-with-custom values;
+	// narrow the type for the JSX below.
+	const editableDetailValue =
+		inDetail &&
+		(detailValue.kind === "text-list" ||
+			detailValue.kind === "multi-with-custom")
+			? detailValue
+			: null;
+
+	const mainListPanel = !config ? (
+		<text fg={theme.colors.muted}>
+			{error ? `Error: ${error}` : "Loading..."}
+		</text>
+	) : (
+		<box flexDirection="column" height="100%">
+			<scrollbox
+				ref={mainScrollRef}
+				scrollY={true}
+				scrollX={false}
+				flexGrow={1}
+			>
+				<box flexDirection="column">
+					{items.map((item, idx) => (
+						// id is content-derived (not positional `${idx}`) so OpenTUI's
+						// reconciler stays in lockstep with React's key-based reconcile.
+						<box key={getItemKey(item)} id={`alias-row-${getItemKey(item)}`}>
+							{renderItem(item, idx === selectedIdx, isGated)}
+						</box>
+					))}
+				</box>
+			</scrollbox>
+		</box>
+	);
+
+	const listPanel =
+		inDetail && editableDetailValue ? (
+			<FlagDetailEditor
+				flag={detailFlag}
+				value={editableDetailValue}
+				onChange={(next) => updateFlag(detailFlag.id, next)}
+				onBack={exitDetail}
+				derivedValues={
+					detailFlag.id === CHANNELS_FLAG_ID && config
+						? derivedChannelValues(config.flags)
+						: undefined
+				}
+				derivedLabel="From --dangerously-load:"
+				toggleLabel={
+					detailFlag.id === CHANNELS_FLAG_ID ? "Enable own channels" : undefined
+				}
+				onDerivedDelete={(v) => removeDevloadChannel(v)}
+			/>
+		) : (
+			mainListPanel
+		);
+
+	const mainDetailPanel = renderDetail(
+		selectedRow,
+		isGated,
+		previewAliasName,
+		previewSegments,
+	);
+	// When editing --channels and there are derived rows, the right pane carries
+	// the contextual instruction about what deleting a derived row does — that
+	// explanation belongs here, not crammed into the left list.
+	const channelsHasDerived =
+		inDetail &&
+		detailFlag.id === CHANNELS_FLAG_ID &&
+		config &&
+		derivedChannelValues(config.flags).length > 0;
+	const derivedNote = channelsHasDerived
+		? "Rows under “From --dangerously-load:” are derived from the --dangerously-load-development-channels flag. Deleting one here removes it from that flag."
+		: undefined;
+	// The right-pane `State:` line is informational — it describes what the alias
+	// actually runs. For --channels that's the FINAL channel list: the union of
+	// the user's own channels and the derived (dev-loaded) ones. We show the
+	// union count so it agrees with the list row's count and the Preview, and
+	// annotate how many are derived so the source is clear. Computed only when
+	// editing --channels; other flags fall back to their own summary.
+	const stateOverride =
+		inDetail && detailFlag.id === CHANNELS_FLAG_ID && config
+			? channelsStateSummary(config.flags)
+			: undefined;
+	const detailDetailPanel = inDetail
+		? renderFlagDetailRightPane(
+				detailFlag,
+				detailValue,
+				previewAliasName,
+				previewSegments,
+				derivedNote,
+				stateOverride,
+			)
+		: null;
+	const detailPanel = inDetail ? detailDetailPanel : mainDetailPanel;
+
+	const enabledCount = config
+		? Object.values(config.flags).filter(isFlagEnabled).length
+		: 0;
+	const subtitle = inDetail
+		? `editing ${detailFlag.flag}`
+		: writeStatus
+			? writeStatus
+			: config
+				? `${enabledCount} flag${enabledCount === 1 ? "" : "s"} enabled`
+				: "";
+
+	// Resolve the rc-file name we'd actually write to (basename of the chosen
+	// shell's path). Falls back to "shell" if no shells were detected — UI
+	// surface mirrors the runtime behavior of `handleWrite`.
+	const writeTarget =
+		shells.find((s) => s.isDefault && s.exists) ?? shells.find((s) => s.exists);
+	const writeLabel = writeTarget
+		? writeTarget.path.split("/").pop() || "shell"
+		: "shell";
+
+	// Dirty when current in-memory flags differ from the rc-file snapshot.
+	// Initial mount sets rcSnapshot from the parsed rc, so this is false
+	// until the user edits.
+	const dirty = config
+		? rcSnapshot !== null && !shallowFlagsEqual(config.flags, rcSnapshot)
+		: false;
+
+	const footerHints: FooterHint[] = inDetail
+		? [
+				{ keys: ["↑", "↓"], label: "move" },
+				{ keys: ["space"], label: "toggle" },
+				{ keys: ["a"], label: "add" },
+				{ keys: ["d"], label: "delete" },
+				{ keys: ["h"], label: "back" },
+			]
+		: [
+				{ keys: ["↑", "↓"], label: "move" },
+				{ keys: ["space"], label: "toggle" },
+				{ keys: ["e"], label: "edit" },
+				{ keys: ["r"], label: "reset" },
+				{
+					keys: ["w"],
+					label: `${dirty ? "*" : ""}write to ${writeLabel}`,
+				},
+			];
+
+	return (
+		<ScreenLayout
+			title="Claude Alias"
+			subtitle={subtitle}
+			currentScreen="alias"
+			footerHints={footerHints}
+			listPanel={listPanel}
+			detailPanel={detailPanel}
+		/>
+	);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Summarize the EFFECTIVE state of `--channels` for the detail `State:` line:
+ * the final channel list that the alias will actually run, i.e. the union of
+ * the user's own (enabled) channels and the derived dev-loaded ones. This must
+ * agree with the list row's union count and the Preview.
+ *
+ * Returns "off" when nothing is emitted, or e.g.:
+ *   - "2 channels" (all own, no derived)
+ *   - "1 channel (from --dangerously-load)" (purely derived, own off/empty)
+ *   - "2 channels (1 from --dangerously-load)" (mixed)
+ */
+function channelsStateSummary(flags: Record<string, FlagValue>): string {
+	const ownValue = flags[CHANNELS_FLAG_ID];
+	const ownValues =
+		ownValue && ownValue.kind === "text-list" && ownValue.enabled
+			? ownValue.values.filter((v) => v.length > 0)
+			: [];
+	const derived = derivedChannelValues(flags);
+	// Union, deduped, matching the writer's render-time union.
+	const total = new Set([...ownValues, ...derived]).size;
+	if (total === 0) return "off";
+	const noun = total === 1 ? "channel" : "channels";
+	if (derived.length === 0) return `${total} ${noun}`;
+	// How many of the union come from the derived flag (after dedup with own).
+	const derivedInUnion = new Set(derived).size;
+	const derivedNote =
+		derivedInUnion === total
+			? "from --dangerously-load"
+			: `${derivedInUnion} from --dangerously-load`;
+	return `${total} ${noun} (${derivedNote})`;
+}
+
+/**
+ * Compare two flag maps for value equality. We render-then-diff via JSON
+ * because FlagValues are small, fully serialisable, and order-insensitive
+ * inside the maps. A property-by-property deep-equal would be more efficient
+ * but the maps have ~14 entries — diff cost is negligible.
+ */
+function shallowFlagsEqual(
+	a: Record<string, FlagValue>,
+	b: Record<string, FlagValue>,
+): boolean {
+	const aKeys = Object.keys(a).sort();
+	const bKeys = Object.keys(b).sort();
+	if (aKeys.length !== bKeys.length) return false;
+	for (let i = 0; i < aKeys.length; i++) {
+		if (aKeys[i] !== bKeys[i]) return false;
+	}
+	for (const k of aKeys) {
+		if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) return false;
+	}
+	return true;
+}
+
+function isFlagEnabled(value: FlagValue | undefined): boolean {
+	if (!value) return false;
+	switch (value.kind) {
+		case "boolean":
+			return value.enabled;
+		case "tri-state":
+			return value.state !== "unset";
+		case "select":
+		case "text":
+		case "optional-text":
+		case "text-list":
+		case "multi-with-custom":
+			return value.enabled;
+	}
+}
+
+/**
+ * Pick a managed-alias name that can't shadow a surviving hand-written alias.
+ *
+ * On a not-lossless adoption we keep the user's original `<original>` line in
+ * the rc file, so the managed block must NOT share its name (shell aliases are
+ * last-definition-wins — a same-named block would override the original and
+ * silently drop the very tokens that made it not-lossless).
+ *
+ * Strategy: prefer the tool's `current` name if it already differs from the
+ * original. Otherwise derive `<original>m`, `<original>m2`, … until we find one
+ * that is valid AND collides with neither the original nor the other detected
+ * claude aliases. Falls back to a timestamp-free deterministic suffix.
+ */
+function pickDistinctName(
+	current: string,
+	original: string,
+	others: string[],
+): string {
+	// Names already taken by aliases we're leaving in place.
+	const taken = new Set<string>([original]);
+	for (const line of others) {
+		const m = /^alias\s+([A-Za-z_][A-Za-z0-9_-]*)\s*=/.exec(line.trim());
+		if (m) taken.add(m[1]);
+	}
+
+	// If our current name is already distinct + valid, just use it.
+	if (
+		current !== original &&
+		!taken.has(current) &&
+		!validateAliasName(current)
+	) {
+		return current;
+	}
+
+	// Derive a suffixed variant from the original.
+	const base = `${original}m`;
+	if (!taken.has(base) && !validateAliasName(base)) return base;
+	for (let n = 2; n < 100; n++) {
+		const cand = `${original}m${n}`;
+		if (!taken.has(cand) && !validateAliasName(cand)) return cand;
+	}
+	// Pathological fallback — should never be reached for sane inputs.
+	return `${original}managed`;
+}
+
+/**
+ * Produce an "enabled by default" value for a flag — what we'd give it when
+ * the user activates a dependent that needs this one on. For booleans this
+ * is just `enabled: true`; for kinds that carry a value (select/text/etc.)
+ * we set `enabled: true` with the catalog default value, leaving the user
+ * free to refine it after.
+ */
+function enableDefault(flag: AliasFlag): FlagValue {
+	switch (flag.kind) {
+		case "boolean":
+			return { kind: "boolean", enabled: true };
+		case "tri-state":
+			return { kind: "tri-state", state: "on" };
+		case "select":
+			return {
+				kind: "select",
+				enabled: true,
+				value: flag.options?.[0]?.value ?? "",
+			};
+		case "text":
+			return { kind: "text", enabled: true, value: "" };
+		case "optional-text":
+			return { kind: "optional-text", enabled: true, value: "" };
+		case "text-list":
+			return {
+				kind: "text-list",
+				enabled: true,
+				values: [...(flag.defaultValues ?? [])],
+			};
+		case "multi-with-custom":
+			return {
+				kind: "multi-with-custom",
+				enabled: true,
+				picked: [],
+				custom: [...(flag.defaultValues ?? [])],
+			};
+	}
+}
+
+/**
+ * Disable a flag while preserving any values the user has already entered.
+ * Used by the cascade-disable path: turning off `--worktree` shouldn't lose
+ * the user's `--tmux=classic` choice — only re-enable the dependency and
+ * the value reappears.
+ */
+function disableValue(value: FlagValue): FlagValue {
+	switch (value.kind) {
+		case "boolean":
+			return { kind: "boolean", enabled: false };
+		case "tri-state":
+			return { kind: "tri-state", state: "unset" };
+		case "select":
+		case "text":
+		case "optional-text":
+		case "text-list":
+		case "multi-with-custom":
+			return { ...value, enabled: false };
+	}
+}
+
+function summarizeValue(value: FlagValue): string {
+	switch (value.kind) {
+		case "boolean":
+			return value.enabled ? "on" : "off";
+		case "tri-state":
+			return value.state;
+		case "select":
+			return value.enabled ? value.value || "(bare)" : "off";
+		case "text":
+		case "optional-text":
+			return value.enabled
+				? value.value
+					? truncate(value.value, 32)
+					: "(empty)"
+				: "off";
+		case "text-list":
+			return value.enabled ? `${value.values.length} item(s)` : "off";
+		case "multi-with-custom": {
+			if (!value.enabled) return "off";
+			const total = new Set([...value.picked, ...value.custom]).size;
+			return total === 0 ? "(no filter)" : `${total} token(s)`;
+		}
+	}
+}
+
+function truncate(s: string, n: number): string {
+	return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}
+
+/**
+ * Quick toggle (enter/space). For boolean → flip. For tri-state → cycle
+ * unset → on → off → unset. For others, just flip the `enabled` field; the
+ * user must press `e` to set the value.
+ */
+function quickToggle(_flag: AliasFlag, value: FlagValue): FlagValue | null {
+	switch (value.kind) {
+		case "boolean":
+			return { kind: "boolean", enabled: !value.enabled };
+		case "tri-state": {
+			const next: "unset" | "on" | "off" =
+				value.state === "unset" ? "on" : value.state === "on" ? "off" : "unset";
+			return { kind: "tri-state", state: next };
+		}
+		case "select":
+			return { ...value, enabled: !value.enabled };
+		case "text":
+		case "optional-text":
+			return { ...value, enabled: !value.enabled };
+		case "text-list":
+			return { ...value, enabled: !value.enabled };
+		case "multi-with-custom":
+			return { ...value, enabled: !value.enabled };
+	}
+}
+
+/**
+ * `e` — edit the value. Modal flow varies by flag kind.
+ */
+async function editFlagValue(
+	flag: AliasFlag,
+	value: FlagValue,
+	modal: ReturnType<typeof useModal>,
+): Promise<FlagValue | null> {
+	switch (value.kind) {
+		case "boolean":
+			return { kind: "boolean", enabled: !value.enabled };
+
+		case "tri-state": {
+			const choice = await modal.select(
+				flag.label,
+				flag.description,
+				[
+					{ label: "Unset (no opinion)", value: "unset" },
+					{ label: `On (${flag.flag})`, value: "on" },
+					...(flag.triStateOff
+						? [{ label: `Off (${flag.triStateOff})`, value: "off" }]
+						: []),
+				],
+				["unset", "on", "off"].indexOf(value.state),
+			);
+			if (!choice) return null;
+			return { kind: "tri-state", state: choice as "unset" | "on" | "off" };
+		}
+
+		case "select": {
+			const opts = flag.options ?? [];
+			const choice = await modal.select(
+				flag.label,
+				flag.description,
+				[
+					{ label: "(disable)", value: "__off__" },
+					...opts.map((o) => ({ label: o.label, value: `v:${o.value}` })),
+				],
+				value.enabled
+					? Math.max(
+							0,
+							opts.findIndex((o) => o.value === value.value),
+						) + 1
+					: 0,
+			);
+			if (choice === null) return null;
+			if (choice === "__off__") return { ...value, enabled: false };
+			return {
+				kind: "select",
+				enabled: true,
+				value: choice.replace(/^v:/, ""),
+			};
+		}
+
+		case "text": {
+			// Lead with a 2-option chooser so the user can disable without going
+			// through `r` reset. Selecting "Set value" jumps to the input modal.
+			const action = await modal.select(
+				flag.label,
+				flag.description,
+				value.enabled
+					? [
+							{
+								label: `Edit value (current: "${truncate(value.value, 32)}")`,
+								value: "__edit__",
+							},
+							{ label: "Disable flag", value: "__off__" },
+						]
+					: [
+							{ label: "Enable with value...", value: "__edit__" },
+							{ label: "Keep disabled", value: "__off__" },
+						],
+				0,
+			);
+			if (action === null) return null;
+			if (action === "__off__") {
+				return { kind: "text", enabled: false, value: value.value };
+			}
+			const v = await modal.input(flag.label, flag.description, value.value);
+			if (v === null) return null;
+			return { kind: "text", enabled: v.length > 0, value: v };
+		}
+
+		case "optional-text": {
+			// Three-option lead: edit value, bare (no value), or disable.
+			const action = await modal.select(
+				flag.label,
+				flag.description,
+				[
+					{
+						label:
+							value.enabled && value.value
+								? `Edit value (current: "${truncate(value.value, 32)}")`
+								: "Set value...",
+						value: "__edit__",
+					},
+					{ label: "Bare flag (no value)", value: "__bare__" },
+					{ label: "Disable flag", value: "__off__" },
+				],
+				value.enabled ? (value.value ? 0 : 1) : 2,
+			);
+			if (action === null) return null;
+			if (action === "__off__") {
+				return { kind: "optional-text", enabled: false, value: value.value };
+			}
+			if (action === "__bare__") {
+				return { kind: "optional-text", enabled: true, value: "" };
+			}
+			const v = await modal.input(flag.label, flag.description, value.value);
+			if (v === null) return null;
+			return { kind: "optional-text", enabled: true, value: v };
+		}
+
+		case "text-list":
+		case "multi-with-custom":
+			// These kinds are routed to the flag-detail sub-screen by
+			// `editSelected`, never to this modal-based editor. If you see this
+			// throw, the caller bypassed the routing in editSelected — fix that
+			// instead of re-introducing the modal cascade.
+			throw new Error(
+				`${flag.kind} flags use the flag-detail sub-screen, not the modal editor`,
+			);
+	}
+}
+
+// ─── Render helpers ─────────────────────────────────────────────────────
+
+/**
+ * The alias-name row sits above all flag groups. We render it with a clear
+ * "Alias:" label and the value styled as the editable field, plus an `[edit]`
+ * hint, so it doesn't blend in with the flag rows below.
+ */
+function renderAliasNameRow(name: string, selected: boolean): React.ReactNode {
+	if (selected) {
+		return (
+			<box key="alias-name-row" flexDirection="row">
+				<text bg={theme.colors.accent} fg={theme.hints.fg}>
+					{`▶ Alias name:  ${name}    [enter to edit]`}
+				</text>
+			</box>
+		);
+	}
+	return (
+		<text key="alias-name-row">
+			<span fg={theme.colors.muted}>{"  Alias name:  "}</span>
+			<span fg={theme.colors.info}>
+				<strong>{name}</strong>
+			</span>
+			<span fg={theme.colors.muted}>{"    [enter to edit]"}</span>
+		</text>
+	);
+}
+
+/** Stable key per item for the windowed list. */
+function getItemKey(item: Item): string {
+	switch (item.kind) {
+		case "alias-name":
+			return "alias-name";
+		case "flag":
+			return `flag:${item.row.flag.id}`;
+		case "header":
+			return `header:${item.label}`;
+	}
+}
+
+/** Dispatch render for one flat-list item. */
+function renderItem(
+	item: Item,
+	isSelected: boolean,
+	isGated: (f: AliasFlag) => boolean,
+): React.ReactNode {
+	switch (item.kind) {
+		case "alias-name":
+			return renderAliasNameRow(item.row.value, isSelected);
+		case "flag":
+			return renderRow(item.row, isSelected, isGated(item.row.flag));
+		case "header":
+			return <text fg={theme.colors.accent}>{item.label}</text>;
+	}
+}
+
+function renderRow(
+	row: FlagRow,
+	selected: boolean,
+	gated: boolean,
+): React.ReactNode {
+	// Prefer the precomputed effective state (e.g. --channels shows enabled when
+	// a dev-loaded channel forces it to emit) over the flag's own enabled flag.
+	const enabled = row.effectiveEnabled ?? isFlagEnabled(row.value);
+	const marker = enabled ? "[x]" : "[ ]";
+	const issueMark = row.issue ? " ⚠" : "";
+	const fg = gated
+		? theme.colors.muted
+		: enabled
+			? theme.colors.text
+			: theme.colors.muted;
+	// Only show a value suffix when the flag carries non-redundant detail.
+	// Boolean / tri-state state is fully conveyed by the checkbox. A precomputed
+	// effectiveDetail (e.g. --channels union count) wins over the own-value one.
+	const detail = row.effectiveDetail ?? enabledDetail(row.value);
+	const detailSuffix = detail ? `  ${detail}` : "";
+	const line = `${selected ? "▶ " : "  "}${marker} ${row.flag.flag}${detailSuffix}${issueMark}`;
+	if (selected) {
+		return (
+			<text key={row.flag.id} bg={theme.colors.accent} fg={theme.hints.fg}>
+				{line}
+			</text>
+		);
+	}
+	return (
+		<text key={row.flag.id} fg={fg}>
+			{line}
+		</text>
+	);
+}
+
+/**
+ * Per-row trailing detail. Returns "" for booleans and tri-states (their state
+ * is already in the checkbox) and for disabled flags (no need to advertise an
+ * unset value). Non-empty for flags that carry an extra value the checkbox
+ * doesn't capture.
+ */
+function enabledDetail(value: FlagValue): string {
+	switch (value.kind) {
+		case "boolean":
+		case "tri-state":
+			return "";
+		case "select":
+			if (!value.enabled) return "";
+			return value.value === "" ? "(bare)" : value.value;
+		case "text":
+		case "optional-text":
+			if (!value.enabled) return "";
+			return value.value ? truncate(value.value, 24) : "(empty)";
+		case "text-list":
+			if (!value.enabled) return "";
+			return value.values.length === 0 ? "(empty)" : `${value.values.length}`;
+		case "multi-with-custom": {
+			if (!value.enabled) return "";
+			const total = new Set([...value.picked, ...value.custom]).size;
+			return total === 0 ? "(no filter)" : `${total} token(s)`;
+		}
+	}
+}
+
+function renderDetail(
+	row: Row | undefined,
+	isGated: (f: AliasFlag) => boolean,
+	aliasName: string,
+	segments: Segment[],
+): React.ReactNode {
+	if (!row) {
+		return <text fg={theme.colors.muted}>No row selected.</text>;
+	}
+
+	const headerAndBody =
+		row.kind === "alias-name"
+			? renderAliasNameDetail(row)
+			: renderFlagDetail(row, isGated);
+
+	// Preview is the only "global" element kept in the detail panel — it
+	// updates as the user toggles, which is the strongest visual feedback for
+	// "what alias am I building". We show argv one-per-line rather than the
+	// raw POSIX-escaped alias body (which contains `'\''` sequences that look
+	// alarming to readers who don't know the close-escape-reopen pattern).
+	return (
+		<box flexDirection="column">
+			{headerAndBody}
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.muted}>Preview:</text>
+			{renderPreviewLines(aliasName, segments)}
+		</box>
+	);
+}
+
+function renderAliasNameDetail(row: AliasNameRow): React.ReactNode {
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.text}>
+				<strong>Alias name</strong>
+			</text>
+			<text fg={theme.colors.muted}>
+				Shell name for the wrapped claude command. Default: "c". Letters,
+				digits, _ or - only.
+			</text>
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.text}>
+				<span fg={theme.colors.muted}>Current: </span>
+				<span fg={theme.colors.text}>
+					<strong>{row.value}</strong>
+				</span>
+			</text>
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.muted}>Enter to rename. r resets to "c".</text>
+		</box>
+	);
+}
+
+function renderFlagDetail(
+	row: FlagRow,
+	isGated: (f: AliasFlag) => boolean,
+): React.ReactNode {
+	const gated = isGated(row.flag);
+	// State must agree with the checkbox and the Preview. For --channels we show
+	// the effective channel-list summary (union of own + derived); other flags
+	// use their own value summary.
+	const stateText = row.stateSummary ?? summarizeValue(row.value);
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.text}>
+				<strong>{row.flag.flag}</strong>
+			</text>
+			<text fg={theme.colors.muted}>{row.flag.description}</text>
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.text}>
+				<span fg={theme.colors.muted}>State: </span>
+				<span fg={theme.colors.text}>{stateText}</span>
+			</text>
+			{gated && (
+				<text fg={theme.colors.muted}>
+					{`Depends on --${row.flag.requires}. Enabling this will turn that on too.`}
+				</text>
+			)}
+			{row.issue && (
+				<text fg={theme.colors.warning}>{`Conflict: ${row.issue.reason}`}</text>
+			)}
+		</box>
+	);
+}
+
+/**
+ * Render the alias preview as one argv arg per line. This replaces the raw
+ * POSIX-escaped alias body (`alias c='claude '\''text with spaces'\'' …'`),
+ * which is correct but visually alarming — readers without POSIX shell
+ * fluency mistake `'\''` for broken quoting.
+ *
+ * We show each argv token on its own row, with values that need quoting
+ * wrapped in plain double quotes (display-only — these are NOT what gets
+ * written to the rc file). Composite segments (templated values) display
+ * with their `{token}` placeholders intact in cyan so users see exactly
+ * what will expand at shell-eval time.
+ *
+ * Example output:
+ *   alias c='claude
+ *     --dangerously-skip-permissions
+ *     --append-system-prompt  "you ae the smaretes model ever"
+ *     --debug                 plugins
+ *   '
+ */
+function renderPreviewLines(
+	aliasName: string,
+	segments: Segment[],
+): React.ReactNode {
+	if (segments.length === 0) {
+		return (
+			<text fg={theme.colors.text}>{`alias ${aliasName || "?"}='claude'`}</text>
+		);
+	}
+	const lines: React.ReactNode[] = [
+		<text
+			key="head"
+			fg={theme.colors.text}
+		>{`alias ${aliasName || "?"}='claude`}</text>,
+	];
+	segments.forEach((seg, i) => {
+		lines.push(
+			// biome-ignore lint/suspicious/noArrayIndexKey: alias arguments are positional by definition and identical tokens can legitimately repeat; the preview re-renders whole
+			<text key={`arg-${i}`} fg={theme.colors.text}>
+				{"  "}
+				{renderPreviewSegment(seg)}
+			</text>,
+		);
+	});
+	lines.push(
+		<text key="tail" fg={theme.colors.text}>
+			{"'"}
+		</text>,
+	);
+	return <>{lines}</>;
+}
+
+function renderPreviewSegment(seg: Segment): React.ReactNode {
+	if (seg.kind === "literal") {
+		return <span fg={theme.colors.text}>{quoteForDisplay(seg.text)}</span>;
+	}
+	// Composite: literal parts as-is, raw parts as `{token}` reconstructed
+	// from the writer's TOKEN_TO_SUB map. We don't have direct access to the
+	// map here, so we reverse-lookup using the same forms.
+	const spans: React.ReactNode[] = [];
+	seg.parts.forEach((p, i) => {
+		if (p.kind === "literal") {
+			spans.push(
+				// biome-ignore lint/suspicious/noArrayIndexKey: parts of one composite argument are positional text fragments with no identity of their own
+				<span key={`p-${i}`} fg={theme.colors.text}>
+					{p.text}
+				</span>,
+			);
+		} else {
+			spans.push(
+				// biome-ignore lint/suspicious/noArrayIndexKey: same positional fragment list as above
+				<span key={`p-${i}`} fg={theme.colors.info}>
+					{substitutionToToken(p.posix)}
+				</span>,
+			);
+		}
+	});
+	return <span>{spans}</span>;
+}
+
+const PREVIEW_SAFE = /^[A-Za-z0-9_\-=,:.\/!@%+]+$/;
+
+function quoteForDisplay(text: string): string {
+	if (text === "") return '""';
+	if (PREVIEW_SAFE.test(text)) return text;
+	// Display-only quoting. We don't have to escape anything for the shell
+	// since this string never reaches a parser — it's just for the user to
+	// read. We do escape an embedded `"` to keep visual balance.
+	return `"${text.replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Reverse-lookup the writer's POSIX substitution codes to their `{token}`
+ * forms. Mirror of `TOKEN_TO_SUB` in `alias-shell-writer.ts`.
+ */
+function substitutionToToken(posixCode: string): string {
+	switch (posixCode) {
+		case '$(basename "$PWD")':
+			return "{folder}";
+		case "$(date +%d)":
+			return "{day}";
+		case "$(date +%m)":
+			return "{month}";
+		case "$(date +%Y)":
+			return "{year}";
+		default:
+			return posixCode;
+	}
+}
+
+function renderFlagDetailRightPane(
+	flag: AliasFlag,
+	value: FlagValue,
+	aliasName: string,
+	segments: Segment[],
+	derivedNote?: string,
+	stateOverride?: string,
+): React.ReactNode {
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.text}>
+				<strong>{flag.flag}</strong>
+			</text>
+			<text fg={theme.colors.muted}>{flag.description}</text>
+			{derivedNote && (
+				<>
+					<text fg={theme.colors.text}> </text>
+					<text fg={theme.colors.muted}>{derivedNote}</text>
+				</>
+			)}
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.text}>
+				<span fg={theme.colors.muted}>State: </span>
+				<span fg={theme.colors.text}>
+					{stateOverride ?? summarizeValue(value)}
+				</span>
+			</text>
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.muted}>Preview:</text>
+			{renderPreviewLines(aliasName, segments)}
+			<text fg={theme.colors.text}> </text>
+			<text fg={theme.colors.muted}>Keys:</text>
+			<text fg={theme.colors.text}>
+				{" "}
+				space/enter toggle the highlighted row
+			</text>
+			<text fg={theme.colors.text}> a add a new value</text>
+			<text fg={theme.colors.text}> d delete the highlighted item</text>
+			<text fg={theme.colors.text}> h back to flag list</text>
+		</box>
+	);
+}