@symbiote-native/navigation 1.0.0

package/src/core/drawer-options/index.ts

@@ -0,0 +1,331 @@
+// Drawer option types + the pure swipe/geometry math. Framework-agnostic (numbers and
+// booleans only, per CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>), shared verbatim by
+// every adapter. Mirrors react-navigation's Drawer prop surface (confirmed against the current
+// @react-navigation/drawer docs): drawerType 'front'/'back'/'slide'/'permanent', drawerPosition,
+// drawerWidth, overlayColor, swipeEnabled + the three swipe-tuning knobs. What is NOT ported:
+// `configureGestureHandler` - a react-native-gesture-handler-specific escape hatch with no
+// PanResponder equivalent (see packages/navigation's README / the drawer feasibility note for the
+// full gap list).
+
+import type { IPanResponderGestureState, ISymbioteEvent } from '@symbiote-native/engine';
+import { isRecord } from '../guards';
+import type { IDrawerSlot } from '../render-drawer';
+
+export type IDrawerType = 'front' | 'back' | 'slide' | 'permanent';
+export type IDrawerPosition = 'left' | 'right';
+
+export interface IDrawerOptions {
+  drawerType?: IDrawerType;
+  drawerPosition?: IDrawerPosition;
+  drawerWidth?: number;
+  overlayColor?: string;
+  swipeEnabled?: boolean;
+  // How far from the position edge a closed-drawer swipe must START to count (react-navigation
+  // default: 32).
+  swipeEdgeWidth?: number;
+  // Minimum accumulated drag distance to snap-open/close on release (react-navigation default: 60).
+  swipeMinDistance?: number;
+  // Minimum release velocity (px/ms, same unit as gestureState.vx) that snaps regardless of
+  // distance (react-navigation default: 500 px/s == 0.5 px/ms).
+  swipeMinVelocity?: number;
+}
+
+// Per-screen options a caller's own renderDrawerContent reads to label its menu entries - the
+// drawer navigator has no built-in menu UI (matching react-native-drawer-layout's Drawer
+// primitive, which the underlying @react-navigation/drawer itself builds its DrawerItemList on
+// top of), so this stays deliberately small next to IScreenOptions's header surface.
+export interface IDrawerScreenOptions {
+  title?: string;
+  drawerLabel?: string;
+}
+
+export const DRAWER_DEFAULT_TYPE: IDrawerType = 'front';
+export const DRAWER_DEFAULT_POSITION: IDrawerPosition = 'left';
+export const DRAWER_DEFAULT_WIDTH = 280;
+export const DRAWER_DEFAULT_OVERLAY_COLOR = 'rgba(0, 0, 0, 0.5)';
+export const DRAWER_DEFAULT_SWIPE_ENABLED = true;
+export const DRAWER_DEFAULT_SWIPE_EDGE_WIDTH = 32;
+export const DRAWER_DEFAULT_SWIPE_MIN_DISTANCE = 60;
+// react-navigation's 500 is px/second; gestureState.vx is px/ms, so the default converts.
+export const DRAWER_DEFAULT_SWIPE_MIN_VELOCITY = 0.5;
+
+// Exported so render-drawer.ts and the adapter can resolve the same defaults without
+// re-declaring the `??` fallback (a second copy would drift the instant a default changes).
+export function resolveDrawerWidth(options: IDrawerOptions): number {
+  return options.drawerWidth ?? DRAWER_DEFAULT_WIDTH;
+}
+
+export function resolveDrawerType(options: IDrawerOptions): IDrawerType {
+  return options.drawerType ?? DRAWER_DEFAULT_TYPE;
+}
+
+export function resolveDrawerPosition(options: IDrawerOptions): IDrawerPosition {
+  return options.drawerPosition ?? DRAWER_DEFAULT_POSITION;
+}
+
+// The animated outputs a progress value of 0 (closed) -> 1 (open) drives, resolved once per
+// drawerType/position/width combination. 'permanent' never animates (no gesture, no snap), so
+// callers short-circuit on isDrawerAnimated before reading this.
+export type IDrawerGeometry = {
+  panelTranslateXClosed: number;
+  panelTranslateXOpen: number;
+  contentTranslateXClosed: number;
+  contentTranslateXOpen: number;
+  overlayOpacityClosed: number;
+  overlayOpacityOpen: number;
+};
+
+export function isDrawerAnimated(options: IDrawerOptions): boolean {
+  return resolveDrawerType(options) !== 'permanent';
+}
+
+export function isDrawerOverlayVisible(options: IDrawerOptions): boolean {
+  const type = resolveDrawerType(options);
+  return type === 'front' || type === 'slide';
+}
+
+// front: only the panel moves (-width -> 0), content stays put, overlay fades in.
+// back: only the content moves, away from the position edge, to reveal the stationary panel;
+//   no overlay (the panel sits fully behind the content, nothing to dim).
+// slide: panel AND content move together by the same delta, overlay fades in (content still
+//   covers the panel partially as they slide in tandem, same as front visually at rest).
+// permanent: static, all zero (isDrawerAnimated() gates callers off this path already).
+export function resolveDrawerGeometry(options: IDrawerOptions): IDrawerGeometry {
+  const width = resolveDrawerWidth(options);
+  const type = resolveDrawerType(options);
+  const sign = resolveDrawerPosition(options) === 'left' ? 1 : -1;
+  const closedPanelX = -sign * width;
+  const openContentX = sign * width;
+
+  switch (type) {
+    case 'back':
+      return {
+        panelTranslateXClosed: 0,
+        panelTranslateXOpen: 0,
+        contentTranslateXClosed: 0,
+        contentTranslateXOpen: openContentX,
+        overlayOpacityClosed: 0,
+        overlayOpacityOpen: 0,
+      };
+    case 'slide':
+      return {
+        panelTranslateXClosed: closedPanelX,
+        panelTranslateXOpen: 0,
+        contentTranslateXClosed: 0,
+        contentTranslateXOpen: openContentX,
+        overlayOpacityClosed: 0,
+        overlayOpacityOpen: 1,
+      };
+    case 'front':
+    case 'permanent':
+    default:
+      return {
+        panelTranslateXClosed: closedPanelX,
+        panelTranslateXOpen: 0,
+        contentTranslateXClosed: 0,
+        contentTranslateXOpen: 0,
+        overlayOpacityClosed: 0,
+        overlayOpacityOpen: 1,
+      };
+  }
+}
+
+export type IDrawerInterpolationRange = {
+  inputRange: readonly [number, number];
+  outputRange: readonly [number, number];
+};
+
+export type IDrawerContentSlotInterpolation = {
+  translateX: IDrawerInterpolationRange;
+};
+
+export type IDrawerOverlaySlotInterpolation = {
+  opacity: IDrawerInterpolationRange;
+  translateX: IDrawerInterpolationRange;
+};
+
+export type IDrawerPanelSlotInterpolation = {
+  translateX: IDrawerInterpolationRange;
+};
+
+const DRAWER_PROGRESS_INPUT_RANGE: readonly [number, number] = [0, 1];
+
+// The pure `{inputRange, outputRange}` half of each slot's `progress.interpolate(...)` call,
+// factored out of react/vue/angular drawer.ts (the same literal config recomputed inline in all
+// three, including three near-identical spots within angular/drawer.ts's own content/overlay/
+// panel style getters) - the adapter still owns the actual `Animated.Value.interpolate()` call
+// (the `Animated.Value` instance is adapter-lifecycle-held per CLAUDE.md
+// <adapters_stay_thin>), this only computes what to feed it.
+//
+// The three slots are NOT symmetric: content and panel each drive only their own translateX, but
+// overlay drives BOTH its own opacity AND a translateX that deliberately tracks CONTENT's delta,
+// not its own - see render-drawer.ts's `drawerChildOrder` header: for `slide`, content itself
+// slides away, and an overlay that didn't follow it would stay pinned full-screen instead of
+// dimming just the content it's meant to cover. The overload set below reflects that asymmetry in
+// the return type per slot, instead of forcing one shape that would leave 'content'/'panel'
+// carrying an unused `opacity` field or 'overlay' missing one it needs.
+export function resolveDrawerSlotInterpolation(
+  geometry: IDrawerGeometry,
+  slot: 'content',
+): IDrawerContentSlotInterpolation;
+export function resolveDrawerSlotInterpolation(
+  geometry: IDrawerGeometry,
+  slot: 'overlay',
+): IDrawerOverlaySlotInterpolation;
+export function resolveDrawerSlotInterpolation(
+  geometry: IDrawerGeometry,
+  slot: 'panel',
+): IDrawerPanelSlotInterpolation;
+export function resolveDrawerSlotInterpolation(
+  geometry: IDrawerGeometry,
+  slot: IDrawerSlot,
+):
+  | IDrawerContentSlotInterpolation
+  | IDrawerOverlaySlotInterpolation
+  | IDrawerPanelSlotInterpolation {
+  switch (slot) {
+    case 'content':
+      return {
+        translateX: {
+          inputRange: DRAWER_PROGRESS_INPUT_RANGE,
+          outputRange: [geometry.contentTranslateXClosed, geometry.contentTranslateXOpen],
+        },
+      };
+    case 'overlay':
+      return {
+        opacity: {
+          inputRange: DRAWER_PROGRESS_INPUT_RANGE,
+          outputRange: [geometry.overlayOpacityClosed, geometry.overlayOpacityOpen],
+        },
+        translateX: {
+          inputRange: DRAWER_PROGRESS_INPUT_RANGE,
+          outputRange: [geometry.contentTranslateXClosed, geometry.contentTranslateXOpen],
+        },
+      };
+    case 'panel':
+      return {
+        translateX: {
+          inputRange: DRAWER_PROGRESS_INPUT_RANGE,
+          outputRange: [geometry.panelTranslateXClosed, geometry.panelTranslateXOpen],
+        },
+      };
+  }
+}
+
+// onStartShouldSetPanResponder gate: while closed, a swipe must START within swipeEdgeWidth of
+// the drawer's position edge (mirrors react-navigation's swipeEdgeWidth). While open, the whole
+// content + overlay area is fair game to drag-close, matching the intuitive "swipe anywhere to
+// dismiss an open drawer" behavior every drawer implementation (including RN's dropped native
+// DrawerLayoutAndroid) shares.
+export function isSwipeStartInEdge(
+  startX: number,
+  screenWidth: number,
+  isOpen: boolean,
+  options: IDrawerOptions,
+): boolean {
+  if (isOpen) return true;
+  const edgeWidth = options.swipeEdgeWidth ?? DRAWER_DEFAULT_SWIPE_EDGE_WIDTH;
+  return resolveDrawerPosition(options) === 'left'
+    ? startX <= edgeWidth
+    : startX >= screenWidth - edgeWidth;
+}
+
+// onMoveShouldSetPanResponder gate: only claim the gesture once it reads as a horizontal drag
+// (RN's own PanResponder examples use this exact dominant-axis check to stay out of a vertical
+// ScrollView's way).
+const MOVE_CLAIM_THRESHOLD = 5;
+
+export function isHorizontalDrag(gestureState: IPanResponderGestureState): boolean {
+  return (
+    Math.abs(gestureState.dx) > MOVE_CLAIM_THRESHOLD &&
+    Math.abs(gestureState.dx) > Math.abs(gestureState.dy)
+  );
+}
+
+export type ISwipeIntent = 'open' | 'close';
+
+// The release-time decision, structurally the same shape as switch.ts's shouldSnapBack: a pure
+// predicate over the accumulated gesture plus the option thresholds, no framework. Distance OR
+// velocity past its threshold, in the direction that would move the drawer toward the opposite
+// of its current state, snaps it there; anything else snaps back to where it started.
+export function resolveSwipeIntent(
+  gestureState: IPanResponderGestureState,
+  isOpen: boolean,
+  options: IDrawerOptions,
+): ISwipeIntent {
+  const sign = resolveDrawerPosition(options) === 'left' ? 1 : -1;
+  // Positive `signedDelta` means "dragging toward open" for a left drawer's rightward drag (and
+  // symmetrically for a right drawer's leftward drag).
+  const signedDx = sign * gestureState.dx;
+  const signedVx = sign * gestureState.vx;
+  const minDistance = options.swipeMinDistance ?? DRAWER_DEFAULT_SWIPE_MIN_DISTANCE;
+  const minVelocity = options.swipeMinVelocity ?? DRAWER_DEFAULT_SWIPE_MIN_VELOCITY;
+
+  const pastDistance = Math.abs(signedDx) >= minDistance;
+  const pastVelocity = Math.abs(signedVx) >= minVelocity;
+  if (!pastDistance && !pastVelocity) return isOpen ? 'open' : 'close';
+
+  // Velocity wins the direction call when it clears its own threshold (a fast flick can reverse
+  // a short drag); otherwise the drag distance's sign decides.
+  const towardOpen = pastVelocity ? signedVx > 0 : signedDx > 0;
+  return towardOpen ? 'open' : 'close';
+}
+
+export function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function toFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+// The touch's real starting page-X, read off the raw event rather than gestureState.x0: the
+// engine's capture phase (core/engine/src/pan-responder/index.ts's
+// onStartShouldSetResponderCapture/onMoveShouldSetResponderCapture) resets gestureState before
+// the bubble-phase onStartShouldSetPanResponder/onMoveShouldSetPanResponder gates run, so x0 is
+// only populated later, inside onResponderGrant. Shaped like core/engine/src/events/index.ts's
+// readTouchPoint but not the same function: that one requires both pageX AND pageY and returns
+// an {x, y} pair for touch-history bookkeeping; this only needs pageX and is private to the
+// SET-gate below, so it stays a separate, narrower helper rather than forcing a shared contract
+// onto two callers with different needs.
+export function startPageXOf(event: ISymbioteEvent): number | undefined {
+  const { nativeEvent } = event;
+  const direct = toFiniteNumber(nativeEvent.pageX);
+  if (direct !== undefined) return direct;
+  const touches = nativeEvent.touches;
+  if (Array.isArray(touches) && isRecord(touches[0])) return toFiniteNumber(touches[0].pageX);
+  return undefined;
+}
+
+// onPanResponderMove's drag-to-progress math: how far the touch has traveled, in progress units
+// (0..1), added to wherever the drag started from. Mirrors the SAME sign convention as
+// resolveSwipeIntent (left drawer: rightward drag is positive-toward-open).
+export function resolveDragProgress(
+  gestureState: IPanResponderGestureState,
+  dragStartProgress: number,
+  options: IDrawerOptions,
+): number {
+  const width = resolveDrawerWidth(options);
+  const sign = resolveDrawerPosition(options) === 'right' ? -1 : 1;
+  const delta = (sign * gestureState.dx) / width;
+  return clamp01(dragStartProgress + delta);
+}
+
+// The composed onStartShouldSetPanResponder/onMoveShouldSetPanResponder gate: swipeEnabled ->
+// isDrawerAnimated -> isSwipeStartInEdge, then (move only) isHorizontalDrag on top. The start
+// gate omits the dominant-axis check on purpose (react-navigation's own edge-swipe idiom: claim
+// on entering the edge, confirm direction only once movement exists to measure).
+export function shouldClaimDrawerSwipe(
+  event: ISymbioteEvent,
+  gestureState: IPanResponderGestureState,
+  screenWidth: number,
+  isOpen: boolean,
+  options: IDrawerOptions,
+  phase: 'start' | 'move',
+): boolean {
+  if ((options.swipeEnabled ?? DRAWER_DEFAULT_SWIPE_ENABLED) === false) return false;
+  if (!isDrawerAnimated(options)) return false;
+  const startX = startPageXOf(event) ?? gestureState.x0;
+  if (!isSwipeStartInEdge(startX, screenWidth, isOpen, options)) return false;
+  return phase === 'start' ? true : isHorizontalDrag(gestureState);
+}

package/src/core/drawer-router-state/drawer-router-state.test.ts

@@ -0,0 +1,116 @@
+// Co-located unit test (ADR 0025) for the pure drawer router reducer - sibling to
+// navigator-state.test.ts (stack). Unlike the stack's push/pop array, the drawer's route list
+// never changes shape (see drawer-router-state.ts's header): only which route is focused
+// (`index`) and whether the panel is open (`isOpen`) can change, so every action here is a
+// jumpTo/open/close/toggle over a FIXED route array.
+
+import { describe, expect, it } from 'vitest';
+import { createInitialDrawerRouterState, drawerRouterReducer, focusedDrawerRoute } from './index';
+import type { IDrawerRouterState } from './index';
+
+const HOME = { key: 'home-1', name: 'Home', params: undefined };
+const PROFILE = { key: 'profile-1', name: 'Profile', params: { tab: 'feed' } };
+const SETTINGS = { key: 'settings-1', name: 'Settings', params: undefined };
+
+function closedState(index = 0): IDrawerRouterState {
+  return { routes: [HOME, PROFILE, SETTINGS], index, isOpen: false };
+}
+
+function openState(index = 0): IDrawerRouterState {
+  return { routes: [HOME, PROFILE, SETTINGS], index, isOpen: true };
+}
+
+describe('createInitialDrawerRouterState', () => {
+  it('focuses the first route and starts closed when no initialRouteName is given', () => {
+    expect(createInitialDrawerRouterState([HOME, PROFILE])).toEqual({
+      routes: [HOME, PROFILE],
+      index: 0,
+      isOpen: false,
+    });
+  });
+
+  it('focuses the route matching initialRouteName', () => {
+    const state = createInitialDrawerRouterState([HOME, PROFILE, SETTINGS], 'Settings');
+    expect(state.index).toBe(2);
+    expect(state.isOpen).toBe(false);
+  });
+
+  it('falls back to the first route when initialRouteName matches nothing', () => {
+    expect(createInitialDrawerRouterState([HOME, PROFILE], 'Nowhere').index).toBe(0);
+  });
+});
+
+describe('drawerRouterReducer — jumpTo', () => {
+  it('focuses the named route', () => {
+    const next = drawerRouterReducer(closedState(0), { type: 'jumpTo', name: 'Profile' });
+    expect(next.index).toBe(1);
+    expect(next.isOpen).toBe(false);
+  });
+
+  it('also closes an already-open drawer when jumping to a different route', () => {
+    const next = drawerRouterReducer(openState(0), { type: 'jumpTo', name: 'Profile' });
+    expect(next.index).toBe(1);
+    expect(next.isOpen).toBe(false);
+  });
+
+  it('closes an open drawer even when jumping to the already-focused route', () => {
+    // Selecting a destination is itself the dismissal gesture (the reducer's own comment) -
+    // that still holds when the destination is the one already on screen.
+    const state = openState(0);
+    const next = drawerRouterReducer(state, { type: 'jumpTo', name: 'Home' });
+    expect(next).not.toBe(state);
+    expect(next).toEqual({ ...state, isOpen: false });
+  });
+
+  it('is a no-op for an unknown route name, same reference returned', () => {
+    const state = closedState(0);
+    expect(drawerRouterReducer(state, { type: 'jumpTo', name: 'Nowhere' })).toBe(state);
+  });
+
+  it('is a no-op when already focused on that route while closed, same reference returned', () => {
+    const state = closedState(0);
+    expect(drawerRouterReducer(state, { type: 'jumpTo', name: 'Home' })).toBe(state);
+  });
+});
+
+describe('drawerRouterReducer — openDrawer', () => {
+  it('opens a closed drawer', () => {
+    expect(drawerRouterReducer(closedState(), { type: 'openDrawer' }).isOpen).toBe(true);
+  });
+
+  it('is a no-op on an already-open drawer, same reference returned', () => {
+    const state = openState();
+    expect(drawerRouterReducer(state, { type: 'openDrawer' })).toBe(state);
+  });
+});
+
+describe('drawerRouterReducer — closeDrawer', () => {
+  it('closes an open drawer', () => {
+    expect(drawerRouterReducer(openState(), { type: 'closeDrawer' }).isOpen).toBe(false);
+  });
+
+  it('is a no-op on an already-closed drawer, same reference returned', () => {
+    const state = closedState();
+    expect(drawerRouterReducer(state, { type: 'closeDrawer' })).toBe(state);
+  });
+});
+
+describe('drawerRouterReducer — toggleDrawer', () => {
+  it('opens a closed drawer', () => {
+    expect(drawerRouterReducer(closedState(), { type: 'toggleDrawer' }).isOpen).toBe(true);
+  });
+
+  it('closes an open drawer', () => {
+    expect(drawerRouterReducer(openState(), { type: 'toggleDrawer' }).isOpen).toBe(false);
+  });
+});
+
+describe('focusedDrawerRoute', () => {
+  it('returns the route at the current index', () => {
+    expect(focusedDrawerRoute(closedState(1))).toBe(PROFILE);
+  });
+
+  it('returns undefined when the route list is empty', () => {
+    expect(focusedDrawerRoute(createInitialDrawerRouterState([]))).toBeUndefined();
+  });
+});

package/src/core/drawer-router-state/index.ts

@@ -0,0 +1,71 @@
+// DrawerRouter: the logic half (framework-agnostic, zero render), sibling to navigator-state.ts
+// and tab-router-state.ts. Unlike the stack's push/pop route array, a drawer's route list is
+// FIXED at mount (one entry per declared <Drawer.Screen>, collected by the adapter exactly like
+// Stack's/Tab's collectRegistry) - the reducer only tracks which one is focused (`index`) and
+// whether the drawer panel is open. Route identity/shape is `IRoute`, reused verbatim from
+// navigator-state.ts (same convention tab-router-state.ts follows) so all three navigators share
+// one route shape.
+
+import type { IRoute } from '../navigator-state';
+
+export type { IRoute } from '../navigator-state';
+
+type IRouteEntry = IRoute<unknown>;
+
+export type IDrawerRouterState = Readonly<{
+  routes: readonly IRouteEntry[];
+  index: number;
+  isOpen: boolean;
+}>;
+
+export type IDrawerRouterAction =
+  | { type: 'jumpTo'; name: string }
+  | { type: 'openDrawer' }
+  | { type: 'closeDrawer' }
+  | { type: 'toggleDrawer' };
+
+const INITIAL_FOCUSED_INDEX = 0;
+
+export function createInitialDrawerRouterState(
+  routes: readonly IRouteEntry[],
+  initialRouteName?: string,
+): IDrawerRouterState {
+  if (initialRouteName === undefined) {
+    return { routes, index: INITIAL_FOCUSED_INDEX, isOpen: false };
+  }
+  const index = routes.findIndex(route => route.name === initialRouteName);
+  return { routes, index: index === -1 ? INITIAL_FOCUSED_INDEX : index, isOpen: false };
+}
+
+// Mirrors @react-navigation/drawer's DrawerActions: jumpTo focuses a route by NAME (TabRouter's
+// own convention, not the stack's by-key popTo) AND closes the drawer - selecting a destination
+// is itself the dismissal gesture, so a plain focus without also closing would leave the panel
+// covering the just-selected screen.
+export function drawerRouterReducer(
+  state: IDrawerRouterState,
+  action: IDrawerRouterAction,
+): IDrawerRouterState {
+  switch (action.type) {
+    case 'jumpTo': {
+      const index = state.routes.findIndex(route => route.name === action.name);
+      if (index === -1) return state;
+      return index === state.index && !state.isOpen ? state : { ...state, index, isOpen: false };
+    }
+
+    case 'openDrawer':
+      return state.isOpen ? state : { ...state, isOpen: true };
+
+    case 'closeDrawer':
+      return state.isOpen ? { ...state, isOpen: false } : state;
+
+    case 'toggleDrawer':
+      return { ...state, isOpen: !state.isOpen };
+
+    default:
+      return state;
+  }
+}
+
+export function focusedDrawerRoute(state: IDrawerRouterState): IRouteEntry | undefined {
+  return state.routes[state.index];
+}

package/src/core/guards.ts

@@ -0,0 +1,23 @@
+// Runtime guards shared across the navigation package's core. Centralizes what used to be ~11
+// independent copies of the same `typeof value === 'object' && value !== null` check scattered
+// across core and every adapter (route-param merges, persisted-JSON validation, vnode-prop
+// narrowing, gesture-event field reads) - several of which had silently drifted on array
+// handling, one excluding arrays, another not, for the same kind of check.
+//
+// Excludes arrays: every current call site (route params, persisted navigator-state JSON,
+// touch-event objects, vnode props) only ever receives a genuine plain object, never a bare list
+// standing in for one - so `Array.isArray` narrows out a real footgun (a malformed persisted
+// value shaped like `[]` would otherwise pass this guard and fail confusingly deeper in, on a
+// missing `.key`/`.name` field, instead of here) at zero cost to the realistic inputs.
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Mirrors @react-navigation's CommonActions.setParams: a shallow merge onto the current params,
+// but only when both sides are genuine plain objects - an array (or any other non-record) on
+// either side means a clean replace instead, never a numeric-key-mangled merge. Shared by
+// navigator-state.ts (Stack) and tab-router-state.ts (Tabs) so the two reducers can't drift on
+// this rule independently.
+export function mergeParams(current: unknown, incoming: unknown): unknown {
+  return isRecord(current) && isRecord(incoming) ? { ...current, ...incoming } : incoming;
+}