Command

Command lets users find and run an action — or jump to a thing — by typing: a ⌘K palette, a searchable action menu, a quick switcher. It's cmdk's combobox+listbox engine wearing the garn layer, elevated to do four things a thin wrapper can't. It NAVIGATES: push nested sub-command pages (pick a project → pick an action) with a back-pill and Backspace-to-pop, or jump straight in with a leading-token prefix. It WAITS: CommandLoading / CommandError / a refined CommandEmpty are first-class async states, not a single 'no results'. It REMEMBERS: useRecentCommands ranks by recency + frequency and biases the filter so power users' commands float up. And it ACTS: an item's shortcut both shows AND fires, and CommandItemActions gives each row a secondary-action panel on → / ⌘.. CommandDialog is the one canonical host — it owns the open-shortcut, controllable open state, and an imperative apiRef (agent-native), and AppShellCommand is a thin pass-through over it. Four headless hooks carry the behavior: useCommandShortcut (bind the open key), useCommandPages (read/drive the stack), useRecentCommands (ranking + injectable store), useCommandSearch (debounced async with request cancellation).

Reach for the canonical host. Use CommandDialog with a shortcut (and maybe openOnSlash) for the global ⌘K palette; the bare Command is for an inline palette (a filter popover, a picker). Don't hand-roll a second ⌘K listener — that's exactly the duplication CommandDialog folds away.

Model async through the flags, not by hand. useCommandSearch owns the debounce, the loading/error/empty machine, and cancels stale requests; wire query/setQuery to CommandInput, loading to Command, and render CommandLoading / CommandError / CommandEmpty off the flags. Pass shouldFilter={false} when the server already returned the matches, so cmdk doesn't re-filter them.

Rank with recents. Call record(value) in an item's onSelect and pass useRecentCommands().filter to <Command filter={…}> to float recents up; render a 'Recent' CommandGroup from recent. The store is injectable (localStorage by default) so it can ride a consumer store.

Bind shortcuts, don't just show them. Put the combo on CommandItem's shortcut (it renders the hint AND fires the item) rather than a bare CommandShortcut (display-only). Every combo needs a non-shift modifier.

Keep it keyboard-driven and named. Type-to-filter, arrow to move, Enter to run, Esc to close; → / ⌘. for a row's action panel; Backspace-on-empty to go back. It's a combobox over a listbox — preserve that. Name the CommandDialog for its context via title/description.