boocode/apps/web/CLAUDE.md

apps/web — BooChat frontend (deep reference)

Per-app engineering notes for apps/web/src/. The frontend is a single React SPA that also hosts the BooCoder 'coder' pane. Cross-cutting commands, database, environment, workflow, and cross-app contracts (WS-frame / provider-type parity, sentinels) live in the root CLAUDE.md. This file auto-loads when you read/edit files under apps/web/.

Stack

• React 18 + React Router v6 + Tailwind v4 + shadcn/radix-ui primitives.
• Shiki for syntax highlighting (async codeToHtml in CodeBlock.tsx and FileViewer in FileBrowserPane.tsx).
• Path alias: @/ maps to src/.
• Mobile interaction primitives: useViewport (matchMedia; mobile <768 / tablet 768–1023 / desktop ≥1024), useSidebarDrawer / useRightRailDrawer (Context + auto-close on useLocation().pathname change), useLongPress (500ms timer, synthetic contextmenu on [data-tab-id]), usePullToRefresh (80px threshold, 600ms hold), SwipeablePaneTab (60px close, 30px vertical bail). Tap-target convention: max-md:min-h-[44px] max-md:min-w-[44px]. Mobile headers: border-b px-3 sm:px-4 py-2 + paddingTop: 'max(0.5rem, env(safe-area-inset-top))'. Hamburger left, FolderTree right.

Key patterns

• hooks/sessionEvents.ts — Module-singleton event bus (Set of listeners) for cross-component communication: session renames, file-open, attachment dispatch. 26-arm discriminated union (and growing). Adding an event type also requires a case in the applyEvent switch in useSidebar.ts (no-op return prev is fine), and a subscribe in any hook that needs it (e.g. useSessionStream for refetch_messages).
• hooks/useSessionStream.ts — WebSocket per session; applyFrame reducer builds the message list from streaming frames.
• hooks/useUserEvents.ts — Single app-level WS to /api/ws/user with exponential-backoff reconnect. Forwards frames onto the sessionEvents bus.
• hooks/useSidebar.ts — Module-singleton with Set<setState> subscriber pattern; one bus subscription guarded by globalThis.__boocode_sidebar_subscribed for HMR safety. Every new SessionEvent type needs a case in applyEvent.
• api/client.ts — Centralized typed fetch wrapper. All endpoints under api.*.

Font / CSS pipeline

• Tailwind v4's @import "tailwindcss" strips font URLs from subsequent CSS @imports — @fontsource* packages must be JS side-effect imports in apps/web/src/main.tsx, not @import in globals.css, or the woff2 files never reach dist/.
• Lightning CSS (inside @tailwindcss/postcss v4) collapses contiguous unicode-ranges to wildcard shorthand (U+0000-FFFF → U+????), which iOS Safari/Vivaldi mishandles (silently drops the font for those codepoints). Use explicit non-collapsible subranges (e.g. U+2500-259F, not U+2500-25FF). The apps/web build script greps dist/assets/*.css for U+2500-259F and fails the build if missing — preserve that guard.
• @font-face blocks must live AFTER all @import statements (CSS spec). Earlier placement silently breaks every subsequent @import.
• JetBrainsMono Nerd Font self-hosted in apps/web/src/fonts/ (TTF from ryanoasis/nerd-fonts) — @fontsource-variable/jetbrains-mono ships subsetted woff2s that don't cover U+2500-259F (box drawing/block elements, used by opencode's banner). "NL" = No Ligatures (matches font-feature-settings: "liga" 0); "Mono" = single-cell icon width so TUI layouts don't desync.
• xterm-addon-webgl rasterizes glyphs via Canvas2D into a GPU atlas; Canvas2D does NOT honor font-display: block — it uses whatever font is registered. Gate xterm init on document.fonts.load(<font-name>) resolving before term.open() (fontsReady in TerminalPane.tsx). iOS Safari/Vivaldi also reclaim WebGL contexts from backgrounded tabs: keep webgl.onContextLoss(() => webgl.dispose()) + recreate via visibilitychange. Do NOT manually dispose+recreate the addon after font load — iOS silently fails the second GL context creation and drops to DOM renderer with stale metrics.

Multi-pane workspace

Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). Pane state lives in sessions.workspace_panes jsonb for cross-device sync. PATCH /api/sessions/:id/workspace persists; session_workspace_updated user-channel frame broadcasts to every device. useWorkspacePanes debounces saves 300ms and dedups echoes by JSON string (legacy localStorage key seeded once on first hydrate, then no longer written). validatePanes(validChatIds) prunes panes referencing deleted chats. Each chat lives in at most one pane; the per-pane tab strip tracks chatIds[] + activeChatIdx, reorder via native HTML5 drag. workspace_panes is a WorkspaceState envelope {panes, tabNumbers, nextTabNumber, closedPaneStack} (tabNumbers = stable session-scoped chatId→number, never reused; closedPaneStack = reopen LIFO, max 10, persisted); hydrate (toWorkspaceState) and the server PATCH validator (z.union([array, envelope])) both accept the legacy bare array and normalize. Closing a chat pane relocates its tabs to the oldest chat/empty pane; reopenPane strips restored chatIds from all live panes first. read_tab_by_number resolves number→chatId through tabNumbers.

Frontend conventions

• overflowWrap not wordWrap — TypeScript's CSSStyleDeclaration marks wordWrap deprecated (error 6385).
• shadcn primitives live in components/ui/. Don't modify them unless adding a new primitive.
• ui/ primitives present: button, card, context-menu, dialog, dropdown-menu, input, label, radio-group, sonner, textarea. No switch/sheet/drawer/badge/checkbox — use a <button role="switch" aria-checked> toggle (a hand-rolled Switch lives in SettingsPane.tsx) and a Dialog-based panel for "drawers".
• inferLanguage() from lib/attachments.ts is the canonical file-extension→language map. CodeBlock.tsx keeps its own LANG_MAP because it also resolves markdown fence names.
• Two UI event buses: hooks/sessionEvents.ts for DB-state events (chat_created, session_updated); lib/events.ts for ephemeral UI (sendToTerminal, terminalsRegistry). Don't merge — different subscriber lifecycles.
• vite.config.ts proxy entries are order-sensitive: more-specific prefixes (/api/term, /ws/term) must come BEFORE /api.
• Mobile pane URL sync (Session.tsx): the ?pane=<id> effect resets activePaneIdx whenever panes changes. New-pane creation on mobile must push ?pane= atomically — addPaneAndSwitch does this; addSplitPane returns the new pane id.
• A scrollable list inside a Dialog on mobile: cap DialogContent (max-h-[85vh] + grid-rows-[auto_minmax(0,1fr)_auto]) and make the list the single scroll region with overscroll-contain — otherwise touch-scroll drags the whole fixed modal / chains to the page.
• xterm.js v5 uses canvas rendering — the browser doesn't see xterm's selection, so the native right-click Copy doesn't work for terminal text. App keybindings (Cmd/Ctrl-C, Cmd/Ctrl-Shift-C) are the path.
• React StrictMode is on (main.tsx): an updater passed to one setState that itself calls another setState (e.g. setClosedPaneStack inside a setPanes updater) is double-invoked in dev. Make such nested updates idempotent — useWorkspacePanes's appendClosed dedupes a value-identical top entry for this reason.
• CoderPane uses ChatInput (components/panes/CoderPane.tsx): shares BooChat's ChatInput for full parity — attachments, paste-to-chip, auto-grow textarea, queued messages during send. sendOneMessage is the send callback; queued messages drain via useEffect when sending goes false.
• AgentComposerBar filters e.installed: provider snapshot entries with installed:false (loading/unavailable) are dropped from the dropdown. getProviderSnapshot must await the full build — returning synchronous loading placeholders makes every provider vanish; surfacing loading states needs a client poll.
• Pane header architecture (mobile vs desktop): desktop coder pane header (BooCode label + [+] [×]) lives in Workspace.tsx gated by isCoder && !isMobile. Mobile coder controls (● ×) live in Session.tsx next to MobileTabSwitcher/NewPaneMenu. AgentComposerBar (provider/mode/model pickers) renders inside CoderPane.tsx on both; the ● status dot is passed via connected prop.
• MessageBubble shared between BooChat and BooCoder (components/MessageBubble.tsx): optional actions?: MessageActions + hideActions? props; CoderPane overrides via CoderMessageList. CoderMessageList passes CoderMessageWire as unknown as Message — the coder shape lacks metadata/kind/summary, so they're undefined (not null). Null-guards on any Message field MUST use loose != null, not !== null (undefined !== null is true → .kind throws → blank-screen crash). The cast hides this from tsc; build passes while runtime crashes.