The whole app blanks while one lazy route loads. Here's the boundary that did it
One Suspense boundary with fallback={null} above the layout hides the top bar and sidebar while a lazy route loads. Genie's react_suspense names it, and a verify claim proves the fix keeps the shell on screen.
The app goes blank because its only Suspense boundary wraps every route, layout included, and its fallback is null. While the lazy route's chunk downloads, React hides everything under that boundary and shows the fallback, which is nothing. A second boundary around <Outlet /> inside the layout keeps the top bar and sidebar on screen and limits the wait to the page area.
This walkthrough runs against Acme Tracker in apps/realworld-legacy, a React 18.3 app built with webpack 5 and React Router 6. The bug is seeded and has an answer key in lazy-route-blank-shell.json. Every command and output below comes from one session on 2026-11-19 with Genie 1.1.0. Absolute paths are shortened to <checkout>. The full, untrimmed output is in the evidence file.
The symptom: the top bar disappears with the page
The bug report says: "Clicking Settings or Reports in the sidebar blanks the whole screen, top bar included, until the page appears." On a local dev server the chunk loads too fast to see that. The app registers an app_backend_faults tool that can delay any request, including JavaScript chunks. Start on Settings, delay the Reports chunk by 2.5 seconds, and click Reports:
agent-browser --session upd-a open http://127.0.0.1:5231/settings
npx genie-react call app_backend_faults '{"rules":[{"path":"/static/js/reports","latencyMs":2500}]}' --session upd-a
agent-browser --session upd-a click 'a.side-nav__link[href="/reports"]'
agent-browser --session upd-a is visible .top-barfalseA screenshot at that moment is an empty grey page. The DOM is still there. In an earlier run from the board, agent-browser get count '#root *' returned 5,827 elements while the screen was blank. React hid the old tree. It did not remove it.
The evidence: one boundary, in fallback, at app.tsx:19
Ask Genie which Suspense boundaries exist and which ones are waiting:
npx genie-react call react_suspense '{"waitingOnly":true}' --session upd-aOutput, trimmed to the capability, the counts and selected boundary fields:
capability:
reactVersion: 18.3.1
bundle: development
asyncDebugInfo: unavailable
reason: react-before-19
counts: {boundaries:1,fallback:1,transitionPending:0,dehydrated:0,content:0}
boundaries[1]:
- {id:16346326761484,name:Suspense,parentBoundaryId:null,state:fallback,stateEvidence:exact,forced:false,blockerStatus:unavailable,source:{file:<checkout>/apps/realworld-legacy/src/app.tsx,line:19,column:5,sourceMapConfidence:served,role:element-callsite}}Three facts settle it. The app has exactly one Suspense boundary (boundaries:1). It is showing its fallback, and Genie read that state directly from React (stateEvidence:exact). It has no parent boundary, and its source is src/app.tsx line 19.
The capability block is the limit. React 18 does not record what a boundary waits on, so blockerStatus is unavailable. Genie cannot tell you it is the ReportsPage chunk. You know that from the click and the delayed request.
The cause: the boundary sits above the layout
Here is src/app.tsx, trimmed to the boundary and the routes it wraps:
export function App() {
return (
<Suspense fallback={null}>
<Routes>
<Route path="/login" element={<LoginPage />} />
<Route
element={
<RequireAuth>
<AppShell />
</RequireAuth>
}
>
{/* board, issues, ... */}
<Route path="reports" element={<ReportsPage />} />
<Route path="settings" element={<SettingsPage />} />
</Route>
</Routes>
</Suspense>
)
}ReportsPage and SettingsPage come from React.lazy. When one of them renders before its chunk has loaded, it suspends. React looks up the tree for the nearest Suspense boundary. AppShell has none, so the nearest is the one in App, above AppShell. React hides that boundary's whole subtree, which includes TopBar and SideNav, and renders fallback={null} in its place.
The fix: a boundary inside the shell
Put a boundary around <Outlet /> in src/layout/app-shell.tsx, with a fallback the user can see. This is the answer key's reference fix:
@@ -1,7 +1,9 @@
import classNames from 'classnames'
+import { Suspense } from 'react'
import { connect } from 'react-redux'
import { Outlet } from 'react-router-dom'
import { useGetConfigQuery } from '../api/service'
+import { Spinner } from '../components/spinner'
import { FeatureFlagsProvider } from '../contexts/feature-flags'
import { CreateIssueModal } from '../features/create-issue/create-issue-modal'
import type { RootState } from '../store'
@@ -25,7 +27,9 @@ function AppShell({ sidebarCollapsed, createIssueOpen }: AppShellProps) {
<TopBar />
<SideNav collapsed={sidebarCollapsed} />
<main className="shell__content">
- <Outlet />
+ <Suspense fallback={<Spinner label="Loading page" />}>
+ <Outlet />
+ </Suspense>
</main>
{config && <NotificationsPoller intervalMs={config.notificationPollMs} />}
{createIssueOpen && <CreateIssueModal />}The root boundary in App stays. It still covers the login route, which renders outside the shell.
The proof: the shell stays, and verify passes
Repeat the same steps on the fixed code. Reload Settings, delay the Reports chunk, click Reports, and read the screen and the boundaries while the chunk loads:
agent-browser --session upd-a is visible .top-bar
agent-browser --session upd-a get text .shell__content
npx genie-react call react_suspense '{}' --session upd-atrue
Loading page…react_suspense output, trimmed to the counts and selected fields of the two boundaries:
counts: {boundaries:2,fallback:1,transitionPending:0,dehydrated:0,content:1}
boundaries[2]:
- {id:15500302090315,name:Suspense,parentBoundaryId:15500302090252,state:fallback,stateEvidence:exact,source:{file:<checkout>/apps/realworld-legacy/src/layout/app-shell.tsx,line:30,column:11}}
- {id:15500302090252,name:Suspense,parentBoundaryId:null,state:content,stateEvidence:exact,source:{file:<checkout>/apps/realworld-legacy/src/app.tsx,line:19,column:5}}The new boundary at app-shell.tsx:30 is the one waiting. The root boundary at app.tsx:19 now shows its content.
To get a verdict with an exit code, wrap the click in a verify window. Each claim states something the fix must make true:
npx genie-react verify begin --session upd-a --name 'open reports' \
--claim 'render ReportsPage min 1' --claim 'render Spinner min 1' \
--claim 'render TopBar max 0' --claim 'suspense TopBar hidden max 0' --claim 'boundaries clean'
agent-browser --session upd-a click 'a.side-nav__link[href="/reports"]'
agent-browser --session upd-a wait .reports-page
npx genie-react verify end vfy_8d82d7b1-52c1-4747-a2d8-3f57ebf1adce --session upd-arender ReportsPage min 1 is the positive control: it proves the click reached the app. render Spinner min 1 says a loading indicator rendered. The Reports page itself uses no Spinner, so only the new fallback can satisfy it. suspense TopBar hidden max 0 says no Suspense fallback replaced the top bar during the window. It counts a fallback even when it resolved before verify end.
Before the fix, trimmed to the verdict and claim lines (exit code 1):
fail vfy_8d82d7b1-52c1-4747-a2d8-3f57ebf1adce "open reports" 15 commits, quiet after 1107 ms (react)
1 pass render ReportsPage min 1 {renders:1,mounts:1,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
2 refused render Spinner min 1 target_not_found: No Spinner instance was mounted at begin or rendered in the window; a target Genie cannot see is not a target that did nothing.
3 pass render TopBar max 0 {renders:0,mounts:0,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
4 fail suspense TopBar hidden max 0 {hidden:1,hidesInWindow:1}
5 pass boundaries clean {caughtDuringWindow:0,caughtAtEnd:0}Claim 4 names the boundary that hid the top bar. Its deciding line is {kind:suspense-hide,hideId:hide:16:2,documentCommitId:16,boundary:Suspense,boundaryId:16346326761484}, the root boundary from react_suspense.
After the fix (exit code 0):
pass vfy_56554e7b-98d4-4254-9622-80b412da5d52 "open reports" 13 commits, quiet after 640 ms (react)
1 pass render ReportsPage min 1 {renders:1,mounts:1,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
2 pass render Spinner min 1 {renders:1,mounts:1,updates:0,remounts:1,semantics:exact,instances:1,activeInstances:0}
3 pass render TopBar max 0 {renders:0,mounts:0,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
4 pass suspense TopBar hidden max 0 {hidden:0,hidesInWindow:1}
5 pass boundaries clean {caughtDuringWindow:0,caughtAtEnd:0}hidesInWindow:1 is the new boundary hiding the page area. It did not hide TopBar, so hidden is 0. In the untrimmed output, the deciding Spinner instance has source app-shell.tsx:30:31, the fallback prop of the new boundary.
Why the render claim is not enough
Look at claim 3. render TopBar max 0 passed before the fix too, while the top bar was hidden. Hiding a subtree behind a Suspense fallback is not a render, so a render claim cannot say "the shell stayed visible". The Suspense claim can, and it is the claim that flips from fail to pass. Genie 1.0.2 had no such claim. Genie still does not read the screen, and every run warns Genie does not check the screen; confirm it with the UI driver. agent-browser is visible .top-bar is that check.
Where you start matters for the render claim. A run that began on the board refused render TopBar max 0 with coverage_incomplete. Navigating away unmounts the whole board, more components than one window keeps:
2 refused render TopBar max 0 coverage_incomplete: Render analysis was incomplete in the window (droppedUnmountFibers 3057), so counts are a lower bound. The interaction unmounted more components than one window keeps, so beginning again loses them again; start from a page that mounts fewer components, such as a shorter list, or claim a lower bound (min) instead.Its fix is change-claim. Starting from Settings, a small page, gave complete coverage. The same board run still failed suspense TopBar hidden max 0 with hidden:1, because the hide log was complete.
On React 18, react_suspense tells you where the waiting boundary is and that it is in fallback, but not what it waits for. React 19 development builds record that, and Genie reports it as blockers. Verify a fix lists every claim form. To hold a fallback on screen without delaying a request, use react_toggle_suspense_fallback from Validate UI states.
Your error boundary caught the error and rendered nothing
An empty card with no error message can be a TypeError that an error boundary swallowed. Genie's react_error_state names the boundary, the thrower and the line.
Find wasted re-renders in React Native with an AI agent: one tap rendered 29 components
An agent drove an Expo app on the iOS Simulator with agent-device, used Genie to find why one tap rendered 29 components, and proved a fix that cut it to 4.