feat(chat): remove legacy chat.html, React 19 architecture, a11y and UX polish

[maxnoller]

Summary

Legacy cleanup

• Delete docs/chat.html (4,066 lines) — the React console at /admin/chat fully replaces it
• Add 301 redirect from /chat and /chat.html to /admin/chat in the gateway
• Update gateway, Docker, and npm E2E tests for the removal

React 19 architectural improvements

• Replace 9 useState calls with single useReducer (typed ChatState/ChatAction with SESSION_SWITCH, SESSION_ID_UPDATE, HISTORY_LOADED, MESSAGES_SET, etc.)
• Replace useQuery for history with useSuspenseQuery + ChatErrorBoundary wrapped in QueryErrorResetBoundary for proper error retry
• Add useTransition for session switches (handleOpenSession, handleEditSave) with aria-busy and pulse animation on the active sidebar session
• Replace raw validateToken useEffect with useQuery(fetchAppStatus) (reuses existing validateToken via re-export)
• Add prefetchQuery on sidebar session hover for instant switching
• Derive branchInfoMap with useMemo instead of separate useState
• Simplify useChatStream interface: setSessionId/setError accept plain (string) => void
• Invalidate chat-history cache after stream completes so switching away and back refetches correctly
• Early-exit in buildBranchInfoMap when branchFamilies is empty (avoids O(n) per RAF frame during streaming)

Accessibility

• Focus-visible outlines on all interactive buttons (matches styles.css color-mix pattern)
• focus-within on .messageBlock to show message actions on keyboard navigation
• prefers-reduced-motion media query to disable slideIn, sessionPulse, and thinkingBounce animations
• aria-label on message action buttons (copy, edit, regenerate) and branch nav buttons (previous/next)
• aria-label="Edit message" on the edit textarea
• Unique aria-label="Open chat sidebar" on mobile hamburger to avoid collision with app shell sidebar trigger

Mobile polish

• 480px small-phone breakpoint with wider bubbles (95%) and tighter padding
• Slash suggestions capped at max-height: 40vh on mobile
• Fix sidebar overlay blocking backdrop click: inset: 0 replaced with explicit top/left/bottom

UX improvements

• Auto-collapse admin sidebar to icon-only mode on the chat page; restore on navigation away
• Add title tooltips to collapsed sidebar nav icons and brand mark
• Show sidebar expand trigger button (aria-expanded="false") when collapsed on desktop

Test plan

• npm --workspace console run test — 165 tests pass
• npx vitest run tests/gateway-http-server.test.ts — 179 tests pass
• Visit /chat → verify 301 redirect to /admin/chat
• On /admin/chat, Tab through all interactive elements → verify visible focus rings
• Resize to <480px → verify mobile layout (wider bubbles, tighter padding)
• Enable prefers-reduced-motion in devtools → verify no animations
• Verify admin sidebar collapses to icons on chat page, expands on other pages
• Hover collapsed sidebar icons → verify tooltips
• Click expand trigger (≡) → sidebar expands; navigate away → stays expanded
• Switch sessions via sidebar → verify pending pulse animation and instant load (prefetched)
• Send a message, switch to another session, switch back → verify messages persist (history cache invalidated)
• Edit a message → verify no Suspense flash (startTransition)
• Trigger a history load error → verify "Try again" button works (QueryErrorResetBoundary)

[maxnoller]

Code review

Found 2 issues:

1. staleTime: Infinity on useSuspenseQuery for chat history means the cache is never invalidated after streaming adds new messages. If a user sends messages in session A (messages accumulate in local state via MESSAGES_SET), then switches to session B and back to session A, useSuspenseQuery returns the stale cached history (pre-streaming), and the HISTORY_LOADED effect overwrites the newer messages. The only invalidateQueries call in the component targets chat-recent, not chat-history. Either invalidate the history cache after streaming completes (refreshRecent is the natural place to also invalidate history), or lower staleTime to a finite value like 45_000 (what the previous useQuery used).

hybridclaw/console/src/routes/chat/chat-page.tsx

Lines 296 to 300 in 17c887e

	queryKey: ['chat-history', auth.token, sessionId],
	queryFn: () => fetchChatHistory(auth.token, sessionId),
	staleTime: Infinity,
	});

2. handleEditSave dispatches SESSION_SWITCH without wrapping in startTransition, while handleOpenSession correctly does. Both trigger a session change that causes useSuspenseQuery to suspend. Without startTransition, React immediately shows the Suspense fallback ("Loading chat..."), causing a visual flash that discards the current chat content. handleOpenSession avoids this by deferring the commit. The same pattern should be applied to handleEditSave.

hybridclaw/console/src/routes/chat/chat-page.tsx

Lines 396 to 400 in 17c887e

	media: msg.media ?? [],
	};
	dispatch({ type: 'SESSION_SWITCH', sessionId: branch.sessionId });
	} catch (err) {
	dispatch({

Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[maxnoller]

Code review

Found 1 issue:

1. historyQuery was switched to useSuspenseQuery and the previous useEffect that forwarded historyQuery.error to an inline error banner was removed. Because refreshRecent now also invalidates the chat-history cache after every stream finalize, any failed background refetch will throw past the local state and tear down the entire ChatPage into ChatErrorBoundary — losing composer text, active session, loaded messages, and sidebar state. The prior useQuery path surfaced this inline without unmounting. Consider handling historyQuery.error inline (e.g., keep useQuery or catch with a narrower boundary around just the history load).

hybridclaw/console/src/routes/chat/chat-page.tsx

Lines 280 to 290 in 92d39f9

	const recentSessions = recentQuery.data?.sessions ?? [];
	const historyQuery = useSuspenseQuery({
	queryKey: ['chat-history', auth.token, sessionId],
	queryFn: () => fetchChatHistory(auth.token, sessionId),
	staleTime: Infinity,
	});
	useEffect(() => {
	const data = historyQuery.data;

Invalidation that can trigger the throw:

hybridclaw/console/src/routes/chat/chat-page.tsx

Lines 200 to 210 in 92d39f9

	const refreshRecent = useCallback(() => {
	void queryClient.invalidateQueries({
	queryKey: ['chat-recent', auth.token, userId],
	});
	// Also invalidate the current session's history cache so that
	// switching away and back refetches with the streamed messages.
	void queryClient.invalidateQueries({
	queryKey: ['chat-history', auth.token, sessionIdRef.current],
	});
	}, [queryClient, auth.token, userId]);

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}