@symbiote-native/navigation 2.1.0 → 3.0.0

package/build/solid/stack/index.js

@@ -0,0 +1,348 @@
+// Stack, the Solid lifecycle half. The route-stack transitions (navigator-state) and the
+// options/props folds (screen-options, render-stack) live in @symbiote-native/navigation core,
+// shared verbatim with the React/Vue/Svelte/Angular adapters; here Solid supplies the lifecycle -
+// a signal for the pushed-route stack, a route-key counter, a callback `ref` for the push/pop/
+// replace handle - plus the descriptor bridge for the header config leaf. Pushing/popping a route
+// is an ordinary child insert/remove: RNSScreenStack diffs its RNSScreen children natively, so no
+// imperative native command is needed here. Neither this nor the Screen marker imports
+// react-native-screens' own React components (they are React internally and crash a non-React
+// adapter); the native views are driven through the ViewConfig ../../register registers. See
+// CLAUDE.md <third_party_rn_packages_are_react_only>.
+//
+// FOUR THINGS DIFFER FROM EVERY OTHER ADAPTER, and each is a place a naive port freezes:
+//
+// 1. THE REGISTRY IS EMPTY WHEN THIS BODY RUNS. Solid cannot inspect children (screen-registry.ts),
+//    and the markers only register once the collector Provider evaluates them - after the body has
+//    returned. So nothing is computed eagerly from the registry: the initial state is seeded lazily
+//    by `seed()` the first time a non-empty registry is observed.
+//
+// 2. ROUTES ARE KEYED BY `route.key`, NOT BY THE ROUTE OBJECT. `setParams` produces a NEW route
+//    object under the same key. A `<For each={routes()}>` keys on object identity and would tear a
+//    screen's whole subtree down and rebuild it on every setParams - losing native-owned state and
+//    every ref. Iterating the KEYS (a memo with an element-wise `equals`) makes a params change
+//    invisible to the list and visible only to the leaf accessors that read it.
+//
+// 3. THE SCREEN IS BUILT BEHIND AN EXPLICIT REBUILD BOUNDARY. Three things legitimately change a
+//    route's native SHAPE rather than its props: `screenViewName` (RN treats RNSModalScreen as a
+//    different view from RNSScreen), `inModal` (a modal nests an inner stack purely to host the
+//    header - isHeaderInModal in core/render-stack.ts), and whether the header config carries a
+//    search-bar child. Each is read in a `createMemo` over those discriminators ALONE with the
+//    build `untrack`ed - the shape .claude/rules/solid-descriptor-bridge.md §5 prescribes. Without
+//    the untrack the memo subscribes to every prop the build reads and re-creates the native screen
+//    on each header-title change. The screen COMPONENT is its own, narrower boundary inside that.
+//
+// 4. FOCUS/STATE EMISSION IS DEFERRED BY A MICROTASK. A screen's subtree - and the subscriptions
+//    createIsFocused/createNavigationState set up inside it - is built by the render effects of the
+//    very update that changed the state, so an inline emit would reach zero subscribers.
+import { For, createEffect, createMemo, createSignal, onCleanup, untrack, } from 'solid-js';
+import { descriptorToSolid } from '@symbiote-native/solid';
+// `createComponent` comes from solid-js, not from the renderer: they are the SAME runtime call
+// (untrack + invoke), but the renderer's is typed to return a host node, which a Solid component
+// legitimately does not have to (a screen may render nothing). `insert`/`insertNode` are the
+// renderer's own, since they mutate the engine tree.
+import { createComponent } from 'solid-js';
+import { insert, insertNode } from '@symbiote-native/solid/renderer';
+import { Platform, debugNodeId, dlog, isSymbioteNode, } from '@symbiote-native/engine';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS, NAVIGATION_EVENT_STATE, RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME, RNS_SCREEN_STACK_VIEW_NAME, RNS_SCREEN_VIEW_NAME, SCREEN_ON_APPEAR, SCREEN_ON_DISAPPEAR, SCREEN_ON_DISMISSED, SCREEN_ON_HEADER_BACK_BUTTON_CLICKED, SCREEN_ON_WILL_APPEAR, SCREEN_ON_WILL_DISAPPEAR, STACK_ON_FINISH_TRANSITIONING, buildSearchBarHandle, buildSearchBarPassthrough, createInitialNavigatorState, createNavigationEmitter, navigatorReducer, reconcileStackRoutes, resolveScreenRenderPlan, resolveStackProps, } from '../../core/index.js';
+import { hostElement } from '../host.js';
+import { NavigationScopeProvider, useNavigationScope, } from '../navigation-context.js';
+import { ScreenCollectorProvider, createScreenSignal, toRegistry, } from '../screen-registry.js';
+import { Screen } from '../screen.js';
+// backTitleVisible defaults to `true` on both platforms per the codegen spec's own default
+// (CT.WithDefault<boolean, 'true'>) - no ios/android divergence in v1 scope.
+const NAVIGATOR_PLATFORM = {
+    defaultHeaderBackTitleVisible: true,
+};
+const EMPTY_STATE = { routes: [] };
+// Route keys must be unique per navigator INSTANCE. React/Vue take that from useId(); Solid has no
+// equivalent, so a module counter stands in - read once, at construction.
+let navigatorSequence = 0;
+function sameShape(a, b) {
+    return (a.viewName === b.viewName &&
+        a.inModal === b.inModal &&
+        a.hasSearchBar === b.hasSearchBar);
+}
+function sameKeys(a, b) {
+    return a.length === b.length && a.every((key, index) => key === b[index]);
+}
+function resolveScreenOptions(entry, args, screenOptions) {
+    const own = typeof entry.options === 'function' ? entry.options(args) : entry.options;
+    return { ...screenOptions, ...own };
+}
+function StackImpl(props) {
+    // Read BEFORE this Stack provides its own per-screen scope below - becomes the `parent` link a
+    // nested screen's useNavigation().getParent() walks. undefined when this Stack is the root.
+    const parentScope = useNavigationScope();
+    const { screens, collector } = createScreenSignal('stack');
+    const registry = createMemo(() => toRegistry(screens()));
+    navigatorSequence += 1;
+    const routeIdPrefix = `stack-${navigatorSequence}`;
+    let routeSequence = 0;
+    function createRoute(name, params) {
+        routeSequence += 1;
+        return { key: `${routeIdPrefix}-${name}-${routeSequence}`, name, params };
+    }
+    // One emitter per route.key, created lazily and pruned once the route is popped (below).
+    const emitters = new Map();
+    function emitterFor(routeKey) {
+        let emitter = emitters.get(routeKey);
+        if (emitter === undefined) {
+            emitter = createNavigationEmitter();
+            emitters.set(routeKey, emitter);
+        }
+        return emitter;
+    }
+    const [dispatched, setDispatched] = createSignal(null);
+    // The initial push, deferred until the markers have registered (header note 1). Cached in a plain
+    // local rather than a memo: it must run EXACTLY once - a memo re-running would mint a second
+    // route key for the same screen and silently reset the stack.
+    let seeded;
+    function seed(entries) {
+        if (seeded !== undefined)
+            return seeded;
+        // Deliberately NOT seeded from an empty registry, even when `initialRouteName` names the route:
+        // <For> maps a key exactly once, so a route minted before its marker exists would be handed a
+        // build with no component and stay blank forever. Waiting one update costs nothing - the
+        // markers register during the same flush this navigator is created in.
+        if (entries.size === 0) {
+            dlog('Stack: no <Stack.Screen> children registered');
+            return EMPTY_STATE;
+        }
+        const initialRouteName = props.initialRouteName ?? entries.keys().next().value;
+        if (initialRouteName === undefined)
+            return EMPTY_STATE;
+        seeded = createInitialNavigatorState(createRoute(initialRouteName, entries.get(initialRouteName)?.initialParams));
+        return seeded;
+    }
+    // A <Stack.Screen> marker can vanish while its route is still in the pushed history, which would
+    // leave that entry with nothing to render (reconcileStackRoutes' header). Reconciling on READ
+    // keeps the repair out of any write path; the next dispatch then persists it.
+    const currentState = createMemo(() => {
+        const entries = registry();
+        const state = dispatched();
+        if (state === null)
+            return seed(entries);
+        return reconcileStackRoutes(state, [...entries.keys()]);
+    });
+    function dispatch(action) {
+        setDispatched(navigatorReducer(currentState(), action));
+    }
+    const handle = {
+        push: (name, params) => dispatch({ type: 'push', route: createRoute(name, params) }),
+        pop: count => dispatch({ type: 'pop', count }),
+        popToTop: () => dispatch({ type: 'popToTop' }),
+        popTo: key => dispatch({ type: 'popTo', key }),
+        replace: (name, params) => dispatch({ type: 'replace', route: createRoute(name, params) }),
+        setParams: (params, key) => dispatch({ type: 'setParams', key, params }),
+        reset: nextState => dispatch({ type: 'reset', state: nextState }),
+        canGoBack: () => currentState().routes.length > 1,
+    };
+    props.ref?.(handle);
+    // Broadcasts the router state to every still-live route's emitter (createNavigationState's
+    // source) and prunes emitters for popped routes. Deferred by a microtask - header note 4.
+    createEffect(() => {
+        const current = currentState();
+        queueMicrotask(() => {
+            for (const route of current.routes) {
+                emitterFor(route.key).emit(NAVIGATION_EVENT_STATE, current);
+            }
+            for (const routeKey of [...emitters.keys()]) {
+                if (!current.routes.some(route => route.key === routeKey)) {
+                    emitters.delete(routeKey);
+                }
+            }
+        });
+    });
+    // Header note 2: keyed on route KEYS, so a setParams (new route object, same key) never reaches
+    // <For> and never rebuilds a screen subtree.
+    const routeKeys = createMemo(() => currentState().routes.map(route => route.key), [], { equals: sameKeys });
+    function renderRoute(routeKey, index) {
+        const route = createMemo(() => currentState().routes.find(candidate => candidate.key === routeKey));
+        const entry = createMemo(() => {
+            const current = route();
+            return current === undefined ? undefined : registry().get(current.name);
+        });
+        const emitter = emitterFor(routeKey);
+        // The host node the app's search-bar ref last saw. `spread` re-runs a bag's `ref` on EVERY prop
+        // change, and an app expects one attach per node the way React's ref contract gives it.
+        let lastSearchBarNode = null;
+        // Keeping the PREVIOUS plan when the route or its marker vanishes: <For> disposes this item in
+        // the same update, but memo evaluation order inside one batch is not ours to choose, so the
+        // live prop accessors below must never observe an undefined plan mid-teardown.
+        const plan = createMemo(previous => {
+            const current = route();
+            const registered = entry();
+            if (current === undefined || registered === undefined)
+                return previous;
+            const merged = resolveScreenOptions(registered, { route: current, navigation: handle }, props.screenOptions);
+            const searchBarOptions = merged.headerSearchBarOptions;
+            return resolveScreenRenderPlan({
+                screenId: current.key,
+                index: index(),
+                routeCount: currentState().routes.length,
+                options: merged,
+                platform: NAVIGATOR_PLATFORM,
+                isAndroid: Platform.OS === 'android',
+                screenPassthrough: {
+                    [SCREEN_ON_DISMISSED]: () => dispatch({ type: 'pop', count: 1 }),
+                    [SCREEN_ON_HEADER_BACK_BUTTON_CLICKED]: () => dispatch({ type: 'pop', count: 1 }),
+                    // onAppear/onDisappear are the definitive visibility boundary (post-transition), so
+                    // 'focus'/'blur' fire exactly once per transition; onWillAppear/onWillDisappear fire
+                    // BEFORE the animation and would double-invoke createFocusEffect, so they only log.
+                    [SCREEN_ON_WILL_APPEAR]: () => dlog(`Stack: route "${current.name}" will appear at t=${Date.now()}`),
+                    [SCREEN_ON_APPEAR]: () => {
+                        dlog(`Stack: route "${current.name}" appeared (focus) at t=${Date.now()}`);
+                        emitter.emit(NAVIGATION_EVENT_FOCUS);
+                    },
+                    [SCREEN_ON_WILL_DISAPPEAR]: () => dlog(`Stack: route "${current.name}" will disappear at t=${Date.now()}`),
+                    [SCREEN_ON_DISAPPEAR]: () => {
+                        dlog(`Stack: route "${current.name}" disappeared (blur) at t=${Date.now()}`);
+                        emitter.emit(NAVIGATION_EVENT_BLUR);
+                    },
+                },
+                searchBarPassthrough: searchBarOptions === undefined
+                    ? undefined
+                    : {
+                        ...buildSearchBarPassthrough(searchBarOptions, message => dlog(`Stack: route "${current.name}" ${message}`)),
+                        // The imperative ref (ISearchBarCommands): `spread` calls a `ref` found in the bag
+                        // with the host node, so it rides down inside passthrough untouched.
+                        ref: (element) => {
+                            const node = isSymbioteNode(element) ? element : null;
+                            if (node === lastSearchBarNode)
+                                return;
+                            lastSearchBarNode = node;
+                            dlog(`Stack: search bar ref, node=${node === null ? 'null' : debugNodeId(node)}`);
+                            searchBarOptions.ref?.(node === null ? null : buildSearchBarHandle(() => node));
+                        },
+                    },
+            });
+        }, undefined);
+        // NOT an early `return undefined` when the plan is still unresolved. <For> maps a key exactly
+        // ONCE, so bailing here would strand the route with nothing to paint for the rest of its life -
+        // and an unresolved plan is the NORMAL first state, since the markers register after the
+        // navigator's body has run (header note 1).
+        const shape = createMemo(() => {
+            const current = plan();
+            if (current === undefined)
+                return undefined;
+            return {
+                viewName: current.screenViewName,
+                inModal: current.inModal,
+                hasSearchBar: current.searchBarProps !== undefined,
+            };
+        }, undefined, {
+            equals: (a, b) => a === b || (a !== undefined && b !== undefined && sameShape(a, b)),
+        });
+        function buildScreen(current) {
+            // Re-read rather than closed over: this runs on every rebuild boundary crossing, and the
+            // fallbacks below keep the live accessors from ever seeing `undefined` mid-teardown.
+            const builtPlan = plan();
+            const builtRoute = route();
+            const builtEntry = entry();
+            if (builtPlan === undefined ||
+                builtRoute === undefined ||
+                builtEntry === undefined) {
+                dlog(`Stack: no screen registered for route key "${routeKey}"`);
+                return undefined;
+            }
+            const livePlan = () => plan() ?? builtPlan;
+            const liveRoute = () => route() ?? builtRoute;
+            const initialComponent = builtEntry.component;
+            const scope = () => ({
+                route: liveRoute(),
+                navigation: handle,
+                emitter,
+                parent: parentScope?.(),
+            });
+            // The narrower boundary inside the shape one: a screen swapping its `component` rebuilds only
+            // the body, never the native screen.
+            const component = createMemo(() => entry()?.component ?? initialComponent);
+            // Must not be flattened away (collapsable: false, supplied by contentWrapperProps) -
+            // react-native-screens' native side finds THIS view type by class check to register a
+            // formSheet's content for sizing (RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME in core/constants.ts).
+            const contentWrapper = hostElement(RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME, () => livePlan().contentWrapperProps);
+            insert(contentWrapper, createComponent(NavigationScopeProvider, {
+                value: scope,
+                // The screen component is created HERE, inside the Provider's own children resolution,
+                // not in a memo declared above it - a Solid computation captures its owner at CREATION,
+                // so a component built outside this getter would run with the enclosing owner and see no
+                // navigation scope at all (useRoute would throw). Reading `component()` tracked makes the
+                // getter the rebuild boundary for a component swap; `untrack` around the build keeps the
+                // screen's own prop reads out of that boundary. No route/navigation props: the screen
+                // reads both through the primitives off the scope provided here.
+                get children() {
+                    const Component = component();
+                    return untrack(() => createComponent(Component, {}));
+                },
+            }));
+            // The header config (and its RNSSearchBar child, when the screen has one) is a pure
+            // Descriptor leaf, so it goes through the shared bridge verbatim, exactly like React's and
+            // Vue's do. Its child COUNT is part of `shape` above, which is what keeps the bridge's
+            // shape-stability contract satisfied when an app adds or removes headerSearchBarOptions.
+            const headerConfig = descriptorToSolid(() => livePlan().headerConfig);
+            const screen = hostElement(current.viewName, () => livePlan().screenProps);
+            if (!current.inModal) {
+                insertNode(screen, headerConfig);
+                insertNode(screen, contentWrapper);
+                return screen;
+            }
+            // A modal/formSheet screen has no UINavigationController of its own on iOS - nest an inner
+            // RNSScreenStack/RNSScreen purely to host the native header bar. Skipping this leaves
+            // RNSScreenStackHeaderConfig with no navigation controller to attach to, so the header
+            // silently never renders.
+            const innerStack = hostElement(RNS_SCREEN_STACK_VIEW_NAME, () => ({
+                style: livePlan().innerStackStyle,
+            }));
+            // activityState mirrors the outer Screen's - RNSScreen.mm treats an unset/inactive nested
+            // screen as not yet pushed, leaving it parked at its pre-push transition position (off past
+            // the bottom edge) instead of its real, presented frame.
+            const innerScreen = hostElement(RNS_SCREEN_VIEW_NAME, () => ({
+                style: livePlan().innerScreenStyle,
+                activityState: livePlan().activityState,
+            }));
+            insertNode(innerScreen, headerConfig);
+            insertNode(innerScreen, contentWrapper);
+            insertNode(innerStack, innerScreen);
+            insertNode(screen, innerStack);
+            return screen;
+        }
+        return createMemo(() => {
+            const current = shape();
+            if (current === undefined)
+                return undefined;
+            return untrack(() => buildScreen(current));
+        });
+    }
+    // Investigation instrumentation (flicker-on-focus bug): STACK_ON_FINISH_TRANSITIONING is the
+    // native signal that the WHOLE push/pop animation finished, as opposed to the per-screen
+    // onAppear/onDisappear. Kept behind DEBUG, never removed.
+    const stackProps = resolveStackProps({
+        passthrough: {
+            [STACK_ON_FINISH_TRANSITIONING]: () => dlog(`Stack: onFinishTransitioning at t=${Date.now()}`),
+        },
+    });
+    const root = hostElement(RNS_SCREEN_STACK_VIEW_NAME, () => stackProps);
+    // The <For> component is created EAGERLY and handed to `insert` as a value, never as
+    // `() => createComponent(For, …)`. The latter would read `each` inside insert's own render
+    // effect, so every route change would re-create the whole list instead of letting For's keyed
+    // mapping reuse the screens it already built.
+    insert(root, createComponent(For, {
+        get each() {
+            return routeKeys();
+        },
+        children: renderRoute,
+    }));
+    onCleanup(() => emitters.clear());
+    // `props.children` is READ here and nowhere else: reading it is what CREATES the markers, and
+    // they must be created inside this Provider so their collectStackScreen() finds the collector on
+    // the owner chain. They paint nothing, so the array is effectively just `root` - and `root` is a
+    // pre-built node reference, so a marker list that changes re-runs this getter without disturbing
+    // the navigator tree.
+    return createComponent(ScreenCollectorProvider, {
+        value: collector,
+        get children() {
+            return [props.children, root];
+        },
+    });
+}
+export const Stack = Object.assign(StackImpl, { Screen });

package/build/solid/tab-screen-props.d.ts

@@ -0,0 +1,13 @@
+import type { Component } from 'solid-js';
+import type { IRoute, ITabNavigatorHandle, ITabOptions } from '../core';
+export type ITabScreenOptionsArgs = {
+    route: IRoute<unknown>;
+    navigation: ITabNavigatorHandle;
+};
+export type ITabScreenOptionsResolver = (args: ITabScreenOptionsArgs) => ITabOptions;
+export type ITabScreenProps = {
+    name: string;
+    component: Component;
+    options?: ITabOptions | ITabScreenOptionsResolver;
+    initialParams?: unknown;
+};

package/build/solid/tab-screen-props.js

@@ -0,0 +1,3 @@
+// Tab.Screen's public prop types. Same split rationale as screen-props.ts: `component` is a Solid
+// value, everything else rides on the agnostic base from ../core.
+export {};

package/build/solid/tabs/index.d.ts

@@ -0,0 +1,14 @@
+import type { JSX } from '@symbiote-native/solid/jsx-runtime';
+import type { ITabNavigatorHandle, ITabOptions } from '../../core';
+import { TabScreen } from '../screen';
+export type { ITabNavigatorHandle } from '../../core';
+export type ITabProps = {
+    initialRouteName?: string;
+    screenOptions?: ITabOptions;
+    ref?: (handle: ITabNavigatorHandle) => void;
+    children?: JSX.Element;
+};
+declare function TabImpl(props: ITabProps): JSX.Element;
+export declare const Tab: typeof TabImpl & {
+    Screen: typeof TabScreen;
+};

package/build/solid/tabs/index.js

@@ -0,0 +1,228 @@
+// Tab, the Solid lifecycle half. The focused-index router (tab-router-state) and the tab-bar
+// Descriptor builder (render-tabs) live in @symbiote-native/navigation core, shared verbatim with
+// every other adapter; here Solid supplies the lifecycle - a signal for the dispatched router
+// state, a callback `ref` for the jumpTo/setParams handle - plus the descriptor bridge for the
+// tab-bar leaf. Unlike Stack, a bottom-tabs bar is a PURE-JS UI painting ordinary
+// `symbiote-view`/`symbiote-text` primitives, so there is no react-native-screens ViewConfig to
+// register here.
+//
+// TWO SOLID-ONLY REBUILD BOUNDARIES, both invisible in every other adapter:
+//
+// 1. THE TAB BAR'S SHAPE FOLLOWS ITS DATA. renderTabBar emits one child per item, and each item
+//    emits an icon wrapper only when it has an icon or a badge - so adding a screen, or a badge
+//    appearing, CHANGES the Descriptor's shape, which descriptorToSolid's shape guard rejects by
+//    design (it builds once and updates props in place). `barSignature` captures exactly the parts
+//    of the data the shape depends on, and the bar is rebuilt when that string changes and only
+//    then. Every other adapter re-renders the whole bar every time and never meets this.
+//
+// 2. ONLY THE FOCUSED SCREEN IS MOUNTED, so a focus change is a genuine rebuild while a
+//    `setParams` on the focused route must NOT be. The content memo therefore depends on the
+//    focused route KEY and its component identity alone, with the build `untrack`ed
+//    (.claude/rules/solid-descriptor-bridge.md §5); the route object itself reaches the screen
+//    through the scope accessor, which is what keeps useRoute() live without rebuilding anything.
+import { createEffect, createMemo, createSignal, untrack } from 'solid-js';
+import { descriptorToSolid } from '@symbiote-native/solid';
+// createComponent from solid-js, insert from the renderer - see stack/index.ts's note.
+import { createComponent } from 'solid-js';
+import { insert } from '@symbiote-native/solid/renderer';
+import { dlog } from '@symbiote-native/engine';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS, createInitialTabState, createNavigationEmitter, diffFocusedRoute, isFocusedRoute, reconcileTabRoutes, renderTabBar, tabRouterReducer, } from '../../core/index.js';
+import { hostElement } from '../host.js';
+import { NavigationScopeProvider, useNavigationScope, } from '../navigation-context.js';
+import { ScreenCollectorProvider, createScreenSignal, toRegistry, } from '../screen-registry.js';
+import { TabScreen } from '../screen.js';
+const TAB_CONTENT_STYLE = { flex: 1 };
+const TAB_ROOT_STYLE = { flex: 1 };
+let navigatorSequence = 0;
+function resolveTabOptions(entry, args, screenOptions) {
+    const own = typeof entry.options === 'function' ? entry.options(args) : entry.options;
+    return { ...screenOptions, ...own };
+}
+// A Descriptor icon is spliced into the bar verbatim, so only its ROOT type is visible here - an
+// app that swaps one Descriptor icon for another of the same type but a different child count
+// would still trip the bridge's shape guard, with the guard's own message. That is the honest
+// boundary: this signature covers the shape decisions render-tabs.ts itself makes.
+function iconKind(icon) {
+    if (icon === undefined)
+        return '-';
+    return typeof icon === 'string' ? 'glyph' : icon.type;
+}
+function barSignature(items) {
+    return items
+        .map(item => `${item.key}:${iconKind(item.icon)}:${item.badge === undefined ? 0 : 1}`)
+        .join('|');
+}
+function TabImpl(props) {
+    // Read BEFORE this Tab provides its own per-screen scope - becomes the `parent` link a nested
+    // screen's useNavigation().getParent() walks. undefined when this Tab is the nesting root.
+    const parentScope = useNavigationScope();
+    const { screens, collector } = createScreenSignal('tab');
+    const registry = createMemo(() => toRegistry(screens()));
+    navigatorSequence += 1;
+    const routeIdPrefix = `tab-${navigatorSequence}`;
+    // Route keys are derived from the screen NAME, never a counter: a Tab's route list is rebuilt
+    // from the registry on every registration change, and a counter would mint a fresh key each time,
+    // re-mounting every screen for an unrelated marker edit.
+    const routes = createMemo(() => [...registry().entries()].map(([name, entry]) => ({
+        key: `${routeIdPrefix}-${name}`,
+        name,
+        params: entry.initialParams,
+    })));
+    // `null` means nothing has dispatched yet, which is what keeps initialRouteName honored when the
+    // markers arrive after the body has already run (screen-registry.ts).
+    const [dispatched, setDispatched] = createSignal(null);
+    const state = createMemo(() => {
+        const current = routes();
+        const previous = dispatched();
+        return previous === null
+            ? createInitialTabState(current, props.initialRouteName)
+            : reconcileTabRoutes(previous, current);
+    });
+    function dispatch(action) {
+        setDispatched(tabRouterReducer(state(), action));
+    }
+    const jumpTo = (name, params) => dispatch({ type: 'jumpTo', name, params });
+    const setParams = (params, key) => dispatch({ type: 'setParams', key, params });
+    const handle = { jumpTo, setParams };
+    props.ref?.(handle);
+    // One emitter per route.key, created lazily and cached for the navigator's whole lifetime. Emitter
+    // IDENTITY (stable, looked up by key) is deliberately decoupled from emit TIMING (deferred below):
+    // a scheme that recreated the emitter on each focus change raced the build of the very screen that
+    // was supposed to subscribe to it.
+    const emitters = new Map();
+    function emitterFor(routeKey) {
+        let emitter = emitters.get(routeKey);
+        if (emitter === undefined) {
+            emitter = createNavigationEmitter();
+            emitters.set(routeKey, emitter);
+        }
+        return emitter;
+    }
+    const focusedKey = createMemo(() => {
+        const current = state();
+        return current.routes[current.index]?.key;
+    });
+    // Tab paints its own bar in pure JS - there is no native onAppear/onDisappear to hook (unlike
+    // Stack's RNSScreen), so focus/blur is synthesized here. The emit is deferred to a microtask,
+    // which resolves only after Solid's whole effect flush has drained - including the build of the
+    // newly focused screen and the subscriptions createIsFocused/createFocusEffect register inside
+    // it. Emitting inline would reach zero subscribers.
+    let lastFocusedKey;
+    createEffect(() => {
+        const nextKey = focusedKey();
+        const { blurKey, focusKey } = diffFocusedRoute(lastFocusedKey, nextKey);
+        if (blurKey === undefined && focusKey === undefined)
+            return;
+        lastFocusedKey = nextKey;
+        queueMicrotask(() => {
+            if (blurKey !== undefined) {
+                dlog(`Tab: route "${blurKey}" blurred at t=${Date.now()}`);
+                emitterFor(blurKey).emit(NAVIGATION_EVENT_BLUR);
+            }
+            if (focusKey !== undefined) {
+                dlog(`Tab: route "${focusKey}" focused at t=${Date.now()}`);
+                emitterFor(focusKey).emit(NAVIGATION_EVENT_FOCUS);
+            }
+        });
+    });
+    const items = createMemo(() => {
+        const current = state();
+        const entries = registry();
+        return current.routes.map((route, index) => {
+            const entry = entries.get(route.name);
+            const focused = isFocusedRoute(index, current.index);
+            if (entry === undefined) {
+                dlog(`Tab: no screen registered for route name "${route.name}"`);
+                return { key: route.key, focused, label: route.name, passthrough: {} };
+            }
+            const options = resolveTabOptions(entry, { route, navigation: handle }, props.screenOptions);
+            return {
+                key: route.key,
+                focused,
+                label: options.tabBarLabel ?? options.title ?? route.name,
+                icon: options.tabBarIcon,
+                badge: options.tabBarBadge,
+                activeTintColor: options.tabBarActiveTintColor,
+                inactiveTintColor: options.tabBarInactiveTintColor,
+                passthrough: {
+                    onPress: () => jumpTo(route.name),
+                    accessibilityRole: 'tab',
+                    accessibilityState: { selected: focused },
+                },
+            };
+        });
+    });
+    const focusedOptions = createMemo(() => {
+        const current = state();
+        const route = current.routes[current.index];
+        const entry = route === undefined ? undefined : registry().get(route.name);
+        if (entry === undefined || route === undefined)
+            return props.screenOptions;
+        return resolveTabOptions(entry, { route, navigation: handle }, props.screenOptions);
+    });
+    // Header note 1: the bar is rebuilt only when its Descriptor SHAPE would change; every tint,
+    // label and badge-value change flows through descriptorToSolid's prop diff on the live nodes.
+    const barShape = createMemo(() => barSignature(items()));
+    const tabBar = createMemo(() => {
+        barShape();
+        return untrack(() => descriptorToSolid(() => renderTabBar({
+            items: items(),
+            style: focusedOptions()?.tabBarStyle,
+            passthrough: {},
+        })));
+    });
+    // Header note 2. Only the focused route's screen is ever mounted (unlike Stack, which keeps every
+    // pushed route alive), so the previous screen's whole subtree - and every listener it registered
+    // - is torn down by Solid's ordinary disposal when focus moves on.
+    const focusedComponent = createMemo(() => {
+        const current = state();
+        const route = current.routes[current.index];
+        return route === undefined
+            ? undefined
+            : registry().get(route.name)?.component;
+    });
+    const content = createMemo(() => {
+        const routeKey = focusedKey();
+        const Component = focusedComponent();
+        return untrack(() => {
+            if (routeKey === undefined || Component === undefined)
+                return undefined;
+            const scope = () => ({
+                route: routeFor(routeKey),
+                navigation: handle,
+                emitter: emitterFor(routeKey),
+                parent: parentScope?.(),
+            });
+            return createComponent(NavigationScopeProvider, {
+                value: scope,
+                // No route/navigation props: the screen reads both through the primitives off the scope
+                // provided here (useRoute / useTabNavigation).
+                get children() {
+                    return createComponent(Component, {});
+                },
+            });
+        });
+    });
+    // Reads the CURRENT object for a key rather than closing over the one that was focused at build
+    // time - the accessor is what makes `setParams` reach a mounted screen's useRoute().
+    function routeFor(routeKey) {
+        const found = state().routes.find(route => route.key === routeKey);
+        return found ?? { key: routeKey, name: '', params: undefined };
+    }
+    const contentHost = hostElement('symbiote-view', () => ({
+        style: TAB_CONTENT_STYLE,
+    }));
+    insert(contentHost, content);
+    const root = hostElement('symbiote-view', () => ({ style: TAB_ROOT_STYLE }));
+    // ONE array insert rather than two: a second `insert` on the same parent would find the first
+    // child already there and REPLACE it (solid-js/universal's insertExpression), while an array is
+    // reconciled by identity - contentHost keeps its node, only the bar is swapped when it rebuilds.
+    insert(root, () => [contentHost, tabBar()]);
+    return createComponent(ScreenCollectorProvider, {
+        value: collector,
+        get children() {
+            return [props.children, root];
+        },
+    });
+}
+export const Tab = Object.assign(TabImpl, { Screen: TabScreen });

package/build/svelte/descriptor-subtree.js

@@ -15,7 +15,9 @@ import { mountDescriptorChildren } from '@symbiote-native/svelte/native-view-bri
 const TEXT_CHILD_MARK = '#';
 function shapeOf(children) {
     return children
-        .map(child => typeof child === 'string' ? TEXT_CHILD_MARK : `${child.type}(${shapeOf(child.children)})`)
+        .map(child => typeof child === 'string'
+        ? TEXT_CHILD_MARK
+        : `${child.type}(${shapeOf(child.children)})`)
         .join(',');
 }
 export function createDescriptorSubtreeSync() {