@symbiote-native/navigation 1.0.0

package/src/vue/composables/composables.test.ts

@@ -0,0 +1,221 @@
+// Co-located Vue-driven test, the Vue twin of react/hooks/hooks.test.tsx. Mirrors
+// ../stack.test.ts's fixture (an injected codegen-shaped RNSScreen ViewConfig exposing
+// onAppear/onDisappear/onWillAppear/onWillDisappear) and drives the same native events stack.ts
+// wires to emit 'focus'/'blur', proving the composables react to the real RNS lifecycle, not to a
+// synthetic shortcut.
+
+import { defineComponent, h, ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount, setNativeViewConfigSource } from '@symbiote-native/vue';
+import type { INativeViewConfig } from '@symbiote-native/engine';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+import { Stack } from '../stack';
+import type { INavigatorHandle } from '../stack';
+import { useFocusEffect, useIsFocused, useNavigation, useNavigationState, useRoute } from './index';
+
+const ROOT_TAG = 4513;
+const SCREEN_VIEW = 'RNSScreen';
+const STACK_VIEW = 'RNSScreenStack';
+const HEADER_CONFIG_VIEW = 'RNSScreenStackHeaderConfig';
+
+function directEvent(registrationName: string) {
+  return { registrationName };
+}
+
+const VIEW_CONFIGS: Record<string, INativeViewConfig> = {
+  [SCREEN_VIEW]: {
+    directEventTypes: {
+      topAppear: directEvent('onAppear'),
+      topDisappear: directEvent('onDisappear'),
+      topWillAppear: directEvent('onWillAppear'),
+      topWillDisappear: directEvent('onWillDisappear'),
+      topDismissed: directEvent('onDismissed'),
+      topHeaderBackButtonClicked: directEvent('onHeaderBackButtonClicked'),
+    },
+    validAttributes: {
+      screenId: true,
+      activityState: true,
+      gestureEnabled: true,
+      stackAnimation: true,
+      stackPresentation: true,
+      transitionDuration: true,
+    },
+  },
+  [STACK_VIEW]: {
+    directEventTypes: { topFinishTransitioning: directEvent('onFinishTransitioning') },
+    validAttributes: {},
+  },
+  [HEADER_CONFIG_VIEW]: {
+    directEventTypes: { topPressHeaderBarButtonItem: directEvent('onPressHeaderBarButtonItem') },
+    validAttributes: { title: true, hidden: true, backTitle: true, backTitleVisible: true },
+  },
+};
+
+const fabric = installFabric();
+setNativeViewConfigSource(name => VIEW_CONFIGS[name]);
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function screenNodes(): IFakeNode[] {
+  const found: IFakeNode[] = [];
+  const collect = (nodes: readonly IFakeNode[]): void => {
+    for (const node of nodes) {
+      if (node.viewName === SCREEN_VIEW) found.push(node);
+      collect(node.children);
+    }
+  };
+  collect(fabric.committed);
+  return found;
+}
+
+function HomeScreen() {
+  return h('symbiote-text', {}, 'home');
+}
+
+function DetailsScreen() {
+  return h('symbiote-text', {}, 'details');
+}
+
+describe('navigation composables', () => {
+  it("useIsFocused reflects the route's native appear/disappear events", async () => {
+    let latestIsFocused: boolean | undefined;
+    // Plain functions used as `component:` are stateless functional components - Vue calls them
+    // fresh on every render and treats their return value as vnodes directly, NOT as a "setup
+    // returns a render fn" component. A screen calling a composable needs a real setup-based
+    // component, hence defineComponent here instead of a bare function.
+    const TrackedHomeScreen = defineComponent(() => {
+      const isFocused = useIsFocused();
+      return () => {
+        latestIsFocused = isFocused.value;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { initialRouteName: 'Home' }, () => [
+            h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Stack.Screen, { name: 'Details', component: DetailsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(latestIsFocused).toBe(false);
+
+    const home = screenNodes()[0];
+    fabric.fireEvent(home.instanceHandle, 'topAppear', {});
+    await tick();
+    expect(latestIsFocused).toBe(true);
+
+    fabric.fireEvent(home.instanceHandle, 'topDisappear', {});
+    await tick();
+    expect(latestIsFocused).toBe(false);
+  });
+
+  it('useFocusEffect runs its effect on focus and its cleanup on blur', async () => {
+    const events: string[] = [];
+    const TrackedHomeScreen = defineComponent(() => {
+      useFocusEffect(() => {
+        events.push('effect');
+        return () => events.push('cleanup');
+      });
+      return () => h('symbiote-text', {}, 'home');
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { initialRouteName: 'Home' }, () => [
+            h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Stack.Screen, { name: 'Details', component: DetailsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(events).toEqual([]);
+
+    const home = screenNodes()[0];
+    fabric.fireEvent(home.instanceHandle, 'topAppear', {});
+    await tick();
+    expect(events).toEqual(['effect']);
+
+    fabric.fireEvent(home.instanceHandle, 'topDisappear', {});
+    await tick();
+    expect(events).toEqual(['effect', 'cleanup']);
+  });
+
+  it('useNavigation().addListener fires on focus and useRoute exposes name/params', async () => {
+    let capturedName: string | undefined;
+    let capturedParams: unknown;
+    const focusEvents: string[] = [];
+
+    const TrackedDetailsScreen = defineComponent(() => {
+      const navigation = useNavigation();
+      const route = useRoute();
+      capturedName = route.value.name;
+      capturedParams = route.value.params;
+      navigation.value.addListener('focus', () => focusEvents.push('focus'));
+      return () => h('symbiote-text', {}, 'details');
+    });
+
+    const handleRef = ref<INavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Stack.Screen, { name: 'Home', component: HomeScreen }),
+            h(Stack.Screen, { name: 'Details', component: TrackedDetailsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    handleRef.value?.push('Details', { id: 7 });
+    await tick();
+    expect(capturedName).toBe('Details');
+    expect(capturedParams).toEqual({ id: 7 });
+
+    const details = screenNodes()[1];
+    fabric.fireEvent(details.instanceHandle, 'topAppear', {});
+    await tick();
+    expect(focusEvents).toEqual(['focus']);
+  });
+
+  it('useNavigationState reflects the route stack growing across a push', async () => {
+    let routeCount: number | undefined;
+    const TrackedHomeScreen = defineComponent(() => {
+      const count = useNavigationState(state => state.routes.length);
+      return () => {
+        routeCount = count.value;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    const handleRef = ref<INavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Stack.Screen, { name: 'Details', component: DetailsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(routeCount).toBe(1);
+
+    handleRef.value?.push('Details');
+    await tick();
+    expect(routeCount).toBe(2);
+
+    handleRef.value?.pop();
+    await tick();
+    expect(routeCount).toBe(1);
+  });
+});

package/src/vue/composables/index.ts

@@ -0,0 +1,12 @@
+export { useNavigation } from './use-navigation';
+export type { INavigationHandle } from './use-navigation';
+export { useStackNavigation } from './use-stack-navigation';
+export type { IStackNavigationHandle } from './use-stack-navigation';
+export { useTabNavigation } from './use-tab-navigation';
+export type { ITabNavigationHandle } from './use-tab-navigation';
+export { useDrawerNavigation } from './use-drawer-navigation';
+export type { IDrawerNavigationHandle } from './use-drawer-navigation';
+export { useRoute } from './use-route';
+export { useIsFocused } from './use-is-focused';
+export { useFocusEffect } from './use-focus-effect';
+export { useNavigationState } from './use-navigation-state';

package/src/vue/composables/use-drawer-navigation.ts

@@ -0,0 +1,25 @@
+// Twin of use-stack-navigation.ts, narrowing to a Drawer handle instead.
+
+import { computed } from '@vue/runtime-core';
+import type { ComputedRef } from '@vue/runtime-core';
+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(): ComputedRef<IDrawerNavigationHandle> {
+  const navigation = useNavigation();
+  return computed(() => {
+    const value = navigation.value;
+    if (!isDrawerNavigatorHandle(value)) {
+      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 value;
+  });
+}

package/src/vue/composables/use-focus-effect.ts

@@ -0,0 +1,37 @@
+// Mirrors @react-navigation's useFocusEffect; Vue twin of react/hooks/use-focus-effect.ts.
+// React's version requires memoizing `effect` (useCallback) since a new identity re-subscribes
+// it like any other useEffect dependency. That doesn't apply here: Vue's setup() runs once, so
+// `effect` is read once at composable-call time and closed over directly by onMounted/onUnmounted -
+// there's no dependency array to go stale.
+
+import { onMounted, onUnmounted } from '@vue/runtime-core';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useFocusEffect(effect: () => (() => void) | void): void {
+  const scope = requireNavigationScope('useFocusEffect');
+
+  let cleanup: (() => void) | void;
+  let unsubscribeFocus: (() => void) | undefined;
+  let unsubscribeBlur: (() => void) | undefined;
+
+  const runEffect = (): void => {
+    cleanup = effect();
+  };
+  const runCleanup = (): void => {
+    cleanup?.();
+    cleanup = undefined;
+  };
+
+  onMounted(() => {
+    const { emitter } = scope.value;
+    unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, runEffect);
+    unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, runCleanup);
+  });
+
+  onUnmounted(() => {
+    unsubscribeFocus?.();
+    unsubscribeBlur?.();
+    runCleanup();
+  });
+}

package/src/vue/composables/use-is-focused.ts

@@ -0,0 +1,34 @@
+// Mirrors @react-navigation's useIsFocused; Vue twin of react/hooks/use-is-focused.ts.
+// Starts `false` rather than guessing from stack position: the route's emitter only fires 'focus'
+// once RNSScreen's native onAppear lands (stack.ts) or the screen mounts focused (tabs.ts/drawer.ts) -
+// a screen genuinely isn't focused at the instant it mounts, the same async gap real native
+// transitions have.
+
+import { onMounted, onUnmounted, ref } from '@vue/runtime-core';
+import type { Ref } from '@vue/runtime-core';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useIsFocused(): Ref<boolean> {
+  const scope = requireNavigationScope('useIsFocused');
+  const isFocused = ref(false);
+  let unsubscribeFocus: (() => void) | undefined;
+  let unsubscribeBlur: (() => void) | undefined;
+
+  onMounted(() => {
+    const { emitter } = scope.value;
+    unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, () => {
+      isFocused.value = true;
+    });
+    unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, () => {
+      isFocused.value = false;
+    });
+  });
+
+  onUnmounted(() => {
+    unsubscribeFocus?.();
+    unsubscribeBlur?.();
+  });
+
+  return isFocused;
+}

package/src/vue/composables/use-navigation-state.ts

@@ -0,0 +1,38 @@
+// Mirrors @react-navigation's useNavigationState; Vue twin of react/hooks/use-navigation-state.ts.
+// The reducer/dispatch machinery lives in core/navigator-state.ts (tab-router-state.ts /
+// drawer-router-state.ts for the other two navigators) - this composable only wires the
+// subscription to the `state` broadcast each render loop re-emits after commit.
+//
+// Seeded from a single-route snapshot ({ routes: [route] }) rather than left undefined: the real
+// broadcast lands after mount (Stack's render loop; tabs.ts/drawer.ts emit on focus), so a
+// selector reading e.g. `state.routes.at(-1)?.name` still resolves correctly on first paint for
+// the common single-route case - the same async gap useIsFocused documents.
+
+import { onMounted, onUnmounted, shallowRef } from '@vue/runtime-core';
+import type { ShallowRef } from '@vue/runtime-core';
+import type { INavigatorState } from '../../core';
+import { NAVIGATION_EVENT_STATE, isRecord } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+function isNavigatorState(value: unknown): value is INavigatorState {
+  return isRecord(value) && Array.isArray(value.routes);
+}
+
+export function useNavigationState<TResult>(
+  selector: (state: INavigatorState) => TResult,
+): ShallowRef<TResult> {
+  const scope = requireNavigationScope('useNavigationState');
+  const result = shallowRef<TResult>(selector({ routes: [scope.value.route] }));
+  let unsubscribe: (() => void) | undefined;
+
+  onMounted(() => {
+    unsubscribe = scope.value.emitter.addListener(NAVIGATION_EVENT_STATE, (state: unknown) => {
+      if (!isNavigatorState(state)) return;
+      result.value = selector(state);
+    });
+  });
+
+  onUnmounted(() => unsubscribe?.());
+
+  return result;
+}

package/src/vue/composables/use-navigation.ts

@@ -0,0 +1,30 @@
+// Mirrors @react-navigation's `navigation.addListener('focus', cb)` surface; Vue twin of
+// react/hooks/use-navigation.ts (returns a ComputedRef, Vue's reactive-primitive convention,
+// instead of a plain value). All pub/sub logic lives in ../../core/navigation-events - this
+// composable only reads the injected navigation scope and binds identity.
+
+import { computed } from '@vue/runtime-core';
+import type { ComputedRef } from '@vue/runtime-core';
+import type { INavigationEventListener, INavigationEventName } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+import type { IAnyNavigatorHandle } from '../navigation-context';
+
+export type INavigationHandle = IAnyNavigatorHandle & {
+  addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+  // Walks exactly ONE hop up the scope'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(): ComputedRef<INavigationHandle> {
+  const scope = requireNavigationScope('useNavigation');
+  return computed(() => {
+    const { navigation, emitter, parent } = scope.value;
+    return { ...navigation, addListener: emitter.addListener, getParent: () => parent?.navigation };
+  });
+}

package/src/vue/composables/use-route.ts

@@ -0,0 +1,13 @@
+// Mirrors @react-navigation's useRoute; Vue twin of react/hooks/use-route.ts (returns a
+// ComputedRef instead of a plain value). Zero logic of its own - the route object itself is built
+// by stack.ts's/tabs.ts's/drawer.ts's render loop from the shared core reducer's state.
+
+import { computed } from '@vue/runtime-core';
+import type { ComputedRef } from '@vue/runtime-core';
+import type { IRoute } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useRoute(): ComputedRef<IRoute<unknown>> {
+  const scope = requireNavigationScope('useRoute');
+  return computed(() => scope.value.route);
+}

package/src/vue/composables/use-stack-navigation.ts

@@ -0,0 +1,28 @@
+// 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, this composable narrows that union ONCE, here, so call sites never write their own
+// 'push' in navigation check. Vue twin of react/hooks/use-stack-navigation.ts.
+
+import { computed } from '@vue/runtime-core';
+import type { ComputedRef } from '@vue/runtime-core';
+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(): ComputedRef<IStackNavigationHandle> {
+  const navigation = useNavigation();
+  return computed(() => {
+    const value = navigation.value;
+    if (!isStackNavigatorHandle(value)) {
+      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 value;
+  });
+}

package/src/vue/composables/use-tab-navigation.ts

@@ -0,0 +1,25 @@
+// Twin of use-stack-navigation.ts, narrowing to a Tab handle instead.
+
+import { computed } from '@vue/runtime-core';
+import type { ComputedRef } from '@vue/runtime-core';
+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(): ComputedRef<ITabNavigationHandle> {
+  const navigation = useNavigation();
+  return computed(() => {
+    const value = navigation.value;
+    if (!isTabNavigatorHandle(value)) {
+      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 value;
+  });
+}

package/src/vue/composables/use-typed-navigation.test.ts

@@ -0,0 +1,205 @@
+// Co-located Vue-driven test for useStackNavigation/useTabNavigation/useDrawerNavigation - the
+// narrowed twins of useNavigation() that hide the union guard. Vue twin of
+// react/hooks/use-typed-navigation.test.tsx.
+
+import { defineComponent, h } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount, setNativeViewConfigSource, Dimensions } from '@symbiote-native/vue';
+import type { INativeViewConfig } from '@symbiote-native/engine';
+import { installFabric } from '@symbiote-native/test-utils';
+import { Stack } from '../stack';
+import { Tab } from '../tabs';
+import { Drawer } from '../drawer';
+import { useDrawerNavigation, useStackNavigation, useTabNavigation } from './index';
+
+const ROOT_TAG = 4613;
+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 - same fixture as
+// drawer.test.ts.
+Dimensions.set({ window: { width: 375, height: 812, scale: 1, fontScale: 1 } });
+
+const fabric = installFabric();
+setNativeViewConfigSource(name => VIEW_CONFIGS[name]);
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function textScreen(label: string) {
+  return () => h('symbiote-text', {}, label);
+}
+
+describe('useStackNavigation', () => {
+  it('returns a concretely-typed Stack handle with push, no narrowing needed', async () => {
+    let canPush = false;
+    const TrackedHomeScreen = defineComponent(() => {
+      const navigation = useStackNavigation();
+      return () => {
+        canPush = typeof navigation.value.push === 'function';
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { initialRouteName: 'Home' }, () => [
+            h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Stack.Screen, { name: 'Details', component: textScreen('details') }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(canPush).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Tab, not a Stack', () => {
+    const TrackedHomeTab = defineComponent(() => {
+      const navigation = useStackNavigation();
+      return () => {
+        void navigation.value;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    expect(() =>
+      mount(
+        ROOT_TAG,
+        defineComponent({
+          setup: () => () =>
+            h(Tab, { initialRouteName: 'Home' }, () => [
+              h(Tab.Screen, { name: 'Home', component: TrackedHomeTab }),
+              h(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', async () => {
+    let canJumpTo = false;
+    const TrackedHomeTab = defineComponent(() => {
+      const navigation = useTabNavigation();
+      return () => {
+        canJumpTo = typeof navigation.value.jumpTo === 'function';
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: TrackedHomeTab }),
+            h(Tab.Screen, { name: 'Search', component: textScreen('search') }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(canJumpTo).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Stack, not a Tab', () => {
+    const TrackedHomeScreen = defineComponent(() => {
+      const navigation = useTabNavigation();
+      return () => {
+        void navigation.value;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    expect(() =>
+      mount(
+        ROOT_TAG,
+        defineComponent({
+          setup: () => () =>
+            h(Stack, { initialRouteName: 'Home' }, () => [
+              h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+              h(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', async () => {
+    let canOpenDrawer = false;
+    const TrackedHomeScreen = defineComponent(() => {
+      const navigation = useDrawerNavigation();
+      return () => {
+        canOpenDrawer = typeof navigation.value.openDrawer === 'function';
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Drawer, { initialRouteName: 'Home' }, () => [
+            h(Drawer.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Drawer.Screen, { name: 'Profile', component: textScreen('profile') }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(canOpenDrawer).toBe(true);
+  });
+
+  it('throws when the nearest navigator is a Stack, not a Drawer', () => {
+    const TrackedHomeScreen = defineComponent(() => {
+      const navigation = useDrawerNavigation();
+      return () => {
+        void navigation.value;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+
+    expect(() =>
+      mount(
+        ROOT_TAG,
+        defineComponent({
+          setup: () => () =>
+            h(Stack, { initialRouteName: 'Home' }, () => [
+              h(Stack.Screen, { name: 'Home', component: TrackedHomeScreen }),
+              h(Stack.Screen, { name: 'Details', component: textScreen('details') }),
+            ]),
+        }),
+      ),
+    ).toThrow(/nearest navigator is not a Drawer/);
+  });
+});