opencode-krates-connector/design/spotlight.md

Design Document: Spotlight Feature Specification

Overview

Spotlight is the universal search and discovery interface that allows users to quickly find and create krates for Kubernetes resources. It's triggered by clicking the canvas or typing any character.

Core Responsibilities

• Handle universal search across Kubernetes resources
• Support fuzzy matching of names, namespaces, labels
• Allow quick creation of krates from search results
• Support filtering by resource type

Trigger

• Click on empty canvas: Open spotlight
• Type any key: Open spotlight with that character pre-seeded
• Esc key: Close spotlight
• Spotlight open: Prevent canvas shortcuts from triggering

Spotlight Anatomy

Search Input

• Position: Top of spotlight panel
• Auto-focused on open
• Placeholder: Search...
• Clear on Esc
• Debounced: 16ms for fuzzy search

Filter Bar

• Location: Below search input
• Filter chips: All, Krates, Namespaces, Pods, Deployments, Services
• Click filter: Apply filter
• Click active filter: Clear filter

Results List

• Position: Below filter bar
• Max height: ~400px
• Scrollable
• Results: Search results + quick actions
• Keyboard navigation: ↑↓ to navigate, Enter to select, Esc to close

Results Item

Content per item:

• Shape glyph (8px, color-coded by type)
• Name (primary text)
• Type badge (muted color)
• Namespace (muted, optional)
• View shortcuts: L, S, D, Y
• Hover: Highlight, show view shortcut tooltips

Search Implementation

Fuzzy Algorithm

function fuzzy(query: string, text: string): number {
  // Prefer starts-with matches
  if (text.toLowerCase().startsWith(query.toLowerCase())) {
    return 1 - query.length / text.length
  }
  
  // Then scoring based on character matching
  let score = 0
  let queryIndex = 0
  
  for (let i = 0; i < text.length && queryIndex < query.length; i++) {
    if (text[i].toLowerCase() === query[queryIndex].toLowerCase()) {
      score++
      queryIndex++
    }
  }
  
  return score / query.length
}

Search Scope

• Namespaces
• Pods
• Deployments
• Services
• ConfigMaps
• Secrets
• Krates (created by user)

Resource Discovery

1. Initial load: Fetch all resources from /api/resources
2. Real-time updates: WebSocket /ws/watch for changes
3. Local cache: Store in Zustand krateStore
4. Filtering: Apply fuzzy search + type filter

Results Organization

Search vs Quick Actions

• Search results: Resource matches (top section)
• Quick actions: Create new krate, open specific view (bottom section)

Quick Actions

• Create krate for ns/{namespace}
• All pods
• All services
• All deployments
• Search again for...

Keyboard Navigation

Key	Context	Action
↑ / ↓	Spotlight open	Move selection
PageUp / PageDown	Spotlight open	Page navigation
Home / End	Spotlight open	First / last item
Enter	Item selected	Create krate / open resource
Esc	Spotlight open	Close spotlight
Space	Input focused	Search space character
Ctrl+K	Anywhere	Open spotlight
/	Anywhere	Open spotlight

View Shortcuts

All use Option/Alt key:

• ⌥L: Open logs view (if supported)
• ⌥S: Open shell view (if supported)
• ⌥D: Open describe view
• ⌥Y: Open YAML view

Krate Creation Flow

1. User selects resource from spotlight
2. Create new krate with:
   • Title: Resource name
   • Color: Namespace color palette
   • Position: Find non-overlapping location
   • Windows: Create detail windows for selected views
3. Fly camera to new krate
4. Zoom to 0.92

State Management

Spotlight State

interface SpotlightState {
  open: boolean;
  query: string;
  filterType: string | null;
  sel: number;
  navigated: boolean;
}

type FilterType = 'all' | 'krate' | 'namespace' | 'pod' | 'deployment' | 'service'

Search State

interface SearchState {
  results: SearchResult[];
  loading: boolean;
  error: string | null;
}

interface SearchResult {
  id: string;
  type: string;
  name: string;
  namespace?: string;
  score: number;
  icon: string;
}

Visual Design

Spotlight Panel

• Position: Fixed, centered horizontally at top of canvas
• Width: 600px
• Max height: 500px
• Background: #1a1e26
• Border: 1px solid rgba(140,165,200,0.18)
• Border-radius: 12px
• Shadow: 0 10px 40px rgba(0,0,0,0.5)

Results Item

• Hover background: rgba(255,255,255,0.04)
• Selected: accentDim (subtle accent color)
• Left border: 2px solid accent when selected
• Padding: 8px 12px
• Font-size: 14px

Color Palette (by namespace)

• default: #6fb1ff
• kube-system: #9c88ff
• kube-public: #4dd6e8
• Custom namespaces: Pick from palette

Gotchas

1. Space character: When spotlight open, space goes to search (not canvas pan)
2. Esc handling: Must be handled in spotlight, not propagate to canvas
3. Fuzzy search: Use debounced search for large datasets
4. Keyboard routing: When spotlight open, route keys to spotlight, not canvas
5. Focus management: Auto-focus input, trap Tab cycle when open
6. Selection reset: Reset selection on query change

Future Enhancements

• Quick pick recent resources
• Star/favorite resources
• Saved searches
• Search history
• Resource previews
• Multi-resource selection