[Juliusolsson05]

Closes #494.

What

src/renderer/src/app/App.tsx goes from a 1152-line god render-root (52 imports, ~34 directly-mounted feature surfaces, 13 root effects, a 70-prop CommandPalette relay) to a 74-line composition root: named cross-cutting hooks → useWorkspace + WorkspaceProvider → layout shell → registry-driven surface groups. Pure extraction — no behavior change intended; every effect body and WHY comment moved verbatim.

How it's structured now

• Surface registry — app/surfaces/registry.tsx aggregates self-contained wrappers (one file per surface, living in the owning feature's surfaces/ folder) into three groups placed at App's exact old DOM positions: <GlobalModals/>, <GlobalOverlays/>, <SidePanels/>. Adding a surface = 1 wrapper file + 1 registry line; App.tsx is never edited. Mirrors the command-registry pattern rather than side-effect self-registration (grep-able, compiler-checked).
• WorkspaceContext (workspace/WorkspaceContext.tsx) — first real workspace context; wrappers consume it instead of prop-drilling. Same re-render semantics as the old props (value is the per-render hook object; documented in the file).
• CommandPalette is self-contained — the ~76-prop relay is deleted; the palette sources store actions/flags, workspace context, and the caffeinate/dev-debug stores itself. CommandContext's shape and every command definition are untouched (keeps this disjoint from Plug-and-play provider architecture: modularize and standardize all provider implementations #394 §7's future command rewrite).
• 13 root effects → feature hooks: useThemeSync, useAiWorkspaceOpenRequests, useDevDebugConfigSync, useCaffeinateSync, useDictationHotkeySync, useRenderedLeaseHygiene, useDebugAutosave, plus the path-picker prefill effect moving into PathPickerSurface.
• New homes for App-local state: agentViewModePickerSessionId → uiShell slice; caffeinate status/message → features/caffeinate/store.ts; dev-debug config → features/debug/devDebugConfig.ts.
• Debug panels → one lazy chunk (features/debug/surfaces/DebugSurfaces.tsx): not fetched until a panel flag first turns on, so debug code leaves the prod tree and initial bundle.
• Shell pieces (app/shell/): RestoreBanner, SettingsBar, MainSurface (mode routing incl. GlobalEditorShell + placement overlay), WelcomeEmpty; barrel re-exports SetupGate so App has no feature-surface imports.

Reviewer attention points (deliberate decisions, documented in the plan/design comments)

1. No when(state) on registry entries (deviation from the issue sketch): mount semantics are load-bearing — modals stay always-mounted-with-open (internal state survives close/reopen), panels stay conditionally mounted. Each wrapper replicates its exact old gating.
2. Debug surfaces are NOT hard-gated on dev-debug (issue sketch said so, but 4 of the 5 panels open without dev-debug today and this refactor is behavior-preserving). The lazy chunk delivers the "out of the prod tree" goal; a hard gate is a one-line follow-up in DebugSurfaces.tsx if wanted.
3. Three fixed-position siblings changed DOM order (TiledDispatchCount overlay + caffeinate toast now render in the overlays group before the modals group; palette is first modal entry). All are position:fixed with explicit z-index; needs one eyeball in the manual pass below.

Gates (all run per-task, 12 commits)

• npx tsc -b (node + web projects) — clean at every commit.
• npm run test:renderer — 14/14 green at every commit.
• Full npm run test — 474/474 tests pass. Two file-level failures exist but are unrelated to this branch (zero changes under packages/): codex-headless JsonlTailer.test.ts is flaky under parallel load (passes in isolation), and agent-voice-dictation hotkeyBinding.test.ts contains no test suite in the pinned submodule (reproduces outside this branch).
• Grep gates: wc -l App.tsx = 74; no useEffect/useState in App.tsx; no leftover effect bodies (configureDictationHotkey|autosaveActiveAgentDebugBundles|getCaffeinateStatus|remoteSetThemeSettings|onAiWorkspaceOpenRequest) under app/.

Manual pass checklist (recommended before merge)

Open each once via palette/keybind: command palette, path picker (new tab ⌘T + resume), tile-tabs, reorder-tabs, pin-agents (pinned-first ordering), bury prompt, debug-bundle note, recording note, view prompts, prompt search, agent activity, close-old-agents, bulk provider switch, agent view-mode picker, rewind-to-prompt, usage modal, tiled-dispatch count, voice dictation, caffeinate toast (auto-dismiss 5s), git bar, worktrees bar, agent status panel, remote panel, 4 debug panels without dev-debug + dev-debug panel with it, Settings/Reader/Spotlight/Global editor (editor state survives mode flips), placement overlay (Esc clears all three flows), theme flip (desktop + remote match), keybind spot-check (⌘T, ⌘1..9, ⌥h/j/k/l, dispatch chords).

#493 coexistence

Another branch is restructuring the feed layers (workspace/semantic, rendering/, features/feed internals). This PR deliberately touches none of those files; the only overlap risk is App-adjacent import lines (e.g. AppearanceMenu now imported from app/shell/SettingsBar.tsx). Whichever lands second rebases trivially.

Plan: docs/superpowers/plans/2026-07-09-app-shell-composition-root.md (committed on this branch).

🤖 Generated with Claude Code