@symbiote-native/navigation 2.0.3 → 2.1.0

package/src/angular/drawer/index.ts

@@ -221,12 +221,14 @@ export class Drawer implements AfterContentInit, OnChanges, OnDestroy, IDrawerNa
     this.dispatch({ type: 'toggleDrawer' });
   };
   readonly jumpTo = (name: string): void => {
-    // Captured BEFORE dispatch, mirroring vue/drawer/index.ts's jumpTo: a signal (like Vue's ref)
-    // mutates synchronously inside dispatch, so reading isOpen after it would already see the
-    // reducer's own isOpen: false and never animate the panel closed.
+    // Both sides of the dispatch, mirroring vue/drawer/index.ts's jumpTo: an unregistered name is
+    // a documented reducer no-op that hands the SAME state back, so animating off the pre-dispatch
+    // snapshot alone would slide the panel shut while the router still says isOpen. The signal is
+    // set synchronously inside dispatch, so the second read is already the reducer's own answer.
     const wasOpen = this.stateSignal()?.isOpen ?? false;
     this.dispatch({ type: 'jumpTo', name });
-    if (wasOpen) this.animateProgressTo(false);
+    const isOpenNow = this.stateSignal()?.isOpen ?? false;
+    if (wasOpen && !isOpenNow) this.animateProgressTo(false);
   };
 
   readonly panResponder = PanResponder.create({

package/src/angular/stack/index.ts

@@ -35,7 +35,7 @@
 // self-registers instead: `adapters/angular/babel-register-composed.cjs` (a Metro babel preset
 // applied bundle-wide, not scoped to adapters/angular) scans this package's own AOT-compiled
 // (`ngc`) `ɵɵngDeclareComponent({selector: 'Stack', ...})` output and auto-calls
-// `registerComposedComponent('Stack')` at bundle time - same mechanism `.examples/angular`
+// `registerComposedComponent('Stack')` at bundle time - same mechanism `examples/angular`
 // navigation-demo screens and `@symbiote-native/slider`'s `Slider` rely on for their own composed
 // components mounted statically or via `NgComponentOutlet`. Unregistered, `createElement('Stack')`
 // falls through to a real `createNode` call and RN paints its own "Unimplemented component"
@@ -73,6 +73,7 @@ import {
   createInitialNavigatorState,
   createNavigationEmitter,
   navigatorReducer,
+  reconcileStackRoutes,
   resolveHeaderInModalStackStyle,
   resolveScreenRenderPlan,
   resolveStackProps,
@@ -242,6 +243,20 @@ export class Stack implements AfterContentInit, OnDestroy, INavigatorHandle {
     for (const screen of this.screenChildren) {
       this.registry.set(screen.name, screen);
     }
+    this.reconcileWithRegistry();
+  }
+
+  // A `<ng-template symbioteScreen>` marker can leave the @ContentChildren query (a marker behind
+  // an `@if`, a data-driven screen list) while its route is still in the pushed history, which
+  // would leave that entry with nothing for componentFor() to mount (reconcileStackRoutes' header).
+  // The signal write lives HERE, in the query-change callback, and never in a computed/template
+  // accessor - reconciliation is a reaction to the registry changing, not a derivation of it.
+  private reconcileWithRegistry(): void {
+    const current = this.stateSignal();
+    if (current === undefined) return;
+    const next = reconcileStackRoutes(current, [...this.registry.keys()]);
+    if (next === current) return;
+    this.commitState(next);
   }
 
   private initializeState(): void {
@@ -269,7 +284,13 @@ export class Stack implements AfterContentInit, OnDestroy, INavigatorHandle {
   private dispatch(action: INavigatorAction): void {
     const current = this.stateSignal();
     if (current === undefined) return;
-    const next = navigatorReducer(current, action);
+    this.commitState(navigatorReducer(current, action));
+  }
+
+  // The one write path into stateSignal, shared by a dispatched action and a registry-driven
+  // reconciliation: both invalidate the plan cache, broadcast to every still-live route, and prune
+  // the emitters of routes that are gone.
+  private commitState(next: INavigatorState): void {
     this.planCache.clear();
     this.stateSignal.set(next);
     const liveRouteKeys = new Set(next.routes.map(route => route.key));

package/src/angular/tabs/index.ts

@@ -39,6 +39,7 @@ import {
   createNavigationEmitter,
   diffFocusedRoute,
   isFocusedRoute,
+  reconcileTabRoutes,
   renderTabBar,
   tabRouterReducer,
 } from '../../core';
@@ -114,10 +115,9 @@ export class Tab implements AfterContentInit, OnDestroy, ITabNavigatorHandle {
     this.dispatch({ type: 'setParams', key, params });
 
   ngAfterContentInit(): void {
-    this.rebuildRegistry();
-    this.initializeState();
+    this.syncRegistry();
     this.tabScreenChildrenSubscription = this.tabScreenChildren.changes.subscribe(() => {
-      this.rebuildRegistry();
+      this.syncRegistry();
     });
   }
 
@@ -141,10 +141,24 @@ export class Tab implements AfterContentInit, OnDestroy, ITabNavigatorHandle {
     }));
   }
 
-  private initializeState(): void {
-    if (this.stateSignal() !== undefined) return;
+  // A <ng-template symbioteTabScreen> can appear or disappear after mount (a marker behind an
+  // @if, a data-driven screen list), so the route list follows the LIVE query instead of staying
+  // frozen at whatever ngAfterContentInit first saw: reconcileTabRoutes (core) keeps each
+  // surviving route's key and accumulated params and moves focus only when the focused route is
+  // the one that left. Runs from the query's own `changes` subscription - an ordinary imperative
+  // callback, deliberately not a computed, since this writes the state signal.
+  private syncRegistry(): void {
+    this.rebuildRegistry();
     const routes = this.routesFromRegistry();
     if (routes.length === 0) dlog('Tab: no <ng-template symbioteTabScreen> children registered');
+    const current = this.stateSignal();
+    if (current !== undefined) {
+      this.stateSignal.set(reconcileTabRoutes(current, routes));
+      return;
+    }
+    // Seeding an empty list would resolve initialRouteName against nothing and lose it once the
+    // markers do arrive, so the state stays unseeded until at least one has registered.
+    if (routes.length === 0) return;
     this.stateSignal.set(createInitialTabState(routes, this.initialRouteName));
   }
 

package/src/core/index.ts

@@ -16,6 +16,11 @@ export {
 } from './navigator-state';
 export type { IRoute, INavigatorState, INavigatorAction } from './navigator-state';
 
+// Drops history entries whose `<Stack.Screen>` marker has unregistered - see
+// stack-router-state.ts's header for why the Stack's history needs this and the Tab's projection
+// does not.
+export { reconcileStackRoutes } from './stack-router-state';
+
 export type {
   IStackAnimation,
   IStackPresentation,
@@ -89,7 +94,12 @@ export { isRecord } from './guards';
 
 // Bottom-tabs navigator: a FOCUSED-INDEX router (not a stack - see tab-router-state.ts) driving
 // a pure-JS tab bar render, framework-agnostic and shared verbatim by every adapter.
-export { createInitialTabState, tabRouterReducer, isFocusedRoute } from './tab-router-state';
+export {
+  createInitialTabState,
+  tabRouterReducer,
+  reconcileTabRoutes,
+  isFocusedRoute,
+} from './tab-router-state';
 export type { ITabRouterState, ITabRouterAction } from './tab-router-state';
 
 export type { ITabBarIcon, ITabOptions } from './tab-options';

package/src/core/stack-router-state/index.ts

@@ -0,0 +1,49 @@
+// StackRouter: the registry-reconciliation half (framework-agnostic, zero render). A Stack's route
+// list is navigation HISTORY, not a projection of the registered `<Stack.Screen>` markers the way a
+// Tab's is (tab-router-state) - it seeds exactly one route and grows only through push/replace. So
+// a marker that unregisters while its route still sits in the history (a marker behind an `{#if}`,
+// a data-driven screen list) leaves behind an entry nothing can render: the route stays, the
+// adapter's componentFor() finds no screen, and the user is parked on a blank RNSScreen with no
+// way to tell what happened. Mirrors @react-navigation/routers' StackRouter.getStateForRouteNames-
+// Change, which filters those routes out of the history and pulls the focused index back into
+// range.
+//
+// Deliberately NOT a navigatorReducer action: this is not something a caller dispatches, it is a
+// reaction to the registry changing underneath an unchanged history, and each adapter observes
+// that change through its own lifecycle. Keeping it a separate pure function lets every adapter
+// wire it its own way without teaching the reducer about a registry it has never seen.
+
+import type { INavigatorState } from '../navigator-state';
+
+// The contract, and the two places it deliberately parts from upstream:
+//
+// - SURVIVORS KEEP THEIR IDENTITY. A stack route's key is COUNTER-derived (every adapter's
+//   createRoute increments a per-navigator sequence), not name-derived like a tab route's, so
+//   re-deriving the list from the registry would hand every survivor a brand-new key and remount
+//   live screens. Only the phantom entries go; every other route object passes through by
+//   reference, params included.
+//
+// - THE FOCUSED ROUTE IS THE TOP ONE. This state carries no `index` field: the focused route is
+//   always the last one (see computeActivityState's comment for why no route can outrank it), so
+//   upstream's `index: Math.min(state.index, routes.length - 1)` degenerates here to "the last
+//   survivor". Dropping the FOCUSED route therefore lands the user on the nearest still-registered
+//   route beneath it - where a pop() would have left them - rather than on nothing.
+//
+// - THE ROUTE LIST IS NEVER EMPTIED. `routes.length - 1` IS the focused index, so an empty list
+//   means no focused route at all - the blank screen this function exists to prevent. When nothing
+//   in the history survives (every marker gone, or the whole screen set swapped for new names) the
+//   state is returned UNCHANGED. Upstream instead pushes a freshly nanoid()-keyed route for
+//   initialRouteName; we cannot, because minting a route key belongs to the caller here
+//   (navigator-state.ts's header) and a derivation that mints one would allocate a new key on every
+//   re-run. Unchanged is also the right answer for the usual cause of a momentarily empty registry
+//   - markers unregistering and re-registering across a re-render - since the next run reconciles
+//   for real.
+export function reconcileStackRoutes(
+  state: INavigatorState,
+  registeredNames: readonly string[],
+): INavigatorState {
+  const routes = state.routes.filter(route => registeredNames.includes(route.name));
+  // filter preserves order, so an unchanged length means nothing was dropped.
+  if (routes.length === state.routes.length || routes.length === 0) return state;
+  return { routes };
+}

package/src/core/tab-router-state/index.ts

@@ -34,6 +34,31 @@ export function createInitialTabState(
   return { routes, index: index === -1 ? INITIAL_FOCUSED_INDEX : index };
 }
 
+// A screen marker can appear or disappear after mount (a marker behind an `{#if}`, a data-driven
+// screen list), so a navigator's route list has to follow its registry instead of staying frozen
+// at whatever createInitialTabState saw first. Mirrors TabRouter.getStateForRouteNamesChange:
+// membership and order come from `nextRoutes`, but a route that survives keeps its IDENTITY (its
+// key) and everything jumpTo/setParams accumulated onto its params - only genuinely new names
+// take their entry from `nextRoutes`. Focus follows the previously focused route's NAME, so an
+// unrelated screen disappearing never moves the user; when the focused route is the one that
+// disappeared, focus falls back to the first route, the same landing spot every unresolvable
+// focus gets here (createInitialTabState's own fallback).
+export function reconcileTabRoutes(
+  state: ITabRouterState,
+  nextRoutes: readonly IRouteEntry[],
+): ITabRouterState {
+  const routes = nextRoutes.map(
+    next => state.routes.find(route => route.name === next.name) ?? next,
+  );
+  const isUnchanged =
+    routes.length === state.routes.length &&
+    routes.every((route, at) => route === state.routes[at]);
+  if (isUnchanged) return state;
+  const focusedName = state.routes[state.index]?.name;
+  const index = routes.findIndex(route => route.name === focusedName);
+  return { routes, index: index === -1 ? INITIAL_FOCUSED_INDEX : index };
+}
+
 // jumpTo moves the focused index to an existing route by name and optionally merges params
 // (navigation.jumpTo(name, params) - the tab-actions doc's own signature); it never adds,
 // removes, or reorders routes (mirrors TabRouter: JUMP_TO is a no-op when the target name isn't

package/src/react/drawer/index.ts

@@ -53,6 +53,7 @@ import type {
   IDrawerDescriptorMap,
   IDrawerNavigatorHandle,
   IDrawerOptions,
+  IDrawerRouterAction,
   IDrawerRouterState,
   IDrawerScreenOptions,
   IDrawerSlot,
@@ -163,8 +164,10 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
   optionsRef.current = options;
   const screenWidthRef = useRef(screenWidth);
   screenWidthRef.current = screenWidth;
-  const isOpenRef = useRef(state.isOpen);
-  isOpenRef.current = state.isOpen;
+  // The whole router state, not just its isOpen bit: jumpTo below has to re-run the reducer to
+  // learn what the dispatch actually produced, and that needs the routes too.
+  const stateRef = useRef(state);
+  stateRef.current = state;
 
   const animateProgressTo = useCallback(
     (open: boolean): void => {
@@ -190,23 +193,31 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
   const handle = useMemo<IDrawerNavigatorHandle>(
     () => ({
       openDrawer: () => {
-        dlog(`Drawer: openDrawer() called, isOpen=${isOpenRef.current} at t=${Date.now()}`);
+        dlog(`Drawer: openDrawer() called, isOpen=${stateRef.current.isOpen} at t=${Date.now()}`);
         animateProgressTo(true);
         dispatch({ type: 'openDrawer' });
       },
       closeDrawer: () => {
-        dlog(`Drawer: closeDrawer() called, isOpen=${isOpenRef.current} at t=${Date.now()}`);
+        dlog(`Drawer: closeDrawer() called, isOpen=${stateRef.current.isOpen} at t=${Date.now()}`);
         animateProgressTo(false);
         dispatch({ type: 'closeDrawer' });
       },
       toggleDrawer: () => {
-        dlog(`Drawer: toggleDrawer() called, isOpen=${isOpenRef.current} at t=${Date.now()}`);
-        animateProgressTo(!isOpenRef.current);
+        dlog(`Drawer: toggleDrawer() called, isOpen=${stateRef.current.isOpen} at t=${Date.now()}`);
+        animateProgressTo(!stateRef.current.isOpen);
         dispatch({ type: 'toggleDrawer' });
       },
       jumpTo: (name: string) => {
-        dispatch({ type: 'jumpTo', name });
-        if (isOpenRef.current) animateProgressTo(false);
+        // An unregistered name is a documented reducer no-op that hands the SAME state back, so
+        // animating off `isOpen` alone would slide the panel shut while the router still says
+        // open. useReducer's dispatch is async - stateRef only catches up on the next render - so
+        // the reducer (a pure function) is re-run here to learn what the dispatch produces, and
+        // the animation runs only on a genuine open -> closed transition.
+        const action: IDrawerRouterAction = { type: 'jumpTo', name };
+        const current = stateRef.current;
+        const next = drawerRouterReducer(current, action);
+        dispatch(action);
+        if (current.isOpen && !next.isOpen) animateProgressTo(false);
       },
     }),
     [animateProgressTo],
@@ -224,7 +235,7 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
           event,
           gestureState,
           screenWidthRef.current,
-          isOpenRef.current,
+          stateRef.current.isOpen,
           optionsRef.current,
           'start',
         ),
@@ -236,13 +247,13 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
           event,
           gestureState,
           screenWidthRef.current,
-          isOpenRef.current,
+          stateRef.current.isOpen,
           optionsRef.current,
           'move',
         ),
       onPanResponderGrant: (): void => {
         dlog('Drawer: gesture grant');
-        dragStartProgress.current = isOpenRef.current ? 1 : 0;
+        dragStartProgress.current = stateRef.current.isOpen ? 1 : 0;
       },
       onPanResponderMove: (
         _event: ISymbioteEvent,
@@ -259,7 +270,11 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
         _event: ISymbioteEvent,
         gestureState: IPanResponderGestureState,
       ): void => {
-        const intent = resolveSwipeIntent(gestureState, isOpenRef.current, optionsRef.current);
+        const intent = resolveSwipeIntent(
+          gestureState,
+          stateRef.current.isOpen,
+          optionsRef.current,
+        );
         const open = intent === 'open';
         dlog(`Drawer: gesture release -> ${open ? 'open' : 'close'}`);
         animateProgressTo(open);
@@ -267,7 +282,7 @@ const DrawerImpl = forwardRef<IDrawerNavigatorHandle, IDrawerProps>((props, forw
       },
       onPanResponderTerminate: (): void => {
         dlog('Drawer: gesture terminated, snapping back');
-        animateProgressTo(isOpenRef.current);
+        animateProgressTo(stateRef.current.isOpen);
       },
     }),
   ).current;

package/src/react/stack/index.ts

@@ -46,6 +46,7 @@ import {
   createInitialNavigatorState,
   createNavigationEmitter,
   navigatorReducer,
+  reconcileStackRoutes,
   resolveScreenRenderPlan,
   resolveStackProps,
 } from '../../core';
@@ -122,7 +123,9 @@ const StackImpl = forwardRef<INavigatorHandle, IStackProps>((props, forwardedRef
     [routeIdPrefix],
   );
 
-  const [state, dispatch] = useReducer(navigatorReducer, undefined, () => {
+  const registeredNames = useMemo(() => [...registry.keys()], [registry]);
+
+  const [dispatchedState, dispatch] = useReducer(navigatorReducer, undefined, () => {
     const initialRouteName = props.initialRouteName ?? registry.keys().next().value;
     if (initialRouteName === undefined) {
       dlog('Stack: no <Stack.Screen> children registered');
@@ -133,6 +136,17 @@ const StackImpl = forwardRef<INavigatorHandle, IStackProps>((props, forwardedRef
     );
   });
 
+  // A <Stack.Screen> marker can unregister while its route is still in the pushed history, which
+  // would leave that entry with nothing to render (reconcileStackRoutes' header). Reconciling here
+  // rather than in an effect repairs the CURRENT paint - the call is pure and hands back the same
+  // reference when nothing changed, so it is safe during render; the effect below only PERSISTS
+  // the repair, so the next push builds on the pruned history instead of the phantom one.
+  const state = reconcileStackRoutes(dispatchedState, registeredNames);
+
+  useEffect(() => {
+    if (state !== dispatchedState) dispatch({ type: 'reset', state });
+  }, [state, dispatchedState]);
+
   const handle = useMemo<INavigatorHandle>(
     () => ({
       push: (name, params) => dispatch({ type: 'push', route: createRoute(name, params) }),

package/src/react/tabs/index.ts

@@ -1,9 +1,9 @@
 // Tab, the React 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 Vue/Angular adapters; here React supplies the lifecycle - useReducer for the focused
-// index, useId for route-key generation, useImperativeHandle for the jumpTo/setParams handle -
-// plus the descriptor bridge for the tab-bar leaf, exactly like Stack bridges its header config
-// (react/stack.ts). Unlike Stack, a bottom-tabs bar is a PURE-JS UI: it paints ordinary
+// with the Vue/Angular adapters; here React supplies the lifecycle - useState for the dispatched
+// router state, useId for route-key generation, useImperativeHandle for the jumpTo/setParams
+// handle - plus the descriptor bridge for the tab-bar leaf, exactly like Stack bridges its header
+// config (react/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.
 
@@ -17,7 +17,7 @@ import {
   useId,
   useImperativeHandle,
   useMemo,
-  useReducer,
+  useState,
 } from 'react';
 import type { ReactElement, ReactNode } from 'react';
 import { descriptorToReact } from '@symbiote-native/react';
@@ -28,10 +28,18 @@ import {
   createInitialTabState,
   createNavigationEmitter,
   isFocusedRoute,
+  reconcileTabRoutes,
   renderTabBar,
   tabRouterReducer,
 } from '../../core';
-import type { IRoute, ITabBarItemView, ITabNavigatorHandle, ITabOptions } from '../../core';
+import type {
+  IRoute,
+  ITabBarItemView,
+  ITabNavigatorHandle,
+  ITabOptions,
+  ITabRouterAction,
+  ITabRouterState,
+} from '../../core';
 import { collectRegistry } from '../collect-registry';
 import { NavigationContext } from '../navigation-context';
 import { TabScreen } from '../tab-screen';
@@ -84,19 +92,44 @@ const TabImpl = forwardRef<ITabNavigatorHandle, ITabProps>((props, forwardedRef)
     [registry, routeIdPrefix],
   );
 
-  const [state, dispatch] = useReducer(tabRouterReducer, undefined, () =>
-    createInitialTabState(routes, props.initialRouteName),
+  // A <Tab.Screen> can appear or disappear after mount (a marker behind a conditional, a
+  // data-driven screen list), so the route list is re-derived from `children` on every render and
+  // the STORED state is reconciled against it (reconcileTabRoutes, core - it preserves each
+  // surviving route's key and accumulated params and keeps focus on the same route NAME) rather
+  // than staying frozen at whatever the first render saw. `null` means no marker had registered
+  // yet: seeding an empty list would resolve initialRouteName against nothing and lose it, so the
+  // state stays derived until either a marker arrives or something dispatches.
+  const [storedState, setStoredState] = useState<ITabRouterState | null>(() =>
+    routes.length === 0 ? null : createInitialTabState(routes, props.initialRouteName),
+  );
+
+  const resolveState = useCallback(
+    (stored: ITabRouterState | null): ITabRouterState =>
+      stored === null
+        ? createInitialTabState(routes, props.initialRouteName)
+        : reconcileTabRoutes(stored, routes),
+    [routes, props.initialRouteName],
   );
 
+  const state = resolveState(storedState);
+
   if (routes.length === 0) dlog('Tab: no <Tab.Screen> children registered');
 
+  // The updater re-resolves rather than closing over `state` so that two dispatches batched into
+  // one render still compose: the second reduces over the first's result, not a stale snapshot.
+  const dispatch = useCallback(
+    (action: ITabRouterAction) =>
+      setStoredState(current => tabRouterReducer(resolveState(current), action)),
+    [resolveState],
+  );
+
   const jumpTo = useCallback(
     (name: string, params?: unknown) => dispatch({ type: 'jumpTo', name, params }),
-    [],
+    [dispatch],
   );
   const setParams = useCallback(
     (params: unknown, key: string) => dispatch({ type: 'setParams', key, params }),
-    [],
+    [dispatch],
   );
 
   const handle = useMemo<ITabNavigatorHandle>(() => ({ jumpTo, setParams }), [jumpTo, setParams]);

package/src/svelte/attachments.ts

@@ -0,0 +1,68 @@
+// Svelte attachments (`{@attach ...}`) for the react-native-screens native leaves.
+//
+// WHY THESE EXIST AT ALL: every react-native-screens Fabric view name is capitalized and
+// un-hyphenated (RNSScreen, RNSScreenStack, RNSScreenStackHeaderConfig, RNSSearchBar, ...), so a
+// literal `<RNSScreen>` in a Svelte template parses as a COMPONENT reference, not an element -
+// the same wall @symbiote-native/slider's 'RNCSlider' leaf hit. Slider sidestepped it by mounting
+// the whole leaf through the Descriptor bridge, which works because that leaf carries no live
+// framework children. A stack screen DOES (the app's own screen component lives inside
+// RNSScreenContentWrapper), so the bridge is not an option here.
+//
+// The way through is `<svelte:element this={'RNSScreen'}>`: it creates the element via
+// `document.createElement(tag)` with a plain runtime string the compiler never inspects, and it
+// accepts ordinary framework children. Its one catch is documented in svelte-adapter-dom-shim
+// skill §15 - a dynamic tag compiles through Svelte's generic setAttribute/property-diffing
+// codegen, NOT the custom-element `p=` property-SET path, so writing `p={bag}` as an ATTRIBUTE on
+// it silently fails. An attachment bypasses that entirely: it is handed the raw element and
+// assigns the property from plain JS, then re-runs whenever the props it read change. Verified
+// against the real compiler + the real shim before this was built on.
+
+import { dlog, isSymbioteNode } from '@symbiote-native/engine';
+import type { ShimElement } from '@symbiote-native/svelte/native-view-bridge';
+import { buildSearchBarHandle } from '../core';
+import type { ISearchBarCommands } from '../core';
+
+// `unknown` rather than `Element`: the value Svelte hands an attachment is one of the DOM shim's
+// own element classes, not a real DOM Element, and a function accepting `unknown` is still
+// assignable everywhere Svelte expects `(element: Element) => ...`.
+function isShimElement(value: unknown): value is ShimElement {
+  return typeof value === 'object' && value !== null && 'engineNode' in value;
+}
+
+// The object-bag prop set, the same entry point every adapter's props go through (routeProp).
+// Re-runs on every change of `props`, and the shim's own `p` setter diffs per key from there.
+export function hostProps(props: Record<string, unknown>): (node: unknown) => void {
+  return node => {
+    if (!isShimElement(node)) {
+      dlog('navigation: hostProps attached to a non-shim element, ignored');
+      return;
+    }
+    node.p = props;
+  };
+}
+
+// The Svelte twin of Angular's SearchBarRefDirective / React's and Vue's callback `ref` on the
+// RNSSearchBar element: fills the app-supplied cell once the native node exists and clears it on
+// teardown. buildSearchBarHandle's own getter is LAZY, so handing it the node here is safe even
+// before the first commit.
+export function searchBarRef(
+  ref: { current: ISearchBarCommands | null } | undefined,
+): (node: unknown) => (() => void) | void {
+  return node => {
+    if (ref === undefined) return;
+    if (!isShimElement(node)) {
+      ref.current = null;
+      return;
+    }
+    const engineNode = node.engineNode;
+    if (!isSymbioteNode(engineNode)) {
+      dlog('navigation: search bar attachment ran before the shim went live');
+      ref.current = null;
+      return;
+    }
+    ref.current = buildSearchBarHandle(() => engineNode);
+    return () => {
+      ref.current = null;
+    };
+  };
+}

package/src/svelte/descriptor-subtree.ts

@@ -0,0 +1,49 @@
+// A shape-CHANGE-tolerant wrapper over @symbiote-native/svelte's Descriptor bridge.
+//
+// `mountDescriptorChildren` (svelte-adapter-dom-shim skill §19) is deliberately shape-stable: it
+// builds each shim node once and only re-sets props thereafter, throwing if the tree shape ever
+// changes, because every `core/components` render-*.ts produces a constant shape. The navigation
+// package's tab bar is the exception - `renderTabBar` emits one child per registered route, and
+// that count genuinely varies (it is 0 until the `<Tab.Screen>` markers have registered, and
+// changes again if a screen is added or removed). Same situation @symbiote-native/slider's own
+// steps-indicator overlay is in, and the same resolution: keep the fast path for the common
+// "same shape, new prop values" case and rebuild only when the shape actually changed.
+//
+// The shape signature covers types and nesting, not just the top-level count, because a tab bar
+// item's own children vary too (an item gains an icon wrapper only when it has an icon or badge).
+
+import { mountDescriptorChildren } from '@symbiote-native/svelte/native-view-bridge';
+import type {
+  IDescriptorChildrenMount,
+  ShimElement,
+} from '@symbiote-native/svelte/native-view-bridge';
+import type { IDescriptorChild } from '@symbiote-native/components';
+
+const TEXT_CHILD_MARK = '#';
+
+function shapeOf(children: readonly IDescriptorChild[]): string {
+  return children
+    .map(child =>
+      typeof child === 'string' ? TEXT_CHILD_MARK : `${child.type}(${shapeOf(child.children)})`,
+    )
+    .join(',');
+}
+
+export function createDescriptorSubtreeSync(): (
+  host: ShimElement | null,
+  children: IDescriptorChild[],
+) => void {
+  let mounted: IDescriptorChildrenMount | undefined;
+  let shape: string | undefined;
+  return (host, children) => {
+    if (host === null) return;
+    const nextShape = shapeOf(children);
+    if (mounted === undefined || nextShape !== shape) {
+      for (const child of host.children.slice()) host.removeChild(child);
+      mounted = mountDescriptorChildren(host, children);
+      shape = nextShape;
+      return;
+    }
+    mounted.update(children);
+  };
+}

package/src/svelte/drawer/drawer-props.ts

@@ -0,0 +1,28 @@
+// Drawer's own public prop surface. Plain `.ts` for the tsc-cannot-see-a-`.svelte`-named-export
+// reason ../screen-props.ts documents.
+
+import type { Snippet } from 'svelte';
+import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import type {
+  IDrawerDescriptorMap,
+  IDrawerNavigatorHandle,
+  IDrawerOptions,
+  IDrawerRouterState,
+} from '../../core';
+
+// React's `renderDrawerContent` render-PROP becomes a Snippet WITH A PARAMETER here (Vue's twin
+// is a scoped slot) - the drawer panel's content is app-authored and needs the router state, the
+// per-route options map, and the navigator handle to paint a menu.
+export type IDrawerContentSlotProps = {
+  state: IDrawerRouterState;
+  descriptors: IDrawerDescriptorMap;
+  navigation: IDrawerNavigatorHandle;
+};
+
+export type IDrawerProps = IDrawerOptions & {
+  initialRouteName?: string;
+  drawerStyle?: IStyleProp<IViewStyle>;
+  // The `<Drawer.Screen>` markers.
+  children?: Snippet;
+  drawerContent?: Snippet<[IDrawerContentSlotProps]>;
+};