feat: implement Phase 9 - Keyboard Shortcuts

Features added:
- Created useKeyboardShortcuts hook for managing keyboard shortcuts
  - Supports modifier keys (Ctrl, Shift, Alt)
  - Automatically ignores shortcuts when input fields are focused
  - ESC key blurs input fields to enable shortcuts
- Added global keyboard shortcuts:
  - / : Focus search field
  - r : Refresh process list
  - a : Select all processes (flat view only)
  - ESC : Clear selection / unfocus
  - ? (Shift+/) : Show keyboard shortcuts help
- Added process navigation shortcuts:
  - j : Select next process
  - k : Select previous process
  - Space : Toggle selection of focused process
  - Auto-scroll to focused process
- Created KeyboardShortcutsHelp modal component:
  - Organized shortcuts by category
  - Visual kbd elements for keys
  - Info about input field behavior
- Added keyboard shortcuts button to processes page header
- Added isFocused prop to ProcessCard with accent ring styling
- Added data-process-id attributes for keyboard navigation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/processes/page.tsx

@@ -1,20 +1,25 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useRef, useEffect } from 'react';
 import { useProcesses } from '@/lib/hooks/useSupervisor';
 import { ProcessCard } from '@/components/process/ProcessCard';
 import { GroupView } from '@/components/groups/GroupView';
 import { GroupSelector } from '@/components/groups/GroupSelector';
 import { BatchActions } from '@/components/process/BatchActions';
 import { ProcessFilters } from '@/components/process/ProcessFilters';
-import { RefreshCw, AlertCircle, CheckSquare } from 'lucide-react';
+import { RefreshCw, AlertCircle, CheckSquare, Keyboard } from 'lucide-react';
 import { Button } from '@/components/ui/button';
+import { useKeyboardShortcuts } from '@/lib/hooks/useKeyboardShortcuts';
+import { KeyboardShortcutsHelp } from '@/components/ui/KeyboardShortcutsHelp';
 import type { ProcessInfo } from '@/lib/supervisor/types';
 
 export default function ProcessesPage() {
   const [viewMode, setViewMode] = useState<'flat' | 'grouped'>('flat');
   const [selectedProcesses, setSelectedProcesses] = useState<Set<string>>(new Set());
   const [filteredProcesses, setFilteredProcesses] = useState<ProcessInfo[]>([]);
+  const [showShortcutsHelp, setShowShortcutsHelp] = useState(false);
+  const [focusedIndex, setFocusedIndex] = useState<number>(-1);
+  const searchInputRef = useRef<HTMLInputElement>(null);
   const { data: processes, isLoading, isError, refetch } = useProcesses();
 
   const handleFilterChange = useCallback((filtered: ProcessInfo[]) => {
@@ -48,6 +53,111 @@ export default function ProcessesPage() {
     setSelectedProcesses(new Set());
   };
 
+  // Get displayedProcesses for keyboard navigation
+  const displayedProcesses = filteredProcesses.length > 0 || !processes ? filteredProcesses : (processes || []);
+
+  // Keyboard shortcuts
+  useKeyboardShortcuts({
+    shortcuts: [
+      {
+        key: '/',
+        description: 'Focus search',
+        action: () => {
+          // Find and focus the search input
+          const searchInput = document.querySelector('input[type="text"]') as HTMLInputElement;
+          if (searchInput) {
+            searchInput.focus();
+          }
+        },
+      },
+      {
+        key: 'r',
+        description: 'Refresh',
+        action: () => {
+          refetch();
+        },
+      },
+      {
+        key: 'a',
+        description: 'Select all',
+        action: () => {
+          if (viewMode === 'flat') {
+            handleSelectAll();
+          }
+        },
+        enabled: viewMode === 'flat' && displayedProcesses.length > 0,
+      },
+      {
+        key: 'Escape',
+        description: 'Clear selection',
+        action: () => {
+          if (selectedProcesses.size > 0) {
+            handleClearSelection();
+          }
+          setFocusedIndex(-1);
+        },
+      },
+      {
+        key: '?',
+        shift: true,
+        description: 'Show keyboard shortcuts',
+        action: () => {
+          setShowShortcutsHelp(true);
+        },
+      },
+      {
+        key: 'j',
+        description: 'Next process',
+        action: () => {
+          if (viewMode === 'flat' && displayedProcesses.length > 0) {
+            setFocusedIndex((prev) => {
+              const next = prev + 1;
+              return next >= displayedProcesses.length ? 0 : next;
+            });
+          }
+        },
+        enabled: viewMode === 'flat' && displayedProcesses.length > 0,
+      },
+      {
+        key: 'k',
+        description: 'Previous process',
+        action: () => {
+          if (viewMode === 'flat' && displayedProcesses.length > 0) {
+            setFocusedIndex((prev) => {
+              const next = prev - 1;
+              return next < 0 ? displayedProcesses.length - 1 : next;
+            });
+          }
+        },
+        enabled: viewMode === 'flat' && displayedProcesses.length > 0,
+      },
+      {
+        key: ' ',
+        description: 'Toggle selection',
+        action: () => {
+          if (viewMode === 'flat' && focusedIndex >= 0 && focusedIndex < displayedProcesses.length) {
+            const process = displayedProcesses[focusedIndex];
+            const fullName = `${process.group}:${process.name}`;
+            handleSelectionChange(fullName, !selectedProcesses.has(fullName));
+          }
+        },
+        enabled: viewMode === 'flat' && focusedIndex >= 0 && displayedProcesses.length > 0,
+      },
+    ],
+  });
+
+  // Auto-select focused process
+  useEffect(() => {
+    if (focusedIndex >= 0 && focusedIndex < displayedProcesses.length) {
+      const process = displayedProcesses[focusedIndex];
+      const fullName = `${process.group}:${process.name}`;
+      const element = document.querySelector(`[data-process-id="${fullName}"]`);
+      if (element) {
+        element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }
+    }
+  }, [focusedIndex, displayedProcesses]);
+
   if (isLoading) {
     return (
       <div className="space-y-6">
@@ -80,8 +190,6 @@ export default function ProcessesPage() {
     );
   }
 
-  const displayedProcesses = filteredProcesses.length > 0 || !processes ? filteredProcesses : processes;
-
   return (
     <div className="space-y-6 animate-fade-in">
       <div className="flex items-center justify-between">
@@ -109,6 +217,14 @@ export default function ProcessesPage() {
             <RefreshCw className="h-4 w-4 mr-2" />
             Refresh
           </Button>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setShowShortcutsHelp(true)}
+            title="Keyboard Shortcuts (Shift+?)"
+          >
+            <Keyboard className="h-4 w-4" />
+          </Button>
         </div>
       </div>
 
@@ -130,15 +246,18 @@ export default function ProcessesPage() {
         <GroupView processes={displayedProcesses} />
       ) : (
         <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
-          {displayedProcesses.map((process) => {
+          {displayedProcesses.map((process, index) => {
             const fullName = `${process.group}:${process.name}`;
+            const isFocused = index === focusedIndex;
             return (
-              <ProcessCard
-                key={fullName}
-                process={process}
-                isSelected={selectedProcesses.has(fullName)}
-                onSelectionChange={handleSelectionChange}
-              />
+              <div key={fullName} data-process-id={fullName}>
+                <ProcessCard
+                  process={process}
+                  isSelected={selectedProcesses.has(fullName)}
+                  onSelectionChange={handleSelectionChange}
+                  isFocused={isFocused}
+                />
+              </div>
             );
           })}
         </div>
@@ -149,6 +268,11 @@ export default function ProcessesPage() {
         processes={displayedProcesses}
         onClearSelection={handleClearSelection}
       />
+
+      {/* Keyboard Shortcuts Help */}
+      {showShortcutsHelp && (
+        <KeyboardShortcutsHelp onClose={() => setShowShortcutsHelp(false)} />
+      )}
     </div>
   );
 }

components/process/ProcessCard.tsx

@@ -14,10 +14,11 @@ import { cn } from '@/lib/utils/cn';
 interface ProcessCardProps {
   process: ProcessInfo;
   isSelected?: boolean;
+  isFocused?: boolean;
   onSelectionChange?: (processId: string, selected: boolean) => void;
 }
 
-export function ProcessCard({ process, isSelected = false, onSelectionChange }: ProcessCardProps) {
+export function ProcessCard({ process, isSelected = false, isFocused = false, onSelectionChange }: ProcessCardProps) {
   const [showSignalModal, setShowSignalModal] = useState(false);
   const [showStdinModal, setShowStdinModal] = useState(false);
   const startMutation = useStartProcess();
@@ -43,7 +44,8 @@ export function ProcessCard({ process, isSelected = false, onSelectionChange }:
       className={cn(
         'transition-all hover:shadow-lg animate-fade-in',
         onSelectionChange && 'cursor-pointer',
-        isSelected && 'ring-2 ring-primary ring-offset-2'
+        isSelected && 'ring-2 ring-primary ring-offset-2',
+        isFocused && 'ring-2 ring-accent ring-offset-2 shadow-xl'
       )}
       onClick={onSelectionChange ? handleCardClick : undefined}
     >

components/ui/KeyboardShortcutsHelp.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { X, Keyboard } from 'lucide-react';
+
+interface KeyboardShortcutsHelpProps {
+  onClose: () => void;
+}
+
+interface ShortcutGroup {
+  title: string;
+  shortcuts: Array<{
+    keys: string[];
+    description: string;
+  }>;
+}
+
+const SHORTCUT_GROUPS: ShortcutGroup[] = [
+  {
+    title: 'Navigation',
+    shortcuts: [
+      { keys: ['/'], description: 'Focus search field' },
+      { keys: ['j'], description: 'Select next process' },
+      { keys: ['k'], description: 'Select previous process' },
+      { keys: ['Esc'], description: 'Clear selection / Close modals' },
+    ],
+  },
+  {
+    title: 'Actions',
+    shortcuts: [
+      { keys: ['r'], description: 'Refresh process list' },
+      { keys: ['Space'], description: 'Toggle process selection' },
+      { keys: ['a'], description: 'Select all processes' },
+      { keys: ['s'], description: 'Start selected processes' },
+      { keys: ['x'], description: 'Stop selected processes' },
+      { keys: ['t'], description: 'Restart selected processes' },
+    ],
+  },
+  {
+    title: 'General',
+    shortcuts: [
+      { keys: ['?'], description: 'Show keyboard shortcuts (this dialog)' },
+    ],
+  },
+];
+
+export function KeyboardShortcutsHelp({ onClose }: KeyboardShortcutsHelpProps) {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm">
+      <Card className="w-full max-w-2xl shadow-2xl max-h-[80vh] overflow-y-auto">
+        <CardHeader>
+          <div className="flex items-center justify-between">
+            <div>
+              <CardTitle className="flex items-center gap-2">
+                <Keyboard className="h-5 w-5" />
+                Keyboard Shortcuts
+              </CardTitle>
+              <CardDescription className="mt-1">
+                Use these keyboard shortcuts to navigate and control processes
+              </CardDescription>
+            </div>
+            <Button variant="ghost" size="icon" onClick={onClose}>
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+        </CardHeader>
+
+        <CardContent className="space-y-6">
+          {SHORTCUT_GROUPS.map((group) => (
+            <div key={group.title}>
+              <h3 className="text-sm font-semibold mb-3 text-muted-foreground uppercase tracking-wide">
+                {group.title}
+              </h3>
+              <div className="space-y-2">
+                {group.shortcuts.map((shortcut, index) => (
+                  <div
+                    key={index}
+                    className="flex items-center justify-between py-2 px-3 rounded-md hover:bg-accent/5"
+                  >
+                    <span className="text-sm">{shortcut.description}</span>
+                    <div className="flex gap-1">
+                      {shortcut.keys.map((key, keyIndex) => (
+                        <kbd
+                          key={keyIndex}
+                          className="px-2 py-1 text-xs font-semibold text-foreground bg-muted border border-border rounded shadow-sm min-w-[2rem] text-center"
+                        >
+                          {key}
+                        </kbd>
+                      ))}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+
+          <div className="pt-4 border-t border-border">
+            <p className="text-xs text-muted-foreground">
+              Note: Most shortcuts are disabled when typing in input fields. Press{' '}
+              <kbd className="px-1 py-0.5 text-xs font-semibold bg-muted border border-border rounded">
+                Esc
+              </kbd>{' '}
+              to exit input fields and enable shortcuts.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

lib/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,88 @@
+import { useEffect, useCallback } from 'react';
+
+export interface KeyboardShortcut {
+  key: string;
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  description: string;
+  action: () => void;
+  enabled?: boolean;
+}
+
+export interface UseKeyboardShortcutsOptions {
+  shortcuts: KeyboardShortcut[];
+  ignoreWhenInputFocused?: boolean;
+}
+
+/**
+ * Hook for managing keyboard shortcuts
+ * Automatically handles event listeners and cleanup
+ */
+export function useKeyboardShortcuts({
+  shortcuts,
+  ignoreWhenInputFocused = true,
+}: UseKeyboardShortcutsOptions) {
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      // Ignore if typing in input/textarea/select
+      if (ignoreWhenInputFocused) {
+        const target = event.target as HTMLElement;
+        const tagName = target.tagName.toLowerCase();
+        const isEditable = target.isContentEditable;
+
+        if (
+          tagName === 'input' ||
+          tagName === 'textarea' ||
+          tagName === 'select' ||
+          isEditable
+        ) {
+          // Allow ESC to blur inputs
+          if (event.key === 'Escape') {
+            target.blur();
+          }
+          return;
+        }
+      }
+
+      // Find matching shortcut
+      for (const shortcut of shortcuts) {
+        if (shortcut.enabled === false) continue;
+
+        const keyMatches = event.key.toLowerCase() === shortcut.key.toLowerCase();
+        const ctrlMatches = shortcut.ctrl ? event.ctrlKey || event.metaKey : !event.ctrlKey && !event.metaKey;
+        const shiftMatches = shortcut.shift ? event.shiftKey : !event.shiftKey;
+        const altMatches = shortcut.alt ? event.altKey : !event.altKey;
+
+        if (keyMatches && ctrlMatches && shiftMatches && altMatches) {
+          event.preventDefault();
+          shortcut.action();
+          break;
+        }
+      }
+    },
+    [shortcuts, ignoreWhenInputFocused]
+  );
+
+  useEffect(() => {
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [handleKeyDown]);
+}
+
+/**
+ * Common keyboard shortcuts for reference
+ */
+export const COMMON_SHORTCUTS = {
+  SEARCH: { key: '/', description: 'Focus search' },
+  REFRESH: { key: 'r', description: 'Refresh data' },
+  SELECT_ALL: { key: 'a', description: 'Select all' },
+  ESCAPE: { key: 'Escape', description: 'Clear selection / Close modal' },
+  HELP: { key: '?', shift: true, description: 'Show keyboard shortcuts' },
+  NEXT: { key: 'j', description: 'Next item' },
+  PREVIOUS: { key: 'k', description: 'Previous item' },
+  SELECT: { key: ' ', description: 'Toggle selection' },
+  START: { key: 's', description: 'Start selected' },
+  STOP: { key: 'x', description: 'Stop selected' },
+  RESTART: { key: 't', description: 'Restart selected' },
+} as const;