opencode-krates-connector/design/spotlight.md

Spotlight Search Feature Specification

Overview

The spotlight is the global search overlay that allows users to find any Kubernetes object or existing krate. It provides fuzzy-ranked search results with quick view shortcuts.

Core Responsibilities

• Display search results ranked by fuzzy matching
• Support typed filters (Tab to cycle through types)
• Provide view shortcuts (Logs, Shell, Describe, YAML)
• Auto-close after keyboard idle and open selected object

UI Components

Layout

• Full-screen backdrop: rgba(7,9,13,.55), backdrop-filter: blur(2px)
• Search panel: width: min(660px, 93vw), top: 15%, centered horizontally
• Panel: background: rgba(16,20,28,.97), border: 1px solid rgba(140,165,200,.26), border-radius: 14px

Sections (top→bottom)

1. Input row (~52px):

   • ⌕ glyph (accent color)
   • Optional type-filter pill
   • Input field (font-size: 18px, IBM Plex Sans)
   • Optional Tab ghost hint

2. Type chips row (scrollable):

   • All / deploy / svc / pods / secrets / config / sts / crd / namespace / ns
   • Scrollable horizontally on small screens
   • Shows selected filter as pill

3. Results list (max-height: 48vh, overflow: auto):

   • Each row: shape glyph + name + subtext (type · ns/namespace) + CRD badge + type badge
   • Selected row highlight: accent background
   • Scrollbar styled (8px, rgba(140,165,200,.18))

4. View chips (expanded on selected row only):

   • ⌥L logs · ⌥S shell · ⌥D describe · ⌥Y yaml
   • Only available views shown (YAML and Describe always shown; Logs and Shell for pods/deployments/daemonsets/statefulsets)
   • Click to open that view for selected result

5. Footer:

   • ↑↓ pick · ⌥L/S/D/Y open views · ⏎ open default · ⇥ filter type · esc done

Fuzzy Search Algorithm

Scoring Formula

Score = character-match score × 10 + type boost

Type Boosts

• CRD: 60
• Deployment: 50
• StatefulSet: 48
• Service: 46
• DaemonSet: 44
• Ingress: 42
• Secret: 24
• ConfigMap: 22
• PVC: 18
• Pod: 16

Character Matching

• Sequential character match
• Bonus for consecutive matches: +3
• Bonus for word-boundary starts: +5

Results

• Capped at 8 results
• Debounce: 16ms (one animation frame) for performance with large datasets

Type Filter

Tab Quick-Filter

• Typing type alias (e.g., pod, svc) shows ghost hint: ⇥ Pods
• Tab locks filter as pill
• Backspace removes filter (only when empty query and filter active)
• Tab cycles through type filters (most-recently-opened first)

View Shortcuts

Key Mapping

All use ⌥ (Alt/Option), NOT Ctrl (reserved for terminal):

• ⌥L = logs
• ⌥S = shell
• ⌥D = describe
• ⌥Y = yaml

Implementation

• Use event.code (layout-safe, e.g., KeyL), not event.key
• Multiple views can be opened before closing spotlight
• Views stack as windows in one krate

Keyboard Navigation

Key	Context	Action
↑ / ↓	Spotlight	Navigate results
Tab	Spotlight	Apply type filter / cycle filters
Backspace	Spotlight (empty query, filter active)	Clear type filter
Enter	Spotlight (result selected)	Open default view + close
⌥L/S/D/Y	Spotlight	Open that view for selected result
Esc	Spotlight	Close spotlight

Auto-Close Behavior

• After 500ms of keyboard idle (no more keypresses)
• Spotlight closes automatically
• Camera flies to the newly created krate
• Debounce timer resets on each keypress

Search Results Include

• Existing krates (jump to working set, camera flies there)
• Namespace results (ns/payments) → opens collection window
• Category results (All Pods, All Services) → opens collection window
• Kubernetes objects: pods, deployments, services, secrets, configmaps, etc.

State

interface SpotlightState {
  open: boolean;
  query: string;
  filterType: string | null;
  sel: number;                 // selected result index
  navigated: boolean;          // true after ↑/↓ press
  session: {                   // tracks views opened before closing
    kid: string;
    objId: string;
    views: string[];
  } | null;
}

Gotchas

1. Fuzzy search speed: For real clusters with thousands of objects, debounce by 16ms or run in Web Worker
2. View shortcuts: Must use event.code for layout safety across OS/keyboard layouts
3. Auto-close timer: Reset on each keypress, don't close during active typing
4. Pre-seeding: All printable characters (not just letters) should pre-seed spotlight