fix(mobile): render the root runtime-error screen instead of a blank frame

[iscekic]

Changelog for users

• A render error that reaches the app's root boundary now shows the designed error screen instead of a blank black frame.
• The screen shows an alert icon, the "Something went wrong" title, the "Please try again." description, and a Retry button.
• Tapping Retry keeps a designed error screen visible, never a blank frame.

Changelog for maintainers

• The root error boundary now renders RuntimeErrorScreen, a plain full-screen centered layout, instead of StateSurface plus a measured QueryError.
• The screen no longer depends on the native surface observer, which withholds its children until it reports a visible geometry — the cause of the blank frame.
• EmptyState and QueryError accept a static placement that renders the content directly, without the CenteredState scroller and without top's top padding.
• static reuses EmptyState's existing non-center branch, so top output is unchanged; start review at apps/mobile/src/components/empty-state.tsx.
• A mounted test asserts the icon, title, description, and a working Retry render with no usable surface geometry and nothing hidden.
• No catalog keys changed; the only behavior change is where the root boundary paints.

E2E proof

[e1] android emulator-5554: runtime error reaches root ErrorBoundary and shows the designed error screen, not a blank frame — android emulator-5554. Reached the state with a temporary root route (apps/mobile/src/app/kwf-runtime-error-probe.tsx, throws on render; deleted after, worktree clean via git status) since files/e2e-index.md exposes no render-error fault hook. SCENE digest e1-scene.log shows 'Something went wrong', 'Please try again.', 'Button Retry' — the RuntimeErrorScreen fallback, not a blank frame. e1-hierarchy.xml shows com.horcrux.svg.SvgView + CircleView (icon graphic present); the icon's appearance is the visual reviewer's. Screenshot e1.png captured for the visual reviewer. No UX-DEFECT observed…

[e2] android emulator-5554: tap Retry returns to the same designed error screen, never a blank frame — android emulator-5554. Scripted scene e2-scenes.json (assert 'Something went wrong' -> tap 'Retry' -> tap 'Dismiss' for the dev-only LogBox overlay -> assert 'Please try again.') reported SCENE e2 OK; digest e2-script.log shows 'Something went wrong', 'Please try again.', 'Button Retry' again after the retry, i.e. the retry re-render never yielded a blank frame (the persistent render error is caught again by the root boundary). Corroborated by e2-scene.log. Replay saved at e2.replay.json. Screenshot e2.png captured for the visual reviewer. No UX-DEFECT observed.

E2E proof — log excerpts

[e1] android emulator-5554: runtime error reaches root ErrorBoundary and shows t -> pass :: android emulator-5554. Reached the state with a temporary root route (apps/mobile/src/app/kwf-runtime-error-probe.tsx, throws on render; deleted after, worktree clean via git status) since files/e2e-index.md exposes no render-error fault hook. SCENE digest e1-scene.log shows 'Something went wrong', 'Please try again.', 'Button Retry' — the RuntimeErrorScreen fallback, not a blank frame. e1-hierarchy.xml shows com.horcrux.svg.SvgView + CircleView (icon graphic present); the icon's appearance is the visual reviewer's. Screenshot e1.png captured for the visual reviewer. No UX-DEFECT observed (clear title, description and Retry next action).
[e2] android emulator-5554: tap Retry returns to the same designed error screen, -> pass :: android emulator-5554. Scripted scene e2-scenes.json (assert 'Something went wrong' -> tap 'Retry' -> tap 'Dismiss' for the dev-only LogBox overlay -> assert 'Please try again.') reported SCENE e2 OK; digest e2-script.log shows 'Something went wrong', 'Please try again.', 'Button Retry' again after the retry, i.e. the retry re-render never yielded a blank frame (the persistent render error is caught again by the root boundary). Corroborated by e2-scene.log. Replay saved at e2.replay.json. Screenshot e2.png captured for the visual reviewer. No UX-DEFECT observed.

/home/igor_kilocode_ai/.local/share/kwf/sections/explorer-app-runtime-error-the-runtime-error-state-render-a155f-594b/e2e-mobile-app/e1-scene.log

SCENE e1 OK
android.widget.LinearLayout com.kilocode.kiloapp:id/action_bar_root tappable [0,0][1080,2400]
android.widget.FrameLayout android:id/content tappable [0,0][1080,2400]
android.view.View Something went wrong tappable [324,1161][757,1226]
android.widget.TextView Please try again. tappable [417,1235][663,1281]
android.widget.Button Retry tappable [461,1318][619,1433]
android.widget.TextView Retry tappable [500,1352][579,1398]
shot: /home/igor_kilocode_ai/.local/share/kwf/sections/explorer-app-runtime-error-the-runtime-error-state-render-a155f-594b/e2e-mobile-app/e1.png

/home/igor_kilocode_ai/.local/share/kwf/sections/explorer-app-runtime-error-the-runtime-error-state-render-a155f-594b/e2e-mobile-app/e2-script.log

SCENE e2 OK
android.widget.LinearLayout com.kilocode.kiloapp:id/action_bar_root tappable [0,0][1080,2400]
android.widget.FrameLayout android:id/content tappable [0,0][1080,2400]
android.view.View Something went wrong tappable [324,1161][757,1226]
android.widget.TextView Please try again. tappable [417,1235][663,1281]
android.widget.Button Retry tappable [461,1318][619,1433]
android.widget.TextView Retry tappable [500,1352][579,1398]

/home/igor_kilocode_ai/.local/share/kwf/sections/explorer-app-runtime-error-the-runtime-error-state-render-a155f-594b/e2e-mobile-app/e2-scene.log

SCENE e2 OK
android.widget.LinearLayout com.kilocode.kiloapp:id/action_bar_root tappable [0,0][1080,2400]
android.widget.FrameLayout android:id/content tappable [0,0][1080,2400]
android.view.View Something went wrong tappable [324,1161][757,1226]
android.widget.TextView Please try again. tappable [417,1235][663,1281]
android.widget.Button Retry tappable [461,1318][619,1433]
android.widget.TextView Retry tappable [500,1352][579,1398]
shot: /home/igor_kilocode_ai/.local/share/kwf/sections/explorer-app-runtime-error-the-runtime-error-state-render-a155f-594b/e2e-mobile-app/e2.png
SCENE e2 OK
android.widget.LinearLayout com.kilocode.kiloapp:id/action_bar_root tappable [0,0][1080,2400]
android.widget.FrameLayout android:id/content tappable [0,0][1080,2400]
android.view.View Something went wrong tappable [324,1161][757,1226]
android.widget.TextView Please try again. tappable [417,1235][663,1281]
android.widget.Button Retry tappable [461,1318][619,1433]
android.widget.TextView Retry tappable [500,1352][579,1398]

Owner request

Explorer finding: app-runtime-error: The runtime-error state renders as a fully blank black frame with no message, icon, or next action, so the failure looks like a crash rather than a designed error screen.

The user-agent explorer found this while using the app like a user.
One finding per item; the explorer never edits product code.

Flow: app-runtime-error
Found on revision: fd04ca1

Repro:

1. set this state first: account e2e-mobile-cloud-android@example.com signed in via emailed code, $10 credits, a second organization, 4 Code Reviewer pull requests, battery 15% discharging, device portrait.
2. open the app on emulator-5554
3. reach the screen the capture names (app-runtime-error)
4. the capture shows the defect named below

Observed: The runtime-error state renders as a fully blank black frame with no message, icon, or next action, so the failure looks like a crash rather than a designed error screen.
Expected: the screen renders without this defect

Evidence (from the device run):

Follow-ups (not changed here)

• not proved live: On emulator-5554 with the e2e-mobile-cloud-android account, trigger the app-runtime-error flow (a render error that reaches the root ErrorBoundary) and confirm the screen shows the alert icon, the 'Something went wrong' title, the 'Please try again.' description and a Retry button instead of a blank black frame. (no capture cited it)
• not proved live: On that runtime-error screen, tap Retry and confirm the app returns to the previous screen or shows the same designed error screen again, never a blank frame. (no capture cited it)

Open findings (not fixed here)

• not proved live: app-runtime-error.png is no longer on the host that took it, so no publish can carry it

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The root error boundary now renders a plain full-screen RuntimeErrorScreen (QueryError placement="static") instead of the geometry-gated StateSurface, and the static branch reuses EmptyState's existing non-center path without altering center/top behavior; no correctness, security, performance, or memory-leak issues found in the changed lines.

Files Reviewed (5 files)

• apps/mobile/src/app/_layout.tsx
• apps/mobile/src/components/empty-state.tsx
• apps/mobile/src/components/query-error.tsx
• apps/mobile/src/components/runtime-error-screen.tsx
• apps/mobile/src/components/runtime-error-screen.mounted.test.tsx

---

_{Reviewed by deepseek-v4.1-flash · Input: 0 · Output: 0 · Cached: 0}

_{Review guidance: REVIEW.md from base branch main}

[iscekic]

This description names a scenario the proof did not capture:

• not proved live: On emulator-5554 with the e2e-mobile-cloud-android account, trigger the app-runtime-error flow (a render error that reaches the root ErrorBoundary) and confirm the screen shows the alert icon, the 'Something went wrong' title, the 'Please try again.' description and a Retry button instead of a blank black frame. (no capture cited it)

A repeated proof run rebuilds the same evidence, so no proof run is dispatched for a named gap. Merging with this gap open is your decision.