From 0f38b2946de5c1e813e8d9a7d4cc4f0820c088f7 Mon Sep 17 00:00:00 2001
From: Konstantin Kolesnyak <constkolesnyak@gmail.com>
Date: Mon, 15 Jun 2026 23:48:23 +0200
Subject: [PATCH] feat(web): keyboard shortcuts (claude.ai parity)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a small shortcut system around a single document-level keydown
listener plus a help modal. Mirrors the bindings claude.ai/chat exposes,
skipping ones that don't map (artifacts, force-send, settings).

Global: ⌘⇧O new chat, ⌘K focus search, ⌘/ shortcuts modal,
Esc cascades to modal → search → stop generation.

Chat: ⌘⇧S sidebar, ⌘⇧; focus input, ⌘⇧C copy last response,
⌘⇧⌫ delete current (confirmed), ⌘\ side panel (already existed).

Mac/Linux labels and Backspace/Delete aliases render automatically.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 web/src/App.tsx                            |  86 ++++++++++++++-
 web/src/components/Chat/ChatInput.tsx      |   1 +
 web/src/components/Chat/SessionSidebar.tsx |   1 +
 web/src/components/ShortcutsModal.tsx      | 122 +++++++++++++++++++++
 web/src/hooks/useKeyboardShortcuts.ts      |  34 ++++++
 web/src/pages/ChatPage.tsx                 |  84 ++++++++++++--
 web/src/stores/uiStore.ts                  |  19 ++++
 web/src/utils/keyboard.ts                  |  95 ++++++++++++++++
 8 files changed, 428 insertions(+), 14 deletions(-)
 create mode 100644 web/src/components/ShortcutsModal.tsx
 create mode 100644 web/src/hooks/useKeyboardShortcuts.ts
 create mode 100644 web/src/stores/uiStore.ts
 create mode 100644 web/src/utils/keyboard.ts

diff --git a/web/src/App.tsx b/web/src/App.tsx
index 9c195ef..9f4ebfa 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -1,8 +1,11 @@
-import { useEffect } from 'react';
-import { Routes, Route, Navigate } from 'react-router-dom';
+import { useEffect, useMemo } from 'react';
+import { Routes, Route, Navigate, useNavigate } from 'react-router-dom';
 import { useAuthStore } from './stores/authStore';
 import { ws } from './api/websocket';
 import { useChatStore } from './stores/chatStore';
+import { useUIStore } from './stores/uiStore';
+import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts';
+import type { ShortcutDef } from './utils/keyboard';
 import { LoginPage } from './components/Auth/LoginPage';
 import { AppShell } from './components/Layout/AppShell';
 import { ChatPage } from './pages/ChatPage';
@@ -22,6 +25,7 @@ import { HouseOfAgentsPage } from './pages/HouseOfAgentsPage';
 import { McpServerDetailPage } from './pages/McpServerDetailPage';
 import { NotificationsPage } from './pages/NotificationsPage';
 import { NotificationToast } from './components/Notifications/NotificationToast';
+import { ShortcutsModal } from './components/ShortcutsModal';
 
 function App() {
   const { authenticated, checking, checkAuth } = useAuthStore();
@@ -42,6 +46,7 @@ function App() {
 
   return (
     <>
+      <GlobalShortcuts />
       <Routes>
         <Route element={<AppShell />}>
           <Route path="/" element={<Navigate to="/chat" replace />} />
@@ -64,8 +69,85 @@ function App() {
         </Route>
       </Routes>
       <NotificationToast />
+      <ShortcutsModal />
     </>
   );
 }
 
+/**
+ * Global keyboard shortcuts — work on every page. Page-scoped chat shortcuts
+ * live in ChatPage so they only activate while the chat view is mounted.
+ *
+ * Esc behavior is intentionally cascaded:
+ *   1. ShortcutsModal swallows Esc first via capture-phase listener.
+ *   2. SessionSidebar's own listener clears search when active.
+ *   3. This handler stops generation only if streaming and nothing else
+ *      is claiming Esc (modal closed, search empty).
+ */
+function GlobalShortcuts() {
+  const navigate = useNavigate();
+
+  const shortcuts = useMemo<ShortcutDef[]>(() => [
+    {
+      id: 'global-new-chat',
+      combo: { mod: true, shift: true, key: 'o' },
+      description: 'New chat',
+      section: 'global',
+      action: () => {
+        navigate('/chat');
+        void useChatStore.getState().createSession();
+      },
+    },
+    {
+      id: 'global-focus-search',
+      combo: { mod: true, key: 'k' },
+      description: 'Focus session search',
+      section: 'global',
+      allowInInput: true, // allow even when focus is in chat textarea
+      action: () => {
+        if (!window.location.pathname.startsWith('/chat')) {
+          navigate('/chat');
+        }
+        // Defer focus until after route change paints the sidebar input.
+        setTimeout(() => {
+          if (useChatStore.getState().sidebarCollapsed) {
+            useChatStore.getState().toggleSidebar();
+          }
+          const el = document.getElementById('nerve-sidebar-search');
+          if (el instanceof HTMLInputElement) {
+            el.focus();
+            el.select();
+          }
+        }, 0);
+      },
+    },
+    {
+      id: 'global-shortcuts-modal',
+      combo: { mod: true, key: '/' },
+      description: 'Show keyboard shortcuts',
+      section: 'global',
+      allowInInput: true,
+      action: () => useUIStore.getState().toggleShortcutsModal(),
+    },
+    {
+      id: 'global-esc-stop',
+      combo: { key: 'Escape' },
+      description: 'Stop generation',
+      section: 'global',
+      // Only fire when nothing else is claiming Esc:
+      // - modal handles its own Esc in capture phase
+      // - sidebar handles Esc only while searching
+      when: () => {
+        if (useUIStore.getState().shortcutsModalOpen) return false;
+        if (!useChatStore.getState().isStreaming) return false;
+        return true;
+      },
+      action: () => useChatStore.getState().stopSession(),
+    },
+  ], [navigate]);
+
+  useKeyboardShortcuts(shortcuts);
+  return null;
+}
+
 export default App;
diff --git a/web/src/components/Chat/ChatInput.tsx b/web/src/components/Chat/ChatInput.tsx
index 7d0217a..cc86669 100644
--- a/web/src/components/Chat/ChatInput.tsx
+++ b/web/src/components/Chat/ChatInput.tsx
@@ -433,6 +433,7 @@ export function ChatInput({ onSend, onStop, isStreaming, disabled }: {
           />
 
           <textarea
+            id="nerve-chat-input"
             ref={textareaRef}
             value={input}
             onChange={(e) => { setInput(e.target.value); handleInput(); }}
diff --git a/web/src/components/Chat/SessionSidebar.tsx b/web/src/components/Chat/SessionSidebar.tsx
index cc0c49c..d1b4c06 100644
--- a/web/src/components/Chat/SessionSidebar.tsx
+++ b/web/src/components/Chat/SessionSidebar.tsx
@@ -142,6 +142,7 @@ export function SessionSidebar({ sessions, activeSession, agentStatus, onSelect,
         <div className="relative">
           <Search size={12} className="absolute left-2 top-1/2 -translate-y-1/2 text-text-faint" />
           <input
+            id="nerve-sidebar-search"
             ref={inputRef}
             type="text"
             value={localQuery}
diff --git a/web/src/components/ShortcutsModal.tsx b/web/src/components/ShortcutsModal.tsx
new file mode 100644
index 0000000..ecd7b83
--- /dev/null
+++ b/web/src/components/ShortcutsModal.tsx
@@ -0,0 +1,122 @@
+import { useEffect } from 'react';
+import { X } from 'lucide-react';
+import { useUIStore } from '../stores/uiStore';
+import { formatCombo, type ShortcutCombo } from '../utils/keyboard';
+
+interface DisplayShortcut {
+  combo: ShortcutCombo;
+  description: string;
+}
+
+interface Section {
+  title: string;
+  items: DisplayShortcut[];
+}
+
+/**
+ * Static display of every keyboard binding. The runtime handlers live in
+ * App.tsx (global) and ChatPage.tsx (chat-scoped) — keep this list in sync
+ * with those when bindings change.
+ */
+const SECTIONS: Section[] = [
+  {
+    title: 'General',
+    items: [
+      { combo: { mod: true, shift: true, key: 'o' }, description: 'New chat' },
+      { combo: { mod: true, key: 'k' }, description: 'Focus session search' },
+      { combo: { mod: true, key: '/' }, description: 'Show keyboard shortcuts' },
+      { combo: { key: 'Escape' }, description: 'Close dialog · clear search · stop generation' },
+    ],
+  },
+  {
+    title: 'Chat',
+    items: [
+      { combo: { mod: true, shift: true, key: 's' }, description: 'Toggle session sidebar' },
+      { combo: { mod: true, shift: true, key: ';' }, description: 'Focus message input' },
+      { combo: { mod: true, shift: true, key: 'c' }, description: 'Copy last response' },
+      { combo: { mod: true, shift: true, key: 'Backspace' }, description: 'Delete current conversation' },
+      { combo: { mod: true, key: '\\' }, description: 'Toggle side panel' },
+    ],
+  },
+  {
+    title: 'Message input',
+    items: [
+      { combo: { key: 'Enter' }, description: 'Send message' },
+      { combo: { shift: true, key: 'Enter' }, description: 'New line' },
+    ],
+  },
+];
+
+export function ShortcutsModal() {
+  const open = useUIStore((s) => s.shortcutsModalOpen);
+  const close = useUIStore((s) => s.closeShortcutsModal);
+
+  // Local Esc handler — runs *before* the document-level shortcut listeners
+  // because modal mount captures it first when focus is inside.
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        close();
+      }
+    };
+    document.addEventListener('keydown', onKey, true); // capture phase = wins
+    return () => document.removeEventListener('keydown', onKey, true);
+  }, [open, close]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 bg-black/60 flex items-center justify-center z-50"
+      onClick={close}
+    >
+      <div
+        className="bg-surface-raised border border-border-subtle rounded-xl w-[520px] max-w-[90vw] max-h-[80vh] flex flex-col"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-3 border-b border-border">
+          <h2 className="text-[15px] font-semibold">Keyboard shortcuts</h2>
+          <button
+            onClick={close}
+            className="text-text-faint hover:text-text-muted cursor-pointer p-1"
+            title="Close"
+          >
+            <X size={18} />
+          </button>
+        </div>
+
+        <div className="overflow-y-auto p-5 space-y-5">
+          {SECTIONS.map((section) => (
+            <div key={section.title}>
+              <h3 className="text-[11px] uppercase tracking-wider text-text-faint font-medium mb-2">
+                {section.title}
+              </h3>
+              <div className="space-y-1.5">
+                {section.items.map((item, idx) => (
+                  <div
+                    key={idx}
+                    className="flex items-center justify-between gap-4 py-1"
+                  >
+                    <span className="text-[13px] text-text-secondary">{item.description}</span>
+                    <Kbd combo={item.combo} />
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Kbd({ combo }: { combo: ShortcutCombo }) {
+  return (
+    <kbd className="px-2 py-1 text-[11px] font-mono text-text-secondary bg-surface border border-border-subtle rounded shrink-0 tabular-nums">
+      {formatCombo(combo)}
+    </kbd>
+  );
+}
diff --git a/web/src/hooks/useKeyboardShortcuts.ts b/web/src/hooks/useKeyboardShortcuts.ts
new file mode 100644
index 0000000..e1764fb
--- /dev/null
+++ b/web/src/hooks/useKeyboardShortcuts.ts
@@ -0,0 +1,34 @@
+import { useEffect } from 'react';
+import { isTypingTarget, matchesCombo, type ShortcutDef } from '../utils/keyboard';
+
+/**
+ * Attach a `document`-level keydown listener that fires the first shortcut
+ * whose combo matches the event. Order matters: more specific shortcuts
+ * should come first.
+ *
+ * Skips when focus is inside an editable element unless the shortcut sets
+ * `allowInInput: true`. Skips when the shortcut's `when()` predicate is
+ * defined and returns false.
+ *
+ * Pass the same array reference across renders if you can — otherwise we
+ * re-register the listener on every render. In practice the callers below
+ * build a fresh array each render but the cost is one removeEventListener +
+ * addEventListener, which is negligible.
+ */
+export function useKeyboardShortcuts(shortcuts: ShortcutDef[]): void {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      const typing = isTypingTarget(e.target);
+      for (const sc of shortcuts) {
+        if (typing && !sc.allowInInput) continue;
+        if (sc.when && !sc.when()) continue;
+        if (!matchesCombo(e, sc.combo)) continue;
+        e.preventDefault();
+        sc.action(e);
+        return;
+      }
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [shortcuts]);
+}
diff --git a/web/src/pages/ChatPage.tsx b/web/src/pages/ChatPage.tsx
index 43eff42..009bced 100644
--- a/web/src/pages/ChatPage.tsx
+++ b/web/src/pages/ChatPage.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { useParams } from 'react-router-dom';
 import { useChatStore } from '../stores/chatStore';
 import { SessionSidebar } from '../components/Chat/SessionSidebar';
@@ -10,6 +10,9 @@ import { SidePanel } from '../components/Chat/SidePanel';
 import { BackgroundJobs } from '../components/Chat/BackgroundJobs';
 import { Loader2, PanelLeftOpen, PanelLeftClose, Files, ExternalLink } from 'lucide-react';
 import { api } from '../api/client';
+import { useKeyboardShortcuts } from '../hooks/useKeyboardShortcuts';
+import type { ShortcutDef } from '../utils/keyboard';
+import type { ChatMessage, TextBlockData } from '../types/chat';
 
 const STATUS_LABELS: Record<string, string> = {
   thinking: 'Thinking...',
@@ -39,17 +42,60 @@ export function ChatPage() {
     sendMessage, stopSession, toggleSidebar, openFilesPanel,
   } = useChatStore();
 
-  // Cmd/Ctrl + \ toggles side panel
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && e.key === '\\') {
-        e.preventDefault();
-        useChatStore.getState().togglePanel();
-      }
-    };
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, []);
+  // Chat-scoped keyboard shortcuts. Global ones (new chat, search, modal,
+  // Esc cascade) live in <GlobalShortcuts /> in App.tsx.
+  const chatShortcuts = useMemo<ShortcutDef[]>(() => [
+    {
+      id: 'chat-toggle-panel',
+      combo: { mod: true, key: '\\' },
+      description: 'Toggle side panel',
+      section: 'chat',
+      action: () => useChatStore.getState().togglePanel(),
+    },
+    {
+      id: 'chat-toggle-sidebar',
+      combo: { mod: true, shift: true, key: 's' },
+      description: 'Toggle session sidebar',
+      section: 'chat',
+      action: () => useChatStore.getState().toggleSidebar(),
+    },
+    {
+      id: 'chat-focus-input',
+      combo: { mod: true, shift: true, key: ';' },
+      description: 'Focus message input',
+      section: 'chat',
+      allowInInput: true,
+      action: () => {
+        const el = document.getElementById('nerve-chat-input');
+        if (el instanceof HTMLTextAreaElement) el.focus();
+      },
+    },
+    {
+      id: 'chat-copy-last',
+      combo: { mod: true, shift: true, key: 'c' },
+      description: 'Copy last response',
+      section: 'chat',
+      action: () => {
+        const text = getLastAssistantText(useChatStore.getState().messages);
+        if (text) void navigator.clipboard.writeText(text);
+      },
+    },
+    {
+      id: 'chat-delete-current',
+      combo: { mod: true, shift: true, key: 'Backspace' },
+      description: 'Delete current conversation',
+      section: 'chat',
+      action: () => {
+        const id = useChatStore.getState().activeSession;
+        if (!id) return;
+        if (window.confirm('Delete this conversation?')) {
+          void useChatStore.getState().deleteSession(id);
+        }
+      },
+    },
+  ], []);
+
+  useKeyboardShortcuts(chatShortcuts);
 
   // Langfuse deep-link status — fetched once. Shows a small "external link"
   // icon when observability is enabled so we can jump from a session to
@@ -192,3 +238,17 @@ export function ChatPage() {
     </div>
   );
 }
+
+/** Walk messages backwards, return the joined text of the most recent assistant turn. */
+function getLastAssistantText(messages: ChatMessage[]): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== 'assistant') continue;
+    const text = m.blocks
+      .filter((b): b is TextBlockData => b.type === 'text')
+      .map((b) => b.content)
+      .join('\n');
+    return text || null;
+  }
+  return null;
+}
diff --git a/web/src/stores/uiStore.ts b/web/src/stores/uiStore.ts
new file mode 100644
index 0000000..3f7cada
--- /dev/null
+++ b/web/src/stores/uiStore.ts
@@ -0,0 +1,19 @@
+import { create } from 'zustand';
+
+/**
+ * Misc UI state that doesn't belong to a single feature store.
+ * Right now: just the keyboard-shortcuts modal flag.
+ */
+interface UIState {
+  shortcutsModalOpen: boolean;
+  openShortcutsModal: () => void;
+  closeShortcutsModal: () => void;
+  toggleShortcutsModal: () => void;
+}
+
+export const useUIStore = create<UIState>((set, get) => ({
+  shortcutsModalOpen: false,
+  openShortcutsModal: () => set({ shortcutsModalOpen: true }),
+  closeShortcutsModal: () => set({ shortcutsModalOpen: false }),
+  toggleShortcutsModal: () => set({ shortcutsModalOpen: !get().shortcutsModalOpen }),
+}));
diff --git a/web/src/utils/keyboard.ts b/web/src/utils/keyboard.ts
new file mode 100644
index 0000000..7295db7
--- /dev/null
+++ b/web/src/utils/keyboard.ts
@@ -0,0 +1,95 @@
+/**
+ * Keyboard shortcut helpers.
+ *
+ * Conventions used by the shortcut system:
+ * - `mod` = Cmd on macOS, Ctrl elsewhere.
+ * - `key` is matched case-insensitively against `event.key`. For symbols like
+ *   `;` or `/` we match the literal character; for letters we match lowercase.
+ * - `Backspace` and `Delete` are treated as aliases so Mac (⌘Shift⌫) and
+ *   Linux/Windows (Ctrl+Shift+Delete) both work for "delete current".
+ */
+
+/** Detect macOS for both label rendering and to know that Cmd ≠ Ctrl. */
+export const isMac =
+  typeof navigator !== 'undefined' &&
+  /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+
+/** Is the platform's "mod" key (Cmd on Mac, Ctrl elsewhere) pressed? */
+export function isMod(e: KeyboardEvent): boolean {
+  return isMac ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey;
+}
+
+/** Focus is in an editable element — most shortcuts should bail out. */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  if (target.isContentEditable) return true;
+  return false;
+}
+
+export interface ShortcutCombo {
+  /** Requires Cmd (Mac) / Ctrl (other). */
+  mod?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  /**
+   * `event.key` value. Examples: "k", "/", ";", "o", "\\", "Backspace",
+   * "Escape". For letters use lowercase. "Backspace" also matches "Delete"
+   * so Mac and Linux bindings coexist.
+   */
+  key: string;
+}
+
+export interface ShortcutDef {
+  id: string;
+  combo: ShortcutCombo;
+  /** Section + description shown in the modal. */
+  description: string;
+  section: 'global' | 'chat' | 'input';
+  /** Only fire when this returns true (e.g. only on /chat). */
+  when?: () => boolean;
+  /** Default false: skipped when focus is in an editable element. */
+  allowInInput?: boolean;
+  action: (e: KeyboardEvent) => void;
+}
+
+/** Does this keydown event match the combo? */
+export function matchesCombo(e: KeyboardEvent, combo: ShortcutCombo): boolean {
+  if (!!combo.mod !== isMod(e)) return false;
+  if (!!combo.shift !== e.shiftKey) return false;
+  if (!!combo.alt !== e.altKey) return false;
+
+  const eventKey = e.key;
+  const wanted = combo.key;
+  if (wanted === 'Backspace') {
+    return eventKey === 'Backspace' || eventKey === 'Delete';
+  }
+  return eventKey.toLowerCase() === wanted.toLowerCase();
+}
+
+/** Human-readable label for the shortcuts modal. */
+export function formatCombo(combo: ShortcutCombo): string {
+  const parts: string[] = [];
+  if (combo.mod) parts.push(isMac ? '⌘' : 'Ctrl');
+  if (combo.shift) parts.push(isMac ? '⇧' : 'Shift');
+  if (combo.alt) parts.push(isMac ? '⌥' : 'Alt');
+  parts.push(formatKey(combo.key));
+  return parts.join(isMac ? ' ' : '+');
+}
+
+function formatKey(key: string): string {
+  switch (key) {
+    case 'Backspace':
+      return isMac ? '⌫' : 'Backspace';
+    case 'Escape':
+      return 'Esc';
+    case 'Enter':
+      return isMac ? '↵' : 'Enter';
+    case '\\':
+      return '\\';
+    default:
+      // Single letters → uppercase; symbols stay as-is.
+      return key.length === 1 ? key.toUpperCase() : key;
+  }
+}