@symbiote-native/navigation 2.0.3 → 2.2.0

package/build/svelte/linking.svelte.js

@@ -0,0 +1,55 @@
+// 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 { resolveRouteFromUrl } from '../core/index.js';
+export function useLinkingIntegration(config, getNavigatorHandle) {
+    $effect(() => {
+        const handle = getNavigatorHandle();
+        if (handle === null) {
+            dlog('useLinkingIntegration: navigatorHandle is not available yet');
+            return;
+        }
+        let cancelled = false;
+        const applyRoute = (url, dispatch) => {
+            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) => {
+            dlog(`useLinkingIntegration: getInitialURL failed: ${String(error)}`);
+        });
+        const subscription = Linking.addEventListener('url', (event) => {
+            dlog(`useLinkingIntegration: url event "${event.url}"`);
+            applyRoute(event.url, handle.push);
+        });
+        return () => {
+            cancelled = true;
+            subscription.remove();
+        };
+    });
+}

package/build/svelte/navigation-context.d.ts

@@ -0,0 +1,14 @@
+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;
+};
+export declare function setNavigationScope(scope: INavigationScope): void;
+export declare function getNavigationScope(): INavigationScope | undefined;
+export declare function requireNavigationScope(runeName: string): INavigationScope;

package/build/svelte/navigation-context.js

@@ -0,0 +1,44 @@
+// 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';
+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) {
+    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() {
+    return getContext(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) {
+    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/build/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/build/svelte/navigation-scope.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { INavigationScopeValue } from './navigation-context';
+type $$ComponentProps = {
+    value: INavigationScopeValue;
+    children?: Snippet;
+};
+declare const NavigationScope: import("svelte").Component<$$ComponentProps, {}, "">;
+type NavigationScope = ReturnType<typeof NavigationScope>;
+export default NavigationScope;

package/build/svelte/registry-host.d.ts

@@ -0,0 +1 @@
+export declare const SCREEN_REGISTRY_HOST_PROPS: Record<string, unknown>;

package/build/svelte/registry-host.js

@@ -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 = {
+    style: { position: 'absolute', width: 0, height: 0, opacity: 0 },
+    pointerEvents: 'none',
+};

package/build/svelte/runes/index.d.ts

@@ -0,0 +1,12 @@
+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/build/svelte/runes/index.js

@@ -0,0 +1,12 @@
+// 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 { useStackNavigation } from './use-stack-navigation.svelte';
+export { useTabNavigation } from './use-tab-navigation.svelte';
+export { useDrawerNavigation } 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/build/svelte/runes/use-drawer-navigation.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { IDrawerNavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation.svelte';
+export type IDrawerNavigationHandle = IDrawerNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useDrawerNavigation(): {
+    readonly current: IDrawerNavigationHandle;
+};

package/build/svelte/runes/use-drawer-navigation.svelte.js

@@ -0,0 +1,19 @@
+// Twin of use-stack-navigation.svelte.ts, narrowing to a Drawer handle instead.
+import { isDrawerNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.svelte';
+export function useDrawerNavigation() {
+    const navigation = useNavigation();
+    const narrowed = $derived.by(() => {
+        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() {
+            return narrowed;
+        },
+    };
+}

package/build/svelte/runes/use-focus-effect.svelte.d.ts

@@ -0,0 +1 @@
+export declare function useFocusEffect(effect: () => (() => void) | void): void;

package/build/svelte/runes/use-focus-effect.svelte.js

@@ -0,0 +1,31 @@
+// 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/index.js';
+import { requireNavigationScope } from '../navigation-context.js';
+export function useFocusEffect(effect) {
+    const scope = requireNavigationScope('useFocusEffect');
+    let cleanup;
+    const runEffect = () => {
+        cleanup = effect();
+    };
+    const runCleanup = () => {
+        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/build/svelte/runes/use-is-focused.svelte.d.ts

@@ -0,0 +1,3 @@
+export declare function useIsFocused(): {
+    readonly current: boolean;
+};

package/build/svelte/runes/use-is-focused.svelte.js

@@ -0,0 +1,34 @@
+// 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/index.js';
+import { requireNavigationScope } from '../navigation-context.js';
+export function useIsFocused() {
+    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() {
+            return isFocused;
+        },
+    };
+}

package/build/svelte/runes/use-navigation-state.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { INavigatorState } from '../../core';
+export declare function useNavigationState<TResult>(selector: (state: INavigatorState) => TResult): {
+    readonly current: TResult;
+};

package/build/svelte/runes/use-navigation-state.svelte.js

@@ -0,0 +1,39 @@
+// 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 { NAVIGATION_EVENT_STATE, isRecord } from '../../core/index.js';
+import { requireNavigationScope } from '../navigation-context.js';
+function isNavigatorState(value) {
+    return isRecord(value) && Array.isArray(value.routes);
+}
+export function useNavigationState(selector) {
+    const scope = requireNavigationScope('useNavigationState');
+    let result = $state.raw(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) => {
+            if (!isNavigatorState(state))
+                return;
+            result = selector(state);
+        });
+    });
+    return {
+        get current() {
+            return result;
+        },
+    };
+}

package/build/svelte/runes/use-navigation.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { INavigationEventListener, INavigationEventName } from '../../core';
+import type { IAnyNavigatorHandle } from '../navigation-context';
+export type INavigationHandle = IAnyNavigatorHandle & {
+    addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+    getParent: () => IAnyNavigatorHandle | undefined;
+};
+export declare function useNavigation(): {
+    readonly current: INavigationHandle;
+};

package/build/svelte/runes/use-navigation.svelte.js

@@ -0,0 +1,26 @@
+// 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 { requireNavigationScope } from '../navigation-context.js';
+export function useNavigation() {
+    const scope = requireNavigationScope('useNavigation');
+    const handle = $derived.by(() => {
+        const { navigation, emitter, parent } = scope.current;
+        return {
+            ...navigation,
+            addListener: emitter.addListener,
+            getParent: () => parent?.navigation,
+        };
+    });
+    return {
+        get current() {
+            return handle;
+        },
+    };
+}

package/build/svelte/runes/use-route.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { IRoute } from '../../core';
+export declare function useRoute(): {
+    readonly current: IRoute<unknown>;
+};

package/build/svelte/runes/use-route.svelte.js

@@ -0,0 +1,12 @@
+// 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 { requireNavigationScope } from '../navigation-context.js';
+export function useRoute() {
+    const scope = requireNavigationScope('useRoute');
+    return {
+        get current() {
+            return scope.current.route;
+        },
+    };
+}

package/build/svelte/runes/use-stack-navigation.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { INavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation.svelte';
+export type IStackNavigationHandle = INavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useStackNavigation(): {
+    readonly current: IStackNavigationHandle;
+};

package/build/svelte/runes/use-stack-navigation.svelte.js

@@ -0,0 +1,22 @@
+// 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 { isStackNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.svelte';
+export function useStackNavigation() {
+    const navigation = useNavigation();
+    const narrowed = $derived.by(() => {
+        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() {
+            return narrowed;
+        },
+    };
+}

package/build/svelte/runes/use-tab-navigation.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { ITabNavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation.svelte';
+export type ITabNavigationHandle = ITabNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useTabNavigation(): {
+    readonly current: ITabNavigationHandle;
+};

package/build/svelte/runes/use-tab-navigation.svelte.js

@@ -0,0 +1,19 @@
+// Twin of use-stack-navigation.svelte.ts, narrowing to a Tab handle instead.
+import { isTabNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.svelte';
+export function useTabNavigation() {
+    const navigation = useNavigation();
+    const narrowed = $derived.by(() => {
+        const value = navigation.current;
+        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;
+    });
+    return {
+        get current() {
+            return narrowed;
+        },
+    };
+}

package/build/svelte/screen-props.d.ts

@@ -0,0 +1,21 @@
+import type { Component } from 'svelte';
+import type { INavigatorHandle, IRoute, IScreenOptions, ISearchBarCommands, ISearchBarOptions } from '../core';
+export type ISvelteSearchBarOptions = ISearchBarOptions & {
+    ref?: {
+        current: ISearchBarCommands | null;
+    };
+};
+export type ISvelteScreenOptions = Omit<IScreenOptions, 'headerSearchBarOptions'> & {
+    headerSearchBarOptions?: ISvelteSearchBarOptions;
+};
+export type IScreenOptionsArgs = {
+    route: IRoute<unknown>;
+    navigation: INavigatorHandle;
+};
+export type IScreenOptionsResolver = (args: IScreenOptionsArgs) => ISvelteScreenOptions;
+export type IScreenProps = {
+    name: string;
+    component: Component;
+    options?: ISvelteScreenOptions | IScreenOptionsResolver;
+    initialParams?: unknown;
+};

package/build/svelte/screen-props.js

@@ -0,0 +1,6 @@
+// Stack.Screen's public prop surface. Split out of `screen.svelte` because plain `tsc --build`
+// resolves an import of a `.svelte` file through svelte's own ambient `declare module '*.svelte'`
+// fallback (a bare default export only) and never parses the real `<script module>` block - so a
+// NAMED type re-exported from a `.svelte` file is invisible to `tsc`. Same rule the Svelte
+// adapter's own `view-props.ts` / `switch-props.ts` follow.
+export {};

package/build/svelte/screen-registry.d.ts

@@ -0,0 +1,17 @@
+import type { Component } from 'svelte';
+export type INavigatorKind = 'stack' | 'tab' | 'drawer';
+export type IRegisteredScreen<TOptions> = {
+    readonly name: string;
+    readonly component: Component;
+    readonly options: TOptions | undefined;
+    readonly initialParams: unknown;
+};
+export type IScreenCollector<TOptions> = {
+    readonly kind: INavigatorKind;
+    register(screen: IRegisteredScreen<TOptions>): void;
+    unregister(screen: IRegisteredScreen<TOptions>): void;
+};
+export declare function setScreenCollector<TOptions>(collector: IScreenCollector<TOptions>): void;
+export declare function collectScreen<TOptions>(kind: INavigatorKind, screen: IRegisteredScreen<TOptions>): void;
+export declare function withoutScreen<TOptions>(screens: readonly IRegisteredScreen<TOptions>[], screen: IRegisteredScreen<TOptions>): IRegisteredScreen<TOptions>[];
+export declare function toRegistry<TOptions>(screens: readonly IRegisteredScreen<TOptions>[]): Map<string, IRegisteredScreen<TOptions>>;

package/build/svelte/screen-registry.js

@@ -0,0 +1,57 @@
+// How a navigator learns about its `<Stack.Screen>` / `<Tab.Screen>` / `<Drawer.Screen>` markers.
+//
+// React reads `children` as an inspectable array; Vue scans the default slot's vnodes
+// (`vnode.type === Screen`); Angular queries `@ContentChildren`. Svelte has NO equivalent: a
+// component receives its children as an opaque `Snippet`, with no way to enumerate or inspect
+// what is inside it (the same wall the Svelte adapter's ScrollView hit for
+// `stickyHeaderIndices`, svelte-adapter-dom-shim skill §18). So registration is INVERTED here:
+// the navigator publishes a collector on the context, each marker registers ITSELF during its own
+// init, and the navigator's route list derives from what came back.
+//
+// Ordering works out because Svelte's initial render is synchronous and top-down: a navigator
+// renders the children snippet BEFORE the `{#each}` that paints its routes, so by the time the
+// route list is first read every marker has already registered. Verified against the real
+// compiler, not assumed.
+//
+// ONE key, not one per navigator kind: nearest-navigator-wins shadowing falls out of Svelte's own
+// context lookup, so a Stack nested inside a Tab screen automatically captures its own markers.
+// The `kind` tag then rejects a MISMATCHED marker (a `<Tab.Screen>` written inside a `<Stack>`)
+// instead of letting it silently register with some far-away ancestor Tab - the failure mode a
+// per-kind key would have.
+import { getContext, onDestroy, setContext } from 'svelte';
+import { dlog } from '@symbiote-native/engine';
+const SCREEN_COLLECTOR_KEY = Symbol('symbiote-navigation-screen-collector');
+// Called once from a navigator's own init, before it renders the children snippet.
+export function setScreenCollector(collector) {
+    setContext(SCREEN_COLLECTOR_KEY, collector);
+}
+// Called once from a marker's own init. Registration is undone on destroy, so a marker behind an
+// `{#if}` disappears from the registry exactly like a Vue slot scan stops seeing a removed vnode.
+export function collectScreen(kind, screen) {
+    const collector = getContext(SCREEN_COLLECTOR_KEY);
+    if (collector === undefined) {
+        dlog(`navigation: <${kind} screen "${screen.name}"> rendered outside any navigator, ignored`);
+        return;
+    }
+    if (collector.kind !== kind) {
+        dlog(`navigation: a ${kind} screen marker ("${screen.name}") was rendered inside a ` +
+            `${collector.kind} navigator, ignored`);
+        return;
+    }
+    collector.register(screen);
+    onDestroy(() => collector.unregister(screen));
+}
+// The navigator side of the pair: a plain, non-reactive list plus the two mutators the collector
+// exposes. The navigator holds the list in `$state.raw` and reassigns it (never mutates in place)
+// so a component reference - a plain function - is never wrapped in a deep reactive proxy, which
+// would break both the getters above and Svelte's own component identity checks.
+export function withoutScreen(screens, screen) {
+    return screens.filter(candidate => candidate !== screen);
+}
+// name -> entry, last registration wins, exactly like Vue's collectRegistry Map.
+export function toRegistry(screens) {
+    const registry = new Map();
+    for (const screen of screens)
+        registry.set(screen.name, screen);
+    return registry;
+}

package/build/svelte/screen.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  // Stack.Screen: a declarative marker that paints nothing. Stack reads it through the
+  // context-based collector (screen-registry.ts) rather than by scanning children the way React
+  // and Vue can, then mounts the registered component itself for each pushed route.
+  //
+  // Every field is handed over as a GETTER over this component's own `$props()` bindings, so the
+  // navigator always sees the CURRENT value - reassigning `options` on an already-mounted marker
+  // reaches the next options fold without re-registering.
+  import { collectScreen } from './screen-registry';
+  import type { IScreenProps } from './screen-props';
+
+  let { name, component, options, initialParams }: IScreenProps = $props();
+
+  collectScreen('stack', {
+    get name(): IScreenProps['name'] {
+      return name;
+    },
+    get component(): IScreenProps['component'] {
+      return component;
+    },
+    get options(): IScreenProps['options'] {
+      return options;
+    },
+    get initialParams(): unknown {
+      return initialParams;
+    },
+  });
+</script>

package/build/svelte/screen.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { IScreenProps } from './screen-props';
+declare const Screen: import("svelte").Component<IScreenProps, {}, "">;
+type Screen = ReturnType<typeof Screen>;
+export default Screen;