feat: add cmd+k hotkey to focus search bar with kbd badge indicator

package.json

@@ -12,6 +12,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@tanstack/react-hotkeys": "^0.3.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },

src/App.css

@@ -153,6 +153,34 @@
   border-color: rgba(var(--fg), 0.2);
 }
 
+.search-bar--has-kbd {
+  padding-right: 72px;
+}
+
+.search-bar-kbd {
+  position: absolute;
+  right: 14px;
+  top: 50%;
+  transform: translateY(-50%);
+  padding: 3px 7px;
+  font-size: 0.72rem;
+  font-family: inherit;
+  color: rgba(var(--fg), 0.45);
+  background: rgba(var(--fg), 0.08);
+  border: 1px solid rgba(var(--fg), 0.18);
+  border-bottom-width: 2px;
+  border-radius: 6px;
+  pointer-events: none;
+  opacity: 1;
+  transition: opacity 150ms;
+  white-space: nowrap;
+  user-select: none;
+}
+
+.search-bar-kbd--hidden {
+  opacity: 0;
+}
+
 /* Search Dropdown */
 .search-dropdown {
   position: absolute;

src/main.tsx

@@ -1,10 +1,13 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
+import { HotkeysProvider } from '@tanstack/react-hotkeys'
 import './index.css'
 import App from './App.tsx'
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <App />
+    <HotkeysProvider>
+      <App />
+    </HotkeysProvider>
   </StrictMode>,
 )

src/screens/HomeScreen/components/SearchBar.test.tsx

@@ -1,10 +1,15 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, fireEvent } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import { HotkeysProvider } from '@tanstack/react-hotkeys';
 import { SearchBar } from './SearchBar.tsx';
 import { scoreMatch, scoreLinkMatch } from './searchScoring.ts';
 import { mockModule, mockModuleWithHiddenLinks } from '../../../test/fixtures.ts';
 import type { ModuleConfig } from '../../../types/config.ts';
 
+function renderWithHotkeys(ui: React.ReactElement) {
+  return render(<HotkeysProvider>{ui}</HotkeysProvider>);
+}
+
 const modules = [mockModule, mockModuleWithHiddenLinks];
 
 describe('scoreMatch', () => {
@@ -251,4 +256,68 @@ describe('SearchBar', () => {
     expect(screen.queryByText('GitHub')).not.toBeInTheDocument();
     expect(input).toHaveValue('');
   });
+
+  it('renders the kbd badge when enabled', () => {
+    renderWithHotkeys(
+      <SearchBar enabled={true} placeholder="Filter..." modules={modules} onNavigate={vi.fn()} />,
+    );
+    // kbd is aria-hidden, so query by element tag
+    const kbd = document.querySelector('kbd');
+    expect(kbd).toBeInTheDocument();
+  });
+
+  it('kbd badge has hidden class when input is focused', () => {
+    renderWithHotkeys(
+      <SearchBar enabled={true} placeholder="Filter..." modules={modules} onNavigate={vi.fn()} />,
+    );
+    const input = screen.getByPlaceholderText('Filter...');
+    const kbd = document.querySelector('kbd')!;
+
+    // Initially the input has autoFocus, so it starts focused — badge is hidden
+    fireEvent.focus(input);
+    expect(kbd).toHaveClass('search-bar-kbd--hidden');
+  });
+
+  it('kbd badge has hidden class when query is non-empty', async () => {
+    const user = userEvent.setup();
+    renderWithHotkeys(
+      <SearchBar enabled={true} placeholder="Filter..." modules={modules} onNavigate={vi.fn()} />,
+    );
+    const input = screen.getByPlaceholderText('Filter...');
+    const kbd = document.querySelector('kbd')!;
+
+    fireEvent.blur(input);
+    await user.type(input, 'g');
+    expect(kbd).toHaveClass('search-bar-kbd--hidden');
+  });
+
+  it('kbd badge does not have hidden class when input is blurred and query is empty', () => {
+    renderWithHotkeys(
+      <SearchBar enabled={true} placeholder="Filter..." modules={modules} onNavigate={vi.fn()} />,
+    );
+    const input = screen.getByPlaceholderText('Filter...');
+    const kbd = document.querySelector('kbd')!;
+
+    fireEvent.blur(input);
+    expect(kbd).not.toHaveClass('search-bar-kbd--hidden');
+  });
+
+  it('Mod+K focuses the search input', async () => {
+    const user = userEvent.setup();
+    renderWithHotkeys(
+      <>
+        <button>other</button>
+        <SearchBar enabled={true} placeholder="Filter..." modules={modules} onNavigate={vi.fn()} />
+      </>,
+    );
+    const input = screen.getByPlaceholderText('Filter...');
+
+    // Move focus to the other button so the input is not focused
+    await user.click(screen.getByRole('button', { name: 'other' }));
+    expect(document.activeElement).not.toBe(input);
+
+    // In jsdom (Linux), Mod resolves to Control; fire Ctrl+K
+    await user.keyboard('{Control>}k{/Control}');
+    expect(document.activeElement).toBe(input);
+  });
 });

src/screens/HomeScreen/components/SearchBar.tsx

@@ -1,9 +1,14 @@
 import { useState, useEffect, useRef, useMemo } from 'react';
+import { useHotkey } from '@tanstack/react-hotkeys';
 import type { LinkConfig, ModuleConfig } from '../../../types/config.ts';
 import { scoreLinkMatch } from './searchScoring.ts';
 
 const MAX_RESULTS = 5;
 
+function isMac(): boolean {
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+
 interface SearchBarProps {
   enabled: boolean;
   placeholder: string;
@@ -28,8 +33,14 @@ function getFaviconUrl(url: string): string {
 export function SearchBar({ enabled, placeholder, modules, onNavigate }: SearchBarProps) {
   const [query, setQuery] = useState('');
   const [selectedIndex, setSelectedIndex] = useState(0);
+  const [isFocused, setIsFocused] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement>(null);
 
+  useHotkey('Mod+K', () => {
+    inputRef.current?.focus();
+  }, { preventDefault: true });
+
   const matches: MatchedLink[] = useMemo(() => {
     if (!query) return [];
 
@@ -62,6 +73,9 @@ export function SearchBar({ enabled, placeholder, modules, onNavigate }: SearchB
 
   if (!enabled) return null;
 
+  const kbdHidden = isFocused || query.length > 0;
+  const kbdLabel = isMac() ? '⌘K' : 'Ctrl K';
+
   function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
     if (e.key === 'Escape') {
       setQuery('');
@@ -80,14 +94,20 @@ export function SearchBar({ enabled, placeholder, modules, onNavigate }: SearchB
     <div className="search-bar-container">
       <div className="search-bar-wrapper">
         <input
-          className="search-bar"
+          ref={inputRef}
+          className={`search-bar${kbdHidden ? '' : ' search-bar--has-kbd'}`}
           type="text"
           placeholder={placeholder}
           value={query}
           onChange={(e) => { setQuery(e.target.value); setSelectedIndex(0); }}
           onKeyDown={handleKeyDown}
+          onFocus={() => setIsFocused(true)}
+          onBlur={() => setIsFocused(false)}
           autoFocus
         />
+        <kbd className={`search-bar-kbd${kbdHidden ? ' search-bar-kbd--hidden' : ''}`} aria-hidden="true">
+          {kbdLabel}
+        </kbd>
         {matches.length > 0 && (
           <ul className="search-dropdown" ref={listRef}>
             {matches.map((link, i) => (