orca/docs/reference/react-performance-audit.md

React Performance Audit

Status: in progress Started: 2026-05-29 Base commit: b7fe967780 (origin/main, release v1.4.35)

Goal

Scan the full React surface for $perf and $react-useeffect issues, keep coverage evidence here, and land the fixes as many small PRs with explicit merge-risk notes.

This document is the audit ledger. A section is not considered fully scanned until it has:

1. File inventory checked from the current worktree.
2. useEffect / useLayoutEffect / useInsertionEffect sites classified.
3. Perf-sensitive patterns checked: timers, subscriptions, observers, JSON.stringify, storage writes, polling, broad store subscriptions, large list rendering, and render-time derived state.
4. Each suspicious site dispositioned as "no change", "needs PR", or "covered by PR".
5. Merge risk recorded for every PR candidate.

Scope

React hook call scan uses all repo *.ts and *.tsx files, then narrows to actual AST hook calls. The React Effect surface found on 2026-05-29 is:

• src/renderer/src/**
• mobile/app/**
• mobile/src/**
• mobile/packages/expo-two-way-audio/src/hooks.ts

Comment-only mentions outside those paths were ignored.

Initial inventory:

Metric	Count
Repo *.ts / *.tsx files	3,011
Files with real Effect hook calls	285
Effect hook call sites	970
useLayoutEffect / useInsertionEffect call sites	44
Empty dependency arrays	111
Effects with cleanup returns	472
Effects with subscription/listener/observer shape	170
Effects with timer or animation-frame shape	128
Effects with JSON.stringify shape	2
Set-state-shaped Effects needing manual review	270
useMemo call sites in React scope	633
useCallback call sites in React scope	1,415
useSyncExternalStore call sites in React scope	8

Coverage Ledger

Current count after low-risk PRs #3038, #3041, #3042, #3044, #3051, #3052, #3053, #3054, #3055, #3056, #3058, #3059, and #3060: 950 Effect hook call sites.

Area	Files / signal	Scan status	Notes
Renderer app shell	src/renderer/src/App.tsx, root components	Inventory complete, manual review pending	Check global listeners, beforeunload, media-query, sidebar resize, active-tab repair.
Terminal / PTY	components/Terminal.tsx, components/terminal-pane/**, components/terminal/**	Inventory complete, manual review pending	High-risk area: xterm lifecycle, scrollback, remote/mobile parity, focus, WebGL, resize.
Browser pane	components/browser-pane/**	Inventory complete, manual review in progress	Highest Effect density: 62 sites in BrowserPane.tsx. Check driver sync, address bar derived state, find state, webview lifetime.
Editor / markdown / Monaco	components/editor/**	Inventory complete, manual review in progress	117 area Effects. Check editor model cleanup, preview scroll restore, search debounce, generated decorations.
Sidebar / worktrees	components/sidebar/**	Inventory complete, manual review in progress	Check worktree list state repair, drag/drop global listeners, kanban pointer flows, inline rename.
Right sidebar / source control	components/right-sidebar/**	Inventory complete, manual review pending	Check polling, PR checks, file explorer watch/reveal, source-control local resets. Git provider compatibility required.
Settings	components/settings/**	Inventory complete, manual review pending	81 area Effects. Many draft-mirror candidates; keep SSH and cross-platform settings behavior intact.
Issue, PR, task pages	TaskPage.tsx, PullRequestPage.tsx, GitHubItemDialog.tsx, GitLabItemDialog.tsx, Linear components	Inventory complete, manual review in progress	Large files with many Effects. Separate GitHub, GitLab, Linear, and generic review behavior.
Onboarding / feature wall	components/onboarding/**, components/feature-wall/**	Inventory complete, manual review pending	Lower merge risk for pure visual/demo state, but avoid changing telemetry semantics.
Status, dashboard, activity	components/status-bar/**, components/dashboard/**, components/activity/**	Inventory complete, manual review in progress	Status-bar account menu close reset covered by #3051. Check interval sharing, retained agent state, activity terminal portals.
Mobile app routes	mobile/app/**	Inventory complete, manual review pending	79 Effects, including large tasks.tsx and session route. Remote-client parity required.
Mobile shared source	mobile/src/**	Inventory complete, manual review pending	Browser pane, transport client context, dictation hook, bottom drawer, new worktree modal.
Expo two-way audio hook	mobile/packages/expo-two-way-audio/src/hooks.ts	Inventory complete, manual review pending	Single Effect plus useSyncExternalStore; verify native subscription cleanup.
Tests with hook mocks	*.test.ts, *.test.tsx, e2e comments	Inventory complete, manual review pending	Do not count comment-only mentions as app Effect sites; update tests beside behavior changes.

Current Findings Queue

These are candidate batches, not final conclusions. Each item needs code inspection before implementation.

Candidate PR	Area	Symptom / wasted work to prove	Likely files	Merge risk
PR A	Small controlled-input resets	Extra render pass from Effects that mirror one prop into local draft state.	BrowserAddressBar.tsx covered by #3038; continue with BrowserFind.tsx, PdfFind.tsx, selected settings draft fields	Low to medium
PR B	Settings draft hydration	Multiple independent Effects mirror persisted settings into draft state.	components/settings/**	Medium
PR C	Browser pane Effect cluster	Large Effect cluster may mix external webview sync, derived UI state, and event-specific state repair.	BrowserPane.tsx, useGrabMode.ts, browser tabs	High
PR D	Terminal tab repair and lifecycle	Effects repair active terminal/browser tab state after render; could cause extra render and focus churn.	Terminal.tsx, useTerminalTabs.ts, TerminalPane.tsx	High
PR E	Right-sidebar polling and source-control state repair	PR checks, branch snapshots, file explorer watch/reveal may repeat work after unrelated state changes.	ChecksPanel.tsx, SourceControl.tsx, useGitStatusPolling.ts, file explorer hooks	High
PR F	Mobile route monoliths	Mobile task/session routes have many chained Effects and timer/refetch patterns.	mobile/app/h/[hostId]/tasks.tsx, mobile/app/h/[hostId]/session/[worktreeId].tsx	High
PR G	Mobile shared components	Visible/open Effects reset modal/drawer state and browser address state.	mobile/src/components/**, mobile/src/browser/MobileBrowserPane.tsx	Medium
PR H	Editor search/preview/decorations	Debounce and scroll-restore Effects may be legitimate external sync but need cleanup/count review.	components/editor/**	Medium to high
PR I	Feature wall/onboarding demos	Animation/demo Effects can often move to event handlers or tighter custom hooks.	components/feature-wall/**, components/onboarding/**	Low to medium
PR J	GitHub filter controls	Extra render pass from mirroring parsed reviewer qualifier into local mode state.	PRFilterDropdowns.tsx covered by #3041	Low
PR K	Sidebar project filter	Extra render pass from mirroring the first filtered repo into command selection state.	SidebarFilter.tsx covered by #3042	Low
PR L	Diff note edit draft	Extra render pass from mirroring saved note body into edit draft while not editing.	DiffCommentCard.tsx covered by #3044	Low
PR M	Status-bar account menus	Extra render pass from closing Claude/Codex account submenus in Effects after the provider menu closes.	StatusBar.tsx covered by #3051	Low
PR N	Browser tab favicon fallback	Extra render pass from resetting failed favicon state in an Effect after tab favicon identity changes.	BrowserTab.tsx covered by #3052	Low
PR O	Workspace title rename draft	Redundant draft sync Effect runs while the inline title rename input is not mounted.	WorktreeTitleInlineRename.tsx covered by #3053	Low
PR P	Feature-wall tour static substep repair	Three no-op Effects scan static step arrays and repair ids that are only written from those arrays.	FeatureWallTourSurface.tsx covered by #3054	Low
PR Q	Repo combobox mount-open state	Mount-only auto-open path uses an Effect and ref guard instead of initializing state from the prop.	RepoCombobox.tsx covered by #3055	Low
PR R	Quick Open query reset	Extra render pass from clearing the Quick Open input after the dialog opens.	QuickOpen.tsx covered by #3056	Low
PR S	Project group dialog open resets	Extra render pass from seeding name/delete dialog local state after the dialog opens.	ProjectGroupNameDialog.tsx, ProjectGroupDeleteDialog.tsx covered by #3058	Low
PR T	Onboarding agent fallback disclosure	Extra render pass from opening the fallback agent list when a selected agent first appears there.	AgentStep.tsx covered by #3059	Low
PR U	Feature-wall tour workflow resets	Four local reset Effects run after workflow changes or close instead of in the selection/close path.	FeatureWallTourSurface.tsx covered by #3060	Low

Merge Risk Scale

Risk	Criteria	Required verification
Low	Isolated local UI state, no persistence, no IPC, no terminal/browser/source-control behavior.	Targeted unit test if available plus pnpm run typecheck:web.
Medium	Settings, editor UI, mobile local UI, or state persisted per workspace but no transport protocol changes.	Targeted tests plus manual interaction or focused Playwright/Electron check when UI behavior changes.
High	Terminal/PTY, browser webview, source control, mobile remote-client, SSH, polling, persistence, or provider behavior.	Targeted tests, pnpm run typecheck:web, and Electron or mobile/manual parity evidence as appropriate.

PR Log

PR	Branch	Area	Risk	Status	Evidence
#3038	nwparker/react-perf	Audit ledger plus browser address bar top-suggestion mirror Effect removal	Low	Merged	pnpm exec oxlint src/renderer/src/components/browser-pane/BrowserAddressBar.tsx; pnpm run typecheck:web.
#3041	nwparker/react-perf-pr-filter	PR reviewer filter mode derived from parsed query plus explicit user override	Low	Merged	pnpm exec oxlint src/renderer/src/components/github/PRFilterDropdowns.tsx; pnpm run typecheck:web.
#3042	nwparker/react-perf-sidebar-filter	Sidebar project filter command selection derived from filtered repos	Low	Merged	pnpm exec oxlint src/renderer/src/components/sidebar/SidebarFilter.tsx; pnpm run typecheck:web.
#3044	nwparker/react-perf-low-risk-2	Diff note card removes saved-body-to-draft mirror Effect	Low	Merged	pnpm exec oxlint src/renderer/src/components/diff-comments/DiffCommentCard.tsx; pnpm run typecheck:web.
#3051	nwparker/react-perf-low-risk-3	Status-bar account submenus collapse in provider menu open-change handlers	Low	Merged	pnpm exec oxlint src/renderer/src/components/status-bar/StatusBar.tsx; pnpm run typecheck:web.
#3052	nwparker/react-perf-low-risk-4	Browser tab favicon failure reset happens during render for new favicon IDs	Low	Merged	pnpm exec oxlint src/renderer/src/components/tab-bar/BrowserTab.tsx; pnpm run typecheck:web.
#3053	nwparker/react-perf-low-risk-5	Inline workspace-title rename removes inactive draft sync Effect	Low	Merged	pnpm exec oxlint src/renderer/src/components/sidebar/WorktreeTitleInlineRename.tsx; pnpm run typecheck:web.
#3054	nwparker/react-perf-low-risk-6	Feature-wall tour removes static substep id repair Effects	Low	Merged	pnpm exec oxlint src/renderer/src/components/feature-wall/FeatureWallTourSurface.tsx; pnpm run typecheck:web.
#3055	nwparker/react-perf-low-risk-7	Repo combobox initializes mount-open state without an Effect	Low	Merged	pnpm exec oxlint src/renderer/src/components/repo/RepoCombobox.tsx; pnpm run typecheck:web.
#3056	nwparker/react-perf-low-risk-8	Quick Open clears its query on the open edge without a reset Effect	Low	Merged	pnpm exec oxlint src/renderer/src/components/QuickOpen.tsx; pnpm run typecheck:web.
#3058	nwparker/react-perf-project-group-dialogs	Project group dialogs reset local open-state during render	Low	Merged	pnpm exec oxlint src/renderer/src/components/sidebar/ProjectGroupDeleteDialog.tsx src/renderer/src/components/sidebar/ProjectGroupNameDialog.tsx; pnpm run typecheck:web.
#3059	nwparker/react-perf-agent-step-latch	Onboarding agent fallback disclosure latch updates during render	Low	Merged	pnpm exec oxlint src/renderer/src/components/onboarding/AgentStep.tsx; pnpm run typecheck:web.
#3060	nwparker/react-perf-feature-tour-resets	Feature-wall tour reset state moves into workflow/close transitions	Low	Open	pnpm exec oxlint src/renderer/src/components/feature-wall/FeatureWallTourSurface.tsx; pnpm run typecheck:web.

Reproduction Commands

Run from the worktree root.

rg --files -g '*.tsx' -g '*.ts' | wc -l
rg -l "\\b(useEffect|useLayoutEffect|React\\.useEffect|React\\.useLayoutEffect)\\b" -g '*.tsx' -g '*.ts' | sort

The exact Effect-site counts above came from a TypeScript AST scan so comment-only mentions are not counted.