Show slash command descriptions under the list

Author: TheGreatAxios

docs/TUI.md

@@ -282,16 +282,25 @@ are painted at the geometry resolver's shared `contentWidth`
 leading marker column and no per-row kind column; the selected row is marked
 by text color only (`paintPaletteList` in `shell.ts`: "the highlighted row
 already stands out by sitting under the cursor, so a leading `>` and a grey
-block would both be saying the same thing twice"). The list also paints with
-no title rule — the filter row (`> query`) directly under the box already
-shows what was typed, so a second header line would say nothing new
-(`repaintPalette`).
+block would both be saying the same thing twice"). Rows stay name-only
+(`/help`, `/model`); the focused command's registry description paints in the
+shared two-line description zone under the list (`openListOverlay({ describe })`,
+`paintDescriptionZone` in `shell.ts`). A missing or blank `description` still
+reserves the zone (rule plus two blank lines); it does not collapse. Built-ins
+have copy; this is the empty-description edge. The list also paints with no
+title rule — slash-popup query lives in the prompt, so an orphan `>` filter
+row under the box would be chrome that says nothing the prompt isn't already
+showing (`repaintPalette`).
 
 ## Slash commands and pickers
 
 `/` at an empty prompt opens the command list, narrowed by name prefix as
-more is typed; Tab completes the name so arguments can be typed, Enter runs
-it. Every entry is backed by the live command registry
+more is typed (`cmd.id` in `openSlashCommands`); Tab completes the name so
+arguments can be typed, Enter runs it. The query lives in the prompt — list
+chrome is in How selectors should work above. When the prefix matches
+nothing, the overlay closes and the prompt is left as typed: `/` then `z`
+with no `z…` command vanishes the list and leaves `/z`. Slash never paints
+a `(no matches)` row. Every entry is backed by the live command registry
 (`src/tui/command-catalog.ts:commandItemsFromRegistry`) — there is no
 separate palette overlay and no shell-owned action outside the registry. The
 overlay this reuses is still internally called `"palette"` (`shell.ts`'s
@@ -331,9 +340,9 @@ The model/provider picker is one flat, type-to-filter list
 (`src/tui/product-host.ts` + `openModelPickerOverlay({ typeToFilter: true })`):
 recent and favorite provider+model pairs sit at the top, then every
 `provider / model` leaf from the catalog. Typing narrows the list in place
-(printable keys claimed by the filter row, same pattern as the command
-palette); Enter selects. Escape closes the picker. The row matching the
-session's live active model gets a `(current)` suffix. Alt+F on a model row
+(printable keys claimed by the picker's own `>` filter row); Enter selects.
+Escape closes the picker. The row matching the session's live active model
+gets a `(current)` suffix. Alt+F on a model row
 still toggles favorite when a favorite hook is wired. While type-to-filter is
 active, bare `j`/`k` type into the filter rather than moving the highlight —
 use arrow keys (or the filtered list's navigation) to move.

src/tui/command-catalog.test.ts

@@ -15,11 +15,13 @@ describe("commandItemsFromRegistry", () => {
       {
         id: "tasks",
         label: "/tasks",
+        description: "Show work list",
         keywords: ["tasks", "Show work list", "slash", "command"],
       },
       {
         id: "clear",
         label: "/clear",
+        description: "Clear screen",
         keywords: ["clear", "Clear screen", "slash", "command"],
       },
     ])
@@ -43,6 +45,24 @@ describe("filterPaletteCommands", () => {
     expect(filterPaletteCommands("picker", catalog).map((c) => c.id)).toEqual([
       "model",
     ])
+    // A rewrite that mapped hits to `{ id, label, keywords }` would stay green
+    // on `.id` alone and blank the overlay description zone after a keystroke.
+    expect(filterPaletteCommands("picker", catalog)[0]?.description).toBe(
+      "Open model picker",
+    )
+  })
+
+  test("empty or whitespace description maps into keywords without false matches", () => {
+    const sparse = commandItemsFromRegistry([
+      { name: "quiet", description: "" },
+      { name: "padded", description: "   " },
+    ])
+    expect(sparse[0]?.keywords).toEqual(["quiet", "", "slash", "command"])
+    expect(sparse[1]?.keywords).toEqual(["padded", "   ", "slash", "command"])
+    expect(filterPaletteCommands("picker", sparse)).toEqual([])
+    expect(filterPaletteCommands("quiet", sparse).map((c) => c.id)).toEqual([
+      "quiet",
+    ])
   })
 
   test("no match returns an empty list", () => {

src/tui/command-catalog.ts

@@ -21,6 +21,8 @@ export type PaletteCommand = {
   readonly label: string
   /** Optional keywords for name-prefix / substring filter. */
   readonly keywords?: readonly string[]
+  /** Registry description for the overlay zone; rows stay name-only. */
+  readonly description?: string
 }
 
 /** Map registry command definitions to `/` list items. */
@@ -29,9 +31,11 @@ export function commandItemsFromRegistry(
 ): PaletteCommand[] {
   return commands.map((c) => ({
     id: c.name,
-    // Name-only rows keep the slash popup scannable; description stays in
-    // keywords so typed filter still finds prose matches.
+    // Name-only rows keep the slash popup scannable; description is a
+    // dedicated field for the overlay zone and stays in keywords so typed
+    // filter still finds prose matches.
     label: `/${c.name}`,
+    description: c.description,
     keywords: [c.name, c.description, "slash", "command"],
   }))
 }

src/tui/palette-paint.test.ts

@@ -188,6 +188,160 @@ describe("palette filters as you type", () => {
   })
 })
 
+const DESCRIBED_CATALOG: readonly PaletteCommand[] = [
+  {
+    id: "help",
+    label: "/help",
+    description: "Show the keyboard shortcut and command overlay",
+  },
+  {
+    id: "model",
+    label: "/model",
+    description: "Switch the active model or provider",
+  },
+  {
+    id: "mcp",
+    label: "/mcp",
+    description: "Manage MCP servers",
+  },
+]
+
+const HELP_DESC = "Show the keyboard shortcut and command overlay"
+const MODEL_DESC = "Switch the active model or provider"
+
+function stripFrameLines(frame: string): string[] {
+  return frame
+    .split("\n")
+    .map((line) => line.replace(/^\s*│/, "").replace(/│\s*$/, "").trimEnd())
+}
+
+/** Interior zone rows under the list rule, before the overlay's bottom border. */
+function zoneAfterList(
+  lines: readonly string[],
+  labels: readonly string[],
+): readonly string[] | undefined {
+  let last = -1
+  for (const [i, line] of lines.entries()) {
+    if (labels.some((label) => line.includes(label))) last = i
+  }
+  if (last < 0) return undefined
+  const below = lines.slice(last + 1)
+  const ruleAt = below.findIndex(
+    (r) => r.includes("─") && !/[┌┐└┘╭╮╰╯]/.test(r),
+  )
+  if (ruleAt < 0) return undefined
+  const afterRule = below.slice(ruleAt + 1)
+  const boxBottom = afterRule.findIndex((r) => /[└┘]/.test(r))
+  return boxBottom >= 0 ? afterRule.slice(0, boxBottom) : afterRule
+}
+
+function expectNameOnlyRows(
+  lines: readonly string[],
+  labels: readonly string[],
+): void {
+  for (const label of labels) {
+    const row = lines.find((r) => r.includes(label))
+    expect(row).toBeDefined()
+    expect(row!.trim()).toBe(label)
+  }
+}
+
+function expectDescriptionUnderListRule(
+  lines: readonly string[],
+  description: string,
+  labels: readonly string[],
+): void {
+  for (const label of labels) {
+    const row = lines.find((r) => r.includes(label))
+    expect(row).toBeDefined()
+    expect(row).not.toContain(description)
+  }
+  const zone = zoneAfterList(lines, labels)
+  expect(zone).toBeDefined()
+  expect(zone!.some((r) => r.includes(description))).toBe(true)
+}
+
+describe("command list description zone", () => {
+  test("paints the focused command's registry description, not on the row", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 100, rows: 32 },
+          wireKeys: false,
+          run: "idle",
+        })
+        openPalette(shell, { catalog: DESCRIBED_CATALOG })
+        await h.renderOnce()
+        const labels = DESCRIBED_CATALOG.map((c) => c.label)
+        const lines = stripFrameLines(h.captureCharFrame())
+        expectNameOnlyRows(lines, labels)
+        expectDescriptionUnderListRule(lines, HELP_DESC, labels)
+      },
+      { width: 100, height: 32 },
+    )
+  })
+
+  test("moving the overlay selection updates the zone to the newly focused command", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 100, rows: 32 },
+          wireKeys: false,
+          run: "idle",
+        })
+        openPalette(shell, { catalog: DESCRIBED_CATALOG })
+        await h.renderOnce()
+        const labels = DESCRIBED_CATALOG.map((c) => c.label)
+        const before = stripFrameLines(h.captureCharFrame())
+        expectDescriptionUnderListRule(before, HELP_DESC, labels)
+        expect(before.join("\n")).not.toContain(MODEL_DESC)
+
+        moveOverlaySelection(shell, 1)
+        await h.renderOnce()
+        const after = stripFrameLines(h.captureCharFrame())
+        expectNameOnlyRows(after, labels)
+        expectDescriptionUnderListRule(after, MODEL_DESC, labels)
+        expect(after.join("\n")).not.toContain(HELP_DESC)
+      },
+      { width: 100, height: 32 },
+    )
+  })
+
+  test("an undescribed row leaves the zone blank without leftover neighbor copy", async () => {
+    const mixed: readonly PaletteCommand[] = [
+      { id: "help", label: "/help", description: HELP_DESC },
+      { id: "model", label: "/model" },
+    ]
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 100, rows: 32 },
+          wireKeys: false,
+          run: "idle",
+        })
+        openPalette(shell, { catalog: mixed })
+        await h.renderOnce()
+        const labels = mixed.map((c) => c.label)
+        const described = stripFrameLines(h.captureCharFrame())
+        expectNameOnlyRows(described, labels)
+        expectDescriptionUnderListRule(described, HELP_DESC, labels)
+        const reserved = shell.layout.heights.overlay_host
+
+        moveOverlaySelection(shell, 1)
+        await h.renderOnce()
+        const blank = stripFrameLines(h.captureCharFrame())
+        expectNameOnlyRows(blank, labels)
+        const zone = zoneAfterList(blank, labels)
+        expect(zone).toBeDefined()
+        expect(zone!.every((r) => r.trim() === "")).toBe(true)
+        expect(blank.join("\n")).not.toContain(HELP_DESC)
+        expect(shell.layout.heights.overlay_host).toBe(reserved)
+      },
+      { width: 100, height: 32 },
+    )
+  })
+})
+
 describe("command list width", () => {
   // Both boxes are children of the same padded root; a width computed a
   // second way for the floating list drifts from the prompt box's "100%".

src/tui/prompt-slash-exit.test.ts

@@ -19,7 +19,12 @@ import {
 } from "./shell"
 
 const CATALOG: readonly PaletteCommand[] = [
-  { id: "model", label: "/model" },
+  {
+    id: "model",
+    label: "/model",
+    description: "Open model picker",
+    keywords: ["model", "Open model picker", "slash", "command"],
+  },
   { id: "mcp", label: "/mcp" },
   { id: "compact", label: "/compact" },
 ]
@@ -29,6 +34,7 @@ type Ctx = {
   readonly dispatched: string[]
   readonly press: (key: string) => void
   readonly render: () => Promise<void>
+  readonly frame: () => string
 }
 
 function withShell(fn: (ctx: Ctx) => Promise<void>): Promise<void> {
@@ -48,6 +54,7 @@ function withShell(fn: (ctx: Ctx) => Promise<void>): Promise<void> {
           dispatched,
           press: (key) => h.pressKey(key as Parameters<typeof h.pressKey>[0]),
           render: h.renderOnce,
+          frame: () => h.captureCharFrame(),
         })
       } finally {
         shell.dispose()
@@ -152,6 +159,32 @@ describe("slash command popup", () => {
       expect(shell.prompt.value).toBe("src/")
     })
   })
+
+  test("an unmatched name prefix closes the popup and keeps the typed text", async () => {
+    await withShell(async ({ shell, press, render, frame }) => {
+      press("/")
+      press("z")
+      await render()
+      expect(isSlashPopupOpen(shell)).toBe(false)
+      expect(shell.overlayList).toBeNull()
+      expect(shell.prompt.value).toBe("/z")
+      expect(shell.overlayItems).not.toContain("(no matches)")
+      expect(frame()).not.toContain("(no matches)")
+    })
+  })
+
+  test("description prose does not keep the slash list open", async () => {
+    await withShell(async ({ shell, press, render, frame }) => {
+      press("/")
+      press("p")
+      await render()
+      expect(isSlashPopupOpen(shell)).toBe(false)
+      expect(shell.overlayList).toBeNull()
+      expect(shell.prompt.value).toBe("/p")
+      expect(shell.overlayItems).not.toContain("(no matches)")
+      expect(frame()).not.toContain("(no matches)")
+    })
+  })
 })
 
 describe("Ctrl+C exit", () => {

src/tui/shell.ts

@@ -3791,6 +3791,12 @@ function repaintPalette(shell: AppShell): void {
     kind: "palette",
     title: state.title,
     items: labels,
+    itemIds: commands.map((c) => c.id),
+    describe: (id) => {
+      const cmd = commands.find((c) => c.id === id)
+      const what = cmd?.description?.trim()
+      return what ? { what } : null
+    },
     // Typed filter row only when the overlay owns keystrokes. The `/` popup
     // keeps its query in the prompt, so a body of `>` would be orphan chrome.
     ...(state.typeToFilter ? { body: `> ${state.query}` } : {}),