@symbiote-native/navigation 2.0.3 → 2.2.0

package/src/svelte/fabric-tree.test-helper.ts

@@ -0,0 +1,95 @@
+// Live-tree walkers the smoke tests in this folder share.
+//
+// `fabric.find()` (from @symbiote-native/test-utils) walks the CREATION log, not the current
+// tree: a node it returns stays "found" forever, and its `props` reflect creation time rather
+// than what is currently committed (svelte-adapter-dom-shim skill §15). Every assertion about
+// what is on screen NOW - "this route is gone after a pop", "this header currently carries this
+// title" - therefore walks `fabric.appRoot()` instead.
+
+export type IFabricNode = {
+  viewName?: string;
+  props?: Record<string, unknown>;
+  children?: IFabricNode[];
+  instanceHandle?: unknown;
+};
+
+function isFabricNode(value: unknown): value is IFabricNode {
+  return typeof value === 'object' && value !== null;
+}
+
+export function walkLive(
+  root: unknown,
+  visit: (node: IFabricNode) => void,
+): void {
+  if (!isFabricNode(root)) return;
+  visit(root);
+  for (const child of root.children ?? []) walkLive(child, visit);
+}
+
+export function findAllLive(root: unknown, viewName: string): IFabricNode[] {
+  const found: IFabricNode[] = [];
+  walkLive(root, node => {
+    if (node.viewName === viewName) found.push(node);
+  });
+  return found;
+}
+
+export function findLive(
+  root: unknown,
+  viewName: string,
+): IFabricNode | undefined {
+  return findAllLive(root, viewName)[0];
+}
+
+export function countLive(root: unknown, viewName: string): number {
+  return findAllLive(root, viewName).length;
+}
+
+export function findLiveByTestId(
+  root: unknown,
+  testID: string,
+): IFabricNode | undefined {
+  let found: IFabricNode | undefined;
+  walkLive(root, node => {
+    if (found === undefined && node.props?.testID === testID) found = node;
+  });
+  return found;
+}
+
+const TEXT_CONTAINER_VIEW_NAMES = new Set(['RCTText', 'RCTVirtualText']);
+
+// Every raw text committed under a parent that cannot hold one - an invalid Fabric child.
+// The gap Svelte leaves between two sibling tags compiles to a ' ' text node, and the shim
+// drops it exactly when the parent takes no raw text (dom-shim/text.ts, svelte-adapter-dom-shim
+// §16b); inside an RCTText the same string is a real word separator and must survive. So the
+// parent, not the string, is what makes a raw text legal, and this returns the ones that are
+// not. Formatted `viewName > "text"` so a failure names the offender.
+export function rawTextsOutsideTextContainer(root: unknown): string[] {
+  const found: string[] = [];
+  const visit = (node: unknown, parent: IFabricNode | undefined): void => {
+    if (!isFabricNode(node)) return;
+    const parentName = parent?.viewName;
+    if (
+      node.viewName === 'RCTRawText' &&
+      (parentName === undefined || !TEXT_CONTAINER_VIEW_NAMES.has(parentName))
+    ) {
+      found.push(`${String(parentName)} > ${JSON.stringify(node.props?.text)}`);
+    }
+    for (const child of node.children ?? []) visit(child, node);
+  };
+  visit(root, undefined);
+  return found;
+}
+
+// A depth-indented `viewName` outline, for asserting the exact committed SHAPE (which is what
+// catches a stray whitespace text node, an extra wrapper, or a missing header).
+export function outline(root: unknown): string[] {
+  const lines: string[] = [];
+  const visit = (node: unknown, depth: number): void => {
+    if (!isFabricNode(node)) return;
+    lines.push(`${'  '.repeat(depth)}${String(node.viewName)}`);
+    for (const child of node.children ?? []) visit(child, depth + 1);
+  };
+  visit(root, 0);
+  return lines;
+}

package/src/svelte/index.ts

@@ -0,0 +1,83 @@
+// @symbiote-native/navigation/svelte: the Svelte 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 codegen specs - never
+// react-native-screens' own React components), then exposes Stack (with Stack.Screen attached)
+// and the navigator handle. Mirrors vue/index.ts's barrel shape.
+
+import '../register';
+
+export { Stack } from './stack';
+export type { INavigatorHandle, IStackProps } from './stack';
+export { default as Screen } from './screen.svelte';
+export type {
+  IScreenOptionsArgs,
+  IScreenOptionsResolver,
+  IScreenProps,
+  ISvelteScreenOptions,
+  ISvelteSearchBarOptions,
+} from './screen-props';
+export type {
+  IScreenOptions,
+  IStackAnimation,
+  IStackPresentation,
+} from '../core';
+
+export {
+  useNavigation,
+  useStackNavigation,
+  useTabNavigation,
+  useDrawerNavigation,
+  useRoute,
+  useIsFocused,
+  useFocusEffect,
+  useNavigationState,
+} from './runes';
+export type {
+  INavigationHandle,
+  IStackNavigationHandle,
+  ITabNavigationHandle,
+  IDrawerNavigationHandle,
+} from './runes';
+export type {
+  INavigationScopeValue,
+  IAnyNavigatorHandle,
+} from './navigation-context';
+
+export { useLinkingIntegration } from './linking.svelte';
+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 { default as TabScreen } from './tab-screen.svelte';
+export type {
+  ITabScreenOptionsArgs,
+  ITabScreenOptionsResolver,
+  ITabScreenProps,
+} from './tab-screen-props';
+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 drawer/index.svelte's header for the feasibility note re:
+// react-native-gesture-handler / react-native-reanimated parity gaps.
+export { Drawer } from './drawer';
+export type {
+  IDrawerContentSlotProps,
+  IDrawerNavigatorHandle,
+  IDrawerProps,
+  IDrawerDescriptorMap,
+} from './drawer';
+export { default as DrawerScreen } from './drawer-screen.svelte';
+export type {
+  IDrawerScreenOptionsArgs,
+  IDrawerScreenOptionsResolver,
+  IDrawerScreenProps,
+} from './drawer-screen-props';
+export type {
+  IDrawerOptions,
+  IDrawerScreenOptions,
+  IDrawerType,
+  IDrawerPosition,
+} from '../core';

package/src/svelte/linking.svelte.ts

@@ -0,0 +1,72 @@
+// useLinkingIntegration: wires the framework-agnostic linking config (../core's
+// resolveRouteFromUrl) onto an existing Stack's INavigatorHandle. Deliberately NOT called from
+// inside stack/index.svelte - app code owns the wiring, the same top-level-prop shape
+// @react-navigation keeps `linking` in on NavigationContainer rather than baking it into the
+// router itself.
+//
+// Svelte-shape difference from React and Vue: React's twin takes the RESOLVED
+// `navigatorHandle: INavigatorHandle` (a React hook re-runs on every render with the caller's
+// current value); Vue's takes the `Ref` object and reads `.value` inside onMounted. A Svelte
+// component's script runs exactly ONCE and its `bind:this` target is only assigned during mount,
+// so this takes a GETTER - the boxed-getter convention this adapter uses everywhere - and reads
+// it INSIDE the effect, i.e. after mount. The read is deliberately TRACKED (no `untrack`, unlike
+// the ./runes files): when the app declares its handle with `$state.raw`, the effect re-runs the
+// moment `bind:this` lands, so the wiring never depends on a mount-ordering guarantee at all.
+// Re-running is safe because the previous run's cleanup tears the subscription down first.
+//
+// `.svelte.ts`: `$effect` is only usable outside a component in a file with this extension.
+
+import { Linking, dlog } from '@symbiote-native/engine';
+import type { IEventSubscription, IUrlEvent } from '@symbiote-native/engine';
+import { resolveRouteFromUrl } from '../core';
+import type { ILinkingConfig, INavigatorHandle } from '../core';
+
+export function useLinkingIntegration(
+  config: ILinkingConfig,
+  getNavigatorHandle: () => INavigatorHandle | null,
+): void {
+  $effect(() => {
+    const handle = getNavigatorHandle();
+    if (handle === null) {
+      dlog('useLinkingIntegration: navigatorHandle is not available yet');
+      return;
+    }
+
+    let cancelled = false;
+
+    const applyRoute = (
+      url: string,
+      dispatch: (name: string, params?: unknown) => void,
+    ): void => {
+      const route = resolveRouteFromUrl(config, url);
+      if (route === null) {
+        dlog(`useLinkingIntegration: no route resolved for "${url}"`);
+        return;
+      }
+      dispatch(route.name, route.params);
+    };
+
+    Linking.getInitialURL()
+      .then(url => {
+        if (cancelled || url === null) return;
+        dlog(`useLinkingIntegration: initial URL "${url}"`);
+        applyRoute(url, handle.replace);
+      })
+      .catch((error: unknown) => {
+        dlog(`useLinkingIntegration: getInitialURL failed: ${String(error)}`);
+      });
+
+    const subscription: IEventSubscription = Linking.addEventListener(
+      'url',
+      (event: IUrlEvent) => {
+        dlog(`useLinkingIntegration: url event "${event.url}"`);
+        applyRoute(event.url, handle.push);
+      },
+    );
+
+    return () => {
+      cancelled = true;
+      subscription.remove();
+    };
+  });
+}

package/src/svelte/navigation-context.ts

@@ -0,0 +1,62 @@
+// The lifecycle half of the framework-agnostic emitter (../core/navigation-events). Svelte's twin
+// of React's Context / Vue's provide-inject is setContext/getContext over one shared key, so a
+// screen's subtree can read its own route, navigator handle, and per-route emitter without
+// prop-drilling.
+//
+// Context in Svelte follows the RUNTIME render tree, not the lexical definition site: a component
+// instantiated inside a snippet the app passed down to <Stack> still sees the context <Stack> (or
+// the NavigationScope it renders) set - verified against the real compiler before this was built
+// on. That is what lets a navigator hand each mounted route its OWN scope: Stack/Tab/Drawer mount
+// one NavigationScope per route (keyed by route.key, exactly like React's per-route
+// `<NavigationContext.Provider>`), and each instance's own init calls the setter once.
+//
+// The value is a BOXED GETTER (`{ get current() }`), never a bare value: Svelte 5 reactivity does
+// not survive being handed out of the declaring scope as a plain value (svelte-adapter-dom-shim
+// skill §21), and consumers must keep seeing the CURRENT route (a setParams that produces a new
+// route object for the same key still has to reach them).
+//
+// `parent` threads the ambient value 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 { getContext, setContext } from 'svelte';
+import type { INavigationEmitter, IRoute, IAnyNavigatorHandle } from '../core';
+export type { IAnyNavigatorHandle };
+
+export type INavigationScopeValue = {
+  route: IRoute<unknown>;
+  navigation: IAnyNavigatorHandle;
+  emitter: INavigationEmitter;
+  parent?: INavigationScopeValue;
+};
+
+export type INavigationScope = { readonly current: INavigationScopeValue };
+
+const NAVIGATION_SCOPE_KEY = Symbol('symbiote-navigation-scope');
+
+// Written only from NavigationScope's own init (navigation-scope.svelte), never by app code.
+export function setNavigationScope(scope: INavigationScope): void {
+  setContext(NAVIGATION_SCOPE_KEY, scope);
+}
+
+// undefined simply means "no ancestor NavigationScope", which is a legitimate state (the nesting
+// root a navigator itself reads on mount) rather than an error - callers that require one go
+// through requireNavigationScope below.
+export function getNavigationScope(): INavigationScope | undefined {
+  return getContext<INavigationScope | undefined>(NAVIGATION_SCOPE_KEY);
+}
+
+// The "throw if missing" half every rune in ./runes needs (useNavigation, useRoute, useIsFocused,
+// useFocusEffect, useNavigationState) - they all read the scope and threw the same shaped error,
+// differing only in which rune name the message names. Centralized here so a wording change lands
+// once instead of five times.
+export function requireNavigationScope(runeName: string): INavigationScope {
+  const scope = getNavigationScope();
+  if (scope === undefined) {
+    throw new Error(
+      `${runeName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`,
+    );
+  }
+  return scope;
+}

package/src/svelte/navigation-scope.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  // The per-route setup boundary: one instance per mounted route, so each route subtree reads its
+  // OWN scope (its own route/emitter) invisible to its siblings. Stack keeps every pushed route
+  // mounted as a sibling subtree; Tab/Drawer mount only the focused one - either way each needs a
+  // distinct provided value, which is an inherent property of any hierarchical
+  // dependency-injection scheme, Svelte's context included.
+  //
+  // `value` is a $props() field, so reading it inside the boxed getter below is a LIVE read: a
+  // later change (setParams producing a new route object for the same key) still reaches every
+  // consumer without re-running setContext, which Svelte only honours during init anyway.
+  import type { Snippet } from 'svelte';
+  import { setNavigationScope } from './navigation-context';
+  import type { INavigationScopeValue } from './navigation-context';
+
+  let {
+    value,
+    children,
+  }: { value: INavigationScopeValue; children?: Snippet } = $props();
+
+  setNavigationScope({
+    get current(): INavigationScopeValue {
+      return value;
+    },
+  });
+</script>
+
+{@render children?.()}

package/src/svelte/registry-host.ts

@@ -0,0 +1,26 @@
+// Where a navigator renders its `<*.Screen>` markers so they can register themselves.
+//
+// The markers have to be RENDERED for their init to run (screen-registry.ts explains why
+// registration is inverted on Svelte), and Svelte turns whitespace between two sibling non-text
+// nodes into a REAL text node - svelte-adapter-dom-shim skill §16, a correctness bug rather than
+// a formatting one. Naturally formatted app markup
+//
+//   <Stack>
+//     <Stack.Screen name="home" component={Home} />
+//     <Stack.Screen name="details" component={Details} />
+//   </Stack>
+//
+// therefore compiles to `from_tree([marker, ' ', marker])`, and each ' ' becomes an RCTRawText
+// engine node parented to whatever host tag holds the `{@render children?.()}` call. Inside a
+// plain `symbiote-view` that is the invalid "text outside a <Text> component" shape; inside
+// RNSScreenStack it is worse, since react-native-screens' native side expects only RNSScreen
+// children there.
+//
+// So the markers are rendered inside a zero-size `symbiote-text` instead: raw text inside an
+// RCTText is LEGAL, which turns the hazard from a device crash into a no-op and makes it
+// structurally impossible rather than a rule app authors have to remember. The cost is one
+// collapsed, non-interactive RCTText per navigator.
+export const SCREEN_REGISTRY_HOST_PROPS: Record<string, unknown> = {
+  style: { position: 'absolute', width: 0, height: 0, opacity: 0 },
+  pointerEvents: 'none',
+};

package/src/svelte/runes/index.ts

@@ -0,0 +1,17 @@
+// The lifecycle bucket. `runes/` (with `*.svelte.ts` files) is Svelte's own term for
+// $state/$effect, parallel to React's `hooks/` and Vue's `composables/` - per CLAUDE.md's
+// <adapter_src_follows_framework_idioms>, every framework entry names this bucket after ITS
+// framework's word for the concept, never a borrowed one.
+
+export { useNavigation } from './use-navigation.svelte';
+export type { INavigationHandle } from './use-navigation.svelte';
+export { useStackNavigation } from './use-stack-navigation.svelte';
+export type { IStackNavigationHandle } from './use-stack-navigation.svelte';
+export { useTabNavigation } from './use-tab-navigation.svelte';
+export type { ITabNavigationHandle } from './use-tab-navigation.svelte';
+export { useDrawerNavigation } from './use-drawer-navigation.svelte';
+export type { IDrawerNavigationHandle } from './use-drawer-navigation.svelte';
+export { useRoute } from './use-route.svelte';
+export { useIsFocused } from './use-is-focused.svelte';
+export { useFocusEffect } from './use-focus-effect.svelte';
+export { useNavigationState } from './use-navigation-state.svelte';

package/src/svelte/runes/use-drawer-navigation.svelte.ts

@@ -0,0 +1,31 @@
+// Twin of use-stack-navigation.svelte.ts, narrowing to a Drawer handle instead.
+
+import type { IDrawerNavigatorHandle } from '../../core';
+import { isDrawerNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation.svelte';
+import type { INavigationHandle } from './use-navigation.svelte';
+
+export type IDrawerNavigationHandle = IDrawerNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useDrawerNavigation(): {
+  readonly current: IDrawerNavigationHandle;
+} {
+  const navigation = useNavigation();
+  const narrowed = $derived.by<IDrawerNavigationHandle>(() => {
+    const value = navigation.current;
+    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;
+  });
+
+  return {
+    get current(): IDrawerNavigationHandle {
+      return narrowed;
+    },
+  };
+}

package/src/svelte/runes/use-focus-effect.svelte.ts

@@ -0,0 +1,41 @@
+// Mirrors @react-navigation's useFocusEffect; Svelte twin of vue/composables/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: a Svelte component's script runs
+// once, so `effect` is read once at call time and closed over directly - there is no dependency
+// array to go stale.
+
+import { untrack } from 'svelte';
+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;
+  const runEffect = (): void => {
+    cleanup = effect();
+  };
+  const runCleanup = (): void => {
+    cleanup?.();
+    cleanup = undefined;
+  };
+
+  // Empty dependency set (see use-is-focused.svelte.ts) so this subscribes once and tears down
+  // once. The teardown also runs any still-pending cleanup, matching Vue's onUnmounted.
+  $effect(() => {
+    const { emitter } = untrack(() => scope.current);
+    const unsubscribeFocus = emitter.addListener(
+      NAVIGATION_EVENT_FOCUS,
+      runEffect,
+    );
+    const unsubscribeBlur = emitter.addListener(
+      NAVIGATION_EVENT_BLUR,
+      runCleanup,
+    );
+    return () => {
+      unsubscribeFocus();
+      unsubscribeBlur();
+      runCleanup();
+    };
+  });
+}

package/src/svelte/runes/use-is-focused.svelte.ts

@@ -0,0 +1,38 @@
+// Mirrors @react-navigation's useIsFocused; Svelte twin of vue/composables/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) or the screen mounts focused (tabs/drawer) - a
+// screen genuinely isn't focused at the instant it mounts, the same async gap real native
+// transitions have.
+
+import { untrack } from 'svelte';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useIsFocused(): { readonly current: boolean } {
+  const scope = requireNavigationScope('useIsFocused');
+  let isFocused = $state(false);
+
+  // `untrack` keeps this effect's dependency set EMPTY, so it subscribes exactly once on mount
+  // and cleans up exactly once on unmount - matching Vue's onMounted/onUnmounted pair. Without
+  // it the effect would re-read `scope.current` and re-subscribe on every setParams (which
+  // produces a new route object for the same key, and therefore the same emitter).
+  $effect(() => {
+    const { emitter } = untrack(() => scope.current);
+    const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, () => {
+      isFocused = true;
+    });
+    const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, () => {
+      isFocused = false;
+    });
+    return () => {
+      unsubscribeFocus();
+      unsubscribeBlur();
+    };
+  });
+
+  return {
+    get current(): boolean {
+      return isFocused;
+    },
+  };
+}

package/src/svelte/runes/use-navigation-state.svelte.ts

@@ -0,0 +1,48 @@
+// Mirrors @react-navigation's useNavigationState; Svelte twin of
+// vue/composables/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 rune only wires the subscription to the `state` broadcast each navigator
+// re-emits after commit.
+//
+// Seeded from a single-route snapshot ({ routes: [route] }) rather than left undefined: the real
+// broadcast lands after mount, 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.
+//
+// `$state.raw`, not `$state`: TResult is arbitrary app data (often the router state itself, whose
+// route objects the reducer compares by identity), and a deep reactive proxy would hand callers
+// a different object than the navigator holds - the same identity rule Vue's shallowRef enforces
+// here.
+
+import { untrack } from 'svelte';
+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,
+): {
+  readonly current: TResult;
+} {
+  const scope = requireNavigationScope('useNavigationState');
+  let result = $state.raw<TResult>(selector({ routes: [scope.current.route] }));
+
+  // Empty dependency set (see use-is-focused.svelte.ts): subscribe once, tear down once.
+  $effect(() => {
+    const { emitter } = untrack(() => scope.current);
+    return emitter.addListener(NAVIGATION_EVENT_STATE, (state: unknown) => {
+      if (!isNavigatorState(state)) return;
+      result = selector(state);
+    });
+  });
+
+  return {
+    get current(): TResult {
+      return result;
+    },
+  };
+}

package/src/svelte/runes/use-navigation.svelte.ts

@@ -0,0 +1,49 @@
+// Mirrors @react-navigation's `navigation.addListener('focus', cb)` surface; the Svelte twin of
+// vue/composables/use-navigation.ts. All pub/sub logic lives in ../../core/navigation-events -
+// this rune only reads the navigation scope off the context and binds identity.
+//
+// `.svelte.ts`, and a BOXED GETTER return (`{ get current() }`) rather than a bare value: runes
+// are only usable outside a component in a `.svelte.ts` file, and Svelte 5 reactivity does not
+// survive being returned as a plain value from a plain function (svelte-adapter-dom-shim skill
+// §21). A caller reads `useNavigation().current` inside a `$derived`/template/`$effect`, exactly
+// like unwrapping Vue's `ComputedRef` via `.value`.
+
+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(): { readonly current: INavigationHandle } {
+  const scope = requireNavigationScope('useNavigation');
+  const handle = $derived.by<INavigationHandle>(() => {
+    const { navigation, emitter, parent } = scope.current;
+    return {
+      ...navigation,
+      addListener: emitter.addListener,
+      getParent: () => parent?.navigation,
+    };
+  });
+
+  return {
+    get current(): INavigationHandle {
+      return handle;
+    },
+  };
+}

package/src/svelte/runes/use-route.svelte.ts

@@ -0,0 +1,16 @@
+// Mirrors @react-navigation's useRoute; Svelte twin of vue/composables/use-route.ts. Zero logic
+// of its own - the route object itself is built by Stack's/Tab's/Drawer's render loop from the
+// shared core reducer's state.
+
+import type { IRoute } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useRoute(): { readonly current: IRoute<unknown> } {
+  const scope = requireNavigationScope('useRoute');
+
+  return {
+    get current(): IRoute<unknown> {
+      return scope.current.route;
+    },
+  };
+}

package/src/svelte/runes/use-stack-navigation.svelte.ts

@@ -0,0 +1,34 @@
+// 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 rune narrows that union ONCE, here, so call sites never write their own
+// 'push' in navigation check. Svelte twin of vue/composables/use-stack-navigation.ts.
+
+import type { INavigatorHandle } from '../../core';
+import { isStackNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation.svelte';
+import type { INavigationHandle } from './use-navigation.svelte';
+
+export type IStackNavigationHandle = INavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useStackNavigation(): {
+  readonly current: IStackNavigationHandle;
+} {
+  const navigation = useNavigation();
+  const narrowed = $derived.by<IStackNavigationHandle>(() => {
+    const value = navigation.current;
+    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;
+  });
+
+  return {
+    get current(): IStackNavigationHandle {
+      return narrowed;
+    },
+  };
+}