Phase 5: desktop responsiveness + engine watchdog

apps/console/CLAUDE.md

@@ -42,9 +42,16 @@ via their pre-hooks.
 - **Entry** — `src/main.tsx` mounts `<ThemeModeProvider><StoreProvider><App/>`.
   The persisted theme is applied *before* first paint to avoid a light flash.
 - **State** — `src/store.tsx` holds all app state and actions (`route`,
-  `resolveConflict`, `send`, view/selection setters) in one context. Callbacks
-  read the freshest values through refs so they don't re-subscribe. State is
-  in-memory only — reloads reset it.
+  `resolveConflict`, `send`, view/selection setters) in **three** contexts, split
+  by how often each changes: `data` (engine answers + every action, and every
+  action has a stable identity), `nav` (view and selection), `input` (the search
+  box and the chat composer — changes per keystroke). `useStoreData()` /
+  `useStoreNav()` / `useStoreInput()` are the narrow hooks; `useStore()` merges
+  all three and re-renders on any of them — it has no production callers left,
+  only test mocks, and new code should not add one. Callbacks read the freshest
+  values through refs so they don't re-subscribe. State is in-memory only —
+  reloads reset it. See the subscribe-narrowly gotcha below before adding a
+  consumer.
 - **Views** — `src/views/` (Canvas, Overview, Sources, Triage, Conflicts,
   Concepts, Files). `App.tsx` is the shell: topbar + subbar + routed view, plus
   the Triage S/R/D keyboard handler. The canvas view stays full-height inside
@@ -107,6 +114,22 @@ Key files: `src/store.tsx` (state), `src/theme.ts` (`css()` + tokens),
   `src/theme.ts`. An unregistered hex renders fine in light mode and silently
   fails to adapt in dark mode. Prefer the `C.*` variable refs for new code;
   if you must write a hex, add it to `HEX_VARS`.
+- **Subscribing to the wrong store context fails silently.** Every view root is
+  `React.memo`'d with no props, so the only thing that re-renders it is a context
+  it actually subscribes to. A component that reads query-derived data without
+  calling `useStoreInput()` does not throw, does not warn, and does not
+  re-render — it just quietly stops updating. That shipped: `Triage` read the
+  query through a store callback closed over a ref, subscribed to `data` + `nav`
+  only, and the Queue's search box stopped filtering entirely. The
+  render-count test could not see it, because "did not re-render" was what it
+  was asserting. Two rules follow: **derive from values you subscribed to, never
+  from a ref inside a stable callback** (which is why `filterSignals` is an
+  exported pure function taking `query`, not a `store.filtered(tab)` method —
+  the argument is what forces the caller to have subscribed); and any view in
+  `SEARCHABLE_VIEWS` (`shell-navigation.ts`) must be in the case table in
+  `render-hygiene.test.tsx`, which types a query that matches nothing and
+  asserts the list actually empties. That suite deliberately holds both halves:
+  the sidebar must NOT repaint on a keystroke, and the active view MUST.
 - **Prefer `C.*` / `css()` over raw styles** so both themes and the
   reduced-motion / focus-visible rules keep working.
 - **`css()` is a simple `;`/`:` splitter** — no nested rules, no `url(...)` with

apps/console/src/App.test.tsx

@@ -166,6 +166,10 @@ describe('Mac-first application shell', () => {
     })
     expect(sidebar?.dataset.collapsed).toBe('false')
     expect(sidebar?.style.width).toBe('232px')
+    // Persistence is debounced — a drag would otherwise write on every
+    // pointermove. The value still has to land, so wait out the quiet period
+    // rather than dropping the assertion.
+    await act(async () => { await new Promise((resolve) => setTimeout(resolve, 320)) })
     expect(JSON.parse(window.localStorage.getItem('contextcake.sidebar') ?? '{}')).toEqual({ collapsed: false, width: 232 })
 
     await act(async () => {

apps/console/src/App.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { useStore } from './store'
+import { useStoreData, useStoreNav } from './store'
 import { C, css, MONO } from './theme'
 import { Sidebar } from './components/Sidebar'
 import { Header } from './components/Header'
@@ -11,6 +11,7 @@ import { Conflicts } from './views/Conflicts'
 import { Concepts } from './views/Concepts'
 import { Files } from './views/Files'
 import { ChatPanel } from './components/ChatPanel'
+import { EngineBanner } from './components/EngineBanner'
 import { SetupWizard } from './components/SetupWizard'
 import { ConnectAgentDialog } from './components/ConnectAgentDialog'
 import { SettingsView } from './components/SettingsView'
@@ -66,7 +67,11 @@ function ErrorState({ kind, message, reload }: { kind: LiveErrorKind; message: s
 }
 
 export function App() {
-  const { view, setView, chatOpen, openChat, closeChat, route, loading, load, error, reload, retryNow, mode, sources, loadErrors, openFilesScope } = useStore()
+  // Deliberately three narrow subscriptions rather than `useStore()`: the shell
+  // owns every memoized child below, so an App render is a whole-tree render.
+  // Typing in the toolbar search must not cause one.
+  const { setView, openChat, closeChat, route, loading, load, error, reload, retryNow, mode, sources, loadErrors, openFilesScope } = useStoreData()
+  const { view, chatOpen } = useStoreNav()
   // Undefined = not yet decided by the auto-trigger effect below; true/false
   // once the user (or the trigger) has taken an explicit stance. Kept separate
   // from `needsSetup` so the wizard's own Success step stays visible even
@@ -102,15 +107,18 @@ export function App() {
 
   const showWizard = wizardOpen === true
   const closeWizard = () => setWizardOpen(false)
-  const reopenWizard = () => setWizardOpen(true)
-  const openConnect = () => {
+  // Handlers that reach a memoized child (Sidebar, Header, Sources, ChatPanel)
+  // are stable identities. A fresh arrow function per render would re-render
+  // the child through its memo and give the whole split back.
+  const reopenWizard = useCallback(() => setWizardOpen(true), [])
+  const openConnect = useCallback(() => {
     if (sources.length === 0 && !sourceSetupComplete) {
       setWizardOpen(true)
       return
     }
     setConnectOpen(true)
-  }
-  const openSettings = () => {
+  }, [sources.length, sourceSetupComplete])
+  const openSettings = useCallback(() => {
     if (window.__CC_DESKTOP?.windows) {
       setDrawerOpen(false)
       // Omit a pane so the native window can restore the user's last one.
@@ -121,7 +129,7 @@ export function App() {
     settingsOpener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null
     setDrawerOpen(false)
     setSettingsOpen(true)
-  }
+  }, [])
   const openPalette = () => {
     paletteOpener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null
     setDrawerOpen(false)
@@ -156,7 +164,7 @@ export function App() {
     setDrawerOpen(false)
     window.requestAnimationFrame(() => opener?.isConnected && opener.focus())
   }, [])
-  const toggleSidebar = () => {
+  const toggleSidebar = useCallback(() => {
     if (window.innerWidth < 900) {
       if (drawerOpen) closeDrawer()
       else {
@@ -165,7 +173,7 @@ export function App() {
       }
     }
     else window.dispatchEvent(new Event('contextcake:toggle-sidebar'))
-  }
+  }, [closeDrawer, drawerOpen])
 
   const paletteCommands = useMemo<PaletteCommand[]>(() => [
     { id: 'home', label: 'Go to Home', keywords: 'overview', shortcut: '⌘1', run: () => setView('overview') },
@@ -189,7 +197,7 @@ export function App() {
     { id: 'ask', label: 'Ask ContextCake', shortcut: '⇧⌘A', run: openAskFromPalette },
     { id: 'settings', label: 'Open Settings', shortcut: '⌘,', run: openSettings },
     { id: 'sidebar', label: 'Toggle Sidebar', run: toggleSidebar },
-  ], [isDesktop, mode, openAskFromPalette, openFilesScope, setView, sources, sourceSetupComplete])
+  ], [isDesktop, mode, openAskFromPalette, openConnect, openFilesScope, openSettings, reopenWizard, setView, sources, toggleSidebar])
   const closeSettings = () => {
     const opener = settingsOpener.current
     setSettingsOpen(false)
@@ -373,6 +381,12 @@ export function App() {
             <div className="sr-only" aria-live="polite">
               {backgroundAnnouncement}
             </div>
+            {/*
+              Above the refresh banner on purpose: a wedged engine is the CAUSE
+              of the failing refresh below it, and holds its own state so this
+              app-wide render never runs for it.
+            */}
+            <EngineBanner />
             {load.refreshError && load.refreshError.message !== dismissedRefreshError && (
               <div role="status" style={css(`display:flex; align-items:center; gap:10px; padding:8px 16px; background:${C.amberFill}; border-bottom:1px solid ${C.amberStroke}; font-size:12px; color:${C.amberText};`)}>
                 <span aria-hidden="true">⚠</span>

apps/console/src/components/BackgroundActivity.test.tsx

@@ -11,7 +11,11 @@ import { LiveDataError } from '../api'
 import type { BackgroundTask, Store } from '../store'
 
 const mocks = vi.hoisted(() => ({ store: { current: null as unknown as Store } }))
-vi.mock('../store', () => ({ useStore: () => mocks.store.current }))
+// The store is three contexts now; this component reads the data half.
+vi.mock('../store', () => {
+  const store = () => mocks.store.current
+  return { useStore: store, useStoreData: store, useStoreNav: store, useStoreInput: store }
+})
 
 let container: HTMLDivElement
 let root: Root

apps/console/src/components/BackgroundActivity.tsx

@@ -13,7 +13,7 @@
 // quiet note, never a spinner in front of an answer).
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { progressPercent } from '../api'
-import { useStore } from '../store'
+import { useStoreData } from '../store'
 import type { BackgroundTask } from '../store'
 import { C, css, MONO } from '../theme'
 
@@ -149,7 +149,7 @@ function TaskRow({ task }: { task: BackgroundTask }) {
 }
 
 export function BackgroundActivity() {
-  const { load, retryNow, setView } = useStore()
+  const { load, retryNow, setView } = useStoreData()
   const { tasks, refreshError, lastRefreshAt } = load
   const [open, setOpen] = useState(false)
   const [anchor, setAnchor] = useState<{ top: number; right: number } | null>(null)

apps/console/src/components/ChatPanel.tsx

@@ -1,12 +1,13 @@
-import { useEffect, useRef, useState } from 'react'
+import { memo, useEffect, useRef, useState } from 'react'
 import { C, css, lc, MONO } from '../theme'
-import { useStore } from '../store'
+import { useStoreData, useStoreInput } from '../store'
 
 const SUGGESTIONS = ['What database do we use?', 'How do we handle on-call?']
 const MCP_CONFIG_CMD = 'claude mcp add contextcake -- node mcp-server.mjs --manifest layers.json'
 
-export function ChatPanel({ keyboardSuspended = false, onConnectAgent, onClose }: { keyboardSuspended?: boolean; onConnectAgent?: () => void; onClose: () => void }) {
-  const { chatMessages, chatBusy, chatInput, setChatInput, send } = useStore()
+function ChatPanelInner({ keyboardSuspended = false, onConnectAgent, onClose }: { keyboardSuspended?: boolean; onConnectAgent?: () => void; onClose: () => void }) {
+  const { setChatInput, send } = useStoreData()
+  const { chatMessages, chatBusy, chatInput } = useStoreInput()
   const scrollRef = useRef<HTMLDivElement>(null)
   const inputRef = useRef<HTMLTextAreaElement>(null)
   const panelRef = useRef<HTMLElement>(null)
@@ -163,3 +164,11 @@ export function ChatPanel({ keyboardSuspended = false, onConnectAgent, onClose }
     </div>
   )
 }
+
+/**
+ * Memoized. The shell re-renders for its own reasons — a drawer, a dialog, a
+ * background-activity tick — and this view has no business repainting for any
+ * of them. It re-renders when the store slices it subscribes to change, and
+ * otherwise not at all.
+ */
+export const ChatPanel = memo(ChatPanelInner)

apps/console/src/components/ConceptDetail.tsx

@@ -3,7 +3,7 @@ import { C, css, lc, MONO, conceptTypeStyle } from '../theme'
 import { layerName } from '../data'
 import type { Concept } from '../data'
 import { filesRevalidation, useLayerFiles } from '../layer-files'
-import { useStore } from '../store'
+import { useStoreData } from '../store'
 import { LayerChip } from './LayerChip'
 
 /** Which document extension wins when one concept id has several files behind it. */
@@ -24,7 +24,7 @@ const contributorKey = (layer: string, conceptId: string) => JSON.stringify([lay
  * link, and so no affordance that opens on an error.
  */
 function useFileByContributor(): Map<string, string> {
-  const { mode, sources, reloadKey } = useStore()
+  const { mode, sources, reloadKey } = useStoreData()
   const { layers } = useLayerFiles(mode, filesRevalidation(sources, reloadKey))
   return useMemo(() => {
     const best = new Map<string, { path: string; rank: number }>()
@@ -43,7 +43,7 @@ function useFileByContributor(): Map<string, string> {
 
 /** "Open file" for one contributor, or nothing when that layer keeps no file here. */
 function OpenFile({ layer, path, conceptId }: { layer: string; path: string | undefined; conceptId: string }) {
-  const { openFilesScope } = useStore()
+  const { openFilesScope } = useStoreData()
   if (!path) return null
   return (
     <button