feat: P3 — keyboard shortcuts + PWA

Keyboard shortcuts:
- useKeyboardShortcuts hook: global keydown listener, supports 'mod+' (⌘ on
  macOS, Ctrl elsewhere), skips when focus is on input/textarea/contenteditable
  except for Escape which always reaches handlers.
- ShortcutHelp modal with <kbd>-styled key combos, grouped by category;
  opens on '?', closes on Esc or backdrop click.
- HelpCircle button in the sidebar header surfaces the modal so users can
  discover shortcuts without knowing the binding.
- Bindings: ? (help) · Esc (close) · s (toggle sidebar) · c (toggle combined
  view) · 1-5 (switch Display Options tab).

PWA:
- vite-plugin-pwa with autoUpdate registration.
- Manifest: name, theme color (#3b82f6), standalone display, relative
  start_url so GitHub Pages and Vercel both work without rebuild.
- Workbox precaches app shell + Inter/JetBrains Mono fonts (~944 KB total)
  for full offline boot. Install prompt appears in Chromium-based browsers.

Tests: +4 cases for formatBinding (103 passing).

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

Author: JavaZeroo

package-lock.json

@@ -45,6 +45,7 @@
     "globals": "^16.0.0",
     "jsdom": "^24.0.0",
     "vite": "^6.3.5",
+    "vite-plugin-pwa": "^1.3.0",
     "vitest": "^1.4.0"
   }
 }

package.json

@@ -174,6 +174,17 @@
   "configModal.example3": "Start: 0, End: empty → shows all data points (default)",
   "configModal.cancel": "Cancel",
   "configModal.save": "Save Config",
+  "shortcuts.title": "Keyboard shortcuts",
+  "shortcuts.close": "Close shortcuts",
+  "shortcuts.hint": "Shortcuts are disabled while typing in inputs. Esc always works.",
+  "shortcuts.aria": "Show keyboard shortcuts",
+  "shortcuts.groupGeneral": "General",
+  "shortcuts.groupView": "View",
+  "shortcuts.groupDisplay": "Display options",
+  "shortcuts.help": "Show shortcuts",
+  "shortcuts.escape": "Close dialog or help",
+  "shortcuts.toggleSidebar": "Toggle sidebar",
+  "shortcuts.toggleCombined": "Toggle combined view",
   "toast.parseError": "Failed to parse {{name}}: {{error}}",
   "toast.parseComplete": "Parsed {{name}}",
   "toast.storageQuotaExceeded": "Storage limit reached. File persistence has been disabled for this session.",

public/locales/en/translation.json

@@ -174,6 +174,17 @@
   "configModal.example3": "起始: 0, 结束: 留空 → 显示全部数据点（默认）",
   "configModal.cancel": "取消",
   "configModal.save": "保存配置",
+  "shortcuts.title": "键盘快捷键",
+  "shortcuts.close": "关闭快捷键面板",
+  "shortcuts.hint": "在输入框聚焦时快捷键暂停（Esc 始终生效）。",
+  "shortcuts.aria": "显示键盘快捷键",
+  "shortcuts.groupGeneral": "通用",
+  "shortcuts.groupView": "视图",
+  "shortcuts.groupDisplay": "显示选项",
+  "shortcuts.help": "显示快捷键",
+  "shortcuts.escape": "关闭对话框或帮助",
+  "shortcuts.toggleSidebar": "切换侧栏",
+  "shortcuts.toggleCombined": "切换合并视图",
   "toast.parseError": "解析 {{name}} 失败：{{error}}",
   "toast.parseComplete": "已解析 {{name}}",
   "toast.storageQuotaExceeded": "存储空间已满，本次会话将不再持久化文件。",

public/locales/zh/translation.json

@@ -10,8 +10,10 @@ import { ThemeToggle } from './components/ThemeToggle';
 import { Header } from './components/Header';
 import { AnnotationsPanel } from './components/AnnotationsPanel.jsx';
 import { CollapsibleCardHeader } from './components/CollapsibleCardHeader.jsx';
+import { ShortcutHelp } from './components/ShortcutHelp.jsx';
 import { useCollapsedSection } from './utils/useCollapsedSection.js';
-import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import { useKeyboardShortcuts } from './utils/useKeyboardShortcuts.js';
+import { PanelLeftClose, PanelLeftOpen, HelpCircle } from 'lucide-react';
 import { mergeFilesWithReplacement } from './utils/mergeFiles.js';
 import { useToast } from './components/ToastContext.jsx';
 import { loadFiles as loadFilesFromStorage, saveFiles as saveFilesToStorage, clearFiles as clearFilesInStorage } from './utils/fileStorage.js';
@@ -122,6 +124,7 @@ function App() {
     try { localStorage.setItem('ui.displayTab', displayTab); } catch { /* noop */ }
   }, [displayTab]);
   const [displayOpen, setDisplayOpen] = useCollapsedSection('display', true);
+  const [helpOpen, setHelpOpen] = useState(false);
   const savingDisabledRef = useRef(false);
   const enabledFiles = uploadedFiles.filter(file => file.enabled);
   const workerRef = useRef(null);
@@ -404,6 +407,23 @@ function App() {
     });
   }, [globalParsingConfig]);
 
+  // Global keyboard shortcuts. Memoized handlers via inline functions —
+  // the hook reads latest bindings via ref, so closures stay fresh.
+  useKeyboardShortcuts({
+    '?': () => setHelpOpen(true),
+    'Escape': () => {
+      setHelpOpen(false);
+      setConfigModalOpen(false);
+    },
+    's': () => setSidebarVisible(v => !v),
+    'c': () => setChartConfig(prev => ({ ...prev, combinedView: !prev.combinedView })),
+    '1': () => setDisplayTab('chart'),
+    '2': () => setDisplayTab('smoothing'),
+    '3': () => setDisplayTab('stats'),
+    '4': () => setDisplayTab('performance'),
+    '5': () => setDisplayTab('baseline')
+  });
+
   // Reset configuration
   const handleResetConfig = useCallback(() => {
     savingDisabledRef.current = true;
@@ -561,6 +581,14 @@ function App() {
                   <div className="ml-auto flex items-center gap-2">
                     <Header />
                     <ThemeToggle />
+                    <button
+                      onClick={() => setHelpOpen(true)}
+                      className="p-1 text-gray-400 hover:text-gray-600 dark:text-gray-400 dark:hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-blue-500 rounded"
+                      aria-label={t('shortcuts.aria')}
+                      title={t('shortcuts.aria') + ' (?)'}
+                    >
+                      <HelpCircle size={16} aria-hidden="true" />
+                    </button>
                   </div>
                   <button
                     onClick={() => setSidebarVisible(false)}
@@ -904,6 +932,37 @@ function App() {
         onSave={handleConfigSave}
         globalParsingConfig={globalParsingConfig}
       />
+
+      <ShortcutHelp
+        isOpen={helpOpen}
+        onClose={() => setHelpOpen(false)}
+        groups={[
+          {
+            title: t('shortcuts.groupGeneral'),
+            items: [
+              { label: t('shortcuts.help'), key: '?' },
+              { label: t('shortcuts.escape'), key: 'Escape' }
+            ]
+          },
+          {
+            title: t('shortcuts.groupView'),
+            items: [
+              { label: t('shortcuts.toggleSidebar'), key: 's' },
+              { label: t('shortcuts.toggleCombined'), key: 'c' }
+            ]
+          },
+          {
+            title: t('shortcuts.groupDisplay'),
+            items: [
+              { label: t('display.tabChart'), key: '1' },
+              { label: t('display.tabSmoothing'), key: '2' },
+              { label: t('display.tabStats'), key: '3' },
+              { label: t('display.tabPerformance'), key: '4' },
+              { label: t('display.tabBaseline'), key: '5' }
+            ]
+          }
+        ]}
+      />
     </div>
   );
 }

src/App.jsx

@@ -0,0 +1,113 @@
+import React, { useEffect, useRef } from 'react';
+import { X, Keyboard } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { formatBinding } from '../utils/useKeyboardShortcuts.js';
+
+// Visual representation of one or more keys, optionally joined by '+'.
+function KeyCombo({ binding }) {
+  const tokens = formatBinding(binding);
+  return (
+    <span className="inline-flex items-center gap-0.5" aria-label={binding}>
+      {tokens.map((tok, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <span className="text-gray-400 dark:text-gray-500 text-xs">+</span>}
+          <kbd className="inline-flex items-center justify-center min-w-[1.5rem] h-6 px-1.5 text-[11px] font-medium font-mono text-gray-700 dark:text-gray-200 bg-gray-100 dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded shadow-[inset_0_-1px_0_rgb(0,0,0,0.06)]">
+            {tok}
+          </kbd>
+        </React.Fragment>
+      ))}
+    </span>
+  );
+}
+
+// Display a sequence of bindings, e.g. ['g', 'd'] = press g then d.
+function KeySequence({ keys }) {
+  return (
+    <span className="inline-flex items-center gap-1">
+      {keys.map((k, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <span className="text-gray-400 dark:text-gray-500 text-xs">then</span>}
+          <KeyCombo binding={k} />
+        </React.Fragment>
+      ))}
+    </span>
+  );
+}
+
+export function ShortcutHelp({ isOpen, onClose, groups }) {
+  const { t } = useTranslation();
+  const closeBtnRef = useRef(null);
+
+  // Send focus to the close button on open so screen readers announce the
+  // dialog, and Escape always lands somewhere useful.
+  useEffect(() => {
+    if (isOpen && closeBtnRef.current) {
+      closeBtnRef.current.focus();
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      className="fixed inset-0 bg-black/50 z-50 flex items-center justify-center p-4 drag-overlay-fade-in"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="shortcut-help-title"
+      onClick={onClose}
+    >
+      <div
+        className="bg-white dark:bg-gray-800 rounded-xl shadow-2xl max-w-lg w-full max-h-[85vh] overflow-y-auto drag-modal-scale-in"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-200 dark:border-gray-700">
+          <div className="flex items-center gap-2">
+            <Keyboard size={18} className="text-blue-600 dark:text-blue-400" aria-hidden="true" />
+            <h2 id="shortcut-help-title" className="text-base font-semibold text-gray-900 dark:text-gray-100">
+              {t('shortcuts.title')}
+            </h2>
+          </div>
+          <button
+            ref={closeBtnRef}
+            type="button"
+            onClick={onClose}
+            className="p-1 text-gray-400 hover:text-gray-700 dark:hover:text-gray-200 rounded focus:outline-none focus:ring-2 focus:ring-blue-500"
+            aria-label={t('shortcuts.close')}
+          >
+            <X size={18} aria-hidden="true" />
+          </button>
+        </div>
+
+        <div className="px-5 py-4 space-y-5">
+          {groups.map((group) => (
+            <section key={group.title} aria-labelledby={`group-${group.title}`}>
+              <h3
+                id={`group-${group.title}`}
+                className="text-[11px] font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400 mb-2"
+              >
+                {group.title}
+              </h3>
+              <ul className="space-y-1.5">
+                {group.items.map((item) => (
+                  <li
+                    key={item.label}
+                    className="flex items-center justify-between text-sm text-gray-700 dark:text-gray-300"
+                  >
+                    <span>{item.label}</span>
+                    {item.sequence
+                      ? <KeySequence keys={item.sequence} />
+                      : <KeyCombo binding={item.key} />}
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </div>
+
+        <div className="px-5 py-3 border-t border-gray-200 dark:border-gray-700 text-xs text-gray-500 dark:text-gray-400">
+          {t('shortcuts.hint')}
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/ShortcutHelp.jsx

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { formatBinding } from '../useKeyboardShortcuts';
+
+// formatBinding is pure and platform-aware; we exercise the platform-neutral
+// paths since jsdom's navigator.platform isn't macOS-like by default.
+
+describe('formatBinding', () => {
+  it('returns the uppercase letter for single-key bindings', () => {
+    expect(formatBinding('s')).toEqual(['S']);
+  });
+
+  it('returns the verbatim name for special keys', () => {
+    expect(formatBinding('Escape')).toEqual(['Escape']);
+  });
+
+  it('orders modifiers before the key', () => {
+    const tokens = formatBinding('shift+k');
+    expect(tokens[tokens.length - 1]).toBe('K');
+    expect(tokens.length).toBe(2);
+  });
+
+  it('handles digit keys', () => {
+    expect(formatBinding('1')).toEqual(['1']);
+  });
+});