Command palette: Group recents, self-heal stale IDs

- Empty-query view shows `Recent` and `All commands` subheaders so the user understands the grouping. Hidden during active search.
- On mount, `pruneRecentCommands(validIds)` drops any recents that no longer match a real palette command (renamed / removed) and saves the cleaned list back — keeps the cap-10 list useful even after registry changes.

Author: vdavid

apps/desktop/src/lib/app-status-store.ts

@@ -267,6 +267,29 @@ export async function pushRecentCommand(commandId: string): Promise<void> {
   }
 }
 
+/**
+ * Loads recents and drops any IDs that aren't in `validIds`. If anything was
+ * pruned, the cleaned list is written back. Returns the (possibly pruned) list.
+ *
+ * Call this on palette open: it self-heals the store against commands that were
+ * renamed or removed since the user last used them. Without it, stale IDs would
+ * just take up slots in the cap-10 list and reduce the visible recents count.
+ */
+export async function pruneRecentCommands(validIds: ReadonlySet<string>): Promise<string[]> {
+  try {
+    const existing = await loadRecentCommands()
+    const pruned = existing.filter((id) => validIds.has(id))
+    if (pruned.length !== existing.length) {
+      const store = await getStore()
+      await store.set('recentCommandIds', pruned)
+      await store.save()
+    }
+    return pruned
+  } catch {
+    return []
+  }
+}
+
 // ============================================================================
 // Settings window section persistence
 // ============================================================================

apps/desktop/src/lib/command-palette/CLAUDE.md

@@ -14,7 +14,7 @@ VS Code/Spotlight-style modal for searching and executing app commands via fuzzy
 ```
 User presses ⌘⇧P
   → +page.svelte sets showCommandPalette = true
-  → CommandPalette mounts, loads recentCommandIds from app-status-store, focuses input
+  → CommandPalette mounts, calls pruneRecentCommands(validIds) (load + drop stale + save), focuses input
   → searchCommands(query, recentCommandIds) returns CommandMatch[] (reactive via $derived)
   → User navigates with ↑/↓ (keyboard cursor) or mouse (hover cursor)
   → Enter / click → pushRecentCommand(id), onExecute(commandId) → handleCommandExecute()
@@ -31,12 +31,14 @@ overlay).
 **Event propagation**: `stopPropagation()` is called on every `keydown` in the overlay `div`'s handler. This prevents
 the file list from scrolling or handling shortcuts behind the modal.
 
-**Recents on empty query**: `loadRecentCommands` / `pushRecentCommand` from `$lib/app-status-store` (Tauri store). On
-mount, the palette loads the recent command IDs and passes them to `searchCommands(query, recentCommandIds)`. When the
-query is empty, recents lead the result (most-recent first), then the rest of the palette commands in registry order. On
-every Enter / click, `pushRecentCommand(id)` records the execution: the ID moves to the front, duplicates are removed,
-the list is capped at 10. The query itself is not persisted across opens — the palette always opens empty so the user's
-last-executed command sits at index 0 (cursor default), making Enter re-run it.
+**Recents on empty query**: `pruneRecentCommands` / `pushRecentCommand` from `$lib/app-status-store` (Tauri store). On
+mount, the palette calls `pruneRecentCommands(validIds)` — this loads the persisted recents, drops any IDs that are no
+longer valid palette commands (renamed / removed since last use), saves the cleaned list back, and returns it. The
+pruned list is then passed to `searchCommands(query, recentCommandIds)`. When the query is empty, recents lead the
+result (most-recent first), with a `Recent` subheader above them and an `All commands` subheader before the rest. On
+every Enter / click, `pushRecentCommand(id)` moves the ID to the front; duplicates are removed; the list is capped
+at 10. The query itself is not persisted across opens — the palette always opens empty so the user's last-executed
+command sits at index 0 (cursor default), making Enter re-run it.
 
 **Own overlay, no shared ModalDialog**: `CommandPalette` manages its own `position: fixed` overlay and `role="dialog"`
 ARIA attributes. It does not use the shared `ModalDialog` component.
@@ -106,6 +108,6 @@ Add the command to `$lib/commands/command-registry.ts` and handle the ID in the
 
 ## Dependencies
 
-- `$lib/commands` — `searchCommands`, `CommandMatch`
-- `$lib/app-status-store` — `loadRecentCommands`, `pushRecentCommand`
+- `$lib/commands` — `searchCommands`, `getPaletteCommands`, `CommandMatch`
+- `$lib/app-status-store` — `pruneRecentCommands`, `pushRecentCommand`
 - CSS variables from `app.css` (`--z-modal`, `--color-accent-subtle`, `--color-bg-secondary`, etc.)

apps/desktop/src/lib/command-palette/CommandPalette.a11y.test.ts

@@ -12,29 +12,31 @@ import CommandPalette from './CommandPalette.svelte'
 import { expectNoA11yViolations } from '$lib/test-a11y'
 
 vi.mock('$lib/app-status-store', () => ({
-  loadRecentCommands: vi.fn(() => Promise.resolve([])),
+  pruneRecentCommands: vi.fn(() => Promise.resolve([])),
   pushRecentCommand: vi.fn(() => Promise.resolve()),
 }))
 
-vi.mock('$lib/commands', () => ({
-  searchCommands: vi.fn((query: string) => {
-    const all = [
-      { command: { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', shortcuts: ['\u2318Q'] }, matchedIndices: [] },
-      { command: { id: 'app.about', name: 'About Cmdr', scope: 'App', shortcuts: [] }, matchedIndices: [] },
-      {
-        command: {
-          id: 'file.copyPath',
-          name: 'Copy path to clipboard',
-          scope: 'Main window',
-          shortcuts: [],
-        },
-        matchedIndices: [],
-      },
-    ]
-    if (!query.trim()) return all
-    return all.filter((c) => c.command.name.toLowerCase().includes(query.toLowerCase()))
-  }),
-}))
+vi.mock('$lib/commands', () => {
+  const all = [
+    { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', shortcuts: ['\u2318Q'], showInPalette: true },
+    { id: 'app.about', name: 'About Cmdr', scope: 'App', shortcuts: [], showInPalette: true },
+    {
+      id: 'file.copyPath',
+      name: 'Copy path to clipboard',
+      scope: 'Main window',
+      shortcuts: [],
+      showInPalette: true,
+    },
+  ]
+  return {
+    getPaletteCommands: vi.fn(() => all),
+    searchCommands: vi.fn((query: string) => {
+      const matches = all.map((command) => ({ command, matchedIndices: [] }))
+      if (!query.trim()) return matches
+      return matches.filter((c) => c.command.name.toLowerCase().includes(query.toLowerCase()))
+    }),
+  }
+})
 
 describe('CommandPalette a11y', () => {
   beforeEach(() => {

apps/desktop/src/lib/command-palette/CommandPalette.svelte

@@ -9,8 +9,8 @@
      * - Blocks keyboard events from propagating to file explorer
      */
     import { onDestroy, onMount, tick } from 'svelte'
-    import { searchCommands, type CommandMatch } from '$lib/commands'
-    import { loadRecentCommands, pushRecentCommand } from '$lib/app-status-store'
+    import { searchCommands, getPaletteCommands, type CommandMatch } from '$lib/commands'
+    import { pruneRecentCommands, pushRecentCommand } from '$lib/app-status-store'
 
     interface Props {
         /** Called when user selects a command */
@@ -40,6 +40,20 @@
     // user's last-executed command — Enter re-runs it.
     const results = $derived(searchCommands(query, recentCommandIds))
 
+    // Boundary between recents and the rest in the empty-query view. Used to
+    // render the "Recent" / "All commands" subheaders. Always 0 when the query
+    // is non-empty (no grouping during search).
+    const recentCount = $derived.by(() => {
+        if (query.trim() || recentCommandIds.length === 0) return 0
+        const recentSet = new Set(recentCommandIds)
+        let n = 0
+        for (const r of results) {
+            if (recentSet.has(r.command.id)) n++
+            else break
+        }
+        return n
+    })
+
     // Reset cursor position when query changes
     $effect(() => {
         void query // Track
@@ -49,8 +63,10 @@
 
     onMount(() => {
         previousActiveElement = document.activeElement instanceof HTMLElement ? document.activeElement : null
-        // Load recents so the empty-query view leads with the user's last-executed commands.
-        void loadRecentCommands().then((ids) => {
+        // Load recents and prune any IDs that no longer correspond to a valid palette
+        // command (renamed or removed since last use). Self-heals the persisted list.
+        const validIds = new Set(getPaletteCommands().map((c) => c.id))
+        void pruneRecentCommands(validIds).then((ids) => {
             recentCommandIds = ids
         })
         inputElement?.focus()
@@ -177,6 +193,12 @@
                 <div class="no-results">No commands found</div>
             {:else}
                 {#each results as match, index (match.command.id)}
+                    {#if recentCount > 0 && index === 0}
+                        <div class="group-heading">Recent</div>
+                    {/if}
+                    {#if recentCount > 0 && index === recentCount}
+                        <div class="group-heading">All commands</div>
+                    {/if}
                     <div
                         class="result-item"
                         class:is-under-cursor={index === cursorIndex}
@@ -269,6 +291,22 @@
         font-size: var(--font-size-md);
     }
 
+    /* Section headers between recents and the rest of the palette */
+    .group-heading {
+        padding: var(--spacing-sm) var(--spacing-lg) var(--spacing-xxs);
+        font-size: var(--font-size-xs);
+        font-weight: 600;
+        color: var(--color-text-tertiary);
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+        border-top: 1px solid var(--color-border);
+    }
+
+    /* First heading sits right after the input — no top border */
+    .group-heading:first-child {
+        border-top: none;
+    }
+
     .result-item {
         display: flex;
         justify-content: space-between;

apps/desktop/src/lib/command-palette/CommandPalette.test.ts

@@ -2,47 +2,39 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { mount, unmount } from 'svelte'
 import { tick } from 'svelte'
 import CommandPalette from './CommandPalette.svelte'
-import { loadRecentCommands, pushRecentCommand } from '$lib/app-status-store'
+import { pruneRecentCommands, pushRecentCommand } from '$lib/app-status-store'
+
+const ALL_COMMANDS = [
+  { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', shortcuts: ['⌘Q'], showInPalette: true },
+  { id: 'app.about', name: 'About Cmdr', scope: 'App', shortcuts: [], showInPalette: true },
+  { id: 'file.copyPath', name: 'Copy path to clipboard', scope: 'Main window', shortcuts: [], showInPalette: true },
+  { id: 'view.showHidden', name: 'Toggle hidden files', scope: 'Main window', shortcuts: ['⌘⇧.'], showInPalette: true },
+]
 
 // Mock the app-status-store to avoid Tauri dependency in tests
 vi.mock('$lib/app-status-store', () => ({
-  loadRecentCommands: vi.fn().mockResolvedValue([]),
+  pruneRecentCommands: vi.fn().mockResolvedValue([]),
   pushRecentCommand: vi.fn().mockResolvedValue(undefined),
 }))
 
 // Mock the commands module to provide test data
 vi.mock('$lib/commands', () => ({
+  getPaletteCommands: vi.fn(() => ALL_COMMANDS),
   searchCommands: vi.fn((query: string, recentIds: string[] = []) => {
-    const allCommands = [
-      { command: { id: 'app.quit', name: 'Quit Cmdr', scope: 'App', shortcuts: ['⌘Q'] }, matchedIndices: [] },
-      { command: { id: 'app.about', name: 'About Cmdr', scope: 'App', shortcuts: [] }, matchedIndices: [] },
-      {
-        command: { id: 'file.copyPath', name: 'Copy path to clipboard', scope: 'Main window', shortcuts: [] },
-        matchedIndices: [],
-      },
-      {
-        command: {
-          id: 'view.showHidden',
-          name: 'Toggle hidden files',
-          scope: 'Main window',
-          shortcuts: ['⌘⇧.'],
-        },
-        matchedIndices: [],
-      },
-    ]
+    const allMatches = ALL_COMMANDS.map((command) => ({ command, matchedIndices: [] }))
     if (!query.trim()) {
       // Mirror the real implementation's recents-first ordering so tests can
       // exercise the wiring without depending on the real fuzzy module.
-      const byId = new Map(allCommands.map((m) => [m.command.id, m]))
+      const byId = new Map(allMatches.map((m) => [m.command.id, m]))
       const recents = recentIds.flatMap((id) => {
         const match = byId.get(id)
         return match ? [match] : []
       })
       const recentSet = new Set(recents.map((m) => m.command.id))
-      const rest = allCommands.filter((m) => !recentSet.has(m.command.id))
+      const rest = allMatches.filter((m) => !recentSet.has(m.command.id))
       return [...recents, ...rest]
     }
-    return allCommands.filter((c) => c.command.name.toLowerCase().includes(query.toLowerCase()))
+    return allMatches.filter((c) => c.command.name.toLowerCase().includes(query.toLowerCase()))
   }),
 }))
 
@@ -55,7 +47,7 @@ describe('CommandPalette', () => {
     mockOnClose = vi.fn()
     // Mock scrollIntoView which isn't available in jsdom
     Element.prototype.scrollIntoView = vi.fn()
-    vi.mocked(loadRecentCommands).mockResolvedValue([])
+    vi.mocked(pruneRecentCommands).mockResolvedValue([])
     vi.mocked(pushRecentCommand).mockClear()
   })
 
@@ -305,7 +297,7 @@ describe('CommandPalette', () => {
   })
 
   it('leads the empty-query list with recents, most-recent first', async () => {
-    vi.mocked(loadRecentCommands).mockResolvedValue(['file.copyPath', 'app.about'])
+    vi.mocked(pruneRecentCommands).mockResolvedValue(['file.copyPath', 'app.about'])
 
     const target = document.createElement('div')
     mount(CommandPalette, {
@@ -358,6 +350,57 @@ describe('CommandPalette', () => {
     expect(mockOnExecute).toHaveBeenCalledWith('app.about')
   })
 
+  it('renders "Recent" and "All commands" subheaders when recents exist', async () => {
+    vi.mocked(pruneRecentCommands).mockResolvedValue(['file.copyPath', 'app.about'])
+
+    const target = document.createElement('div')
+    mount(CommandPalette, {
+      target,
+      props: { onExecute: mockOnExecute, onClose: mockOnClose },
+    })
+    await tick()
+    await tick()
+
+    const headings = Array.from(target.querySelectorAll('.group-heading')).map((el) => el.textContent?.trim())
+    expect(headings).toEqual(['Recent', 'All commands'])
+  })
+
+  it('renders no group subheaders when there are no recents', async () => {
+    vi.mocked(pruneRecentCommands).mockResolvedValue([])
+
+    const target = document.createElement('div')
+    mount(CommandPalette, {
+      target,
+      props: { onExecute: mockOnExecute, onClose: mockOnClose },
+    })
+    await tick()
+    await tick()
+
+    expect(target.querySelectorAll('.group-heading').length).toBe(0)
+  })
+
+  it('renders no group subheaders during an active search', async () => {
+    vi.mocked(pruneRecentCommands).mockResolvedValue(['file.copyPath'])
+
+    const target = document.createElement('div')
+    mount(CommandPalette, {
+      target,
+      props: { onExecute: mockOnExecute, onClose: mockOnClose },
+    })
+    await tick()
+    await tick()
+
+    const input = target.querySelector('input')
+    if (input) {
+      input.value = 'copy'
+      input.dispatchEvent(new InputEvent('input', { bubbles: true }))
+    }
+    await tick()
+
+    // Grouping is for the recents view only; typing collapses it.
+    expect(target.querySelectorAll('.group-heading').length).toBe(0)
+  })
+
   it('does not throw if the previously focused element is no longer in the DOM', async () => {
     const trigger = document.createElement('button')
     document.body.appendChild(trigger)