@sigx/lynx-navigation 0.1.0 → 0.1.2

package/src/hooks/use-nav-serializer.ts

@@ -0,0 +1,239 @@
+import { effect, onMounted, onUnmounted } from '@sigx/lynx';
+import { useNav } from './use-nav.js';
+import { useNavRoutes } from './use-nav-internal.js';
+import type { StackEntry } from '../types.js';
+
+/**
+ * Plain JSON snapshot of a navigator. The whole point of holding navigation
+ * state in signals is that this is a one-liner — `JSON.stringify(nav.stack)`.
+ *
+ * Shape is deliberately minimal:
+ *
+ *   {
+ *     version: 1,
+ *     stack: [ { key, route, params, search, state, presentation }, ... ],
+ *   }
+ *
+ * `version` lets future schema migrations (or hard breakage) reject old
+ * snapshots cleanly rather than restoring incompatible state.
+ *
+ * Per spec resolved-decisions: only the root navigator is persisted in v1.
+ * Per-tab / nested-navigator stacks are deferred until the nested-navigators
+ * follow-up slice lands.
+ */
+export interface NavSnapshot {
+    version: number;
+    stack: StackEntry[];
+}
+
+export const NAV_SNAPSHOT_VERSION = 1;
+
+/**
+ * Adapter contract for `useNavSerializer`. Implementations bridge to whatever
+ * storage backend the host app uses — `@sigx/lynx-storage`, `localStorage`,
+ * an MMKV bridge, etc. Both methods may be async; the hook awaits load before
+ * applying anything to the stack and fires save in a debounced manner.
+ *
+ *   - `load()` returns `null` (or rejects) when no snapshot exists, when the
+ *     stored payload is malformed, or when the host opts not to restore on
+ *     this launch.
+ *   - `save(snapshot)` persists the latest stack. The hook drops save errors
+ *     on the floor — losing a write is preferable to crashing the navigator.
+ */
+export interface NavStorageAdapter {
+    load(): Promise<NavSnapshot | null> | NavSnapshot | null;
+    save(snapshot: NavSnapshot): Promise<void> | void;
+}
+
+export interface UseNavSerializerOptions {
+    storage: NavStorageAdapter;
+    /**
+     * Trailing-edge debounce in ms before pushing a stack change to storage.
+     * Defaults to 250ms — quick enough that a force-quit one tick after a
+     * push is recoverable, slow enough that rapid `pop/push` flurries
+     * coalesce into one write.
+     */
+    debounceMs?: number;
+    /**
+     * Optional callback after a successful restore — lets the host run
+     * post-restore wiring (analytics, focus shifts, etc.) only when we
+     * actually applied state, not on every mount.
+     */
+    onRestored?: (snapshot: NavSnapshot) => void;
+    /**
+     * Optional callback when a snapshot is rejected (validation failed or
+     * load threw). Defaults to silent. Useful for logging during migration.
+     */
+    onRestoreError?: (reason: 'version' | 'shape' | 'unknown-route' | 'load-threw', err?: unknown) => void;
+}
+
+/**
+ * Wire a navigator's stack to a storage adapter.
+ *
+ * On mount:
+ *   1. Call `storage.load()`.
+ *   2. Validate the snapshot (version match, every entry's route still
+ *      registered).
+ *   3. On success, `nav.reset({ stack })` to apply.
+ *   4. On any failure, leave the stack alone (initial route remains).
+ *
+ * Then subscribe to `nav.stack` and call `storage.save(snapshot)` debounced.
+ *
+ * Why we don't validate `params` / `search` against schemas here: schemas
+ * are part of the route definition, and re-running them across all entries
+ * on every launch costs more than it's worth. The contract is "entries were
+ * validated when they were pushed; if the schema has since changed in a
+ * breaking way, bump `version` to reject old snapshots wholesale." Callers
+ * who want a stricter check can run their own validation in
+ * `storage.load()` and return `null` on mismatch.
+ */
+export function useNavSerializer(options: UseNavSerializerOptions): void {
+    const nav = useNav();
+    const routes = useNavRoutes();
+    const debounceMs = options.debounceMs ?? 250;
+    const onRestored = options.onRestored;
+    const onErr = options.onRestoreError;
+
+    // Mutable mount/state flags. Plain closure vars (no signals) — we don't
+    // want any of this driving a render and we don't want it tracked by the
+    // save-effect below.
+    let mounted = true;
+    let restoreDone = false;
+    let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+    let stopEffect: (() => void) | null = null;
+
+    onMounted(() => {
+        // Kick off the load synchronously — adapters that return a value
+        // immediately (sync stores, test doubles) hit the resolve branch on
+        // the same tick. Promise adapters resolve on the microtask queue;
+        // the `mounted` guard catches teardown races.
+        Promise.resolve()
+            .then(() => options.storage.load())
+            .then((snap) => {
+                if (!mounted) return;
+                if (snap == null) {
+                    restoreDone = true;
+                    startSaveEffect();
+                    return;
+                }
+                if (!isValidShape(snap)) {
+                    onErr?.('shape');
+                    restoreDone = true;
+                    startSaveEffect();
+                    return;
+                }
+                if (snap.version !== NAV_SNAPSHOT_VERSION) {
+                    onErr?.('version');
+                    restoreDone = true;
+                    startSaveEffect();
+                    return;
+                }
+                // Drop the snapshot if any entry references a route the app
+                // no longer knows about — partial restoration is worse than
+                // no restoration (could leave the user stranded on a screen
+                // whose params won't validate when read by `useParams`).
+                for (const entry of snap.stack) {
+                    if (!routes[entry.route]) {
+                        onErr?.('unknown-route');
+                        restoreDone = true;
+                        startSaveEffect();
+                        return;
+                    }
+                }
+                if (snap.stack.length === 0) {
+                    onErr?.('shape');
+                    restoreDone = true;
+                    startSaveEffect();
+                    return;
+                }
+                nav.reset({ stack: snap.stack });
+                onRestored?.(snap);
+                restoreDone = true;
+                startSaveEffect();
+            })
+            .catch((err) => {
+                if (!mounted) return;
+                onErr?.('load-threw', err);
+                restoreDone = true;
+                startSaveEffect();
+            });
+    });
+
+    function startSaveEffect() {
+        if (!mounted || stopEffect) return;
+        // The first effect run is just the initial subscription read — it
+        // happens immediately when `effect()` is called, before any user
+        // navigation, and represents the stack-as-restored (or the initial
+        // route when there was nothing to restore). Either way, we don't
+        // want to persist it: in the restore case it would race with the
+        // adapter that just supplied this state, and in the fresh case
+        // it's redundant.
+        let firstRun = true;
+        const runner = effect(() => {
+            const stack = nav.stack;
+            const snapshot: NavSnapshot = {
+                version: NAV_SNAPSHOT_VERSION,
+                stack: stack.map((e) => ({
+                    key: e.key,
+                    route: e.route,
+                    params: e.params,
+                    search: e.search,
+                    state: e.state,
+                    presentation: e.presentation,
+                })),
+            };
+            if (firstRun) {
+                firstRun = false;
+                return;
+            }
+            schedule(snapshot);
+        });
+        stopEffect = () => runner.stop();
+    }
+
+    function schedule(snapshot: NavSnapshot) {
+        if (pendingTimer != null) clearTimeout(pendingTimer);
+        pendingTimer = setTimeout(() => {
+            pendingTimer = null;
+            try {
+                const r = options.storage.save(snapshot);
+                if (r && typeof (r as Promise<void>).catch === 'function') {
+                    (r as Promise<void>).catch(() => {
+                        // Save errors are intentionally swallowed — see the
+                        // hook doc-comment. Hosts that need visibility can
+                        // wrap their adapter.
+                    });
+                }
+            } catch {
+                // Same rationale.
+            }
+        }, debounceMs);
+    }
+
+    onUnmounted(() => {
+        mounted = false;
+        if (pendingTimer != null) {
+            clearTimeout(pendingTimer);
+            pendingTimer = null;
+        }
+        if (stopEffect) {
+            stopEffect();
+            stopEffect = null;
+        }
+    });
+}
+
+function isValidShape(s: unknown): s is NavSnapshot {
+    if (!s || typeof s !== 'object') return false;
+    const obj = s as { version?: unknown; stack?: unknown };
+    if (typeof obj.version !== 'number') return false;
+    if (!Array.isArray(obj.stack)) return false;
+    for (const entry of obj.stack) {
+        if (!entry || typeof entry !== 'object') return false;
+        const e = entry as Record<string, unknown>;
+        if (typeof e.key !== 'string') return false;
+        if (typeof e.route !== 'string') return false;
+        if (typeof e.presentation !== 'string') return false;
+    }
+    return true;
+}

package/src/hooks/use-screen-options.ts

@@ -0,0 +1,48 @@
+/**
+ * `useScreenOptions` — imperative merge into the current entry's options.
+ *
+ * Use this when options need to be set from an effect rather than declared
+ * statically via `<Screen title=…>`. The canonical case is "title becomes
+ * known after a fetch":
+ *
+ * ```ts
+ * const user = useFetchUser(id);
+ * useScreenOptions(() => ({
+ *     title: user.value?.displayName ?? 'Loading…',
+ * }));
+ * ```
+ *
+ * The callback runs in a tracked `effect` — any signals it reads cause it
+ * to re-run and re-merge. This is strictly additive: returning a partial
+ * options object only touches the keys it sets, and returning `undefined`
+ * for a key clears it.
+ *
+ * Static usage where the options never change can pass a plain object and
+ * skip the effect — internally we detect that and merge once. Hosts that
+ * pass a getter pay for the subscription; hosts that pass an object don't.
+ */
+import { effect, onUnmounted } from '@sigx/lynx';
+import { useScreenRegistry } from './use-nav-internal.js';
+import { mergeOptions } from '../internal/screen-registry.js';
+import type { ScreenOptions } from '../types.js';
+
+export function useScreenOptions(
+    optionsOrFn: ScreenOptions | (() => ScreenOptions),
+): void {
+    const registry = useScreenRegistry();
+
+    if (typeof optionsOrFn !== 'function') {
+        mergeOptions(registry, optionsOrFn);
+        return;
+    }
+
+    // Reactive path: every signal touched inside the getter is tracked, so
+    // the merge re-runs when any of them change. `mergeOptions` does per-key
+    // writes on a deeply-reactive proxy, so consumers (HeaderBar) only
+    // re-render the parts they actually read.
+    const runner = effect(() => {
+        const next = optionsOrFn();
+        mergeOptions(registry, next);
+    });
+    onUnmounted(() => runner.stop());
+}

package/src/href.ts

@@ -1,5 +1,9 @@
 import type { RouteId, RouteParams, RouteSearch } from './register.js';
 import type { RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav.js';
+import { buildUrl } from './url/build.js';
+import { parseHrefImpl } from './url/parse.js';
+import { getRouteRegistry } from './url/registry.js';
+import { validateSync } from './url/validate.js';
 
 /**
  * A typed reference to a navigation target — what `<Link to={...}>` consumes
@@ -25,6 +29,15 @@ export interface Href<K extends RouteId = RouteId> {
  * params schema, one for routes that require params. See `RoutesWithParams`
  * in `./hooks/use-nav.js` for why this isn't expressed as a single conditional.
  *
+ * Requires a `<NavigationRoot>` (or an explicit `_setRouteRegistry` call) to
+ * have run — the URL form is built against the active route registry. The
+ * typed pieces (`route`, `params`, `search`) are returned regardless; `url`
+ * is `null` when the route declares no `path` template.
+ *
+ * Schema validation errors throw — pass already-validated values from
+ * `useParams` / `useSearch` to round-trip safely, or wrap in try/catch when
+ * building hrefs from external input.
+ *
  * @example
  * ```ts
  * hrefFor('profile', { id: '42' });               // → { route, params, search: {}, url: '/users/42' }
@@ -38,21 +51,65 @@ export function hrefFor<K extends RoutesWithParams>(
     params: RouteParams<K>,
     search?: RouteSearch<K>,
 ): Href<K>;
-export function hrefFor(name: string, ..._args: unknown[]): Href {
-    void name;
-    void _args;
-    throw new Error(
-        'hrefFor() runtime is not implemented yet — this is the type spike.',
-    );
+export function hrefFor(name: string, ...args: unknown[]): Href {
+    const registry = getRouteRegistry();
+    const def = registry.routes[name];
+    if (!def) {
+        throw new Error(
+            `[lynx-navigation] hrefFor('${name}'): route is not in the active registry.`,
+        );
+    }
+
+    // Disambiguate the overloads: routes with a params schema get
+    // (name, params, search?); routes without get (name, search?). The
+    // typed overloads enforce this at compile time, but at runtime we need
+    // to peek at the schema presence to know how to interpret `args`.
+    const hasParamsSchema = !!def.params;
+    let rawParams: Record<string, unknown> | undefined;
+    let rawSearch: Record<string, unknown> | undefined;
+    if (hasParamsSchema) {
+        rawParams = args[0] as Record<string, unknown> | undefined;
+        rawSearch = args[1] as Record<string, unknown> | undefined;
+    } else {
+        rawParams = undefined;
+        rawSearch = args[0] as Record<string, unknown> | undefined;
+    }
+
+    const paramsOutcome = validateSync(def.params, rawParams ?? {});
+    if (!paramsOutcome.ok) {
+        throw new Error(
+            `[lynx-navigation] hrefFor('${name}'): params validation failed — ${paramsOutcome.issues.join('; ')}`,
+        );
+    }
+    const searchOutcome = validateSync(def.search, rawSearch ?? {});
+    if (!searchOutcome.ok) {
+        throw new Error(
+            `[lynx-navigation] hrefFor('${name}'): search validation failed — ${searchOutcome.issues.join('; ')}`,
+        );
+    }
+
+    const params = paramsOutcome.value as Record<string, unknown>;
+    const search = searchOutcome.value as Record<string, unknown>;
+    const url = buildUrl(name, params, search);
+
+    return {
+        route: name as RouteId,
+        params: params as never,
+        search: search as never,
+        url,
+    };
 }
 
 /**
  * Parse a URL string into a typed Href against the registered routes.
- * Returns `null` if no route's `path` template matches.
+ * Returns `null` if no route's `path` template matches the URL or if the
+ * extracted params/search fail the route's schema validation.
+ *
+ * Accepts both absolute (`myapp://host/path?q`) and pathname-only
+ * (`/path?q`) forms — the pathname is matched against each route's
+ * compiled template. Iteration order is the registration order; first match
+ * wins.
  */
 export function parseHref(url: string): Href | null {
-    void url;
-    throw new Error(
-        'parseHref() runtime is not implemented yet — this is the type spike.',
-    );
+    return parseHrefImpl(url);
 }

package/src/index.ts

@@ -12,10 +12,37 @@ export type { Nav, RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav
 export { useParams } from './hooks/use-params.js';
 export { useSearch } from './hooks/use-search.js';
 export { useHardwareBack } from './hooks/use-hardware-back.js';
+export { useLinkingNav } from './hooks/use-linking-nav.js';
+export type { UseLinkingNavOptions } from './hooks/use-linking-nav.js';
+export { useIsFocused, useFocusEffect } from './hooks/use-focus.js';
+export { useScreenOptions } from './hooks/use-screen-options.js';
+export {
+    useNavSerializer,
+    NAV_SNAPSHOT_VERSION,
+} from './hooks/use-nav-serializer.js';
+export type {
+    NavSnapshot,
+    NavStorageAdapter,
+    UseNavSerializerOptions,
+} from './hooks/use-nav-serializer.js';
 export { hrefFor, parseHref } from './href.js';
 export type { Href } from './href.js';
+// URL bridge internals: `_setRouteRegistry` is a leading-underscore export —
+// intended for tests, deep-link bootstrap before a NavigationRoot mounts, and
+// any other integration that needs to seed the registry imperatively.
+export { _setRouteRegistry, _clearRouteRegistry } from './url/registry.js';
+export { compilePath } from './url/compile.js';
+export type { CompiledPath } from './url/compile.js';
 export { NavigationRoot } from './components/NavigationRoot.js';
 export { Stack } from './components/Stack.js';
+export { Screen } from './components/Screen.js';
+export { Header } from './components/Header.js';
+export { Tabs, useTabs } from './components/Tabs.js';
+export type { TabInfo, TabsNav } from './components/Tabs.js';
+export { TabBar } from './components/TabBar.js';
+export type { TabRenderContext } from './components/TabBar.js';
+export { Drawer, useDrawer } from './components/Drawer.js';
+export type { DrawerNav } from './components/Drawer.js';
 export { Link } from './components/Link.js';
 export type { LinkProps } from './components/Link.js';
 export type {
@@ -29,6 +56,8 @@ export type {
     RouteDefinition,
     RouteMap,
     RouteRequiresParams,
+    ScreenOptions,
+    ScreenSlotFills,
     SearchOf,
     StackEntry,
     StandardSchemaV1,

package/src/internal/screen-registry.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-entry registry of `<Screen>` options + slot fills.
+ *
+ * Each `<EntryScope>` allocates one of these on mount and provides it to
+ * descendants via `defineProvide(useScreenRegistry, ...)`. The Screen
+ * component and its sub-components (`<Screen.Header>`, `<Screen.HeaderLeft>`,
+ * `<Screen.HeaderRight>`, `<Screen.TabBarItem>`) write into the registry as
+ * they mount.
+ *
+ * Reads track because options/slots are stored in signals — when a child
+ * re-renders and registers a new slot fill, the navigator-side consumer
+ * (HeaderBar / TabBar, shipped in later slices) reactively updates.
+ *
+ * Cross-entry lookup is exposed via the navigator's `getScreenRegistry(key)`
+ * so a persistent HeaderBar can read slots from the currently-focused entry
+ * without needing to be itself remounted on each navigation.
+ */
+import { signal, type Signal } from '@sigx/lynx';
+import type {
+    ScreenOptions,
+    ScreenSlotFills,
+    StackEntry,
+} from '../types.js';
+
+/**
+ * Reactive container for one screen's options and slot fills.
+ *
+ * `options` and `slots` are deeply-reactive object signals (sigx's `signal()`
+ * of an object returns a Proxy that tracks per-key reads and notifies
+ * per-key writes). Writers assign individual keys; readers subscribe to the
+ * keys they actually use — no whole-object reads, no read/write cycles in
+ * setup.
+ */
+export interface ScreenRegistry {
+    readonly entry: StackEntry;
+    /** Reactive ScreenOptions — written per-key by `<Screen>`. */
+    readonly options: Signal<ScreenOptions>;
+    /** Reactive ScreenSlotFills — written per-key by `<Screen.Header>` et al. */
+    readonly slots: Signal<ScreenSlotFills>;
+}
+
+/** Create a fresh registry for an entry. Options and slots start empty. */
+export function createScreenRegistry(entry: StackEntry): ScreenRegistry {
+    return {
+        entry,
+        options: signal<ScreenOptions>({}),
+        slots: signal<ScreenSlotFills>({}),
+    };
+}
+
+/**
+ * Set a single slot fill on a registry. Pass `undefined` to clear.
+ * Per-key write on the proxy — does not read other keys, so it can't loop
+ * with effects that read different slot keys.
+ */
+export function setSlot<K extends keyof ScreenSlotFills>(
+    registry: ScreenRegistry,
+    name: K,
+    fill: ScreenSlotFills[K] | undefined,
+): void {
+    if (fill === undefined) {
+        // Assigning undefined keeps the key around in the proxy; explicit
+        // delete is what consumers checking `name in slots` expect.
+        delete registry.slots[name];
+        return;
+    }
+    (registry.slots as ScreenSlotFills)[name] = fill;
+}
+
+/**
+ * Merge partial options into a registry. Each option key is written
+ * independently on the proxy — `undefined` keys clear that option.
+ */
+export function mergeOptions(
+    registry: ScreenRegistry,
+    patch: ScreenOptions,
+): void {
+    for (const key of Object.keys(patch) as (keyof ScreenOptions)[]) {
+        const v = patch[key];
+        if (v === undefined) {
+            delete registry.options[key];
+        } else {
+            // Property-level assignment on a deeply-reactive proxy: notifies
+            // only subscribers of this specific key, never reads the whole
+            // options object, so it can't trigger the setup that wrote it.
+            (registry.options as unknown as Record<string, unknown>)[key] = v;
+        }
+    }
+}

package/src/navigator/core.ts

@@ -1,11 +1,14 @@
 import {
     runOnMainThread,
     signal,
+    untrack,
     type Signal,
     type SharedValue,
 } from '@sigx/lynx';
-import { withTiming } from '@sigx/motion';
+import { isLazyComponent } from '@sigx/lynx';
+import { withTiming } from '@sigx/lynx-motion';
 import type { Nav } from '../hooks/use-nav.js';
+import type { ScreenRegistry } from '../internal/screen-registry.js';
 import type {
     PopOptions,
     Presentation,
@@ -43,15 +46,50 @@ export interface NavigatorState {
         commitBackGesture(): void;
         cancelBackGesture(): void;
     };
+    /**
+     * Internal: cross-entry `<Screen>` registry lookup.
+     *
+     * Each `<EntryScope>` registers its `ScreenRegistry` here on mount and
+     * removes it on unmount. The navigator's persistent chrome (HeaderBar /
+     * TabBar, shipped in later slices) calls `getScreenRegistry(entry.key)`
+     * to read the currently-focused screen's options/slot fills without
+     * being itself remounted on each navigation.
+     *
+     * Returns `undefined` when no screen for that key has mounted yet (or
+     * after it has unmounted) — consumers must tolerate this and render
+     * defaults.
+     */
+    readonly _screens: {
+        register(registry: ScreenRegistry): void;
+        unregister(entryKey: string): void;
+        get(entryKey: string): ScreenRegistry | undefined;
+    };
 }
 
 /**
  * Slide-from-right transition timing. Kept as constants so screen options
  * can override per-screen later (Phase 0.5). Duration is in seconds — that's
- * what `@sigx/motion`'s `withTiming` expects (per `with-timing.ts`).
+ * what `@sigx/lynx-motion`'s `withTiming` expects (per `with-timing.ts`).
  */
 const TRANSITION_DURATION_SEC = 0.28;
 
+/**
+ * Kick off a lazy component's chunk fetch when its route is navigated to.
+ *
+ * Lazy routes (`component: lazy(() => import('./Heavy.js'))`) start loading
+ * the moment `push`/`replace` is called rather than waiting until render
+ * tries to instantiate them — by the time `<Stack>` swaps screens the chunk
+ * is usually already resolved, so the user sees the screen instead of the
+ * `<Suspense fallback>`. Fire-and-forget: errors here surface through
+ * `<Suspense>` at render time.
+ */
+function preloadRouteComponent(component: unknown): void {
+    if (isLazyComponent(component)) {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        component.preload().catch(() => {});
+    }
+}
+
 let entryKeyCounter = 0;
 function nextEntryKey(): string {
     entryKeyCounter += 1;
@@ -104,7 +142,7 @@ export interface CreateNavigatorOptions {
      * SharedValue driving push/pop transition progress. Created in
      * `<NavigationRoot>` setup via `useSharedValue(0)` so the bridge
      * plumbing is wired (SharedValue is an MT-bridged ref). When undefined,
-     * navigations are instant — used by tests against `@sigx/testing-lynx`
+     * navigations are instant — used by tests against `@sigx/lynx-testing`
      * that don't have an MT runtime.
      */
     progress?: SharedValue<number>;
@@ -181,7 +219,7 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
             // MT-side direct write — `sv.value` is a BG-side getter/setter
             // that emits a "read-only on BG" warning when set; the actual
             // MT field (which `withTiming`'s animate() reads as the start
-            // value) is `sv.current.value`. See `packages/runtime-lynx/src/
+            // value) is `sv.current.value`. See `packages/lynx-runtime/src/
             // animated/shared-value.ts:14-44`.
             sv.current.value = 0;
             withTiming(sv, t, { duration: d });
@@ -201,6 +239,7 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
                     `Known routes: ${Object.keys(routes).join(', ') || '(none)'}`,
             );
         }
+        preloadRouteComponent(routes[name].component);
         const newEntry = makeEntry(name, params, search, options, routes);
         const cur = getStack();
         const prevTop = cur[cur.length - 1];
@@ -234,6 +273,7 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
                 `[lynx-navigation] replace('${name}'): route is not registered.`,
             );
         }
+        preloadRouteComponent(routes[name].component);
         const entry = makeEntry(name, params, search, options, routes);
         const cur = getStack();
         // Replace doesn't animate in v1 — it's a swap, not a forward/back nav.
@@ -382,5 +422,47 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
         nav,
         routes,
         _gesture: { beginBackGesture, commitBackGesture, cancelBackGesture },
+        _screens: createScreenRegistries(),
+    };
+}
+
+/**
+ * Map-backed `_screens` controller. Pulled out as a tiny factory so test
+ * tooling can call it directly when asserting registry behaviour without
+ * standing up an entire navigator.
+ *
+ * Not reactive — `<EntryScope>` registers once at setup and unregisters at
+ * unmount, so reads from the navigator's chrome are point-in-time lookups,
+ * and the registry's own internal signals carry the reactive payload.
+ */
+function createScreenRegistries(): NavigatorState['_screens'] {
+    const byKey = new Map<string, ScreenRegistry>();
+    // Reactive version tick — bumped on every register/unregister so consumers
+    // (HeaderBar's computeds) re-evaluate their lookups when entries come and
+    // go. `Map.get` itself isn't tracked, so without this a chrome component
+    // that renders before its target entry mounts would never see the late
+    // arrival of the registry.
+    const version = signal({ v: 0 });
+    return {
+        register(reg: ScreenRegistry) {
+            byKey.set(reg.entry.key, reg);
+            // `register` is called from `<EntryScope>` setup, which itself
+            // runs inside a tracked scope. Read-then-write on `version`
+            // would self-loop, so we untrack the bump.
+            untrack(() => { version.v = version.v + 1; });
+        },
+        unregister(key: string) {
+            byKey.delete(key);
+            untrack(() => { version.v = version.v + 1; });
+        },
+        get(key: string) {
+            // Touch the version signal so the caller's reactive scope
+            // re-runs on the next register/unregister. The actual returned
+            // value still comes from the plain Map — registries themselves
+            // are signal-backed, so once a caller has one in hand they
+            // track the bits they care about (options/slots) directly.
+            void version.v;
+            return byKey.get(key);
+        },
     };
 }