@symbiote-native/navigation 1.0.0

package/src/vue/tabs/index.ts

@@ -0,0 +1,302 @@
+// 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 type { VNode } 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';
+import type {
+  INavigationEmitter,
+  IRoute,
+  ITabBarItemView,
+  ITabNavigatorHandle,
+  ITabOptions,
+} from '../../core';
+import { NavigationScope, injectNavigationScope } from '../navigation-context';
+import { TabScreen } from '../tab-screen';
+import type { ITabScreenOptionsArgs, ITabScreenProps } from '../tab-screen';
+
+export type { ITabNavigatorHandle } from '../../core';
+
+// React's `children?: ReactNode` becomes Vue's default slot instead (registered screens, read via
+// collectRegistry below).
+export type ITabProps = {
+  initialRouteName?: string;
+  screenOptions?: ITabOptions;
+};
+
+type ITabRegistryEntry = {
+  component: ITabScreenProps['component'];
+  options: ITabScreenProps['options'];
+  initialParams: unknown;
+};
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function asComponent(value: unknown): ITabScreenProps['component'] | undefined {
+  if (typeof value === 'function') return value as ITabScreenProps['component'];
+  return isRecord(value) ? (value as ITabScreenProps['component']) : 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: unknown): ITabOptions | undefined {
+  return isRecord(value) ? (value as ITabOptions) : undefined;
+}
+
+function asTabOptionsOrResolver(value: unknown): ITabScreenProps['options'] {
+  if (typeof value === 'function') return value as ITabScreenProps['options'];
+  return asTabOptions(value);
+}
+
+function collectRegistry(vnodes: readonly VNode[]): Map<string, ITabRegistryEntry> {
+  const registry = new Map<string, ITabRegistryEntry>();
+  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: ITabRegistryEntry,
+  screenComponentProps: ITabScreenOptionsArgs,
+  screenOptions: ITabOptions | undefined,
+): ITabOptions {
+  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<ITabProps>(
+  (_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: Map<string, ITabRegistryEntry>): IRoute<unknown>[] {
+      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: Parameters<typeof tabRouterReducer>[1]): void {
+      state.value = tabRouterReducer(state.value, action);
+    }
+
+    const jumpTo = (name: string, params?: unknown): void =>
+      dispatch({ type: 'jumpTo', name, params });
+    const setParams = (params: unknown, key: string): void =>
+      dispatch({ type: 'setParams', key, params });
+
+    const handle: ITabNavigatorHandle = { 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: typeof state.value): string | undefined {
+      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<string, INavigationEmitter>();
+    function emitterFor(routeKey: string): INavigationEmitter {
+      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: IRoute<unknown> | undefined = state.value.routes[state.value.index];
+
+      const items: ITabBarItemView[] = 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: ITabOptions | undefined =
+        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/src/vue/tabs/tabs.test.ts

@@ -0,0 +1,278 @@
+// Co-located Vue-driven pipeline test, the Vue twin of react/tabs.test.tsx. Unlike Stack (which
+// drives real native RNSScreen views and needs an injected codegen-shaped ViewConfig - see
+// stack.test.ts), the tab bar is a PURE-JS UI painted from ordinary `symbiote-view`/`symbiote-text`
+// primitives, so no ViewConfig source is needed here at all. Proves: only the focused route's
+// screen mounts, jumpTo() moves focus, a tap (synthesized by the engine from a
+// topTouchStart/topTouchEnd pair on the tab button) drives the same jumpTo, and per-tab options
+// (label/badge/tint) reach the tab bar.
+
+import { defineComponent, h, ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount } from '@symbiote-native/vue';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+import { Tab } from './index';
+import type { ITabNavigatorHandle } from './index';
+import { useFocusEffect, useIsFocused, useNavigation, useRoute } from '../composables';
+
+const ROOT_TAG = 4640;
+const TOUCH_START = 'topTouchStart';
+const TOUCH_END = 'topTouchEnd';
+
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function findAllText(nodes: readonly IFakeNode[]): string[] {
+  const found: string[] = [];
+  const collect = (list: readonly IFakeNode[]): void => {
+    for (const node of list) {
+      if (node.viewName === 'RCTRawText' && typeof node.props.text === 'string')
+        found.push(node.props.text);
+      collect(node.children);
+    }
+  };
+  collect(nodes);
+  return found;
+}
+
+// The tab bar row: the second child of Tab's root `symbiote-view` (content wrapper first, bar
+// second - see tabs.ts's final h() call).
+function tabBarRow(): IFakeNode {
+  const root = fabric.appRoot();
+  const tabRoot = root.children[0];
+  const bar = tabRoot?.children[1];
+  if (!bar) throw new Error('no tab bar row was committed');
+  return bar;
+}
+
+async function tapItem(index: number): Promise<void> {
+  const item = tabBarRow().children[index];
+  if (!item) throw new Error(`no tab item at index ${index}`);
+  fabric.fireEvent(item.instanceHandle, TOUCH_START, {
+    touches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+    changedTouches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+  });
+  fabric.fireEvent(item.instanceHandle, TOUCH_END, {
+    touches: [],
+    changedTouches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+  });
+  await tick();
+}
+
+function HomeScreen() {
+  return h('symbiote-text', {}, 'home');
+}
+
+function ProfileScreen() {
+  return h('symbiote-text', {}, 'profile');
+}
+
+describe('Vue Tab navigator', () => {
+  it('mounts only the initial focused route content, and the tab bar for every registered route', async () => {
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, {
+              name: 'Home',
+              component: HomeScreen,
+              options: { tabBarLabel: 'Home' },
+            }),
+            h(Tab.Screen, {
+              name: 'Profile',
+              component: ProfileScreen,
+              options: { tabBarLabel: 'Profile' },
+            }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(findAllText(fabric.committed)).toContain('home');
+    expect(findAllText(fabric.committed)).not.toContain('profile');
+    expect(tabBarRow().children).toHaveLength(2);
+    expect(findAllText(tabBarRow().children)).toEqual(['Home', 'Profile']);
+  });
+
+  it('jumpTo() switches the focused screen content', async () => {
+    const handleRef = ref<ITabNavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: HomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    handleRef.value?.jumpTo('Profile');
+    await tick();
+    expect(findAllText(fabric.committed)).toContain('profile');
+    expect(findAllText(fabric.committed)).not.toContain('home');
+  });
+
+  it('a tap on a tab bar item drives the same jumpTo as the imperative handle', async () => {
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: HomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(findAllText(fabric.committed)).toContain('home');
+    await tapItem(1);
+    expect(findAllText(fabric.committed)).toContain('profile');
+    expect(findAllText(fabric.committed)).not.toContain('home');
+  });
+
+  it('jumpTo() to an unknown route name is a no-op', async () => {
+    const handleRef = ref<ITabNavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: HomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    handleRef.value?.jumpTo('Nowhere');
+    await tick();
+    expect(findAllText(fabric.committed)).toContain('home');
+  });
+
+  it('exposes route.params to the focused screen via useRoute() after jumpTo', async () => {
+    let receivedParams: unknown;
+    const ParamsScreen = defineComponent(() => {
+      const route = useRoute();
+      return () => {
+        receivedParams = route.value.params;
+        return h('symbiote-text', {}, 'params');
+      };
+    });
+    const handleRef = ref<ITabNavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: HomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: ParamsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    handleRef.value?.jumpTo('Profile', { id: 42 });
+    await tick();
+    expect(receivedParams).toEqual({ id: 42 });
+  });
+
+  it('resolves tabBarBadge onto the focused-agnostic tab item', async () => {
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: HomeScreen, options: { tabBarBadge: 3 } }),
+            h(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(findAllText(tabBarRow().children)).toContain('3');
+  });
+
+  // Before this fix, Tab never wrapped its focused screen in a NavigationScope at all, so every
+  // one of these composables threw "must be used within a screen rendered by <Stack>" the moment
+  // a Tab screen called them. These cases prove the scope is now provided and the focus semantics
+  // are wired.
+  it('useNavigation()/useRoute() are usable inside a Tab screen, and useIsFocused() reflects the focused tab', async () => {
+    let homeIsFocused: boolean | undefined;
+    let homeRouteName: string | undefined;
+    let profileIsFocused: boolean | undefined;
+
+    // Plain functions used as `component:` are stateless functional components - Vue calls them
+    // fresh on every render and treats their return value as vnodes directly, NOT as a "setup
+    // returns a render fn" component. A screen calling a composable needs a real setup-based
+    // component (onMounted/inject require a persistent instance across renders), hence
+    // defineComponent here instead of a bare function.
+    const TrackedHomeScreen = defineComponent(() => {
+      const navigation = useNavigation();
+      const isFocused = useIsFocused();
+      const route = useRoute();
+      expect(typeof navigation.value.jumpTo).toBe('function');
+      return () => {
+        homeIsFocused = isFocused.value;
+        homeRouteName = route.value.name;
+        return h('symbiote-text', {}, 'home');
+      };
+    });
+    const TrackedProfileScreen = defineComponent(() => {
+      const isFocused = useIsFocused();
+      return () => {
+        profileIsFocused = isFocused.value;
+        return h('symbiote-text', {}, 'profile');
+      };
+    });
+
+    const handleRef = ref<ITabNavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: TrackedProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    expect(homeIsFocused).toBe(true);
+    expect(homeRouteName).toBe('Home');
+
+    handleRef.value?.jumpTo('Profile');
+    await tick();
+    expect(profileIsFocused).toBe(true);
+  });
+
+  it('useFocusEffect runs on Tab focus and its cleanup once jumpTo moves focus away', async () => {
+    const events: string[] = [];
+    const TrackedHomeScreen = defineComponent(() => {
+      useFocusEffect(() => {
+        events.push('effect');
+        return () => events.push('cleanup');
+      });
+      return () => h('symbiote-text', {}, 'home');
+    });
+
+    const handleRef = ref<ITabNavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Tab, { ref: handleRef, initialRouteName: 'Home' }, () => [
+            h(Tab.Screen, { name: 'Home', component: TrackedHomeScreen }),
+            h(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+          ]),
+      }),
+    );
+    await tick();
+    // Tab paints no native RNSScreen (unlike Stack), so there is no onAppear to wait for - the
+    // focused screen's useFocusEffect runs as soon as it mounts.
+    expect(events).toEqual(['effect']);
+
+    handleRef.value?.jumpTo('Profile');
+    await tick();
+    expect(events).toEqual(['effect', 'cleanup']);
+  });
+});

package/symbiote-navigation.podspec

@@ -0,0 +1,84 @@
+require 'json'
+require 'fileutils'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+native_screens_package_json = `node --print "require.resolve('react-native-screens/package.json', { paths: [process.argv[1]] })" "#{__dir__}"`.strip
+native_screens_root = File.dirname(native_screens_package_json)
+
+# CocoaPods enumerates a pod's files with ONE recursive `Dir.glob(root + '**/*')` walk
+# (Sandbox::PathList#read_file_system), and Ruby's `**` never descends into a symlinked
+# subdirectory it encounters mid-walk (confirmed: it lists the symlink as an entry but
+# never recurses into it) — true whether the symlink crosses the app's node_modules or
+# points straight at the vendored library. react-native-screens lives behind pnpm's own
+# .pnpm-store symlinks, so no relative-path or same-directory-symlink trick can reach it;
+# the files must be REAL entries under this pod's own directory. Physically vendor them
+# (directories stay real, so `**` still recurses through them normally) instead of trying
+# to glob through any symlink. If this glob ever matches zero files, thirdPartyFabricComponents
+# silently gets a nil class entry and Fabric crashes building that dictionary at app startup —
+# not a build-time error, since NSClassFromString only resolves at runtime.
+vendor_dir = File.join(__dir__, '.rn-screens')
+FileUtils.rm_rf(vendor_dir)
+FileUtils.mkdir_p(vendor_dir)
+%w[ios common cpp].each do |subdir|
+  src = File.join(native_screens_root, subdir)
+  FileUtils.cp_r(src, File.join(vendor_dir, subdir)) if File.directory?(src)
+end
+
+# Swift is excluded: react-native-screens' own podspec only sets DEFINES_MODULE (required
+# for its Swift files to build) under an opt-in "gamma" flag, precisely because it conflicts
+# with React-RCTImage (a dependency both that podspec and this one carry) not defining a
+# module — their own comment says as much ("we can not have Swift code in stable package").
+# The only non-gamma Swift file (ios/utils/RNSLog.swift) is a logging helper unused by
+# RNSScreen/RNSScreenStack/RNSScreenStackHeaderConfig; everything that imports the Swift
+# bridging header lives under ios/gamma/, which is already excluded below. So the stable
+# native-stack surface never needs Swift compiled at all — matching upstream's own default.
+source_files_exts = '{h,m,mm,cpp}'
+
+Pod::Spec.new do |s|
+  s.name         = 'symbiote-navigation'
+  s.version      = package['version']
+  s.summary      = 'Symbiote wrapper for react-native-screens native stack primitives.'
+  s.license      = package['license'] || 'MIT'
+  s.authors      = package['author'] || 'symbiote'
+  s.homepage     = package['homepage'] || 'https://github.com/symbiote/symbiote'
+  s.platforms    = { :ios => '15.1', :visionos => '1.0' }
+  s.source       = { :git => 'https://github.com/symbiote/symbiote.git', :tag => "v#{s.version}" }
+
+  s.source_files  = ".rn-screens/ios/**/*.#{source_files_exts}"
+  s.exclude_files = ".rn-screens/ios/gamma/**/*.#{source_files_exts}"
+
+  s.subspec 'common' do |ss|
+    ss.source_files = [
+      '.rn-screens/common/cpp/**/*.{cpp,h}',
+      '.rn-screens/cpp/**/*.{cpp,h}',
+    ]
+    ss.header_dir = 'rnscreens'
+    # Must point at the vendored copy, not native_screens_root: an include resolved via
+    # this search path pulls in a second, physically distinct copy of the same headers
+    # already compiled from .rn-screens/common/cpp, and two distinct files defining the
+    # same class have no shared include guard — "redefinition of 'RNSSafeAreaViewState'".
+    ss.pod_target_xcconfig = {
+      'HEADER_SEARCH_PATHS' => "\"#{File.join(vendor_dir, 'common/cpp')}\""
+    }
+  end
+
+  if defined?(install_modules_dependencies)
+    install_modules_dependencies(s)
+  else
+    s.dependency 'React-Core'
+    s.compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32 -DRCT_NEW_ARCH_ENABLED=1'
+    s.pod_target_xcconfig = {
+      'HEADER_SEARCH_PATHS' => '"$(PODS_ROOT)/boost"',
+      'OTHER_CPLUSPLUSFLAGS' => '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1',
+      'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17'
+    }
+    s.dependency 'React-RCTFabric'
+    s.dependency 'React-Codegen'
+    s.dependency 'RCT-Folly'
+    s.dependency 'RCTRequired'
+    s.dependency 'RCTTypeSafety'
+    s.dependency 'ReactCommon/turbomodule/core'
+  end
+  s.dependency 'React-RCTImage'
+end