@symbiote-native/navigation 2.0.3 → 2.2.0

package/src/svelte/stack/stack-screen.svelte

@@ -0,0 +1,205 @@
+<script lang="ts" module>
+  import type { INavigatorPlatform } from '../../core';
+
+  // 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: INavigatorPlatform = {
+    defaultHeaderBackTitleVisible: true,
+  };
+
+  // react-native-screens' RNSScreenStackHeaderConfig.mm requires every header child to be an
+  // RNSScreenStackHeaderSubview; `type: 'searchBar'` is how it knows which slot this one fills.
+  const HEADER_SUBVIEW_PROPS: Record<string, unknown> = { type: 'searchBar' };
+</script>
+
+<script lang="ts">
+  // One mounted route's native chrome. Split out of index.svelte so each route owns its own plan
+  // derivation and its own attachments, torn down by an ordinary component unmount when the route
+  // is popped - the Svelte equivalent of Vue's per-route render-loop closure.
+  //
+  // Every react-native-screens view here goes through `<svelte:element this={'RNSScreen'}>`
+  // rather than a literal tag: their Fabric names are capitalized and un-hyphenated, so a literal
+  // tag would parse as a COMPONENT reference in a Svelte template. Their props ride an
+  // `{@attach hostProps(...)}` attachment rather than an attribute, because a dynamic tag
+  // compiles through Svelte's generic setAttribute path and never the custom-element property-SET
+  // path the object bag depends on - see ../attachments.ts for the full reasoning.
+  //
+  // Whitespace between sibling tags in the per-route tree is inert: the shim drops a
+  // whitespace-only text node whose parent takes no raw text, so it never becomes an RCTRawText
+  // child of a react-native-screens view (dom-shim/text.ts, svelte-adapter-dom-shim skill §16b).
+  import { Platform, dlog } from '@symbiote-native/engine';
+  import {
+    NAVIGATION_EVENT_BLUR,
+    NAVIGATION_EVENT_FOCUS,
+    RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME,
+    RNS_SCREEN_STACK_HEADER_CONFIG_VIEW_NAME,
+    RNS_SCREEN_STACK_HEADER_SUBVIEW_VIEW_NAME,
+    RNS_SCREEN_STACK_VIEW_NAME,
+    RNS_SCREEN_VIEW_NAME,
+    RNS_SEARCH_BAR_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,
+    buildSearchBarPassthrough,
+    resolveScreenRenderPlan,
+  } from '../../core';
+  import type { IScreenRenderPlan } from '../../core';
+  import { hostProps, searchBarRef } from '../attachments';
+  import NavigationScope from '../navigation-scope.svelte';
+  import type { INavigationScopeValue } from '../navigation-context';
+  import type { IStackScreenProps } from './stack-props';
+
+  let {
+    route,
+    index,
+    routeCount,
+    options,
+    navigation,
+    emitter,
+    parentScope,
+    // Destructured under a capitalized name because a Svelte template resolves a component tag
+    // only from a capitalized identifier.
+    component: ScreenComponent,
+    onPopRequested,
+  }: IStackScreenProps = $props();
+
+  const searchBarOptions = $derived(options.headerSearchBarOptions);
+
+  const plan = $derived.by<IScreenRenderPlan>(() =>
+    resolveScreenRenderPlan({
+      screenId: route.key,
+      index,
+      routeCount,
+      options,
+      platform: NAVIGATOR_PLATFORM,
+      isAndroid: Platform.OS === 'android',
+      screenPassthrough: {
+        [SCREEN_ON_DISMISSED]: onPopRequested,
+        [SCREEN_ON_HEADER_BACK_BUTTON_CLICKED]: onPopRequested,
+        // 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()}`,
+          );
+          emitter.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()}`,
+          );
+          emitter.emit(NAVIGATION_EVENT_BLUR);
+        },
+      },
+      // The imperative SearchBarCommands ref rides its OWN attachment on the RNSSearchBar leaf
+      // below (../attachments.ts), never this passthrough map - same split Angular uses, so no
+      // `ref` key can leak through to Fabric as a real prop.
+      searchBarPassthrough: searchBarOptions
+        ? buildSearchBarPassthrough(searchBarOptions, message =>
+            dlog(`Stack: route "${route.name}" ${message}`),
+          )
+        : undefined,
+    }),
+  );
+
+  // Investigation instrumentation (flicker-on-focus bug): the actual timing/z-order-relevant
+  // values resolved onto the native RNSScreen, once per mounted route - rules a stackAnimation/
+  // transitionDuration mismatch against react-native-screens' own native default in or out. Kept
+  // behind DEBUG, never removed.
+  let hasLoggedScreenProps = false;
+  $effect(() => {
+    const screenProps = plan.screenProps;
+    if (hasLoggedScreenProps) return;
+    hasLoggedScreenProps = true;
+    dlog(
+      `Stack: route "${route.name}" resolved screen props ` +
+        `stackAnimation=${String(screenProps.stackAnimation)} ` +
+        `stackPresentation=${String(screenProps.stackPresentation)} ` +
+        `transitionDuration=${String(screenProps.transitionDuration)} ` +
+        `gestureEnabled=${String(screenProps.gestureEnabled)} at t=${Date.now()}`,
+    );
+  });
+
+  // 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. activityState mirrors the
+  // outer screen's own value - RNSScreen.mm treats an unset/inactive nested screen as not yet
+  // pushed, leaving it parked at its pre-push transition position.
+  const innerStackProps = $derived<Record<string, unknown>>({
+    style: plan.innerStackStyle,
+  });
+  const innerScreenProps = $derived<Record<string, unknown>>({
+    style: plan.innerScreenStyle,
+    activityState: plan.activityState,
+  });
+
+  const scopeValue = $derived<INavigationScopeValue>({
+    route,
+    navigation,
+    emitter,
+    parent: parentScope,
+  });
+</script>
+
+{#snippet chrome()}
+  <svelte:element
+    this={RNS_SCREEN_STACK_HEADER_CONFIG_VIEW_NAME}
+    {@attach hostProps(plan.headerConfig.props)}
+  >
+    {#if plan.searchBarProps !== undefined}
+      <svelte:element
+        this={RNS_SCREEN_STACK_HEADER_SUBVIEW_VIEW_NAME}
+        {@attach hostProps(HEADER_SUBVIEW_PROPS)}
+      >
+        <svelte:element
+          this={RNS_SEARCH_BAR_VIEW_NAME}
+          {@attach hostProps(plan.searchBarProps)}
+          {@attach searchBarRef(searchBarOptions?.ref)}
+        />
+      </svelte:element>
+    {/if}
+  </svelte:element>
+  <svelte:element
+    this={RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME}
+    {@attach hostProps(plan.contentWrapperProps)}
+  >
+    <NavigationScope value={scopeValue}>
+      <ScreenComponent />
+    </NavigationScope>
+  </svelte:element>
+{/snippet}
+
+<svelte:element
+  this={plan.screenViewName}
+  {@attach hostProps(plan.screenProps)}
+>
+  {#if plan.inModal}
+    <svelte:element
+      this={RNS_SCREEN_STACK_VIEW_NAME}
+      {@attach hostProps(innerStackProps)}
+    >
+      <svelte:element
+        this={RNS_SCREEN_VIEW_NAME}
+        {@attach hostProps(innerScreenProps)}
+      >
+        {@render chrome()}
+      </svelte:element>
+    </svelte:element>
+  {:else}
+    {@render chrome()}
+  {/if}
+</svelte:element>

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,6 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program. adapters/svelte gets these for free because render.ts does a real value import from
+// 'svelte' (any file in a program importing a module loads its ambient globals for the whole
+// program); this package has no such import, so a triple-slash reference does the same job
+// explicitly rather than relying on an incidental side-effect.
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,147 @@
+// The compile-and-load harness every `*.smoke.test.ts` in this folder uses.
+//
+// There is no `.svelte`-aware bundler wired into this repo's vitest (svelte-adapter-dom-shim
+// skill §15, a deliberate choice), so a test that needs to RUN a component compiles the real
+// source with `svelte/compiler` itself and dynamic-`import()`s the output. Three rules fall out
+// of that, all of them learned the hard way in the adapter's own smokes:
+//
+//  1. The compiled file must sit NEXT TO the real source, because its own relative imports
+//     (`./stack-screen.svelte`, `../navigation-context`) resolve from wherever the compiled FILE
+//     lives, not from where the source did.
+//  2. Every `.svelte` specifier inside the compiled output has to be rewritten to the compiled
+//     twin, recursively - a navigator pulls in stack-screen.svelte, which pulls in
+//     navigation-scope.svelte.
+//  3. Node's `import()` caches by path, so re-writing new content to a path a previous test
+//     already imported hands back the STALE module. Every harness instance therefore stamps its
+//     own id into the filenames.
+//
+// `aliases` covers the one case relative rewriting cannot: `@symbiote-native/svelte`'s main
+// barrel re-exports real `.svelte` sources, which Vite's plain (svelte-plugin-free) transform
+// cannot parse at all - so a test that needs something from it points the specifier at a module
+// it compiled itself instead.
+
+import { compile } from 'svelte/compiler';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+// The real Metro pipeline's own `.svelte.ts` compile step (TS-strip, then `compileModule` to
+// desugar the runes). Reused rather than reimplemented, so the runes in ./runes are exercised
+// through the ACTUAL shipped compile path - a bare, uncompiled `$state`/`$effect` call throws
+// `rune_outside_svelte` at runtime. Default-imported because it is a `.cjs` module.
+import metroSvelteTransformer from '@symbiote-native/svelte/metro-svelte-transformer';
+
+const {
+  compileSvelteModuleFile,
+}: {
+  compileSvelteModuleFile: (source: string, filename: string) => string;
+} = metroSvelteTransformer;
+
+const COMPILE_OPTIONS = {
+  generate: 'client',
+  fragments: 'tree',
+  css: 'external',
+} as const;
+const SVELTE_SPECIFIER_PATTERN = /(['"])(\.{1,2}\/[^'"]*\.svelte)\1/g;
+
+export type ISvelteHarness = {
+  // Compile a real `.svelte` file plus everything it imports; returns the compiled entry path.
+  compileFile(sveltePath: string): string;
+  // Compile an inline fixture written into `dir`, so its own relative imports resolve from there.
+  compileSource(dir: string, name: string, source: string): string;
+  cleanup(): void;
+};
+
+export function createSvelteHarness(
+  id: string,
+  aliases: Readonly<Record<string, string>> = {},
+): ISvelteHarness {
+  const written: string[] = [];
+  const compiledBySource = new Map<string, string>();
+
+  function outPathFor(sveltePath: string): string {
+    const stem = basename(sveltePath).replace(/\./g, '-');
+    return join(dirname(sveltePath), `.smoke-compiled-${id}-${stem}.mjs`);
+  }
+
+  // `./` is prepended unless the path already walks up: every compiled file's basename STARTS
+  // with a dot (`.smoke-compiled-...`), so a bare "starts with '.'" check would leave it looking
+  // like a bare package specifier to the resolver.
+  function relativeSpecifier(fromFile: string, target: string): string {
+    const specifier = relative(dirname(fromFile), target);
+    return specifier.startsWith('..') ? specifier : `./${specifier}`;
+  }
+
+  function rewrite(code: string, outPath: string): string {
+    let rewritten = code.replace(
+      SVELTE_SPECIFIER_PATTERN,
+      (_match, quote: string, spec: string) => {
+        const childSource = resolve(dirname(outPath), spec);
+        const childOut = compileFile(childSource);
+        return `${quote}${relativeSpecifier(outPath, childOut)}${quote}`;
+      },
+    );
+    for (const [specifier, target] of Object.entries(aliases)) {
+      rewritten = rewritten
+        .split(`'${specifier}'`)
+        .join(`'${relativeSpecifier(outPath, target)}'`);
+      rewritten = rewritten
+        .split(`"${specifier}"`)
+        .join(`"${relativeSpecifier(outPath, target)}"`);
+    }
+    return rewritten;
+  }
+
+  function emit(
+    sveltePath: string,
+    source: string,
+    isRuneModule: boolean,
+  ): string {
+    const outPath = outPathFor(sveltePath);
+    // Registered BEFORE compiling so a cycle between two components terminates.
+    compiledBySource.set(sveltePath, outPath);
+    written.push(outPath);
+    const filename = basename(sveltePath);
+    const code = isRuneModule
+      ? compileSvelteModuleFile(source, `${filename}.ts`)
+      : compile(source, { ...COMPILE_OPTIONS, filename }).js.code;
+    writeFileSync(outPath, rewrite(code, outPath));
+    return outPath;
+  }
+
+  // A `./x.svelte` specifier is a COMPONENT when `x.svelte` exists on disk and a rune MODULE
+  // when `x.svelte.ts` does - the same two-way split the Metro transformer makes on the real
+  // filename.
+  function compileFile(sveltePath: string): string {
+    const cached = compiledBySource.get(sveltePath);
+    if (cached !== undefined) return cached;
+    const runeModulePath = `${sveltePath}.ts`;
+    if (!existsSync(sveltePath) && existsSync(runeModulePath)) {
+      return emit(sveltePath, readFileSync(runeModulePath, 'utf8'), true);
+    }
+    return emit(sveltePath, readFileSync(sveltePath, 'utf8'), false);
+  }
+
+  return {
+    compileFile,
+    compileSource(dir, name, source) {
+      return emit(join(dir, `${name}.svelte`), source, false);
+    },
+    cleanup() {
+      for (const file of written) rmSync(file, { force: true });
+      written.length = 0;
+      compiledBySource.clear();
+    },
+  };
+}
+
+// The compiled module's default export, narrowed without a cast so a test never silently mounts
+// `undefined`.
+export async function loadComponent(compiledPath: string): Promise<unknown> {
+  // pathToFileURL rather than a `file://${...}` template: the literal form makes Vite's import
+  // analyzer log an "Invalid file URL" warning for the un-substituted placeholder.
+  const mod: unknown = await import(pathToFileURL(compiledPath).href);
+  if (mod === null || typeof mod !== 'object' || !('default' in mod)) {
+    throw new Error(`${compiledPath} produced no default export`);
+  }
+  return mod.default;
+}

package/src/svelte/tab-screen-props.ts

@@ -0,0 +1,22 @@
+// Tab.Screen's public prop surface - mirrors screen-props.ts minus the stack-only concepts (no
+// push/pop lifecycle, no header search bar). Split out of `tab-screen.svelte` for the same
+// tsc-cannot-see-a-`.svelte`-named-export reason screen-props.ts documents.
+
+import type { Component } from 'svelte';
+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/src/svelte/tab-screen.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  // Tab.Screen: a declarative marker that paints nothing, registered through the same
+  // context-based collector Stack.Screen uses (screen-registry.ts). The `'tab'` kind tag is what
+  // stops it from silently registering with an ancestor Stack/Drawer when it is written in the
+  // wrong place. See CLAUDE.md <third_party_rn_packages_are_react_only> - this and Tab import
+  // nothing from react-native.
+  import { collectScreen } from './screen-registry';
+  import type { ITabScreenProps } from './tab-screen-props';
+
+  let { name, component, options, initialParams }: ITabScreenProps = $props();
+
+  collectScreen('tab', {
+    get name(): ITabScreenProps['name'] {
+      return name;
+    },
+    get component(): ITabScreenProps['component'] {
+      return component;
+    },
+    get options(): ITabScreenProps['options'] {
+      return options;
+    },
+    get initialParams(): unknown {
+      return initialParams;
+    },
+  });
+</script>

package/src/svelte/tabs/index.svelte

@@ -0,0 +1,269 @@
+<script lang="ts" module>
+  // Tab, the Svelte 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/Vue/Angular entries; here Svelte supplies the lifecycle - `$state.raw` for the
+  // router (its twin of useReducer), a module counter for route-key generation, `export
+  // function`s 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: 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.
+  //
+  // Screens are discovered through the context collector (../screen-registry.ts), not by reading
+  // `children` - see stack/index.svelte's header for why, and ../registry-host.ts for where the
+  // markers are rendered.
+  let tabInstanceCounter = 0;
+
+  const TAB_ROOT_PROPS: Record<string, unknown> = { style: { flex: 1 } };
+  const TAB_CONTENT_PROPS: Record<string, unknown> = { style: { flex: 1 } };
+</script>
+
+<script lang="ts">
+  import type { Component } from 'svelte';
+  import { onDestroy, tick } from 'svelte';
+  import { dlog } from '@symbiote-native/engine';
+  import type { ShimElement } from '@symbiote-native/svelte/native-view-bridge';
+  import {
+    NAVIGATION_EVENT_BLUR,
+    NAVIGATION_EVENT_FOCUS,
+    createInitialTabState,
+    createNavigationEmitter,
+    diffFocusedRoute,
+    isFocusedRoute,
+    reconcileTabRoutes,
+    renderTabBar,
+    tabRouterReducer,
+  } from '../../core';
+  import type {
+    IDescriptor,
+    INavigationEmitter,
+    IRoute,
+    ITabBarItemView,
+    ITabNavigatorHandle,
+    ITabOptions,
+    ITabRouterAction,
+    ITabRouterState,
+  } from '../../core';
+  import { createDescriptorSubtreeSync } from '../descriptor-subtree';
+  import { getNavigationScope } from '../navigation-context';
+  import type { INavigationScopeValue } from '../navigation-context';
+  import NavigationScope from '../navigation-scope.svelte';
+  import { SCREEN_REGISTRY_HOST_PROPS } from '../registry-host';
+  import {
+    setScreenCollector,
+    toRegistry,
+    withoutScreen,
+  } from '../screen-registry';
+  import type { IRegisteredScreen } from '../screen-registry';
+  import type { ITabScreenProps } from '../tab-screen-props';
+  import type { ITabProps } from './tab-props';
+
+  let { initialRouteName, screenOptions, children }: ITabProps = $props();
+
+  // Read BEFORE this Tab establishes its own per-screen NavigationScope - becomes the `parent`
+  // link a nested screen's useNavigation().getParent() walks. undefined at the nesting root.
+  const parentScope = getNavigationScope();
+
+  const routeIdPrefix = `tab-${(tabInstanceCounter += 1)}`;
+
+  let screens = $state.raw<IRegisteredScreen<ITabScreenProps['options']>[]>([]);
+  setScreenCollector<ITabScreenProps['options']>({
+    kind: 'tab',
+    register: screen => {
+      screens = [...screens, screen];
+    },
+    unregister: screen => {
+      screens = withoutScreen(screens, screen);
+    },
+  });
+
+  const registry = $derived(toRegistry(screens));
+
+  // A tab's route list is a PROJECTION of the registry, not navigation history the way Stack's
+  // is: a marker registering or unregistering must add or drop its tab. Unlike Stack, a route key
+  // here is derived from the route NAME rather than an incrementing sequence, so re-deriving this
+  // list on every registry change re-keys nothing.
+  const registeredRoutes = $derived.by<IRoute<unknown>[]>(() =>
+    [...registry.entries()].map(([name, entry]) => ({
+      key: `${routeIdPrefix}-${name}`,
+      name,
+      params: entry.initialParams,
+    })),
+  );
+
+  // The dispatched half is the only STATE here; the registry half is re-derived and reconciled
+  // against it on every change (reconcileTabRoutes, core - it is what preserves each surviving
+  // route's key/params and keeps the focus on the same route NAME). Nothing needs memoizing
+  // inside the derivation, so there is no state write during a derivation to avoid in the first
+  // place. Until something dispatches there is nothing to reconcile against, hence the seed.
+  let dispatchedState = $state.raw<ITabRouterState | null>(null);
+
+  const state = $derived.by<ITabRouterState>(() => {
+    if (registeredRoutes.length === 0)
+      dlog('Tab: no <Tab.Screen> children registered');
+    const dispatched = dispatchedState;
+    return dispatched === null
+      ? createInitialTabState(registeredRoutes, initialRouteName)
+      : reconcileTabRoutes(dispatched, registeredRoutes);
+  });
+
+  function dispatch(action: ITabRouterAction): void {
+    dispatchedState = tabRouterReducer(state, action);
+  }
+
+  export function jumpTo(name: string, params?: unknown): void {
+    dispatch({ type: 'jumpTo', name, params });
+  }
+  export function setParams(params: unknown, key: string): void {
+    dispatch({ type: 'setParams', key, params });
+  }
+
+  const handle: ITabNavigatorHandle = { jumpTo, setParams };
+
+  // One emitter per route.key, created lazily and cached for the navigator's whole lifetime -
+  // mirrors Stack's own `emitters` map. This decouples emitter IDENTITY (stable, looked up by
+  // key, read below when a route's NavigationScope is built) from emit TIMING (must wait until
+  // the focused screen has actually mounted and subscribed).
+  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. Keyed on the route KEY (not the route
+  // object) so a setParams-only change doesn't spuriously re-fire focus/blur.
+  //
+  // The bookkeeping updates immediately, but the actual emit is deferred to `tick()` - Svelte's
+  // twin of Vue's nextTick, and needed for the same reason: the newly-focused screen's own
+  // `$effect`s (its useIsFocused/useFocusEffect subscriptions) are created during THIS flush,
+  // after this effect was, so emitting synchronously here would reach zero subscribers.
+  let previousFocusedKey: string | undefined;
+  $effect(() => {
+    const nextKey = state.routes[state.index]?.key;
+    const { blurKey, focusKey } = diffFocusedRoute(previousFocusedKey, nextKey);
+    if (blurKey === undefined && focusKey === undefined) return;
+    previousFocusedKey = nextKey;
+    void tick().then(() => {
+      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);
+      }
+    });
+  });
+
+  onDestroy(() => {
+    if (previousFocusedKey !== undefined) {
+      emitterFor(previousFocusedKey).emit(NAVIGATION_EVENT_BLUR);
+    }
+  });
+
+  function resolveTabOptions(
+    entry: IRegisteredScreen<ITabScreenProps['options']> | undefined,
+    route: IRoute<unknown>,
+  ): ITabOptions {
+    const own =
+      entry === undefined
+        ? undefined
+        : typeof entry.options === 'function'
+          ? entry.options({ route, navigation: handle })
+          : entry.options;
+    return { ...screenOptions, ...own };
+  }
+
+  const items = $derived.by<ITabBarItemView[]>(() =>
+    state.routes.map((route, index) => {
+      const entry = registry.get(route.name);
+      const focused = isFocusedRoute(index, state.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);
+      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 focusedRoute = $derived(state.routes[state.index]);
+  const focusedOptions = $derived(
+    focusedRoute === undefined
+      ? screenOptions
+      : resolveTabOptions(registry.get(focusedRoute.name), focusedRoute),
+  );
+
+  const tabBar = $derived.by<IDescriptor>(() =>
+    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 unmount when
+  // focus moves on.
+  const focusedScreen = $derived.by<
+    { scope: INavigationScopeValue; component: Component } | undefined
+  >(() => {
+    if (focusedRoute === undefined) return undefined;
+    const entry = registry.get(focusedRoute.name);
+    if (entry === undefined) return undefined;
+    return {
+      component: entry.component,
+      scope: {
+        route: focusedRoute,
+        navigation: handle,
+        emitter: emitterFor(focusedRoute.key),
+        parent: parentScope?.current,
+      },
+    };
+  });
+
+  // The bar's ROOT stays a literal template tag (so `bind:this` has a statically known tag) and
+  // only its children go through the Descriptor bridge - the uniform shape every Svelte component
+  // consuming a `render-*.ts` uses (svelte-adapter-dom-shim skill §19). The item count varies with
+  // the registry, hence the shape-change-tolerant wrapper rather than the raw bridge.
+  let tabBarHost = $state.raw<ShimElement | null>(null);
+  const syncTabBarChildren = createDescriptorSubtreeSync();
+  $effect(() => {
+    const host = tabBarHost;
+    const barChildren = tabBar.children;
+    syncTabBarChildren(host, barChildren);
+  });
+</script>
+
+<symbiote-view p={TAB_ROOT_PROPS}>
+  <symbiote-text p={SCREEN_REGISTRY_HOST_PROPS}>
+    {@render children?.()}
+  </symbiote-text>
+  <symbiote-view p={TAB_CONTENT_PROPS}>
+    {#if focusedScreen !== undefined}
+      {@const FocusedComponent = focusedScreen.component}
+      <NavigationScope value={focusedScreen.scope}>
+        <FocusedComponent />
+      </NavigationScope>
+    {/if}
+  </symbiote-view>
+  <symbiote-view p={tabBar.props} bind:this={tabBarHost} />
+</symbiote-view>