roboco/panel/docs/frontend/command-palette.md

Command Palette Reference

The global command palette enables keyboard-driven navigation across the entire RoboCo panel. Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from any page to open it, then fuzzy-search tasks, agents, projects, and navigation pages. When the input is empty, recently visited items appear instead.

Usage

Opening

• Mac: Cmd+K
• Windows/Linux: Ctrl+K
• Opens a Radix Dialog-based search overlay positioned at 20% from the top of the viewport

Keyboard Navigation

Key	Action
Arrow Down	Move selection down (wraps at end)
Arrow Up	Move selection up (wraps at start)
Enter	Navigate to the currently selected item
Escape	Close the palette (Radix Dialog built-in dismiss)

Search Categories

Results are grouped into four categories, appearing in this order:

1. Tasks — searched server-side by title, description, and short ID (via tasksApi.list({q}))
2. Agents — fuzzy-matched on name and slug (client-side)
3. Projects — fuzzy-matched on project name (client-side)
4. Pages — fuzzy-matched on page title from the sidebar navigation (client-side)

Each category shows up to 6 results. Enter navigates to the entity's detail page:

• Task: /tasks/{id}
• Agent: /agents/{id}
• Project: /projects?q={name} (filters the project list since no dedicated detail route exists)
• Page: the page's navigation href

Recents

When the input is empty (before or after clearing a search), the palette shows Recent items — up to 10 entries pulled from localStorage under the key roboco-cmd-recents. These are ordered by most recent first.

Recents are populated on navigation: whenever you press Enter or click a result, that item is added to recents (or moved to the front if already there). The recents list is capped at 10 items; older entries are automatically dropped.

---

Architecture

Component: CommandPalette

File: panel/src/components/layout/command-palette.tsx

A thin Radix Dialog renderer around the useCommandPalette hook. The component:

• Mounts once in the dashboard layout (panel/src/app/(dashboard)/layout.tsx) so the hotkey works on every page
• Listens for Cmd+K / Ctrl+K globally and opens the dialog
• Delegates all search/navigation logic to the hook
• Renders grouped results with icons, titles, and subtitles
• Handles arrow key and Enter navigation

Props: None — fully self-contained.

Key Features:

• Auto-focuses the input on open (via Radix's onOpenAutoFocus)
• Wrapping text (long titles are truncated with text-truncate)
• Shows "No results" when a search returns nothing; "No recent items yet" when recents are empty
• Icon for each result type (task = ListTodo, agent = Bot, project = FolderGit2, page = Compass)

Hook: useCommandPalette

File: panel/src/hooks/use-command-palette.ts

Manages all data, keyboard navigation, and navigation state for the palette. Returns:

{
  open: boolean;
  setOpen: (next: boolean) => void;
  query: string;
  setQuery: (value: string) => void;
  groups: CommandGroup[];           // Grouped results: Tasks, Agents, Projects, Pages
  flatItems: CommandItem[];         // Flattened items for keyboard navigation
  selectedIndex: number;            // Currently highlighted result
  moveSelection: (delta: number) => void;  // +1/-1 for arrow keys
  selectCurrent: () => void;        // Navigate to flatItems[selectedIndex]
  navigateTo: (item: CommandItem) => void; // Navigate + add to recents + close
}

Features:

• Dialog state driven by UI Store: useUIStore().commandPaletteOpen and .setCommandPaletteOpen() manage open/close (so other components like header search can open it via the store)
• Debounced search: Typed input is debounced 150ms before triggering results (cheap debounce, not caching the query)
• Server-side task search: Tasks are fetched via tasksApi.list({ q: trimmedQuery }) only while the dialog is open and the query is non-empty; client-side for agents/projects/pages
• Recents on empty query: loadRecents() is called fresh each time the query becomes empty, so a pick made just before closing appears immediately on the next open
• Selection resets on new query: Typing clears and resets selectedIndex to 0 (jump to top result)
• Dialog close resets state: Closing the dialog clears the query and selection so the next open starts fresh
• Flat navigation index: flatItems is a flat array across all groups; selectedIndex wraps around and addresses items by position, not group

Export: Exported as named export from @/hooks/use-command-palette, used by CommandPalette component.

Helper: fuzzyScore(query: string, label: string): number | null

File: panel/src/lib/fuzzy-match.ts

Pure function that scores a label against a fuzzy query. Returns a score (lower is better) or null if the query doesn't match.

Algorithm: Subsequence matching — every character in the query must appear in the label in order (not necessarily contiguous). Score rewards contiguous matches and early matches; gaps are penalized.

Usage: Called by scoreAndSort() to rank agents, projects, and pages.

Helper: loadRecents() / addRecent(item)

File: panel/src/lib/command-palette-recents.ts

localStorage-backed functions for managing recent items.

• loadRecents(): Returns the current recent items array (up to 10) from localStorage key roboco-cmd-recents, or [] if empty/missing
• addRecent(item): Adds or moves item to the front of recents, caps the array at 10, and saves back to localStorage

Item shape: { type: CommandRecentType, id: string, title: string }

CommandRecentType: Union type of "task" | "agent" | "project" | "page"

---

Data Flow

1. User presses Cmd+K
   ↓
2. Global keydown listener in CommandPalette detects it
   ↓
3. setOpen(true) fires, opening the Radix Dialog
   ↓
4. User types in the input
   ↓
5. onChange → setQuery() → debounceMs 150ms → groups re-compute
   ↓
6. Groups fetch tasks (server-side if query non-empty, only while open)
   ↓
7. Agents/projects/pages are fuzzy-scored client-side
   ↓
8. Arrow keys move selectedIndex within flatItems
   ↓
9. Enter presses selectCurrent() → navigateTo(item)
   ↓
10. navigateTo() calls addRecent() then router.push()
   ↓
11. setDialogOpen(false) closes the palette and resets state

---

Verification Against Live Data

All four search categories are backed by live API data or real navigation config:

• Tasks: Fetched from the backend via tasksApi.list({ q, limit: 6 }), which already fuzzy-searches by title/description/id-prefix
• Agents: Fetched from the backend via useAgentDefinitions(), which returns all agent definitions
• Projects: Fetched from the backend via useProjects(), which returns all projects
• Pages: Statically imported from navItems in panel/src/components/layout/sidebar.tsx — the source of truth for the sidebar navigation

This ensures the palette always searches against populated, real data. Mock or stub data is never used in place of live API calls.

---

Known Limitations & Future Improvements

1. No dedicated project detail route: Projects link to a filtered list view (/projects?q={name}) rather than a detail page, since no such route exists
2. Maximum 6 results per group: This is a hardcoded limit (MAX_RESULTS_PER_GROUP) to keep the results concise and readable
3. localStorage persistence: Recents are stored in the browser's localStorage, so they are device/profile-specific and not synced across sessions

---

Testing

The command palette is tested in panel/src/components/layout/__tests__/command-palette.test.tsx and panel/src/hooks/__tests__/use-command-palette.test.ts with coverage for:

• Opening on Cmd+K / Ctrl+K
• Rendering grouped results with live data
• Keyboard navigation (arrow keys, Enter, Escape)
• Closing on Escape or navigation
• Empty-query recents display
• "No results" message on empty results
• Recents updates on navigation
• Result click handling