@symbiote-native/navigation 1.0.0

package/src/react/hooks/use-drawer-navigation.ts

@@ -0,0 +1,21 @@
+// Twin of use-stack-navigation.ts, narrowing to a Drawer handle instead. See that file's header
+// for why this exists: it hides the union-narrowing guard inside the library instead of every call site.
+
+import type { IDrawerNavigatorHandle } from '../../core';
+import { isDrawerNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type IDrawerNavigationHandle = IDrawerNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useDrawerNavigation(): IDrawerNavigationHandle {
+  const navigation = useNavigation();
+  if (!isDrawerNavigatorHandle(navigation)) {
+    throw new Error(
+      'useDrawerNavigation() was called from a component whose nearest navigator is not a Drawer. ' +
+        'Use useNavigation() instead if this component can render under more than one navigator kind.',
+    );
+  }
+  return navigation;
+}

package/src/react/hooks/use-focus-effect.ts

@@ -0,0 +1,36 @@
+// Thin useEffect wrapper: runs `effect` while the route is focused and runs its own returned
+// cleanup on blur - exactly React.useEffect's contract, just re-armed on every focus/blur pair
+// instead of once on mount - mirrors @react-navigation's useFocusEffect. Callers should memoize
+// `effect` (React.useCallback), same requirement the upstream hook documents, since a new
+// `effect` identity re-subscribes here like any other useEffect dependency change.
+
+import { useEffect } from 'react';
+import type { EffectCallback } from 'react';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { useRequiredNavigationContext } from '../navigation-context';
+
+export function useFocusEffect(effect: EffectCallback): void {
+  const context = useRequiredNavigationContext('useFocusEffect');
+  const { emitter } = context;
+
+  useEffect(() => {
+    let cleanup: ReturnType<EffectCallback> | undefined;
+
+    const runEffect = (): void => {
+      cleanup = effect();
+    };
+    const runCleanup = (): void => {
+      cleanup?.();
+      cleanup = undefined;
+    };
+
+    const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, runEffect);
+    const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, runCleanup);
+
+    return () => {
+      unsubscribeFocus();
+      unsubscribeBlur();
+      runCleanup();
+    };
+  }, [emitter, effect]);
+}

package/src/react/hooks/use-is-focused.ts

@@ -0,0 +1,26 @@
+// Thin useEffect wrapper: subscribes to the route's focus/blur pair and returns whether it's
+// currently focused, re-rendering on change - mirrors @react-navigation's useIsFocused. Starts
+// `false` rather than guessing from stack position: the route's emitter only fires 'focus' once
+// RNSScreen's native onAppear actually lands (stack.ts), so a screen genuinely isn't focused yet
+// at the instant it mounts - same async gap real native transitions have.
+
+import { useEffect, useState } from 'react';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { useRequiredNavigationContext } from '../navigation-context';
+
+export function useIsFocused(): boolean {
+  const context = useRequiredNavigationContext('useIsFocused');
+  const { emitter } = context;
+  const [isFocused, setIsFocused] = useState(false);
+
+  useEffect(() => {
+    const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, () => setIsFocused(true));
+    const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, () => setIsFocused(false));
+    return () => {
+      unsubscribeFocus();
+      unsubscribeBlur();
+    };
+  }, [emitter]);
+
+  return isFocused;
+}

package/src/react/hooks/use-navigation-state/index.ts

@@ -0,0 +1,47 @@
+// Thin selector wrapper: subscribes to the router's `state` broadcast (stack.ts's render loop
+// re-emits the full INavigatorState to every route's emitter after each commit) and returns
+// `selector(state)`, re-rendering only when the emitted state changes - mirrors
+// @react-navigation's useNavigationState. The reducer/dispatch machinery it selects over lives in
+// core/navigator-state.ts; this hook only wires the subscription + local re-render.
+//
+// Seeded from a single-route snapshot ({ routes: [route] }) rather than left undefined: the real
+// broadcast lands a tick later (post-commit useEffect), so a selector reading e.g.
+// `state.routes.at(-1)?.name` still resolves correctly on first paint for the common single-route
+// case, closing the same async gap useIsFocused documents.
+//
+// Live updates currently only arrive under <Stack> - it's the only navigator that emits
+// NAVIGATION_EVENT_STATE (its post-commit useEffect in stack.ts); <Tab>/<Drawer> don't broadcast
+// it, so under those this hook silently stays on its initial snapshot.
+
+import { useEffect, useRef, useState } from 'react';
+import type { INavigatorState } from '../../../core';
+import { NAVIGATION_EVENT_STATE, isRecord } from '../../../core';
+import { useRequiredNavigationContext } from '../../navigation-context';
+
+export function useNavigationState<TResult>(
+  selector: (state: INavigatorState) => TResult,
+): TResult {
+  const context = useRequiredNavigationContext('useNavigationState');
+  const { route, emitter } = context;
+  const [result, setResult] = useState(() => selector({ routes: [route] }));
+
+  // selector is typically an inline arrow at the call site (`useNavigationState(s => ...)`), a
+  // fresh identity every render - read through a ref so the effect below doesn't need `selector`
+  // in its deps, and doesn't unsubscribe/resubscribe on every render because of it (the same trap
+  // useFocusEffect's own comment documents for its `effect` argument).
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  useEffect(() => {
+    return emitter.addListener(NAVIGATION_EVENT_STATE, (state: unknown) => {
+      if (!isNavigatorState(state)) return;
+      setResult(selectorRef.current(state));
+    });
+  }, [emitter]);
+
+  return result;
+}
+
+function isNavigatorState(value: unknown): value is INavigatorState {
+  return isRecord(value) && Array.isArray(value.routes);
+}

package/src/react/hooks/use-navigation-state/use-navigation-state.test.ts

@@ -0,0 +1,85 @@
+// Co-located React-driven test (ADR 0025) for useNavigationState's subscription lifecycle.
+// hooks.test.tsx already exercises the hook's OBSERVABLE behavior (state.routes.length tracking a
+// real Stack push/pop) - this file targets a narrower, easy-to-miss regression: the call site's
+// selector is typically an inline arrow (`useNavigationState(s => s.routes.length)`), a fresh
+// function identity every render, so an effect keyed on `selector` unsubscribes/resubscribes on
+// every parent re-render instead of once. A fake emitter (rather than a real Stack) isolates
+// exactly that churn, independent of any router/native-screen machinery.
+
+import { act, createElement, useReducer } from 'react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import type { INavigationEmitter, INavigationEventListener, INavigatorState } from '../../../core';
+import { NavigationContext } from '../../navigation-context';
+import type { INavigationContextValue } from '../../navigation-context';
+import { useNavigationState } from './index';
+
+const ROOT_TAG = 833;
+
+const fabric = installFabric();
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useNavigationState subscription lifecycle', () => {
+  it('subscribes to the emitter once, not once per render, across a fresh inline selector', () => {
+    let subscribeCount = 0;
+    let unsubscribeCount = 0;
+    const listeners = new Set<INavigationEventListener>();
+    const fakeEmitter: INavigationEmitter = {
+      emit: () => {},
+      addListener: (_event, listener) => {
+        subscribeCount += 1;
+        listeners.add(listener);
+        return () => {
+          unsubscribeCount += 1;
+          listeners.delete(listener);
+        };
+      },
+    };
+    const contextValue: INavigationContextValue = {
+      route: { key: 'home-1', name: 'Home', params: undefined },
+      navigation: {
+        push: () => {},
+        pop: () => {},
+        popToTop: () => {},
+        popTo: () => {},
+        replace: () => {},
+        setParams: () => {},
+        reset: (_state: INavigatorState) => {},
+        canGoBack: () => false,
+      },
+      emitter: fakeEmitter,
+    };
+
+    let triggerRerender: (() => void) | undefined;
+
+    function Child(): null {
+      // Deliberately a fresh inline selector on every render - the exact call-site shape
+      // (`useNavigationState(s => ...)`) that causes the churn this test guards against.
+      useNavigationState(state => state.routes.length);
+      return null;
+    }
+
+    function Harness(): ReturnType<typeof createElement> {
+      const [, dispatch] = useReducer((n: number) => n + 1, 0);
+      triggerRerender = () => dispatch();
+      return createElement(
+        NavigationContext.Provider,
+        { value: contextValue },
+        createElement(Child),
+      );
+    }
+
+    act(() => mount(ROOT_TAG, createElement(Harness)));
+    expect(subscribeCount).toBe(1);
+
+    act(() => triggerRerender?.());
+    act(() => triggerRerender?.());
+    act(() => triggerRerender?.());
+
+    expect(subscribeCount).toBe(1);
+    expect(unsubscribeCount).toBe(0);
+  });
+});

package/src/react/hooks/use-navigation.ts

@@ -0,0 +1,36 @@
+// Thin lifecycle wrapper: returns the current screen's navigator handle (push/pop/replace/... for a
+// Stack screen, jumpTo/setParams for a Tab screen, openDrawer/... for a Drawer screen) plus
+// addListener bound to that route's own emitter - mirrors @react-navigation's
+// `navigation.addListener('focus', cb)` surface. All pub/sub logic lives in
+// ../../core/navigation-events; this hook only reads NavigationContext and binds identity.
+
+import { useMemo } from 'react';
+import type { INavigationEventListener, INavigationEventName } from '../../core';
+import { useRequiredNavigationContext } from '../navigation-context';
+import type { IAnyNavigatorHandle } from '../navigation-context';
+
+export type INavigationHandle = IAnyNavigatorHandle & {
+  addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+  // Walks exactly ONE hop up navigation-context.ts's `parent` chain to the enclosing navigator's
+  // handle - e.g. a Tab screen nested inside a Stack screen calling getParent() to push a new
+  // Stack route. Callers narrow the union themselves ('push' in parent, etc.). Deliberately NOT
+  // react-navigation's getParent(id) (named/targeted ancestor lookup) or a target-based dispatch
+  // to a specific nested navigator by name - plain immediate-parent walking is v1 scope; multi-hop
+  // ancestry would need each returned handle to carry its own getParent, which the plain
+  // per-navigator handle types (INavigatorHandle/ITabNavigatorHandle/IDrawerNavigatorHandle) don't.
+  getParent: () => IAnyNavigatorHandle | undefined;
+};
+
+export function useNavigation(): INavigationHandle {
+  const context = useRequiredNavigationContext('useNavigation');
+  const { navigation, emitter, parent } = context;
+
+  return useMemo(
+    () => ({
+      ...navigation,
+      addListener: emitter.addListener,
+      getParent: () => parent?.navigation,
+    }),
+    [navigation, emitter, parent],
+  );
+}

package/src/react/hooks/use-route.ts

@@ -0,0 +1,11 @@
+// Thin lifecycle wrapper: returns the current screen's IRoute from NavigationContext - mirrors
+// @react-navigation's useRoute. Zero logic of its own; the route object itself is built by
+// stack.ts's render loop from the core reducer's state.
+
+import type { IRoute } from '../../core';
+import { useRequiredNavigationContext } from '../navigation-context';
+
+export function useRoute(): IRoute<unknown> {
+  const context = useRequiredNavigationContext('useRoute');
+  return context.route;
+}

package/src/react/hooks/use-stack-navigation.ts

@@ -0,0 +1,23 @@
+// useNavigation() returns a union (IAnyNavigatorHandle) since it doesn't know which navigator
+// mounted the calling component. When a component genuinely knows it only ever renders under a
+// Stack (the common case for anything nested a few levels below a Stack screen), this hook
+// narrows that union ONCE, here, so call sites never write their own 'push' in navigation check.
+
+import type { INavigatorHandle } from '../../core';
+import { isStackNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type IStackNavigationHandle = INavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useStackNavigation(): IStackNavigationHandle {
+  const navigation = useNavigation();
+  if (!isStackNavigatorHandle(navigation)) {
+    throw new Error(
+      'useStackNavigation() was called from a component whose nearest navigator is not a Stack. ' +
+        'Use useNavigation() instead if this component can render under more than one navigator kind.',
+    );
+  }
+  return navigation;
+}

package/src/react/hooks/use-tab-navigation.ts

@@ -0,0 +1,21 @@
+// Twin of use-stack-navigation.ts, narrowing to a Tab handle instead. See that file's header for
+// why this exists: it hides the union-narrowing guard inside the library instead of every call site.
+
+import type { ITabNavigatorHandle } from '../../core';
+import { isTabNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type ITabNavigationHandle = ITabNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useTabNavigation(): ITabNavigationHandle {
+  const navigation = useNavigation();
+  if (!isTabNavigatorHandle(navigation)) {
+    throw new Error(
+      'useTabNavigation() was called from a component whose nearest navigator is not a Tab. ' +
+        'Use useNavigation() instead if this component can render under more than one navigator kind.',
+    );
+  }
+  return navigation;
+}

package/src/react/hooks/use-typed-navigation.test.tsx

@@ -0,0 +1,187 @@
+// Co-located React-driven test (ADR 0025) for useStackNavigation/useTabNavigation/
+// useDrawerNavigation - the narrowed twins of useNavigation() that hide the union guard.
+
+import { act, createElement, createRef } from 'react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount, setNativeViewConfigSource, Dimensions } from '@symbiote-native/react';
+import type { INativeViewConfig } from '@symbiote-native/engine';
+import { installFabric } from '@symbiote-native/test-utils';
+import { Stack } from '../stack';
+import type { INavigatorHandle } from '../stack';
+import { Tab } from '../tabs';
+import { Drawer } from '../drawer';
+import { useDrawerNavigation, useStackNavigation, useTabNavigation } from './index';
+
+const ROOT_TAG = 613;
+const SCREEN_VIEW = 'RNSScreen';
+const STACK_VIEW = 'RNSScreenStack';
+
+const VIEW_CONFIGS: Record<string, INativeViewConfig> = {
+  [SCREEN_VIEW]: {
+    directEventTypes: {
+      topAppear: { registrationName: 'onAppear' },
+      topDisappear: { registrationName: 'onDisappear' },
+      topWillAppear: { registrationName: 'onWillAppear' },
+      topWillDisappear: { registrationName: 'onWillDisappear' },
+      topDismissed: { registrationName: 'onDismissed' },
+      topHeaderBackButtonClicked: { registrationName: 'onHeaderBackButtonClicked' },
+    },
+    validAttributes: {
+      screenId: true,
+      activityState: true,
+      gestureEnabled: true,
+      stackAnimation: true,
+      stackPresentation: true,
+      transitionDuration: true,
+    },
+  },
+  [STACK_VIEW]: {
+    directEventTypes: { topFinishTransitioning: { registrationName: 'onFinishTransitioning' } },
+    validAttributes: {},
+  },
+};
+
+// Drawer reads the screen width off useWindowDimensions() to resolve its swipe edge zone;
+// headless has no DeviceInfo native module, so seed a concrete width once (Dimensions is a
+// module-level singleton) - same fixture as drawer.test.tsx.
+Dimensions.set({ window: { width: 375, height: 812, scale: 1, fontScale: 1 } });
+
+const fabric = installFabric();
+setNativeViewConfigSource(name => VIEW_CONFIGS[name]);
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function textScreen(label: string) {
+  return () => createElement('symbiote-text', {}, label);
+}
+
+describe('useStackNavigation', () => {
+  it('returns a concretely-typed Stack handle with push, no narrowing needed', () => {
+    let canPush = false;
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      const navigation = useStackNavigation();
+      canPush = typeof navigation.push === 'function';
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    const ref = createRef<INavigatorHandle>();
+    mount(
+      ROOT_TAG,
+      createElement(
+        Stack,
+        { ref, initialRouteName: 'Home' },
+        createElement(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+        createElement(Stack.Screen, { name: 'Details', component: textScreen('details') }),
+      ),
+    );
+    expect(canPush).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Tab, not a Stack', () => {
+    function TrackedHomeTab(): ReturnType<typeof createElement> {
+      useStackNavigation();
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    expect(() => {
+      act(() => {
+        mount(
+          ROOT_TAG,
+          createElement(
+            Tab,
+            { initialRouteName: 'Home' },
+            createElement(Tab.Screen, { name: 'Home', component: TrackedHomeTab }),
+            createElement(Tab.Screen, { name: 'Search', component: textScreen('search') }),
+          ),
+        );
+      });
+    }).toThrow(/nearest navigator is not a Stack/);
+  });
+});
+
+describe('useTabNavigation', () => {
+  it('returns a concretely-typed Tab handle with jumpTo, no narrowing needed', () => {
+    let canJumpTo = false;
+    function TrackedHomeTab(): ReturnType<typeof createElement> {
+      const navigation = useTabNavigation();
+      canJumpTo = typeof navigation.jumpTo === 'function';
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: TrackedHomeTab }),
+        createElement(Tab.Screen, { name: 'Search', component: textScreen('search') }),
+      ),
+    );
+    expect(canJumpTo).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Stack, not a Tab', () => {
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      useTabNavigation();
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    expect(() => {
+      act(() => {
+        mount(
+          ROOT_TAG,
+          createElement(
+            Stack,
+            { initialRouteName: 'Home' },
+            createElement(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            createElement(Stack.Screen, { name: 'Details', component: textScreen('details') }),
+          ),
+        );
+      });
+    }).toThrow(/nearest navigator is not a Tab/);
+  });
+});
+
+describe('useDrawerNavigation', () => {
+  it('returns a concretely-typed Drawer handle with openDrawer, no narrowing needed', () => {
+    let canOpenDrawer = false;
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      const navigation = useDrawerNavigation();
+      canOpenDrawer = typeof navigation.openDrawer === 'function';
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    mount(
+      ROOT_TAG,
+      createElement(
+        Drawer,
+        { initialRouteName: 'Home' },
+        createElement(Drawer.Screen, { name: 'Home', component: TrackedHomeScreen }),
+        createElement(Drawer.Screen, { name: 'Profile', component: textScreen('profile') }),
+      ),
+    );
+    expect(canOpenDrawer).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Stack, not a Drawer', () => {
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      useDrawerNavigation();
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    expect(() => {
+      act(() => {
+        mount(
+          ROOT_TAG,
+          createElement(
+            Stack,
+            { initialRouteName: 'Home' },
+            createElement(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            createElement(Stack.Screen, { name: 'Details', component: textScreen('details') }),
+          ),
+        );
+      });
+    }).toThrow(/nearest navigator is not a Drawer/);
+  });
+});

package/src/react/index.ts

@@ -0,0 +1,52 @@
+// @symbiote-native/navigation/react: the React native-stack navigator over react-native-screens'
+// native view primitives. Importing this barrel first registers the native views' ViewConfigs
+// (../register, a side-effect import of the three codegen specs - never react-native-screens' own
+// React components), then exposes Stack (with Stack.Screen attached) and the navigator handle.
+
+import '../register';
+
+export { Stack } from './stack';
+export type { INavigatorHandle, IStackProps } from './stack';
+export { Screen } from './screen';
+export type { IScreenOptionsArgs, IScreenOptionsResolver, IScreenProps } from './screen';
+export type { IScreenOptions, IStackAnimation, IStackPresentation } from '../core';
+
+export { useNavigation, useRoute, useIsFocused, useFocusEffect, useNavigationState } from './hooks';
+export type { INavigationHandle } from './hooks';
+export { useStackNavigation, useTabNavigation, useDrawerNavigation } from './hooks';
+export type {
+  IStackNavigationHandle,
+  ITabNavigationHandle,
+  IDrawerNavigationHandle,
+} from './hooks';
+export { NavigationContext } from './navigation-context';
+export type { INavigationContextValue, IAnyNavigatorHandle } from './navigation-context';
+
+export { useLinkingIntegration } from './linking';
+export type { ILinkingConfig, IScreenLinkingConfig } from '../core';
+
+// Tab: the bottom-tabs navigator, a PURE-JS UI (no react-native-screens views involved, so no
+// extra ViewConfig registration is needed beyond the ../register import above).
+export { Tab } from './tabs';
+export type { ITabNavigatorHandle, ITabProps } from './tabs';
+export { TabScreen } from './tab-screen';
+export type {
+  ITabScreenOptionsArgs,
+  ITabScreenOptionsResolver,
+  ITabScreenProps,
+} from './tab-screen';
+export type { ITabOptions, ITabBarIcon } from '../core';
+
+// Drawer: the swipeable drawer navigator, a PURE-JS UI (PanResponder + Animated, no
+// react-native-screens views involved, so no extra ViewConfig registration is needed beyond the
+// ../register import above). See react/drawer.ts's header for the feasibility note re:
+// react-native-gesture-handler / react-native-reanimated parity gaps.
+export { Drawer } from './drawer';
+export type { IDrawerNavigatorHandle, IDrawerProps, IDrawerDescriptorMap } from './drawer';
+export { DrawerScreen } from './drawer-screen';
+export type {
+  IDrawerScreenOptionsArgs,
+  IDrawerScreenOptionsResolver,
+  IDrawerScreenProps,
+} from './drawer-screen';
+export type { IDrawerOptions, IDrawerScreenOptions, IDrawerType, IDrawerPosition } from '../core';

package/src/react/linking.ts

@@ -0,0 +1,59 @@
+// useLinkingIntegration: wires the framework-agnostic linking config (../core's
+// resolveRouteFromUrl) onto an existing Stack ref's INavigatorHandle. Deliberately NOT called
+// from inside stack.ts - app code owns the wiring (a <Stack ref={...}> plus this hook alongside
+// it), the same top-level-prop shape @react-navigation keeps `linking` in on NavigationContainer
+// rather than baking it into the router itself.
+
+import { useEffect, useRef } from 'react';
+import { Linking, dlog } from '@symbiote-native/engine';
+import type { IUrlEvent } from '@symbiote-native/engine';
+import { resolveRouteFromUrl } from '../core';
+import type { ILinkingConfig } from '../core';
+import type { INavigatorHandle } from '../core';
+
+export function useLinkingIntegration(
+  config: ILinkingConfig,
+  navigatorHandle: INavigatorHandle,
+): void {
+  // Refs, not effect deps: `navigatorHandle` is re-created by Stack on every push/pop
+  // (see stack.ts's useMemo deps including `state.routes.length`), so depending on it directly
+  // would resubscribe on every navigation instead of once on mount.
+  const configRef = useRef(config);
+  configRef.current = config;
+  const handleRef = useRef(navigatorHandle);
+  handleRef.current = navigatorHandle;
+
+  useEffect(() => {
+    function applyRoute(url: string, dispatch: (name: string, params?: unknown) => void): void {
+      const route = resolveRouteFromUrl(configRef.current, url);
+      if (route === null) {
+        dlog(`useLinkingIntegration: no route resolved for "${url}"`);
+        return;
+      }
+      dispatch(route.name, route.params);
+    }
+
+    let cancelled = false;
+
+    Linking.getInitialURL()
+      .then(url => {
+        if (cancelled || url === null) return;
+        dlog(`useLinkingIntegration: initial URL "${url}"`);
+        applyRoute(url, handleRef.current.replace);
+      })
+      .catch((error: unknown) => {
+        dlog(`useLinkingIntegration: getInitialURL failed: ${String(error)}`);
+      });
+
+    const subscription = Linking.addEventListener('url', (event: IUrlEvent) => {
+      dlog(`useLinkingIntegration: url event "${event.url}"`);
+      applyRoute(event.url, handleRef.current.push);
+    });
+
+    return () => {
+      cancelled = true;
+      subscription.remove();
+    };
+    // Mount-once: freshness of config/navigatorHandle is read through the refs above.
+  }, []);
+}

package/src/react/navigation-context.ts

@@ -0,0 +1,40 @@
+// The lifecycle half of the framework-agnostic emitter (../core/navigation-events): a plain
+// React Context so a screen's subtree can read its own route, navigator handle, and per-route
+// emitter without prop-drilling - the same role @react-navigation's NavigationContext /
+// NavigationRouteContext play, collapsed into one context since a symbiote screen only ever needs
+// its OWN route (no per-navigator param-list generics in v1 scope - see screen.ts). Provided
+// per-screen by each of stack.ts/tabs.ts/drawer.ts's render loop, consumed by the hooks in
+// ./hooks. `parent` threads the ambient context a navigator read on ITS OWN mount (undefined at
+// the root) into the value it provides to its own screens, forming a linked list - this is what
+// lets a screen nested inside e.g. a Stack-screen-renders-a-Tab composition reach the enclosing
+// Stack via useNavigation().getParent().
+
+import { createContext, useContext } from 'react';
+import type { INavigationEmitter, IRoute, IAnyNavigatorHandle } from '../core';
+export type { IAnyNavigatorHandle } from '../core';
+
+// A nested navigator (e.g. a Tab rendered as a Stack screen's content) means a screen's OWN
+// navigation prop and its PARENT's handle can be different navigator kinds, so the Context
+// value's `navigation` field must stay a union rather than Stack-specific. Consumers narrow it
+// themselves (e.g. `'push' in handle` picks out a Stack handle) - no `as` casts.
+export type INavigationContextValue = {
+  route: IRoute<unknown>;
+  navigation: IAnyNavigatorHandle;
+  emitter: INavigationEmitter;
+  parent?: INavigationContextValue;
+};
+
+export const NavigationContext = createContext<INavigationContextValue | undefined>(undefined);
+
+// Every hook in ./hooks needs the same `useContext(NavigationContext)` + missing-provider throw,
+// so it's co-located here instead of repeated per hook. `hookName` keeps each hook's own name in
+// the thrown message.
+export function useRequiredNavigationContext(hookName: string): INavigationContextValue {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    throw new Error(
+      `${hookName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`,
+    );
+  }
+  return context;
+}