claudeup 4.17.0 → 4.19.0

package/src/ui/screens/AliasScreen.tsx

@@ -0,0 +1,1534 @@
+import React, { useEffect, useState, useCallback, useMemo, useRef } from "react";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import { useApp, useModal } from "../state/AppContext.js";
+import { useKeyboardHandler } from "../hooks/useKeyboardHandler.js";
+import { ScreenLayout, type FooterHint } from "../components/layout/index.js";
+import { FlagDetailEditor } from "../components/FlagDetailEditor.js";
+import {
+  ALIAS_FLAGS,
+  FLAG_GROUPS,
+  type AliasFlag,
+} from "../../data/alias-flags.js";
+import {
+  defaultAliasConfig,
+  defaultValueFor,
+  validateAliasName,
+  derivedChannelValues,
+  withoutDerivedChannel,
+  CHANNELS_FLAG_ID,
+  DEFAULT_ALIAS_NAME,
+  type AliasConfig,
+  type FlagValue,
+} from "../../services/alias-store.js";
+import { loadAliasName, saveAliasName } from "../../services/alias-settings.js";
+import {
+  detectShells,
+  renderArgs,
+  validateConfig,
+  writeAliasToShell,
+  parseAliasFromRc,
+  findAdoptableAlias,
+  type ShellTarget,
+  type FlagValidationIssue,
+  type Segment,
+  type AdoptableAlias,
+} from "../../services/alias-shell-writer.js";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+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>();
+          while (queue.length > 0) {
+            const 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="gray">{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="#7e57c2" fg="white">
+          {`▶ Alias name:  ${name}    [enter to edit]`}
+        </text>
+      </box>
+    );
+  }
+  return (
+    <text key="alias-name-row">
+      <span fg="gray">{"  Alias name:  "}</span>
+      <span fg="cyan">
+        <strong>{name}</strong>
+      </span>
+      <span fg="gray">{"    [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="#7e57c2">{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 ? "gray" : enabled ? "white" : "gray";
+  // 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="#7e57c2" fg="white">
+        {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="gray">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> </text>
+      <text fg="gray">Preview:</text>
+      {renderPreviewLines(aliasName, segments)}
+    </box>
+  );
+}
+
+function renderAliasNameDetail(row: AliasNameRow): React.ReactNode {
+  return (
+    <box flexDirection="column">
+      <text fg="white">
+        <strong>Alias name</strong>
+      </text>
+      <text fg="gray">
+        Shell name for the wrapped claude command. Default: "c". Letters,
+        digits, _ or - only.
+      </text>
+      <text> </text>
+      <text>
+        <span fg="gray">Current: </span>
+        <span fg="white">
+          <strong>{row.value}</strong>
+        </span>
+      </text>
+      <text> </text>
+      <text fg="gray">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="white">
+        <strong>{row.flag.flag}</strong>
+      </text>
+      <text fg="gray">{row.flag.description}</text>
+      <text> </text>
+      <text>
+        <span fg="gray">State: </span>
+        <span fg="white">{stateText}</span>
+      </text>
+      {gated && (
+        <text fg="gray">
+          {`Depends on --${row.flag.requires}. Enabling this will turn that on too.`}
+        </text>
+      )}
+      {row.issue && (
+        <text fg="yellow">{`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="white">{`alias ${aliasName || "?"}='claude'`}</text>;
+  }
+  const lines: React.ReactNode[] = [
+    <text key="head" fg="white">{`alias ${aliasName || "?"}='claude`}</text>,
+  ];
+  segments.forEach((seg, i) => {
+    lines.push(
+      <text key={`arg-${i}`} fg="white">
+        {"  "}
+        {renderPreviewSegment(seg)}
+      </text>,
+    );
+  });
+  lines.push(
+    <text key="tail" fg="white">
+      {"'"}
+    </text>,
+  );
+  return <>{lines}</>;
+}
+
+function renderPreviewSegment(seg: Segment): React.ReactNode {
+  if (seg.kind === "literal") {
+    return <span fg="white">{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(
+        <span key={`p-${i}`} fg="white">
+          {p.text}
+        </span>,
+      );
+    } else {
+      spans.push(
+        <span key={`p-${i}`} fg="cyan">
+          {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="white">
+        <strong>{flag.flag}</strong>
+      </text>
+      <text fg="gray">{flag.description}</text>
+      {derivedNote && (
+        <>
+          <text> </text>
+          <text fg="gray">{derivedNote}</text>
+        </>
+      )}
+      <text> </text>
+      <text>
+        <span fg="gray">State: </span>
+        <span fg="white">{stateOverride ?? summarizeValue(value)}</span>
+      </text>
+      <text> </text>
+      <text fg="gray">Preview:</text>
+      {renderPreviewLines(aliasName, segments)}
+      <text> </text>
+      <text fg="gray">Keys:</text>
+      <text fg="white">  space/enter toggle the highlighted row</text>
+      <text fg="white">  a add a new value</text>
+      <text fg="white">  d delete the highlighted item</text>
+      <text fg="white">  h back to flag list</text>
+    </box>
+  );
+}