refactor(router): a Navigator adapter as the seam

[chrisnojima]

Problem

The navigation seam was "a module of 25 functions reaching a process-global navigationRef". Because there was no injectable adapter, the only way to substitute navigation was to mock the module — so 14 test files hand-rolled jest.mock('@/constants/router', ...), each declaring a different partial shape of it.

navigateAppend also carried hidden temporal state: a 1000ms in-flight dedupe window that no test could reach.

util/safe-navigation.tsx (12 lines) was the only hook-shaped adapter, covering 2 of ~25 operations — ~60 call sites against ~479 going straight to the module global.

Change

New constants/navigator.tsx:

NavigatorRef = {isReady, getRootState, dispatch, addListener}
makeNavigator(ref)   // adds the seven tree-aware ops on top

Exactly two adapters — the real container-ref binding and test/fake-navigator.ts — which is what makes the seam real rather than hypothetical.

constants/router.tsx's free functions become one-line bindings to getNavigator(), so all ~479 call sites are untouched.

Mocks eliminated

15 of 15. The 14 jest.mock factories, plus constants/navigate-to-thread.test.ts, which stubbed the container ref by hand and carried a 10-line comment working around the module-global _pendingAppend — that cache is now per-navigator, so the workaround is gone.

Previously untestable, now tested

The in-flight dedupe window, the visible-route dupe check, navUpToScreen's three branches (popTo / in-place reset / replaceIfMissing), clearModals' filter, switchTab, setChatRootParams, navigateUp/popStack. constants/tests/navigator.test.ts is 29 tests.

14 mutations, each caught — including dropping the in-flight dedupe, widening the window to 100s, neutering clearModals' filter, and making the fake ignore ready.

Fixed along the way

test/mocks/react-navigation-core.js's CommonActions.navigate and setParams built payloads no version of React Navigation produces (the bare name; params without their {params} wrapper). Tests asserting on those actions were asserting a shape production never dispatches.

Behaviour change, flagged not hidden

switchTab/setChatRootParams now bail explicitly when routes[0] isn't loggedIn. Previously switchTab dispatched TabActions.jumpTo at the logged-out stack router, which has no JUMP_TO handler — same outcome, now intentional.

Out of scope

Chat logic stays in constants/router.tsx. The dispatches in router-v2/common.tsx, tab-bar.desktop.tsx and teams/confirm-modals/ target a specific navigator handed to a component, not the root — not this seam, noted in the module header.

Validation

lint:all clean — 0 bailed out, 0 whole-props deps, tsc clean both projects.
jest --runInBand — 231 suites / 2281 tests (baseline 230 / 2236).