fix(startup): show a recoverable screen when Buzz fails to open or crashes - #3085

Summary

Part 2 of 3 from the errors-3 work (DA-12). When Buzz cannot finish opening, the window today stays on the looping "Opening Buzz" mark with nothing a person can do; when the running app hits a React error no boundary catches, the window goes blank. Screen readers hear only "Opening Buzz". This PR adds a recoverable fallback that needs nothing from the app bundle: Buzz couldn’t open for startup failures, Buzz stopped working for a crash after launch, each with Reload, Restart Buzz on the desktop, and the error behind a collapsed Details. A start that takes more than 20 seconds says This is taking longer than usual. and offers Reload while still opening by itself if it finishes.

Changes

• 1c6351d09 fix(startup): DA-12 show "Buzz couldn’t open" when startup fails
• dd9ee5339 fix(startup): DA-12 say "Buzz stopped working" when a running app crashes

Mechanisms:

• Bundle-independent DOM fallback in public/launch-init.js: builds the page with plain DOM and the tokens startup.css already loads, removes the launch, hides and inerts #root and #buzz-toast-root, reveals a still-hidden first-welcome Mac window, and focuses Reload. Later failures append to Details.
• error / unhandledrejection listeners in launch-init.js (capture phase, so a failed <script> load counts) that fail startup until React has the app, then leave other errors to the running app.
• Startup try/catch in src/main.tsx around createServices() and the first render, reporting through showStartupFailure() in src/app/launch.ts; startupHandedToReact() tells launch-init.js once React has the app.
• onUncaughtError on createRoot: an error no boundary caught reaches the same fallback with the component stack in Details.
• 20 s watchdog: adds "This is taking longer than usual." [Reload] to the launch status region; the launch still leaves on its own if it ends.
• Post-launch "Buzz stopped working": once React had the app and the launch is gone, the fallback's title and sentence say the app stopped, not that it couldn't open.
• Test infra for these journeys: a startupFailureFixture build option (tests/browser/build.mjs) that throws where window.__buzzFixtureStartupFailure says (services, render, running), and expectedStartupFailure in tests/browser/fixture.mjs so a journey's injected failure passes the console/page-error gate.
• docs/buzz-help.md describes the behaviour.

Evidence

Headless Chromium 1280×800, light theme, launchAnimation: true, driven by tests/browser/fixture.mjs. Before is the merge base 40e6ccb597 with only this branch's test infra applied; After is this branch.

1. Main bundle fails to load (desktop), at 15 s

2. The same, with Details expanded

3. createServices() throws (storage unavailable), at 15 s

4. App throws during its first render

5. Watchdog: the bundle is held, at 20 s

6. Crash after launch (the app's content throws on the next navigation)

7. Browser build (no Tauri stub): Reload only

8. Screen-reader view (Playwright aria snapshot)

Text of the same snapshots, from page.locator("body").ariaSnapshot() with the bundle failing to load (desktop stub):

Before (the same in every scenario above, except the crash after launch, where the body has no accessible nodes at all):

- status "Opening Buzz":
  - img "Buzz"

After:

- main "Buzz couldn’t open":
  - alert:
    - heading "Buzz couldn’t open" [level=1]
    - paragraph: Something went wrong while starting. Your messages and settings are safe.
  - button "Reload"
  - button "Restart Buzz"
  - group: Details

After, slow launch at 20 s (the launch is a status region, so the added text is read when it appears):

- status "Opening Buzz":
  - img "Buzz"
  - paragraph: This is taking longer than usual.
  - button "Reload"

After, crash after launch:

- main "Buzz stopped working":
  - alert:
    - heading "Buzz stopped working" [level=1]
    - paragraph: Something went wrong. Your messages and settings are safe.
  - button "Reload"
  - group: Details

9. Reload with the bundle restored

Videos

Same scripted steps in both builds: open with the bundle failing, wait 20 s (sped up 8× with a caption saying so), restore the bundle, then click Reload where there is one. Captions are in a band under the content.

Before

After

Side by side

Testing

Run in the PR worktree at dd9ee5339:

bin/pnpm exec biome format .                      # Checked 3235 files. No fixes applied.
bin/pnpm exec biome lint --error-on-warnings .    # Checked 3336 files. Found 30 infos (pre-existing), exit 0
bin/node scripts/design-system/check-icons.mjs    # ok
bin/pnpm typecheck                                # tsc --noEmit: ok
bin/pnpm design:typecheck                         # tsc -p tsconfig.design.json: ok
bin/pnpm exec vitest run src/app/launch.test.ts src/app/device-settings.test.ts \
  src/app/App.profile.test.tsx src/app/IdentitySettings.test.tsx src/app/entity-navigation.test.tsx
                                                  # 5 files, 117 tests passed
bin/pnpm exec playwright test --config tests/browser/playwright.config.mjs \
  --project=chromium --project=webkit --no-deps \
  tests/browser/startup-failure.spec.mjs tests/browser/startup.spec.mjs
                                                  # 34 passed (2.3m): 6 startup-failure + 11 startup journeys per engine

Not run here: just scan, the native build, and a human test in the desktop app (Restart Buzz is exercised only through a __TAURI_INTERNALS__ stub).

Notes

• src/main.tsx is a FOUNDATION file. It was changed on explicit human instruction: startup is wrapped in try/catch, createRoot gets onUncaughtError, and startupHandedToReact() runs after the first render. Please give it the stricter review.
• The plan and before/after notes are in Staged (project "Errors 3").
• PR 1 of 3 (DA-9, Huddles) and PR 3 of 3 (DA-23, plugin update checks) are independent of this one.

🤖 Generated with Claude Code