claudeup 4.17.0 → 4.18.0

package/src/ui/screens/AliasScreen.tsx

@@ -0,0 +1,1402 @@
+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 } from "../components/layout/index.js";
+import {
+  ALIAS_FLAGS,
+  FLAG_GROUPS,
+  type AliasFlag,
+} from "../../data/alias-flags.js";
+import {
+  defaultAliasConfig,
+  defaultValueFor,
+  validateAliasName,
+  DEFAULT_ALIAS_NAME,
+  type AliasConfig,
+  type FlagValue,
+} from "../../services/alias-store.js";
+import { loadAliasName, saveAliasName } from "../../services/alias-settings.js";
+import {
+  detectShells,
+  renderArgs,
+  renderAlias,
+  validateConfig,
+  writeAliasToShell,
+  parseAliasFromRc,
+  type ShellTarget,
+  type FlagValidationIssue,
+} 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;
+}
+
+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 };
+
+/**
+ * Items shown in the flag-detail sub-screen. Distinct from `Item` because the
+ * navigation context is different (one flag, not the whole catalog).
+ */
+type DetailItem =
+  | { kind: "toggle"; enabled: boolean }
+  | { kind: "value"; index: number; text: string }
+  | { kind: "picklist"; token: string; picked: boolean }
+  | { kind: "custom"; index: number; text: string }
+  | { kind: "add" }
+  | { kind: "header"; label: string };
+
+function isSelectableDetailItem(item: DetailItem): boolean {
+  return item.kind !== "header";
+}
+
+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" });
+  const [detailSelectedIdx, setDetailSelectedIdx] = useState(0);
+  // 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,
+  );
+
+  // ── 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;
+        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.)
+            }
+          } catch {
+            // rc unreadable — fall back to defaults; not a hard error.
+          }
+        }
+
+        if (cancelled) return;
+        setConfig(base);
+        setShells(s);
+        setRcSnapshot(parsedFlags ?? base.flags);
+      } 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) {
+        out.push({
+          kind: "flag",
+          row: {
+            kind: "flag",
+            flag,
+            value: config.flags[flag.id] ?? defaultValueFor(flag),
+            issue: issueMap.get(flag.id),
+          },
+        });
+      }
+    }
+
+    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
+  // value in `config.flags[flagId]`. Kinds vary by flag.kind (text-list vs
+  // multi-with-custom).
+  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;
+
+  const detailItems: DetailItem[] = useMemo(() => {
+    if (!detailFlag || !detailValue) return [];
+    if (detailValue.kind === "text-list") {
+      const out: DetailItem[] = [
+        { kind: "toggle", enabled: detailValue.enabled },
+      ];
+      if (detailValue.values.length > 0) {
+        out.push({ kind: "header", label: "Values" });
+        detailValue.values.forEach((v, i) =>
+          out.push({ kind: "value", index: i, text: v }),
+        );
+      }
+      out.push({ kind: "add" });
+      return out;
+    }
+    if (detailValue.kind === "multi-with-custom") {
+      const pickedSet = new Set(detailValue.picked);
+      const out: DetailItem[] = [
+        { kind: "toggle", enabled: detailValue.enabled },
+      ];
+      if ((detailFlag.picklist?.length ?? 0) > 0) {
+        out.push({ kind: "header", label: "Common filters" });
+        for (const tok of detailFlag.picklist!) {
+          out.push({ kind: "picklist", token: tok, picked: pickedSet.has(tok) });
+        }
+      }
+      if (detailValue.custom.length > 0) {
+        out.push({ kind: "header", label: "Custom tokens" });
+        detailValue.custom.forEach((v, i) =>
+          out.push({ kind: "custom", index: i, text: v }),
+        );
+      }
+      out.push({ kind: "add" });
+      return out;
+    }
+    return [];
+  }, [detailFlag, detailValue]);
+
+  const detailSelectableIndices = useMemo(
+    () => detailItems.flatMap((it, i) => (isSelectableDetailItem(it) ? [i] : [])),
+    [detailItems],
+  );
+
+  // Reset detail selection on entering / on items shape change.
+  useEffect(() => {
+    if (viewMode.kind !== "flag-detail") return;
+    if (detailSelectableIndices.length === 0) return;
+    if (!detailItems[detailSelectedIdx] || !isSelectableDetailItem(detailItems[detailSelectedIdx])) {
+      setDetailSelectedIdx(detailSelectableIndices[0]);
+    }
+  }, [viewMode, detailItems, detailSelectableIndices, detailSelectedIdx]);
+
+  // ── 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 };
+      });
+    },
+    [],
+  );
+
+  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") {
+      setDetailSelectedIdx(0);
+      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 {
+      const r = await writeAliasToShell(config, target);
+      await modal.message(
+        "Alias written",
+        `${r.action === "created" ? "Created" : "Updated"} ${r.path}\n\nRun \`source ${r.path}\` or open a new shell to use it.`,
+        "success",
+      );
+      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]);
+
+  // ── 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],
+  );
+
+  // ── Flag-detail sub-screen mutators ───────────────────────────────────
+  const moveDetailSelection = useCallback(
+    (dir: 1 | -1) => {
+      if (detailSelectableIndices.length === 0) return;
+      const cursorPos = detailSelectableIndices.indexOf(detailSelectedIdx);
+      const nextPos =
+        cursorPos === -1
+          ? dir === 1
+            ? 0
+            : detailSelectableIndices.length - 1
+          : Math.min(
+              detailSelectableIndices.length - 1,
+              Math.max(0, cursorPos + dir),
+            );
+      setDetailSelectedIdx(detailSelectableIndices[nextPos]);
+    },
+    [detailSelectableIndices, detailSelectedIdx],
+  );
+
+  const handleDetailToggle = useCallback(() => {
+    if (!detailFlag || !detailValue) return;
+    const item = detailItems[detailSelectedIdx];
+    if (!item) return;
+    if (item.kind === "toggle") {
+      if (detailValue.kind === "text-list") {
+        updateFlag(detailFlag.id, { ...detailValue, enabled: !detailValue.enabled });
+      } else if (detailValue.kind === "multi-with-custom") {
+        updateFlag(detailFlag.id, { ...detailValue, enabled: !detailValue.enabled });
+      }
+      return;
+    }
+    if (item.kind === "picklist" && detailValue.kind === "multi-with-custom") {
+      const pickedSet = new Set(detailValue.picked);
+      const next = pickedSet.has(item.token)
+        ? detailValue.picked.filter((p) => p !== item.token)
+        : [...detailValue.picked, item.token];
+      updateFlag(detailFlag.id, {
+        ...detailValue,
+        enabled: true,
+        picked: next,
+      });
+      return;
+    }
+    if (item.kind === "add") {
+      void handleDetailAdd();
+      return;
+    }
+    // value / custom rows: enter does nothing destructive; use `d` to delete.
+  }, [detailFlag, detailValue, detailItems, detailSelectedIdx, updateFlag]);
+
+  const handleDetailAdd = useCallback(async () => {
+    if (!detailFlag || !detailValue) return;
+    if (detailValue.kind === "text-list") {
+      const v = await modal.input(`Add to ${detailFlag.flag}`, "Value");
+      if (v === null || v.length === 0) return;
+      updateFlag(detailFlag.id, {
+        ...detailValue,
+        enabled: true,
+        values: [...detailValue.values, v],
+      });
+      return;
+    }
+    if (detailValue.kind === "multi-with-custom") {
+      const v = await modal.input(
+        `Add custom token`,
+        'Token (e.g. "router" or "!file" for negation)',
+      );
+      if (v === null || v.length === 0) return;
+      updateFlag(detailFlag.id, {
+        ...detailValue,
+        enabled: true,
+        custom: [...detailValue.custom, v],
+      });
+      return;
+    }
+  }, [detailFlag, detailValue, modal, updateFlag]);
+
+  const handleDetailDelete = useCallback(async () => {
+    if (!detailFlag || !detailValue) return;
+    const item = detailItems[detailSelectedIdx];
+    if (!item) return;
+    if (item.kind === "value" && detailValue.kind === "text-list") {
+      const target = detailValue.values[item.index];
+      const ok = await modal.confirm(
+        "Remove item?",
+        `Remove "${truncate(target, 60)}" from ${detailFlag.flag}?`,
+      );
+      if (!ok) return;
+      updateFlag(detailFlag.id, {
+        ...detailValue,
+        values: detailValue.values.filter((_, i) => i !== item.index),
+      });
+      return;
+    }
+    if (item.kind === "custom" && detailValue.kind === "multi-with-custom") {
+      const target = detailValue.custom[item.index];
+      const ok = await modal.confirm(
+        "Remove custom token?",
+        `Remove "${truncate(target, 60)}" from ${detailFlag.flag}?`,
+      );
+      if (!ok) return;
+      updateFlag(detailFlag.id, {
+        ...detailValue,
+        custom: detailValue.custom.filter((_, i) => i !== item.index),
+      });
+      return;
+    }
+  }, [detailFlag, detailValue, detailItems, detailSelectedIdx, modal, updateFlag]);
+
+  const exitDetail = useCallback(() => {
+    setViewMode({ kind: "main" });
+    setDetailSelectedIdx(0);
+  }, []);
+
+  // ── Keyboard handler ──────────────────────────────────────────────────
+  // Dispatches on viewMode so sub-screen keybindings don't leak into main.
+  useKeyboardHandler((input, key) => {
+    if (state.modal) return;
+
+    if (viewMode.kind === "flag-detail") {
+      if (input === "j" || key.downArrow) {
+        moveDetailSelection(1);
+        return;
+      }
+      if (input === "k" || key.upArrow) {
+        moveDetailSelection(-1);
+        return;
+      }
+      if (key.return || input === " " || key.name === "space") {
+        handleDetailToggle();
+        return;
+      }
+      if (input === "a") {
+        void handleDetailAdd();
+        return;
+      }
+      if (input === "d") {
+        void handleDetailDelete();
+        return;
+      }
+      if (input === "h") {
+        exitDetail();
+        return;
+      }
+      // Esc is handled by the global handler — it'll exit the entire screen
+      // back to plugins, which is fine. `h` is the documented "back to main".
+      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 previewBlock = config ? renderAlias(config, "zsh").block : "";
+
+  // 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);
+  const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
+
+  useEffect(() => {
+    mainScrollRef.current?.scrollChildIntoView(`alias-row-${selectedIdx}`);
+  }, [selectedIdx]);
+
+  useEffect(() => {
+    if (viewMode.kind !== "flag-detail") return;
+    detailScrollRef.current?.scrollChildIntoView(
+      `alias-detail-row-${detailSelectedIdx}`,
+    );
+  }, [detailSelectedIdx, viewMode]);
+
+  const inDetail = viewMode.kind === "flag-detail" && detailFlag && detailValue;
+
+  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) => (
+            <box key={getItemKey(item)} id={`alias-row-${idx}`}>
+              {renderItem(item, idx === selectedIdx, isGated)}
+            </box>
+          ))}
+        </box>
+      </scrollbox>
+    </box>
+  );
+
+  const detailListPanel = inDetail ? (
+    <box flexDirection="column" height="100%">
+      <text fg="#7e57c2">
+        <strong>{detailFlag.flag}</strong>
+      </text>
+      <text fg="gray">{`(h to go back to all flags)`}</text>
+      <text> </text>
+      <scrollbox
+        ref={detailScrollRef}
+        scrollY={true}
+        scrollX={false}
+        flexGrow={1}
+      >
+        <box flexDirection="column">
+          {detailItems.map((item, idx) => (
+            <box key={getDetailItemKey(item, idx)} id={`alias-detail-row-${idx}`}>
+              {renderDetailItem(item, idx === detailSelectedIdx)}
+            </box>
+          ))}
+        </box>
+      </scrollbox>
+    </box>
+  ) : null;
+
+  const listPanel = inDetail ? detailListPanel : mainListPanel;
+
+  const mainDetailPanel = renderDetail(selectedRow, isGated, previewBlock);
+  const detailDetailPanel = inDetail
+    ? renderFlagDetailRightPane(detailFlag, detailValue, previewBlock)
+    : null;
+  const detailPanel = inDetail ? detailDetailPanel : mainDetailPanel;
+
+  const enabledCount = config
+    ? Object.values(config.flags).filter(isFlagEnabled).length
+    : 0;
+  const subtitle = inDetail
+    ? `editing ${detailFlag.flag}`
+    : 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 = inDetail
+    ? renderFooterHints([
+        { keys: ["↑", "↓"], label: "move" },
+        { keys: ["space"], label: "toggle" },
+        { keys: ["a"], label: "add" },
+        { keys: ["d"], label: "delete" },
+        { keys: ["h"], label: "back" },
+      ])
+    : renderFooterHints([
+        { 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 ────────────────────────────────────────────────────────────
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * 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 {
+  const enabled = 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.
+  const detail = 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,
+  previewBlock: string,
+): 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". Shells live in the list-panel legend.
+  return (
+    <box flexDirection="column">
+      {headerAndBody}
+      <text> </text>
+      <text fg="gray">Preview (zsh/bash):</text>
+      <text fg="white">{firstLine(previewBlock, 1)}</text>
+    </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);
+  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">{summarizeValue(row.value)}</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>
+  );
+}
+
+function firstLine(block: string, skip: number): string {
+  const lines = block.split("\n");
+  return lines[skip] ?? "";
+}
+
+/**
+ * Render footer hints as keycap badges + labels. Keys are rendered with an
+ * inverted color (white bg, dark fg) so they read as visual chips rather
+ * than letters dropped into prose. Multi-key bindings (`↑↓`) render as one
+ * combined badge.
+ */
+function renderFooterHints(
+  hints: Array<{ keys: string[]; label: string }>,
+): React.ReactNode {
+  const nodes: React.ReactNode[] = [];
+  hints.forEach((hint, i) => {
+    if (i > 0) {
+      nodes.push(
+        <span key={`gap-${i}`} fg="gray">
+          {"   "}
+        </span>,
+      );
+    }
+    nodes.push(
+      <span key={`k-${i}`} bg="#3f3f46" fg="#fafafa">
+        {` ${hint.keys.join("")} `}
+      </span>,
+    );
+    nodes.push(
+      <span key={`l-${i}`} fg="gray">
+        {` ${hint.label}`}
+      </span>,
+    );
+  });
+  return <text>{nodes}</text>;
+}
+
+// ─── Flag-detail sub-screen render helpers ─────────────────────────────
+
+function getDetailItemKey(item: DetailItem, idx: number): string {
+  switch (item.kind) {
+    case "toggle":
+      return "toggle";
+    case "value":
+      return `value:${item.index}`;
+    case "picklist":
+      return `pick:${item.token}`;
+    case "custom":
+      return `custom:${item.index}`;
+    case "add":
+      return "add";
+    case "header":
+      return `header:${item.label}:${idx}`;
+  }
+}
+
+function renderDetailItem(
+  item: DetailItem,
+  isSelected: boolean,
+): React.ReactNode {
+  if (item.kind === "header") {
+    return <text fg="#7e57c2">{item.label}</text>;
+  }
+  const cursor = isSelected ? "▶ " : "  ";
+  let body: string;
+  switch (item.kind) {
+    case "toggle":
+      body = `[${item.enabled ? "x" : " "}] Enable flag`;
+      break;
+    case "value":
+      body = item.text;
+      break;
+    case "picklist":
+      body = `[${item.picked ? "x" : " "}] ${item.token}`;
+      break;
+    case "custom":
+      body = item.text;
+      break;
+    case "add":
+      body = "+ Add new...";
+      break;
+  }
+  const line = `${cursor}${body}`;
+  if (isSelected) {
+    return (
+      <text bg="#7e57c2" fg="white">
+        {line}
+      </text>
+    );
+  }
+  return <text fg="white">{line}</text>;
+}
+
+function renderFlagDetailRightPane(
+  flag: AliasFlag,
+  value: FlagValue,
+  previewBlock: string,
+): React.ReactNode {
+  return (
+    <box flexDirection="column">
+      <text fg="white">
+        <strong>{flag.flag}</strong>
+      </text>
+      <text fg="gray">{flag.description}</text>
+      <text> </text>
+      <text>
+        <span fg="gray">State: </span>
+        <span fg="white">{summarizeValue(value)}</span>
+      </text>
+      <text> </text>
+      <text fg="gray">Preview (zsh/bash):</text>
+      <text fg="white">{firstLine(previewBlock, 1)}</text>
+      <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>
+  );
+}