# 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
```typescript
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