spinuptui 0.19.0

package/src/ui/Explain.tsx

@@ -0,0 +1,158 @@
+// "Explain this screen" overlay — contextual, in-context guidance (Pass 2).
+//
+// Distinct from the `?` keybinding reference: this is scoped to the CURRENT view
+// and speaks in outcomes — what each pane is for and what each action actually
+// accomplishes *here*. Opened with `i` from any view. Because it's per-route,
+// every new (often novel) workflow ships with its own plain-language explanation
+// rather than relying on the user to translate a flat key-list back to the screen.
+
+import { theme } from "../lib/theme.ts"
+import type { Route } from "./store.tsx"
+
+interface Guide {
+  title: string
+  summary: string
+  panes?: [string, string][]
+  actions: [string, string][]
+}
+
+const GUIDES: Record<Route, Guide> = {
+  dashboard: {
+    title: "Dashboard",
+    summary: "A high-level read on your whole account — fleet health, what needs attention, and recent activity.",
+    panes: [
+      ["Stat cards", "Totals: servers, sites, fleet disk, pending WordPress updates"],
+      ["Disk usage", "Servers ranked by how full their disk is"],
+      ["Needs attention", "Servers/sites with problems (offline, reboot or upgrade due)"],
+      ["Recent activity", "The latest deploys and operations"],
+    ],
+    actions: [
+      ["1–5", "Switch tabs"],
+      ["r", "Refresh from the API"],
+    ],
+  },
+  servers: {
+    title: "Servers",
+    summary: "Browse every server and drill into the sites it hosts.",
+    panes: [
+      ["Servers", "All your servers"],
+      ["Sites", "Sites on the selected server"],
+      ["Details", "Everything about the highlighted server or site"],
+    ],
+    actions: [
+      ["→ / ⏎", "Drill in (server → its sites)"],
+      ["h", "Server health over SSH (CPU / memory / disk)"],
+      ["a", "Server actions: reboot or restart a service"],
+      ["d", "Identify the app running on a site (SSH)"],
+      ["u", "Change a site's PHP version"],
+      ["o / w", "Open the site · open it in the SpinupWP web app"],
+      ["s", "Open a terminal and SSH into the site"],
+      ["t / v / L", "Local copy: open a terminal · open the local URL · link or edit"],
+    ],
+  },
+  stacks: {
+    title: "Stacks",
+    summary: "Your fleet grouped by app type (Standard WP / Bedrock / Non-WP), with a fleet-wide PHP version breakdown.",
+    panes: [
+      ["Groups", "App-type buckets; Non-WP expands into WHMCS / Laravel / …"],
+      ["Sites", "The sites in the selected group"],
+      ["PHP versions", "How many sites run each PHP version (EOL flagged)"],
+    ],
+    actions: [
+      ["d", "Identify the app on a site (SSH)"],
+      ["D", "Identify every app in the selected group"],
+      ["S", "Find local copies on your disk and link them"],
+      ["f", "Report sites with no local copy (filter by stack with ←/→)"],
+      ["u", "Change a site's PHP version"],
+      ["t / v / L", "Local copy: terminal · local URL · link or edit"],
+      ["o / w", "Open the site · open it in SpinupWP"],
+      ["s", "Open a terminal and SSH into the site"],
+    ],
+  },
+  search: {
+    title: "Search",
+    summary: "Jump to any server or site across your whole account by typing its name, domain, or IP.",
+    panes: [
+      ["Results", "Matches, narrowed as you type"],
+      ["Details / Actions", "Info on the selection, or its action menu when focused"],
+    ],
+    actions: [
+      ["type", "Filter results"],
+      ["Tab / →", "Hand focus from the box to the result's actions"],
+      ["o / w / u", "Open · open in SpinupWP · change PHP"],
+      ["s", "SSH into the site (opens a terminal)"],
+      ["t / v / L", "Local copy: terminal · local URL · link or edit"],
+      ["d / p / m", "DB backup · pull prod→local · production media fallback"],
+      ["a / h", "Server actions · server health"],
+    ],
+  },
+  events: {
+    title: "Events",
+    summary: "A live feed of deploys, reboots, and operations across your account.",
+    actions: [
+      ["1–5", "Switch tabs"],
+      ["r", "Refresh"],
+    ],
+  },
+}
+
+export function ExplainOverlay({ route }: { route: Route }) {
+  const g = GUIDES[route]
+  return (
+    <box
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        justifyContent: "center",
+        alignItems: "center",
+        zIndex: 120,
+      }}
+    >
+      <box
+        title={` ${g.title} — what's on this screen `}
+        titleColor={theme.brand}
+        bottomTitle=" press i or Esc to close "
+        bottomTitleAlignment="center"
+        border
+        borderColor={theme.borderActive}
+        backgroundColor={theme.bgPanel}
+        style={{ flexDirection: "column", width: 72, paddingLeft: 2, paddingRight: 2, paddingTop: 1, paddingBottom: 1 }}
+      >
+        <text content={g.summary} fg={theme.text} />
+        <box style={{ height: 1 }} />
+
+        {g.panes && (
+          <box style={{ flexDirection: "column" }}>
+            <text content="On screen" fg={theme.accent} attributes={1} />
+            {g.panes.map(([label, desc]) => (
+              <box key={label} style={{ flexDirection: "row" }}>
+                <text content={label.padEnd(16)} fg={theme.brand} wrapMode="none" style={{ flexShrink: 0 }} />
+                <text content={desc} fg={theme.textDim} wrapMode="none" style={{ flexShrink: 1 }} />
+              </box>
+            ))}
+            <box style={{ height: 1 }} />
+          </box>
+        )}
+
+        <text content="What you can do" fg={theme.accent} attributes={1} />
+        {g.actions.map(([k, desc]) => (
+          <box key={k} style={{ flexDirection: "row" }}>
+            <text content={k.padEnd(11)} fg={theme.brand} wrapMode="none" style={{ flexShrink: 0 }} />
+            <text content={desc} fg={theme.text} wrapMode="none" style={{ flexShrink: 1 }} />
+          </box>
+        ))}
+        <box style={{ height: 1 }} />
+
+        <box style={{ flexDirection: "row" }}>
+          <text content="◆ " fg={theme.good} style={{ flexShrink: 0 }} />
+          <text content="linked locally    " fg={theme.textDim} style={{ flexShrink: 0 }} />
+          <text content="↑N " fg={theme.warn} style={{ flexShrink: 0 }} />
+          <text content="pending WordPress updates" fg={theme.textDim} wrapMode="none" style={{ flexShrink: 1 }} />
+        </box>
+      </box>
+    </box>
+  )
+}

package/src/ui/Header.tsx

@@ -0,0 +1,117 @@
+// Top navigation bar: brand mark, tab strip, and live account summary.
+
+import { theme } from "../lib/theme.ts"
+import { useStore, isNewServerInFlight, isVanityInFlight, isCloneInFlight, type Route } from "./store.tsx"
+import { timeAgo, truncate } from "../lib/format.ts"
+import { Spinner } from "./components.tsx"
+import { APP_NAME, APP_VERSION } from "../version.ts"
+import { isDevMode } from "../dev/devMode.ts"
+
+const TABS: { route: Route; key: string; label: string }[] = [
+  { route: "dashboard", key: "1", label: "Dashboard" },
+  { route: "servers", key: "2", label: "Servers" },
+  { route: "stacks", key: "3", label: "Stacks" },
+  { route: "search", key: "4", label: "Search" },
+  { route: "events", key: "5", label: "Events" },
+]
+
+// A one-line "what is this view, and what can I do here" subtitle per tab —
+// the cheapest in-context teaching surface. Phrased in outcomes, naming the few
+// actions a user would reach for. Shown directly under the nav strip.
+const SUBTITLES: Record<Route, string> = {
+  dashboard: "Your account at a glance — fleet health, what needs attention, recent activity",
+  servers: "Browse servers and their sites  ·  h server health  ·  u change PHP  ·  L link a local copy",
+  stacks: "Your fleet grouped by app type  ·  d identify an app (SSH)  ·  S find local copies on your disk",
+  search: "Jump to any server or site by name  ·  Tab hands focus to the result's actions",
+  events: "Recent deploys, reboots, and operations across your account",
+}
+
+export function Header() {
+  const { route, servers, sites, loading, lastUpdated, updateInfo, newServerJob, vanityJob, cloneJob, cloneServer, kumaStatus } = useStore()
+  const kumaDown = [...kumaStatus.values()].filter((s) => s.up === false).length
+  const updateReady = updateInfo?.updateAvailable ?? false
+  const building = isNewServerInFlight(newServerJob)
+  // The sshkey step is the one that waits on the USER (add your key, confirm in
+  // the overlay) — a spinner there reads as "working" when nothing is running,
+  // so it gets a distinct waiting badge that says what it wants and where.
+  const vanityWaiting = vanityJob?.step === "sshkey"
+  const connecting = isVanityInFlight(vanityJob) && !vanityWaiting
+  const vanityStuck = vanityJob != null && vanityJob.step === "error"
+  // Show a clone badge only when it's running AND backgrounded (wizard closed) — the
+  // open wizard covers the screen, so no badge is needed there.
+  const cloning = isCloneInFlight(cloneJob) && cloneServer == null
+
+  return (
+    <box style={{ flexDirection: "column", flexShrink: 0 }}>
+      <box
+        style={{
+          flexDirection: "row",
+          height: 1,
+          backgroundColor: theme.bgAlt,
+          paddingLeft: 1,
+          paddingRight: 1,
+          alignItems: "center",
+        }}
+      >
+        <text content={`◆ ${APP_NAME}`} fg={theme.brand} style={{ flexShrink: 0 }} />
+        <text content={` v${APP_VERSION}`} fg={theme.textFaint} style={{ flexShrink: 0 }} />
+        {updateReady && <text content={` ✦ v${updateInfo!.latest}`} fg={theme.update} attributes={1} style={{ flexShrink: 0 }} />}
+        {isDevMode() && <text content=" DEV MODE " fg={theme.bg} bg={theme.purple} attributes={1} style={{ flexShrink: 0 }} />}
+        <box style={{ width: 2, flexShrink: 0 }} />
+        {TABS.map((tab) => {
+          const active = tab.route === route
+          return (
+            <box key={tab.route} style={{ flexDirection: "row", flexShrink: 0 }}>
+              <text content={` ${tab.key} `} fg={active ? theme.bg : theme.textFaint} bg={active ? theme.brand : undefined} />
+              <text
+                content={`${tab.label}  `}
+                fg={active ? theme.text : theme.textDim}
+                bg={active ? theme.bgPanel : undefined}
+              />
+            </box>
+          )
+        })}
+        <box style={{ flexGrow: 1 }} />
+        {/* A server provision runs for ~10 min in the background; surface it from
+            any tab so it isn't invisible once the New Server overlay is closed
+            (press c on the Servers tab to reopen the live tracker). */}
+        {building && (
+          <box style={{ flexDirection: "row", flexShrink: 0, alignItems: "center" }}>
+            <Spinner interval={120} color={theme.warn} />
+            <text content={`  Provisioning ${truncate(newServerJob!.hostname, 22)}  `} fg={theme.warn} wrapMode="none" />
+          </box>
+        )}
+        {/* Vanity build runs in the background too — surface it so it's reachable
+            after the site is created (press V on its server to reopen). A stuck
+            (errored) build is flagged too so it isn't lost. */}
+        {connecting && (
+          <box style={{ flexDirection: "row", flexShrink: 0, alignItems: "center" }}>
+            <Spinner interval={120} color={theme.warn} />
+            <text content={`  Connecting ${truncate(vanityJob!.hostname, 22)} — press V  `} fg={theme.warn} wrapMode="none" />
+          </box>
+        )}
+        {vanityWaiting && (
+          <text content={`  ○ ${truncate(vanityJob!.hostname, 20)} needs your SSH key — press V  `} fg={theme.warn} style={{ flexShrink: 0 }} wrapMode="none" />
+        )}
+        {vanityStuck && <text content={`  ⚠ ${truncate(vanityJob!.hostname, 20)} — press V  `} fg={theme.bad} style={{ flexShrink: 0 }} wrapMode="none" />}
+        {/* A backgrounded clone keeps running in the store — surface it so it's
+            reachable (press C on the source server to reopen the live roster). */}
+        {cloning && (
+          <box style={{ flexDirection: "row", flexShrink: 0, alignItems: "center" }}>
+            <Spinner interval={120} color={theme.warn} />
+            <text content={`  Cloning ${truncate(cloneJob!.sourceServerName, 20)} — press C  `} fg={theme.warn} wrapMode="none" />
+          </box>
+        )}
+        {/* Uptime Kuma: only bad news earns header space — silence when all up. */}
+        {kumaDown > 0 && <text content={`  ▼ ${kumaDown} monitor${kumaDown === 1 ? "" : "s"} down  `} fg={theme.bad} style={{ flexShrink: 0 }} wrapMode="none" />}
+        {loading && <Spinner interval={100} />}
+        <text content={`  ${servers.length} servers · ${sites.length} sites  `} fg={theme.textDim} style={{ flexShrink: 0 }} />
+        <text content={lastUpdated ? `updated ${timeAgo(lastUpdated.toISOString())}` : "loading…"} fg={theme.textFaint} style={{ flexShrink: 0 }} />
+      </box>
+      <box style={{ flexDirection: "row", height: 1, paddingLeft: 1, paddingRight: 1, alignItems: "center" }}>
+        <text content="💡 " fg={theme.accent} style={{ flexShrink: 0 }} />
+        <text content={SUBTITLES[route]} fg={theme.textDim} wrapMode="none" style={{ flexGrow: 1, flexShrink: 1 }} />
+      </box>
+    </box>
+  )
+}

package/src/ui/Help.tsx

@@ -0,0 +1,296 @@
+// Help overlay: an "About SpinupTUI" column plus the keybindings, laid out in
+// responsive columns so it stays short on wide terminals and stacks on narrow
+// ones. Rendered on top via zIndex. Opened/closed with `?`.
+
+import { useState, type ReactNode } from "react"
+import { useKeyboard, useTerminalDimensions } from "@opentui/react"
+import { theme } from "../lib/theme.ts"
+import { APP_NAME, APP_VERSION, REPO_URL } from "../version.ts"
+import { Sparkle, Spinner } from "./components.tsx"
+import { useStore } from "./store.tsx"
+import { runSelfUpdate, installChannel, PACKAGE_UPDATE_CMD, type UpdateInfo, type SelfUpdateResult } from "../lib/appUpdate.ts"
+
+type Section = { title: string; keys: [string, string][] }
+
+const GLOBAL: Section = {
+  title: "Global",
+  keys: [
+    ["1 … 5", "Switch tabs"],
+    ["r", "Refresh from the API"],
+    ["/", "Global search"],
+    ["i", "Explain the current screen"],
+    ["?", "This help"],
+    ["q · Ctrl+C", "Quit · force quit"],
+  ],
+}
+
+const NAV: Section = {
+  title: "Navigate & act",
+  keys: [
+    ["↑/↓  j/k", "Move selection"],
+    ["Enter / →", "Drill in"],
+    ["← / Esc", "Back / collapse"],
+    ["Tab", "Switch column focus"],
+    ["g / G", "Jump to top / bottom"],
+    ["o", "Open the site's URL"],
+    ["s", "SSH into the site"],
+    ["h", "Server health (SSH)"],
+    ["w", "Open in SpinupWP web app"],
+    ["a", "Server actions (reboot/restart)"],
+    ["c", "Create a new server"],
+    ["C", "Clone this server to a new one"],
+    ["S", "Connect sudo on the server"],
+    ["u", "Change PHP version"],
+    ["H", "Enable/disable HTTPS"],
+    ["P", "Purge page + object cache"],
+    ["K", "Grant SpinupTUI's SSH key (sudo)"],
+    ["d", "Identify a site's app (SSH)"],
+  ],
+}
+
+const LOCAL: Section = {
+  title: "Local working copy",
+  keys: [
+    ["L", "Link / edit local copy"],
+    ["t", "Terminal at the local copy"],
+    ["v", "Open the local URL"],
+    ["S", "Scan & batch-link (Stacks)"],
+    ["f", "Sites needing a local copy"],
+  ],
+}
+
+const DBMEDIA: Section = {
+  title: "Database & media (local)",
+  keys: [
+    ["d", "Download prod DB backup (Search)"],
+    ["p", "Pull prod DB → local (opt-in)"],
+    ["m", "Production media fallback"],
+  ],
+}
+
+const DNS: Section = {
+  title: "DNS hosts",
+  keys: [
+    ["n / N", "Site / server DNS inventory"],
+    ["Enter", "Edit a record's TTL"],
+    ["c", "Connect provider / open console"],
+    ["✓ ↗ ○ ·", "editable · web · needs key · ?"],
+  ],
+}
+
+const MARKERS: Section = {
+  title: "Row markers",
+  keys: [
+    ["◆", "Local copy linked"],
+    ["↑N", "Pending WP updates"],
+    ["⇣ / ⬇", "Sync / backup running"],
+  ],
+}
+
+const SEARCHTAB: Section = {
+  title: "Search tab",
+  keys: [
+    ["Tab / →", "Box → result actions"],
+    ["← / Esc", "Back to the box"],
+  ],
+}
+
+// Column groupings: two balanced columns on wide screens, one column otherwise.
+const TWO_COLS: Section[][] = [
+  [GLOBAL, NAV, SEARCHTAB],
+  [LOCAL, DBMEDIA, DNS, MARKERS],
+]
+const ONE_COL: Section[][] = [[GLOBAL, NAV, LOCAL, DBMEDIA, DNS, MARKERS, SEARCHTAB]]
+
+const ABOUT_W = 34
+const SC_W_MIN = 34 // never narrower than this; below it, fall back to one column
+
+function KeyRow({ k, desc }: { k: string; desc: string }) {
+  return (
+    <box style={{ flexDirection: "row" }}>
+      <box style={{ width: 13, flexShrink: 0 }}>
+        <text content={k} fg={theme.brand} wrapMode="none" />
+      </box>
+      <text content={desc} fg={theme.text} style={{ flexGrow: 1, flexShrink: 1 }} />
+    </box>
+  )
+}
+
+function SectionBlock({ section }: { section: Section }) {
+  return (
+    <box style={{ flexDirection: "column" }}>
+      <text content={section.title} fg={theme.accent} attributes={1} />
+      {section.keys.map(([k, desc]) => (
+        <KeyRow key={k} k={k} desc={desc} />
+      ))}
+      <box style={{ height: 1 }} />
+    </box>
+  )
+}
+
+function ShortcutColumn({ sections, width }: { sections: Section[]; width: number }) {
+  return (
+    <box style={{ flexDirection: "column", width, flexShrink: 0 }}>
+      {sections.map((s) => (
+        <SectionBlock key={s.title} section={s} />
+      ))}
+    </box>
+  )
+}
+
+type SelfUpdateState = "idle" | "running" | SelfUpdateResult
+
+function AboutColumn({
+  width,
+  updateInfo,
+  selfUpdate,
+}: {
+  width: number
+  updateInfo: UpdateInfo | null
+  selfUpdate: SelfUpdateState
+}) {
+  const line = (content: string, fg: string = theme.textDim): ReactNode => (
+    <text content={content} fg={fg} wrapMode="none" />
+  )
+  return (
+    <box style={{ flexDirection: "column", width, flexShrink: 0 }}>
+      <box style={{ flexDirection: "row" }}>
+        <text content={`◆ ${APP_NAME}`} fg={theme.brand} attributes={1} />
+        <text content={`  v${APP_VERSION}`} fg={theme.text} />
+      </box>
+      <box style={{ flexDirection: "row" }}>
+        <text content="n " fg={theme.brand} />
+        <text content={`what's new in v${APP_VERSION}`} fg={theme.textFaint} wrapMode="none" />
+      </box>
+      <box style={{ height: 1 }} />
+      {line("A terminal control center for")}
+      {line("your SpinupWP account.")}
+      <box style={{ height: 1 }} />
+      <text content="UPDATING" fg={theme.accent} attributes={1} />
+      {updateInfo?.updateAvailable ? (
+        <box style={{ flexDirection: "row" }}>
+          <Sparkle color={theme.update} />
+          <text content={`  v${updateInfo.latest} available`} fg={theme.update} attributes={1} wrapMode="none" />
+        </box>
+      ) : updateInfo ? (
+        line("You're on the latest.", theme.textFaint)
+      ) : null}
+      {updateInfo?.updateAvailable && selfUpdate === "idle" && installChannel() === "git" ? (
+        <box style={{ flexDirection: "row" }}>
+          <text content="u " fg={theme.brand} attributes={1} />
+          <text content="update now (git pull)" fg={theme.textDim} wrapMode="none" />
+        </box>
+      ) : null}
+      {selfUpdate === "running" ? (
+        <box style={{ flexDirection: "row" }}>
+          <Spinner color={theme.brand} interval={120} />
+          <text content=" pulling…" fg={theme.textDim} wrapMode="none" />
+        </box>
+      ) : null}
+      {selfUpdate !== "idle" && selfUpdate !== "running" ? (
+        <text content={selfUpdate.message} fg={selfUpdate.ok ? theme.good : theme.bad} />
+      ) : null}
+      {installChannel() === "package" ? (
+        <>
+          {line("Manual:")}
+          {line(PACKAGE_UPDATE_CMD, theme.text)}
+        </>
+      ) : (
+        <>
+          {line("Manual: git pull in your")}
+          {line("checkout — spinuptui picks")}
+          {line("it up immediately.")}
+        </>
+      )}
+      <box style={{ height: 1 }} />
+      <box style={{ flexDirection: "row" }}>
+        <text content="check  " fg={theme.textFaint} />
+        <text content="spinuptui --version" fg={theme.text} wrapMode="none" />
+      </box>
+      <box style={{ height: 1 }} />
+      {line(REPO_URL.replace(/^https:\/\//, ""), theme.textFaint)}
+      {line("Built with OpenTUI", theme.textFaint)}
+    </box>
+  )
+}
+
+export function HelpOverlay({ onClose }: { onClose: () => void }) {
+  const { width } = useTerminalDimensions()
+  const { updateInfo, showReleaseNotes } = useStore()
+  const aboutLeft = width >= 96
+  const twoShortcutCols = width >= 118
+
+  const [selfUpdate, setSelfUpdate] = useState<SelfUpdateState>("idle")
+  useKeyboard((key) => {
+    if (key.name === "n") {
+      // Close Help first — ReleaseNotes owns its own keyboard once open, and
+      // leaving Help mounted underneath would double-handle every keypress.
+      onClose()
+      showReleaseNotes()
+      return
+    }
+    if (key.name !== "u") return
+    if (installChannel() !== "git") return
+    if (!updateInfo?.updateAvailable || selfUpdate === "running") return
+    setSelfUpdate("running")
+    void runSelfUpdate().then(setSelfUpdate)
+  })
+
+  // Fill the terminal up to a cap, then size columns to the content area (box
+  // width − 2 border − 4 padding). Computing widths from the real space keeps it
+  // from clipping on narrow terminals and from sprawling on ultra-wide ones.
+  const GAP = 3
+  const boxWidth = Math.min(width - 4, 152)
+  const content = boxWidth - 6
+
+  const groups = twoShortcutCols ? TWO_COLS : ONE_COL
+  const cols = groups.length
+  const aboutWidth = aboutLeft ? ABOUT_W : content
+  const scArea = aboutLeft ? content - ABOUT_W - GAP : content
+  const scWidth = Math.max(SC_W_MIN, Math.floor((scArea - (cols - 1) * GAP) / cols))
+
+  const shortcutCols = groups.map((sections, i) => (
+    <box key={i} style={{ marginLeft: aboutLeft || i > 0 ? GAP : 0 }}>
+      <ShortcutColumn sections={sections} width={scWidth} />
+    </box>
+  ))
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        justifyContent: "center",
+        alignItems: "center",
+        zIndex: 100,
+      }}
+    >
+      <box
+        title={` ${APP_NAME} — Help `}
+        titleColor={theme.brand}
+        bottomTitle=" press ? or Esc to close "
+        bottomTitleAlignment="center"
+        border
+        borderColor={theme.borderActive}
+        backgroundColor={theme.bgPanel}
+        style={{ flexDirection: "column", width: boxWidth, paddingLeft: 2, paddingRight: 2, paddingTop: 1, paddingBottom: 1 }}
+      >
+        {aboutLeft ? (
+          <box style={{ flexDirection: "row", alignItems: "flex-start" }}>
+            <AboutColumn width={aboutWidth} updateInfo={updateInfo} selfUpdate={selfUpdate} />
+            {shortcutCols}
+          </box>
+        ) : (
+          <box style={{ flexDirection: "column" }}>
+            <AboutColumn width={aboutWidth} updateInfo={updateInfo} selfUpdate={selfUpdate} />
+            <box style={{ height: 1 }} />
+            {shortcutCols}
+          </box>
+        )}
+      </box>
+    </box>
+  )
+}

package/src/ui/List.tsx

@@ -0,0 +1,95 @@
+// A generic, keyboard-navigable, windowed list.
+//
+// The parent owns `selectedIndex` (so it can react to selection changes); this
+// component owns only the scroll offset, which it keeps in sync so the selected
+// row stays visible. Rendering each row is delegated to `renderRow`, giving each
+// view full control over columns and colors.
+
+import { useEffect, useState, type ReactNode } from "react"
+import { theme } from "../lib/theme.ts"
+
+export interface ListProps<T> {
+  items: T[]
+  selectedIndex: number
+  // Number of rows available to render (the viewport height in rows).
+  viewportRows: number
+  renderRow: (item: T, selected: boolean, index: number) => ReactNode
+  // Whether this list currently has focus (affects the selection highlight color).
+  focused?: boolean
+  emptyText?: string
+  // Optional fixed key extractor; defaults to index.
+  keyFor?: (item: T, index: number) => string | number
+}
+
+export function List<T>({
+  items,
+  selectedIndex,
+  viewportRows,
+  renderRow,
+  focused = true,
+  emptyText = "Nothing here.",
+  keyFor,
+}: ListProps<T>) {
+  const [offset, setOffset] = useState(0)
+  const rows = Math.max(1, viewportRows)
+
+  // Keep the selected row within the visible window [offset, offset+rows).
+  useEffect(() => {
+    setOffset((cur) => {
+      const maxOffset = Math.max(0, items.length - rows)
+      let next = cur
+      if (selectedIndex < cur) next = selectedIndex
+      else if (selectedIndex >= cur + rows) next = selectedIndex - rows + 1
+      return Math.min(Math.max(0, next), maxOffset)
+    })
+  }, [selectedIndex, rows, items.length])
+
+  if (items.length === 0) {
+    return (
+      <box style={{ flexGrow: 1, justifyContent: "center", alignItems: "center" }}>
+        <text content={emptyText} fg={theme.textFaint} />
+      </box>
+    )
+  }
+
+  const start = Math.min(offset, Math.max(0, items.length - rows))
+  const visible = items.slice(start, start + rows)
+  const hasAbove = start > 0
+  const hasBelow = start + rows < items.length
+
+  return (
+    <box style={{ flexGrow: 1, flexDirection: "column" }}>
+      {visible.map((item, i) => {
+        const index = start + i
+        const selected = index === selectedIndex
+        return (
+          <box
+            key={keyFor ? keyFor(item, index) : index}
+            style={{
+              flexDirection: "row",
+              height: 1,
+              backgroundColor: selected ? (focused ? theme.selectedBg : theme.bgAlt) : undefined,
+            }}
+          >
+            {renderRow(item, selected, index)}
+          </box>
+        )
+      })}
+      {/* Scroll affordance: show counts when the list overflows the viewport. */}
+      {(hasAbove || hasBelow) && (
+        <box style={{ flexDirection: "row", justifyContent: "flex-end", height: 1 }}>
+          <text
+            content={`${hasAbove ? "↑" : " "}${hasBelow ? "↓" : " "} ${selectedIndex + 1}/${items.length}`}
+            fg={theme.textFaint}
+          />
+        </box>
+      )}
+    </box>
+  )
+}
+
+// Shared helper for list views: clamp/move a selection index with wrap-around.
+export function moveSelection(current: number, delta: number, length: number): number {
+  if (length === 0) return 0
+  return (current + delta + length) % length
+}