fix: prevent onboarding crash when back-navigation empties page stack

[bengotow]

Summary

Fixes Sentry issue MAILSPRING-CLIENT-26 — 23 users affected, 59 occurrences.

Error: Cannot find component for page: undefined
Location: OnboardingRoot.render() in onboarding-root.tsx

Root Cause

OnboardingStore._onMoveToPreviousPage pops from _pageStack with no bounds check. If the action fires when only one page is on the stack (e.g. rapid back-button double-clicks, or any duplicate dispatch of moveToPreviousPage), the stack becomes empty. page() then returns undefined, and OnboardingRoot.render() throws an unhandled error instead of degrading gracefully.

The stale-closure risk in PageTopBar: closeAction captures pageDepth from props at render time. A rapid double-click could fire both handlers with pageDepth = 2 before the re-render reflecting the first pop, triggering moveToPreviousPage() twice in succession and draining the stack to zero.

Fix (two layers)

1. onboarding-store.ts — Guard in _onMoveToPreviousPage: bail out early if the stack has only one page, making it impossible to empty the stack via back-navigation.

2. onboarding-root.tsx — Defensive fallback in render(): if page is somehow still undefined (any future unknown cause), close/quit the window gracefully instead of throwing an unhandled exception that reaches Sentry.

Test plan

• Launch onboarding as a new user (welcome page). Verify the X button closes the window and does not crash.
• Navigate forward to account-choose, then rapidly double-click the back button. Verify no crash — should land on welcome page or close gracefully.
• Normal onboarding flow completes without regression.

https://claude.ai/code/session_01PGz7rfpJU4fs2QMeT7sdYw

---

Generated by Claude Code

[indent-staging]

PR Summary

Fixes Sentry MAILSPRING-CLIENT-26 (23 users) where rapid back-button clicks in onboarding double-dispatched moveToPreviousPage — the click handler reads stale pageDepth from React props, so two clicks at depth 2 both pass the gate — draining OnboardingStore._pageStack and causing OnboardingRoot.render() to throw Cannot find component for page: undefined. After review feedback, the defensive render-time fallback was reverted, leaving only the root-cause store fix.

• OnboardingStore._onMoveToPreviousPage now early-returns when _pageStack.length <= 1, establishing "stack is non-empty" as a real invariant and turning stale-state rapid clicks into a safe no-op (no spurious trigger()).
• OnboardingRoot.render is unchanged from master (the prior defensive AppEnv.quit/close fallback was reverted in commit 02784a9, preserving the loud throw for any future invalid page name).

Issues

All clear! No issues remaining. 🎉

2 issues already resolved

• Latent: the new render fallback silently closes/quits the window for any unknown state.page, which would swallow a future OnboardingActions.moveToPage('typo') instead of surfacing the loud error the previous throw provided. No regression today — every current caller passes a literal page name that exists in PageComponents — but worth keeping in mind if you add new pages. (fixed by commit 02784a9)
• Nit: AppEnv.quit()/AppEnv.close() are invoked from inside OnboardingRoot.render(), which is a React-purity smell — side effects belong in componentDidUpdate/componentDidMount. Harmless in practice because the store-level guard makes this branch unreachable via the primary fix, but moving the call to componentDidUpdate (and just returning null in render) would be cleaner. (fixed by commit 02784a9)

CI Checks

All CI checks passed on commit 02784a9.

Custom Rules 3 rules evaluated, 3 passed, 0 failed

This is a longer title to see what happens when they are too long to fit
B
Ben Rule

[bengotow]

I agree with Indent, @claude can you keep just the app/internal_packages/onboarding/lib/onboarding-store.ts change in this PR? Let's not do the defensive fallback, just the one fix should be sufficient.