@symbiote-native/navigation 2.0.1 → 2.0.2

package/build/vue/stack/index.d.ts

@@ -0,0 +1,9 @@
+import type { IScreenProps, IVueScreenOptions } from '../screen';
+export type { INavigatorHandle } from '../../core';
+export type IStackProps = {
+    initialRouteName?: string;
+    screenOptions?: IVueScreenOptions;
+};
+export declare const Stack: import("vue").DefineSetupFnComponent<IStackProps, {}, {}, IStackProps & {}, import("vue").PublicProps> & {
+    Screen: import("vue").DefineSetupFnComponent<IScreenProps, {}, {}, IScreenProps & {}, import("vue").PublicProps>;
+};

package/build/vue/stack/index.js

@@ -0,0 +1,279 @@
+// Stack, the Vue 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/Angular adapters; here Vue supplies the lifecycle - a plain ref
+// for the pushed-route stack (Vue's twin of useReducer: reassign `.value` from the same pure
+// reducer), useId + a closure counter for route-key generation, expose() for the push/pop/replace
+// navigator handle - plus the descriptor bridge for the header config leaf. Pushing/popping a
+// route is an ordinary child mount/unmount: RNSScreenStack diffs its RNSScreen children natively,
+// so no imperative native command is needed here at all. Neither this nor the Screen marker
+// imports react-native-screens' own React components (ScreenStack.tsx et al - hooks, crashes a
+// non-React adapter); the native views are driven directly through the ViewConfig ../register
+// registers. See CLAUDE.md <third_party_rn_packages_are_react_only>.
+import { defineComponent, h, shallowRef, useId } from '@vue/runtime-core';
+import { descriptorToVue, normalizeVueAttrs } from '@symbiote-native/vue';
+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, computeActivityState, createInitialNavigatorState, createNavigationEmitter, isRecord, navigatorReducer, resolveScreenRenderPlan, resolveStackProps, } from '../../core/index.js';
+import { NavigationScope, injectNavigationScope } from '../navigation-context.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, so a single constant
+// stands in for the per-platform injection point ISliderPlatform-style adapters use elsewhere.
+const NAVIGATOR_PLATFORM = { defaultHeaderBackTitleVisible: true };
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asComponent(value) {
+    if (typeof value === 'function')
+        return value;
+    return isRecord(value) ? value : undefined;
+}
+// screenOptions/options each carry ~20 independently-optional fields (IScreenOptions,
+// navigator-props.ts) forwarded wholesale into the core resolvers below - a per-field guard would
+// just hand-reimplement TypeScript's own structural check, so this narrows only the object-ness at
+// the exact I/O edge where Vue's untyped attrs enter the strongly-typed core surface, per
+// CLAUDE.md's ts-js rule ("the I/O edge where data enters the type system, in the narrowest form").
+function asScreenOptions(value) {
+    return isRecord(value) ? value : undefined;
+}
+function asScreenOptionsOrResolver(value) {
+    if (typeof value === 'function')
+        return value;
+    return asScreenOptions(value);
+}
+function collectRegistry(vnodes) {
+    const registry = new Map();
+    for (const vnode of vnodes) {
+        if (vnode.type !== Screen || !isRecord(vnode.props))
+            continue;
+        const name = asString(vnode.props.name);
+        const component = asComponent(vnode.props.component);
+        if (name === undefined || component === undefined)
+            continue;
+        registry.set(name, {
+            component,
+            options: asScreenOptionsOrResolver(vnode.props.options),
+            initialParams: vnode.props.initialParams,
+        });
+    }
+    return registry;
+}
+function resolveScreenOptions(entry, screenOptionsArgs, screenOptions) {
+    const own = typeof entry.options === 'function' ? entry.options(screenOptionsArgs) : entry.options;
+    return { ...screenOptions, ...own };
+}
+const StackImpl = defineComponent((_props, { attrs: rawAttrs, slots, expose }) => {
+    const attrs = normalizeVueAttrs(rawAttrs);
+    // Read BEFORE this Stack establishes its own per-screen NavigationScope below - becomes
+    // the `parent` link a nested screen's useNavigation().getParent() walks (e.g. this Stack
+    // rendered as a Tab screen's content reaches that Tab via this value). undefined when this
+    // Stack is the nesting root. Kept as the injected ref itself (not unwrapped here) so the
+    // render loop below always reads its CURRENT `.value`, matching React's useContext
+    // re-reading on every render.
+    const ambientScopeRef = injectNavigationScope();
+    const routeIdPrefix = useId();
+    let routeSequence = 0;
+    // One emitter per route.key, keyed exactly like routeSequence's counter is scoped - created
+    // lazily the first time a route is rendered, pruned once it's popped off the stack (below).
+    const emitters = new Map();
+    // Investigation instrumentation (flicker-on-focus bug): route keys whose resolved
+    // transition/animation-timing props have already been logged, so the once-per-mount dump
+    // below doesn't spam on every re-render. Kept behind DEBUG, never removed.
+    const loggedScreenPropKeys = new Set();
+    function emitterFor(routeKey) {
+        let emitter = emitters.get(routeKey);
+        if (emitter === undefined) {
+            emitter = createNavigationEmitter();
+            emitters.set(routeKey, emitter);
+        }
+        return emitter;
+    }
+    function createRoute(name, params) {
+        routeSequence += 1;
+        return { key: `${routeIdPrefix}-${name}-${routeSequence}`, name, params };
+    }
+    const initialRegistry = collectRegistry(slots.default?.() ?? []);
+    const initialRouteName = asString(attrs.initialRouteName) ?? initialRegistry.keys().next().value;
+    let initialState;
+    if (initialRouteName === undefined) {
+        dlog('Stack: no <Stack.Screen> children registered');
+        initialState = createInitialNavigatorState({
+            key: routeIdPrefix,
+            name: '',
+            params: undefined,
+        });
+    }
+    else {
+        initialState = createInitialNavigatorState(createRoute(initialRouteName, initialRegistry.get(initialRouteName)?.initialParams));
+    }
+    const state = shallowRef(initialState);
+    function dispatch(action) {
+        state.value = navigatorReducer(state.value, 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: () => state.value.routes.length > 1,
+    };
+    expose(handle);
+    // Broadcasts the router state to every still-live route's emitter (useNavigationState's
+    // source) after each commit, and prunes emitters for routes popped off the stack - mirroring
+    // React's own subscribe-in-effect pattern. `watch` isn't needed here (unlike React's
+    // useEffect, which must be deferred past render to avoid a descendant setState-during-render):
+    // Vue's provide/inject + shallowRef.value writes are safe to perform directly inside the
+    // render closure below, so the broadcast happens right there, once per render.
+    function broadcastState() {
+        for (const route of state.value.routes) {
+            emitterFor(route.key).emit(NAVIGATION_EVENT_STATE, state.value);
+        }
+        for (const routeKey of emitters.keys()) {
+            if (!state.value.routes.some(route => route.key === routeKey))
+                emitters.delete(routeKey);
+        }
+    }
+    return () => {
+        broadcastState();
+        const registry = collectRegistry(slots.default?.() ?? []);
+        const screenOptions = asScreenOptions(attrs.screenOptions);
+        // Investigation instrumentation (flicker-on-focus bug): STACK_ON_FINISH_TRANSITIONING is
+        // the native signal that the WHOLE push/pop animation has finished (as opposed to
+        // onAppear/onDisappear, which are per-screen) - logging it lets the per-screen
+        // appear/disappear timestamps be checked against the actual transition-complete moment.
+        // Kept behind DEBUG, never removed.
+        const stackProps = resolveStackProps({
+            passthrough: {
+                [STACK_ON_FINISH_TRANSITIONING]: () => dlog(`Stack: onFinishTransitioning at t=${Date.now()}`),
+            },
+        });
+        const children = state.value.routes.map((route, index) => {
+            const entry = registry.get(route.name);
+            if (entry === undefined) {
+                dlog(`Stack: no screen registered for route name "${route.name}"`);
+                return null;
+            }
+            const screenOptionsArgs = { route, navigation: handle };
+            const mergedOptions = resolveScreenOptions(entry, screenOptionsArgs, screenOptions);
+            const activityState = computeActivityState(index, state.value.routes.length);
+            // Investigation instrumentation (flicker-on-focus bug): fires on EVERY Stack render, not
+            // just on transitions, so the log stream shows whether a route's activityState/index ever
+            // changes outside of a push/pop dispatch. Kept behind DEBUG, never removed.
+            dlog(`Stack: render route "${route.name}" index=${index}/${state.value.routes.length - 1} ` +
+                `activityState=${activityState} at t=${Date.now()}`);
+            const routeEmitter = emitterFor(route.key);
+            const searchBarOptions = mergedOptions.headerSearchBarOptions;
+            const plan = resolveScreenRenderPlan({
+                screenId: route.key,
+                index,
+                routeCount: state.value.routes.length,
+                options: mergedOptions,
+                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-
+                    // animation), so 'focus'/'blur' fire exactly once per transition; onWillAppear/
+                    // onWillDisappear fire BEFORE the animation runs, so wiring them to emit() too would
+                    // double-invoke useFocusEffect per transition - they only get a debug log here.
+                    [SCREEN_ON_WILL_APPEAR]: () => dlog(`Stack: route "${route.name}" will appear at t=${Date.now()}`),
+                    [SCREEN_ON_APPEAR]: () => {
+                        dlog(`Stack: route "${route.name}" appeared (focus) at t=${Date.now()}`);
+                        routeEmitter.emit(NAVIGATION_EVENT_FOCUS);
+                    },
+                    [SCREEN_ON_WILL_DISAPPEAR]: () => dlog(`Stack: route "${route.name}" will disappear at t=${Date.now()}`),
+                    [SCREEN_ON_DISAPPEAR]: () => {
+                        dlog(`Stack: route "${route.name}" disappeared (blur) at t=${Date.now()}`);
+                        routeEmitter.emit(NAVIGATION_EVENT_BLUR);
+                    },
+                },
+                searchBarPassthrough: searchBarOptions
+                    ? {
+                        ...buildSearchBarPassthrough(searchBarOptions, message => dlog(`Stack: route "${route.name}" ${message}`)),
+                        // The imperative ref (SearchBarCommands): a function ref attached straight to the
+                        // RNSSearchBar host element via `passthrough.ref` - descriptorToVue's h() call
+                        // hands the raw engine node to a plain function ref same as Switch/TextInput's
+                        // setNodeRef. Built fresh per mount/unmount, never captured eagerly
+                        // (buildSearchBarHandle's own lazy-getter contract is satisfied trivially here
+                        // since `node` is already resolved).
+                        ref: (el) => {
+                            const node = isSymbioteNode(el) ? el : null;
+                            // Investigation instrumentation (search-bar-ref "node not committed" bug):
+                            // compare this debugNodeId against the mirror.set/dispatchViewCommand logs in
+                            // commit.ts - same id on both sides proves the ref really does hold the
+                            // committed node; a mismatch proves a stale closure instead. Kept behind DEBUG,
+                            // never removed.
+                            dlog(`Stack: search bar ref callback, node=${node === null ? 'null' : debugNodeId(node)} at t=${Date.now()}`);
+                            const appRef = searchBarOptions.ref;
+                            if (appRef === undefined)
+                                return;
+                            appRef.value = node === null ? null : buildSearchBarHandle(() => node);
+                        },
+                    }
+                    : undefined,
+            });
+            // Investigation instrumentation (flicker-on-focus bug): the actual timing/z-order-relevant
+            // values resolved onto the native RNSScreen, once per route.key (not every render) -
+            // rules a stackAnimation/transitionDuration mismatch against react-native-screens' own
+            // native default in or out. Kept behind DEBUG, never removed.
+            if (!loggedScreenPropKeys.has(route.key)) {
+                loggedScreenPropKeys.add(route.key);
+                dlog(`Stack: route "${route.name}" resolved screen props ` +
+                    `stackAnimation=${String(plan.screenProps.stackAnimation)} ` +
+                    `stackPresentation=${String(plan.screenProps.stackPresentation)} ` +
+                    `transitionDuration=${String(plan.screenProps.transitionDuration)} ` +
+                    `gestureEnabled=${String(plan.screenProps.gestureEnabled)} at t=${Date.now()}`);
+            }
+            // Must not be flattened away (collapsable: false) - react-native-screens' native side
+            // finds THIS specific view type by class check to register a formSheet's content for
+            // sizing (see RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME's comment in core/constants.ts). A
+            // `push` screen doesn't need it, but a `formSheet` one is otherwise left with no content
+            // ever attached natively.
+            const content = h(RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME, plan.contentWrapperProps, [
+                h(NavigationScope, {
+                    value: {
+                        route,
+                        navigation: handle,
+                        emitter: routeEmitter,
+                        parent: ambientScopeRef?.value,
+                    },
+                }, 
+                // No route/navigation props: the screen reads both through composables off the
+                // NavigationScope provided just above (useRoute / useStackNavigation).
+                () => h(entry.component)),
+            ]);
+            // react-native-screens' own Screen.tsx swaps in a DIFFERENT Fabric component
+            // ('RNSModalScreen') for a modally-presented screen - its native updateLayoutMetrics:
+            // relies on this exact class to know it must NOT apply Yoga's computed frame (see
+            // resolveScreenViewName's comment in core/render-stack.ts). The nested Screen
+            // isHeaderInModal adds below is always plain 'RNSScreen': react-native-screens' own inner
+            // Screen never carries a presentation prop either, since it exists purely to host the
+            // header, not to be modally presented itself.
+            // A modal/formSheet screen has no UINavigationController of its own on iOS - nest an
+            // inner RNSScreenStack/RNSScreen purely to host the native header bar (see
+            // isHeaderInModal's comment in core/render-stack.ts). Skipping this leaves
+            // RNSScreenStackHeaderConfig with no navigation controller to attach to, so the header
+            // silently never renders.
+            return plan.inModal
+                ? h(plan.screenViewName, { key: route.key, ...plan.screenProps }, [
+                    h(RNS_SCREEN_STACK_VIEW_NAME, { style: plan.innerStackStyle }, [
+                        h(RNS_SCREEN_VIEW_NAME, 
+                        // activityState mirrors the outer Screen's own value - react-native-screens'
+                        // 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.
+                        { style: plan.innerScreenStyle, activityState: plan.activityState }, [descriptorToVue(plan.headerConfig), content]),
+                    ]),
+                ])
+                : h(plan.screenViewName, { key: route.key, ...plan.screenProps }, [
+                    descriptorToVue(plan.headerConfig),
+                    content,
+                ]);
+        });
+        return h(RNS_SCREEN_STACK_VIEW_NAME, stackProps, children);
+    };
+}, { name: 'Stack', inheritAttrs: false });
+export const Stack = Object.assign(StackImpl, { Screen });

package/build/vue/tab-screen.d.ts

@@ -0,0 +1,14 @@
+import type { Component } from '@vue/runtime-core';
+import type { IRoute, ITabOptions, ITabNavigatorHandle } from '../core';
+export type ITabScreenOptionsArgs = {
+    route: IRoute<unknown>;
+    navigation: ITabNavigatorHandle;
+};
+export type ITabScreenOptionsResolver = (props: ITabScreenOptionsArgs) => ITabOptions;
+export type ITabScreenProps = {
+    name: string;
+    component: Component;
+    options?: ITabOptions | ITabScreenOptionsResolver;
+    initialParams?: unknown;
+};
+export declare const TabScreen: import("vue").DefineSetupFnComponent<ITabScreenProps, {}, {}, ITabScreenProps & {}, import("vue").PublicProps>;

package/build/vue/tab-screen.js

@@ -0,0 +1,11 @@
+// Tab.Screen: a declarative marker, never rendered on its own - Tab reads its props via a
+// default-slot scan (see tabs.ts's collectRegistry) to build the static name -> {component,
+// options} registry, then mounts the FOCUSED route's component itself. The Vue twin of
+// react/tab-screen.ts's TabScreen, mirroring screen.ts's slot-scanning marker pattern minus the
+// stack-only concepts (no push/pop lifecycle events to wire); see CLAUDE.md
+// <third_party_rn_packages_are_react_only> - this and Tab import nothing from react-native.
+import { defineComponent } from '@vue/runtime-core';
+export const TabScreen = defineComponent(() => () => null, {
+    name: 'TabScreen',
+    inheritAttrs: false,
+});

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

@@ -0,0 +1,10 @@
+import type { ITabOptions } from '../../core';
+import type { ITabScreenProps } from '../tab-screen';
+export type { ITabNavigatorHandle } from '../../core';
+export type ITabProps = {
+    initialRouteName?: string;
+    screenOptions?: ITabOptions;
+};
+export declare const Tab: import("vue").DefineSetupFnComponent<ITabProps, {}, {}, ITabProps & {}, import("vue").PublicProps> & {
+    Screen: import("vue").DefineSetupFnComponent<ITabScreenProps, {}, {}, ITabScreenProps & {}, import("vue").PublicProps>;
+};

package/build/vue/tabs/index.js

@@ -0,0 +1,209 @@
+// Tab, the Vue 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
+// the React/Angular adapters; here Vue supplies the lifecycle - a plain ref for the focused index
+// (Vue's twin of useReducer), useId for route-key generation, expose() for the jumpTo/setParams
+// handle - plus the descriptor bridge for the tab-bar leaf, exactly like Stack bridges its header
+// config (stack.ts). Unlike Stack, a bottom-tabs bar is a PURE-JS UI: it paints ordinary
+// `symbiote-view`/`symbiote-text` primitives via the shared render fn, so there is no
+// react-native-screens ViewConfig to register here - Tab needs no `../register` import.
+import { defineComponent, h, nextTick, onMounted, onUnmounted, shallowRef, useId, watch, } from '@vue/runtime-core';
+import { descriptorToVue, normalizeVueAttrs } from '@symbiote-native/vue';
+import { dlog } from '@symbiote-native/engine';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS, createInitialTabState, createNavigationEmitter, diffFocusedRoute, isFocusedRoute, isRecord, renderTabBar, tabRouterReducer, } from '../../core/index.js';
+import { NavigationScope, injectNavigationScope } from '../navigation-context.js';
+import { TabScreen } from '../tab-screen.js';
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asComponent(value) {
+    if (typeof value === 'function')
+        return value;
+    return isRecord(value) ? value : undefined;
+}
+// ITabOptions carries a handful of independently-optional fields forwarded wholesale into the
+// shared render fn below - same "narrow the object-ness, cast at the exact I/O edge" rationale
+// stack.ts's asScreenOptions documents (CLAUDE.md's ts-js rule).
+function asTabOptions(value) {
+    return isRecord(value) ? value : undefined;
+}
+function asTabOptionsOrResolver(value) {
+    if (typeof value === 'function')
+        return value;
+    return asTabOptions(value);
+}
+function collectRegistry(vnodes) {
+    const registry = new Map();
+    for (const vnode of vnodes) {
+        if (vnode.type !== TabScreen || !isRecord(vnode.props))
+            continue;
+        const name = asString(vnode.props.name);
+        const component = asComponent(vnode.props.component);
+        if (name === undefined || component === undefined)
+            continue;
+        registry.set(name, {
+            component,
+            options: asTabOptionsOrResolver(vnode.props.options),
+            initialParams: vnode.props.initialParams,
+        });
+    }
+    return registry;
+}
+function resolveTabOptions(entry, screenComponentProps, screenOptions) {
+    const own = typeof entry.options === 'function' ? entry.options(screenComponentProps) : entry.options;
+    return { ...screenOptions, ...own };
+}
+const TAB_CONTENT_STYLE = { flex: 1 };
+const TAB_ROOT_STYLE = { flex: 1 };
+const TabImpl = defineComponent((_props, { attrs: rawAttrs, slots, expose }) => {
+    const attrs = normalizeVueAttrs(rawAttrs);
+    // Read BEFORE this Tab establishes its own per-screen NavigationScope below - becomes the
+    // `parent` link a nested screen's useNavigation().getParent() walks (e.g. this Tab rendered
+    // as a Stack screen's content reaches that Stack via this value). undefined when this Tab is
+    // the nesting root.
+    const ambientScopeRef = injectNavigationScope();
+    const routeIdPrefix = useId();
+    function buildRoutes(registry) {
+        return Array.from(registry.entries()).map(([name, entry]) => ({
+            key: `${routeIdPrefix}-${name}`,
+            name,
+            params: entry.initialParams,
+        }));
+    }
+    const initialRegistry = collectRegistry(slots.default?.() ?? []);
+    const initialRoutes = buildRoutes(initialRegistry);
+    if (initialRoutes.length === 0)
+        dlog('Tab: no <Tab.Screen> children registered');
+    const state = shallowRef(createInitialTabState(initialRoutes, asString(attrs.initialRouteName)));
+    function dispatch(action) {
+        state.value = tabRouterReducer(state.value, action);
+    }
+    const jumpTo = (name, params) => dispatch({ type: 'jumpTo', name, params });
+    const setParams = (params, key) => dispatch({ type: 'setParams', key, params });
+    const handle = { jumpTo, setParams };
+    expose(handle);
+    // 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: emit 'focus' once the newly-focused
+    // route's content has mounted, 'blur' when it's about to be replaced or Tab itself unmounts.
+    // Keyed on the route KEY (not the route object) so a setParams-only change (new route object,
+    // same key) doesn't spuriously re-fire focus/blur - mirrors tabs.ts's React twin exactly,
+    // just expressed as a `watch` over the focused key instead of a useEffect dependency array.
+    function focusedKeyOf(current) {
+        return current.routes[current.index]?.key;
+    }
+    // One emitter per route.key, created lazily and cached for the navigator's whole lifetime -
+    // mirrors stack.ts's own `emitters` map. This decouples emitter IDENTITY (stable, looked up
+    // by key, read by the render closure below when it builds a route's NavigationScope) from
+    // emit TIMING (must wait until the focused screen has actually mounted and subscribed): a
+    // scheme that instead tried to recreate/swap `routeEmitter` synchronously on each focus
+    // change raced Vue's own render/mount cycle no matter which watch `flush` timing it used -
+    // 'pre' emits before the new screen's onMounted subscribes, 'post' emits AFTER the render
+    // closure already needed the (still up-to-date) emitter to build that screen's NavigationScope
+    // in the FIRST place. A stable per-key lookup sidesteps the race entirely.
+    const emitters = new Map();
+    function emitterFor(routeKey) {
+        let emitter = emitters.get(routeKey);
+        if (emitter === undefined) {
+            emitter = createNavigationEmitter();
+            emitters.set(routeKey, emitter);
+        }
+        return emitter;
+    }
+    // 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: emit 'focus' once the newly-focused
+    // route's content has mounted, 'blur' when it's about to be replaced or Tab itself unmounts.
+    // Keyed on the route KEY (not the route object) so a setParams-only change (new route object,
+    // same key) doesn't spuriously re-fire focus/blur - mirrors tabs.ts's React twin exactly,
+    // just expressed as a `watch` over the focused key instead of a useEffect dependency array.
+    let focusedRouteKey = focusedKeyOf(state.value);
+    onMounted(() => {
+        if (focusedRouteKey !== undefined) {
+            dlog(`Tab: route "${focusedRouteKey}" focused at t=${Date.now()}`);
+            emitterFor(focusedRouteKey).emit(NAVIGATION_EVENT_FOCUS);
+        }
+    });
+    // The bookkeeping (which key is focused) updates immediately so the render closure below
+    // always reads the right route; the actual emit is deferred to nextTick(), which resolves
+    // only after the CURRENT flush cycle fully drains - including the newly-focused screen's own
+    // onMounted (subscribing its useIsFocused/useFocusEffect listeners). flush:'post' alone is
+    // NOT enough here: it only guarantees this callback runs after THIS component's own render
+    // effect, not after an arbitrary sibling post-flush job (a just-mounted child's onMounted)
+    // that may be queued after it in the same batch - nextTick is the one API that waits for the
+    // WHOLE cycle, not just this watcher's own slot in it.
+    watch(() => focusedKeyOf(state.value), nextKey => {
+        const { blurKey, focusKey } = diffFocusedRoute(focusedRouteKey, nextKey);
+        if (blurKey === undefined && focusKey === undefined)
+            return;
+        focusedRouteKey = nextKey;
+        nextTick(() => {
+            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);
+            }
+        });
+    });
+    onUnmounted(() => {
+        if (focusedRouteKey !== undefined)
+            emitterFor(focusedRouteKey).emit(NAVIGATION_EVENT_BLUR);
+    });
+    return () => {
+        const registry = collectRegistry(slots.default?.() ?? []);
+        const screenOptions = asTabOptions(attrs.screenOptions);
+        if (registry.size === 0)
+            dlog('Tab: no <Tab.Screen> children registered');
+        const focusedRoute = state.value.routes[state.value.index];
+        const items = state.value.routes.map((route, index) => {
+            const entry = registry.get(route.name);
+            const focused = isFocusedRoute(index, state.value.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 }, 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 focusedEntry = focusedRoute ? registry.get(focusedRoute.name) : undefined;
+        const focusedOptions = focusedEntry && focusedRoute
+            ? resolveTabOptions(focusedEntry, { route: focusedRoute, navigation: handle }, screenOptions)
+            : screenOptions;
+        const tabBar = descriptorToVue(renderTabBar({ items, style: focusedOptions?.tabBarStyle, passthrough: {} }));
+        // Only the focused route's screen is ever mounted (unlike Stack, which keeps every pushed
+        // route alive), so a fresh NavigationScope per focus change is sufficient - the previous
+        // screen's whole subtree (and any listeners it registered) is torn down by an ordinary Vue
+        // unmount when focus moves on.
+        const content = focusedEntry && focusedRoute
+            ? h(NavigationScope, {
+                value: {
+                    route: focusedRoute,
+                    navigation: handle,
+                    emitter: emitterFor(focusedRoute.key),
+                    parent: ambientScopeRef?.value,
+                },
+            }, 
+            // No route/navigation props: the screen reads both through composables off the
+            // NavigationScope provided just above (useRoute / useTabNavigation).
+            () => h(focusedEntry.component))
+            : null;
+        return h('symbiote-view', { style: TAB_ROOT_STYLE }, [
+            h('symbiote-view', { style: TAB_CONTENT_STYLE }, content === null ? [] : [content]),
+            tabBar,
+        ]);
+    };
+}, { name: 'Tab', inheritAttrs: false });
+export const Tab = Object.assign(TabImpl, { Screen: TabScreen });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/navigation",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Native stack navigator for SymbioteNative, built on react-native-screens' native view primitives (RNSScreen/RNSScreenStack) — one framework-agnostic core, reachable from the React, Vue, and Angular adapters.",
   "license": "MIT",
   "repository": {
@@ -188,14 +188,14 @@
     "@vue/runtime-core": "^3.5.13",
     "react": "19.2.3",
     "typescript": "~6.0.0",
+    "@symbiote-native/test-utils": "0.1.6",
     "@symbiote-native/angular": "0.6.1",
     "@symbiote-native/react": "0.2.8",
-    "@symbiote-native/test-utils": "0.1.6",
     "@symbiote-native/engine": "0.1.7",
     "@symbiote-native/vue": "0.3.8"
   },
   "scripts": {
-    "clean": "rm -rf build",
+    "clean": "rm -rf build-ngc",
     "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
     "typecheck": "tsc --build",
     "format": "prettier --write \"src/**/*.{ts,tsx}\""