@sigx/lynx-navigation 0.1.3 → 0.4.0

package/src/index.ts

@@ -5,46 +5,48 @@
  * Coming next: Screen with slot-based header API, MTS transitions, Tabs.
  */
 
-export { defineRoutes } from './define-routes.js';
-export type { Register, RegisteredRoutes, RouteId, RouteParams, RouteSearch } from './register.js';
-export { useNav } from './hooks/use-nav.js';
-export type { Nav, RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav.js';
-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 { defineRoutes } from './define-routes';
+export type { Register, RegisteredRoutes, RouteId, RouteParams, RouteSearch } from './register';
+export { useNav } from './hooks/use-nav';
+export type { Nav, RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav';
+export { useParams } from './hooks/use-params';
+export { useSearch } from './hooks/use-search';
+export { useHardwareBack } from './hooks/use-hardware-back';
+export { useLinkingNav } from './hooks/use-linking-nav';
+export type { UseLinkingNavOptions } from './hooks/use-linking-nav';
+export { useIsFocused, useFocusEffect } from './hooks/use-focus';
+export { useScreenOptions } from './hooks/use-screen-options';
+export { useScreenChrome } from './hooks/use-screen-chrome';
+export type { ScreenChrome } from './hooks/use-screen-chrome';
 export {
     useNavSerializer,
     NAV_SNAPSHOT_VERSION,
-} from './hooks/use-nav-serializer.js';
+} from './hooks/use-nav-serializer';
 export type {
     NavSnapshot,
     NavStorageAdapter,
     UseNavSerializerOptions,
-} from './hooks/use-nav-serializer.js';
-export { hrefFor, parseHref } from './href.js';
-export type { Href } from './href.js';
+} from './hooks/use-nav-serializer';
+export { hrefFor, parseHref } from './href';
+export type { Href } from './href';
 // 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 { _setRouteRegistry, _clearRouteRegistry } from './url/registry';
+export { compilePath } from './url/compile';
+export type { CompiledPath } from './url/compile';
+export { NavigationRoot } from './components/NavigationRoot';
+export { Stack } from './components/Stack';
+export { Screen } from './components/Screen';
+export { Header } from './components/Header';
+export { Tabs, useTabs } from './components/Tabs';
+export type { TabInfo, TabsNav } from './components/Tabs';
+export { TabBar } from './components/TabBar';
+export type { TabRenderContext } from './components/TabBar';
+export { Drawer, useDrawer } from './components/Drawer';
+export type { DrawerNav } from './components/Drawer';
+export { Link } from './components/Link';
+export type { LinkProps } from './components/Link';
 export type {
     ComponentLike,
     EmptyParams,
@@ -64,4 +66,4 @@ export type {
     TransitionKind,
     TransitionRole,
     TransitionState,
-} from './types.js';
+} from './types';

package/src/internal/layer-plan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure layer-plan computation for `<Stack>`'s render.
+ *
+ * Given (stack, transition, progress), produces an ordered list of
+ * `Layer`s — each is an entry to render plus an optional transform
+ * spec for animation. The Stack render emits one absolutely-positioned
+ * `<view>` per layer, stacked bottom-to-top in document order.
+ *
+ * Why this is its own module: the layer-selection logic is the only
+ * non-obvious part of the navigator's render path, and the rules are
+ * easier to read (and unit-test) as a pure function over the
+ * navigator's state than as inline render branches.
+ *
+ * Rules:
+ *
+ *  - **Idle (no transition).** Render the topmost non-overlay entry
+ *    as the base, plus every overlay entry above it. Overlays
+ *    (`modal` / `fullScreen` / `transparent-modal`) keep their
+ *    underneath mounted; cards replace their underneath in the base
+ *    layer.
+ *
+ *  - **Card transition.** Two layers: the underneath entry (animated
+ *    with the parallax-card-underneath spec) and the top entry
+ *    (animated with the slide-in-from-right spec). After the
+ *    transition completes, the idle rule kicks in — the underneath
+ *    unmounts because the new top becomes the sole base.
+ *
+ *  - **Overlay transition.** The full idle layer stack up through the
+ *    underneath entry stays static (no transform). The animated top
+ *    is the only layer with a transform. After the transition, the
+ *    overlay either joins the static idle stack (push) or unmounts
+ *    (pop).
+ *
+ * The Layer.key for the Stack render is
+ * `layer-${entry.key}-${animVariant(layer.animation)}`. The variant
+ * suffix forces a remount when an entry transitions from animated to
+ * static (or vice versa) — `useAnimatedStyle` can't re-bind mid-life,
+ * so we get a fresh `useAnimatedStyle` call per animation state.
+ * Modal underneath layers never animate, so they stay statically
+ * keyed across the modal lifecycle and their state (per-tab Stack,
+ * scroll, in-flight inputs) survives.
+ */
+import type { SharedValue } from '@sigx/lynx';
+import type { Presentation, StackEntry, TransitionState } from '../types';
+export type LayerAnimation = {
+    axis: 'translateX' | 'translateY';
+    inputRange: readonly [number, number];
+    outputRange: readonly [number, number];
+    progress: SharedValue<number>;
+};
+export interface Layer {
+    /** The entry whose component renders inside this layer. */
+    readonly entry: StackEntry;
+    /** When non-null, the layer's host view binds a `useAnimatedStyle` mapper. */
+    readonly animation: LayerAnimation | null;
+}
+export declare function isOverlayPresentation(p: Presentation): boolean;
+/**
+ * Suffix used in a layer's render key. Stable for the layer's
+ * lifetime (same entry, same animation kind) and changes when the
+ * animation transitions on/off so the Layer remounts and rebinds.
+ */
+export declare function animationVariant(animation: LayerAnimation | null): string;
+/**
+ * Compute the visible-layer list for one render of `<Stack>`. Pure —
+ * unit-testable independently of the renderer.
+ */
+export declare function computeLayers(stack: readonly StackEntry[], transition: TransitionState | null, progress: SharedValue<number> | null): Layer[];

package/src/internal/layer-plan.ts

@@ -0,0 +1,187 @@
+/**
+ * Pure layer-plan computation for `<Stack>`'s render.
+ *
+ * Given (stack, transition, progress), produces an ordered list of
+ * `Layer`s — each is an entry to render plus an optional transform
+ * spec for animation. The Stack render emits one absolutely-positioned
+ * `<view>` per layer, stacked bottom-to-top in document order.
+ *
+ * Why this is its own module: the layer-selection logic is the only
+ * non-obvious part of the navigator's render path, and the rules are
+ * easier to read (and unit-test) as a pure function over the
+ * navigator's state than as inline render branches.
+ *
+ * Rules:
+ *
+ *  - **Idle (no transition).** Render the topmost non-overlay entry
+ *    as the base, plus every overlay entry above it. Overlays
+ *    (`modal` / `fullScreen` / `transparent-modal`) keep their
+ *    underneath mounted; cards replace their underneath in the base
+ *    layer.
+ *
+ *  - **Card transition.** Two layers: the underneath entry (animated
+ *    with the parallax-card-underneath spec) and the top entry
+ *    (animated with the slide-in-from-right spec). After the
+ *    transition completes, the idle rule kicks in — the underneath
+ *    unmounts because the new top becomes the sole base.
+ *
+ *  - **Overlay transition.** The full idle layer stack up through the
+ *    underneath entry stays static (no transform). The animated top
+ *    is the only layer with a transform. After the transition, the
+ *    overlay either joins the static idle stack (push) or unmounts
+ *    (pop).
+ *
+ * The Layer.key for the Stack render is
+ * `layer-${entry.key}-${animVariant(layer.animation)}`. The variant
+ * suffix forces a remount when an entry transitions from animated to
+ * static (or vice versa) — `useAnimatedStyle` can't re-bind mid-life,
+ * so we get a fresh `useAnimatedStyle` call per animation state.
+ * Modal underneath layers never animate, so they stay statically
+ * keyed across the modal lifecycle and their state (per-tab Stack,
+ * scroll, in-flight inputs) survives.
+ */
+import type { SharedValue } from '@sigx/lynx';
+import { SCREEN_HEIGHT, SCREEN_WIDTH } from './screen-width';
+import type {
+    Presentation,
+    StackEntry,
+    TransitionKind,
+    TransitionState,
+} from '../types';
+
+const PARALLAX_FACTOR = 0.3;
+
+export type LayerAnimation = {
+    axis: 'translateX' | 'translateY';
+    inputRange: readonly [number, number];
+    outputRange: readonly [number, number];
+    progress: SharedValue<number>;
+};
+
+export interface Layer {
+    /** The entry whose component renders inside this layer. */
+    readonly entry: StackEntry;
+    /** When non-null, the layer's host view binds a `useAnimatedStyle` mapper. */
+    readonly animation: LayerAnimation | null;
+}
+
+export function isOverlayPresentation(p: Presentation): boolean {
+    return p === 'modal' || p === 'fullScreen' || p === 'transparent-modal';
+}
+
+/**
+ * Suffix used in a layer's render key. Stable for the layer's
+ * lifetime (same entry, same animation kind) and changes when the
+ * animation transitions on/off so the Layer remounts and rebinds.
+ */
+export function animationVariant(animation: LayerAnimation | null): string {
+    if (!animation) return 'static';
+    // Output range alone identifies the transition shape — different
+    // animations (card-top vs card-underneath vs overlay-top, push vs
+    // pop) all land on different range tuples.
+    return `${animation.axis}:${animation.outputRange[0]}->${animation.outputRange[1]}`;
+}
+
+/**
+ * Card-presentation transition transforms. `role='top'` is the entry
+ * being pushed/popped; `role='underneath'` is the one parallaxing.
+ */
+function cardAnimation(
+    role: 'top' | 'underneath',
+    kind: TransitionKind,
+    progress: SharedValue<number>,
+): LayerAnimation {
+    if (kind === 'push') {
+        if (role === 'top') {
+            return { axis: 'translateX', inputRange: [0, 1], outputRange: [SCREEN_WIDTH, 0], progress };
+        }
+        return { axis: 'translateX', inputRange: [0, 1], outputRange: [0, -PARALLAX_FACTOR * SCREEN_WIDTH], progress };
+    }
+    // pop
+    if (role === 'top') {
+        return { axis: 'translateX', inputRange: [0, 1], outputRange: [0, SCREEN_WIDTH], progress };
+    }
+    return { axis: 'translateX', inputRange: [0, 1], outputRange: [-PARALLAX_FACTOR * SCREEN_WIDTH, 0], progress };
+}
+
+/**
+ * Overlay-presentation transition transform for the animated top.
+ * The underneath of an overlay transition does not animate (modal
+ * doesn't reposition its background); we render it as a static layer
+ * instead, so this function only produces the top's transform.
+ */
+function overlayTopAnimation(
+    kind: TransitionKind,
+    progress: SharedValue<number>,
+): LayerAnimation {
+    if (kind === 'push') {
+        return { axis: 'translateY', inputRange: [0, 1], outputRange: [SCREEN_HEIGHT, 0], progress };
+    }
+    return { axis: 'translateY', inputRange: [0, 1], outputRange: [0, SCREEN_HEIGHT], progress };
+}
+
+/**
+ * Compute the visible-layer list for one render of `<Stack>`. Pure —
+ * unit-testable independently of the renderer.
+ */
+export function computeLayers(
+    stack: readonly StackEntry[],
+    transition: TransitionState | null,
+    progress: SharedValue<number> | null,
+): Layer[] {
+    if (!transition) {
+        // Idle: topmost non-overlay base + any overlays above it.
+        let baseIdx = stack.length - 1;
+        while (baseIdx > 0 && isOverlayPresentation(stack[baseIdx].presentation)) {
+            baseIdx -= 1;
+        }
+        return stack.slice(baseIdx).map((entry) => ({ entry, animation: null }));
+    }
+
+    // A transition is in flight. `progress` may still be null when
+    // animations are disabled — produce static layers in that case
+    // (the animation never plays; the transition timer just ticks).
+    const isOverlay = isOverlayPresentation(transition.topEntry.presentation);
+    if (!isOverlay) {
+        // Card transition: just the two participating entries, both
+        // animated (parallax underneath + slide top).
+        return [
+            {
+                entry: transition.underneathEntry,
+                animation: progress ? cardAnimation('underneath', transition.kind, progress) : null,
+            },
+            {
+                entry: transition.topEntry,
+                animation: progress ? cardAnimation('top', transition.kind, progress) : null,
+            },
+        ];
+    }
+
+    // Overlay transition: render the full idle layer stack up through
+    // the underneath entry (all static — they don't animate) plus the
+    // animated top.
+    const underneathIdx = stack.findIndex(
+        (e) => e.key === transition.underneathEntry.key,
+    );
+    // If the underneath isn't in the stack (e.g. mid-pop where the
+    // stack mutation already removed an entry), fall back to the
+    // current top of the stack.
+    const lastStaticIdx = underneathIdx >= 0 ? underneathIdx : stack.length - 1;
+
+    let baseIdx = lastStaticIdx;
+    while (baseIdx > 0 && isOverlayPresentation(stack[baseIdx].presentation)) {
+        baseIdx -= 1;
+    }
+
+    const staticLayers: Layer[] = stack
+        .slice(baseIdx, lastStaticIdx + 1)
+        .map((entry) => ({ entry, animation: null }));
+
+    return [
+        ...staticLayers,
+        {
+            entry: transition.topEntry,
+            animation: progress ? overlayTopAnimation(transition.kind, progress) : null,
+        },
+    ];
+}

package/{dist/internal/screen-registry.js → src/internal/screen-registry.d.ts}

@@ -15,45 +15,34 @@
  * so a persistent HeaderBar can read slots from the currently-focused entry
  * without needing to be itself remounted on each navigation.
  */
-import { signal } from '@sigx/lynx';
-/** Create a fresh registry for an entry. Options and slots start empty. */
-export function createScreenRegistry(entry) {
-    return {
-        entry,
-        options: signal({}),
-        slots: signal({}),
-    };
+import { type Signal } from '@sigx/lynx';
+import type { ScreenOptions, ScreenSlotFills, StackEntry } from '../types';
+/**
+ * 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 declare function createScreenRegistry(entry: StackEntry): ScreenRegistry;
 /**
  * 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(registry, name, fill) {
-    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[name] = fill;
-}
+export declare function setSlot<K extends keyof ScreenSlotFills>(registry: ScreenRegistry, name: K, fill: ScreenSlotFills[K] | undefined): void;
 /**
  * Merge partial options into a registry. Each option key is written
  * independently on the proxy — `undefined` keys clear that option.
  */
-export function mergeOptions(registry, patch) {
-    for (const key of Object.keys(patch)) {
-        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[key] = v;
-        }
-    }
-}
-//# sourceMappingURL=screen-registry.js.map
+export declare function mergeOptions(registry: ScreenRegistry, patch: ScreenOptions): void;

package/src/internal/screen-registry.ts

@@ -20,7 +20,7 @@ import type {
     ScreenOptions,
     ScreenSlotFills,
     StackEntry,
-} from '../types.js';
+} from '../types';
 
 /**
  * Reactive container for one screen's options and slot fills.

package/src/internal/screen-width.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Logical screen dimensions (in dp) read from `lynx.SystemInfo` at module
+ * load. Falls back to typical phone values if SystemInfo isn't available —
+ * module load happens BG-side after the bundle initializes, by which time
+ * `lynx.SystemInfo` is populated, so the fallback only fires in tests /
+ * SSR / non-Lynx hosts.
+ *
+ * Used by:
+ *   - `<ScreenContainer>` for the slide-from-right (translateX) and
+ *     slide-from-bottom (translateY, modal) transform output ranges.
+ *   - `<EdgeBackHandle>` for the gesture commit threshold (`dx / width`).
+ *
+ * Both must agree, otherwise the commit threshold and the animation
+ * geometry won't line up. Single shared module avoids drift.
+ */
+export declare const SCREEN_WIDTH: number;
+export declare const SCREEN_HEIGHT: number;

package/src/internal/screen-width.ts

@@ -1,34 +1,42 @@
 /**
- * Logical screen width (in dp) read from `lynx.SystemInfo` at module load.
- * Falls back to 400 (typical phone) if SystemInfo isn't available — module
- * load happens BG-side after the bundle initializes, by which time
- * `lynx.SystemInfo` is populated, so the fallback only fires in tests / SSR /
- * non-Lynx hosts.
+ * Logical screen dimensions (in dp) read from `lynx.SystemInfo` at module
+ * load. Falls back to typical phone values if SystemInfo isn't available —
+ * module load happens BG-side after the bundle initializes, by which time
+ * `lynx.SystemInfo` is populated, so the fallback only fires in tests /
+ * SSR / non-Lynx hosts.
  *
  * Used by:
- *   - `<ScreenContainer>` for the slide-from-right transform output range.
+ *   - `<ScreenContainer>` for the slide-from-right (translateX) and
+ *     slide-from-bottom (translateY, modal) transform output ranges.
  *   - `<EdgeBackHandle>` for the gesture commit threshold (`dx / width`).
  *
  * Both must agree, otherwise the commit threshold and the animation
- * geometry won't line up. Single shared constant avoids drift.
+ * geometry won't line up. Single shared module avoids drift.
  */
 
 declare const lynx:
-    | { SystemInfo?: { pixelWidth?: number; pixelRatio?: number } }
+    | {
+        SystemInfo?: {
+            pixelWidth?: number;
+            pixelHeight?: number;
+            pixelRatio?: number;
+        };
+    }
     | undefined;
 
-function readScreenWidth(): number {
+function readDp(prop: 'pixelWidth' | 'pixelHeight', fallback: number): number {
     try {
         const info = typeof lynx !== 'undefined' ? lynx?.SystemInfo : undefined;
-        const pw = info?.pixelWidth;
+        const px = info?.[prop];
         const pr = info?.pixelRatio || 1;
-        if (typeof pw === 'number' && pw > 0) {
-            return Math.round(pw / pr);
+        if (typeof px === 'number' && px > 0) {
+            return Math.round(px / pr);
         }
     } catch {
         // Lynx globals not present (test env / SSR) — use fallback.
     }
-    return 400;
+    return fallback;
 }
 
-export const SCREEN_WIDTH = readScreenWidth();
+export const SCREEN_WIDTH = readDp('pixelWidth', 400);
+export const SCREEN_HEIGHT = readDp('pixelHeight', 800);

package/src/navigator/core.d.ts

@@ -0,0 +1,96 @@
+import { type SharedValue } from '@sigx/lynx';
+import type { Nav } from '../hooks/use-nav';
+import type { ScreenRegistry } from '../internal/screen-registry';
+import type { RouteMap, StackEntry } from '../types';
+/**
+ * The reactive backing state for one navigator instance.
+ *
+ * Two reactive signals drive the public surface:
+ *   - `stack` is the entry array (read via `nav.stack` / `nav.current`).
+ *   - `transition` is non-null only while a push/pop animation is in flight;
+ *     `<Stack>` reads it to decide whether to render one screen or two.
+ *
+ * Pop is committed *after* its slide animation completes — `nav.canGoBack`
+ * stays true during the slide, then flips when the entry actually leaves the
+ * stack. Push commits its stack mutation immediately and animates the new
+ * entry in.
+ */
+export interface NavigatorState {
+    readonly nav: Nav;
+    readonly routes: RouteMap;
+    /**
+     * Internal: BG-side gesture-back controller used by `<EdgeBackHandle>`.
+     * The `progress` SharedValue is wired here so a gesture worklet can write
+     * it directly on MT; the begin/commit/cancel methods set the transition
+     * state appropriately without driving their own auto-animation (the
+     * gesture worklet is in charge of that).
+     */
+    readonly _gesture: {
+        beginBackGesture(): void;
+        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;
+        /** Identity-checked: no-op when a newer registry has taken the slot. */
+        unregister(registry: ScreenRegistry): void;
+        get(entryKey: string): ScreenRegistry | undefined;
+    };
+    /**
+     * Internal: set `nav.isLocallyFocused` from outside.
+     *
+     * `<Stack>` calls this when its host entry's locally-focused state
+     * changes (top of parent + parent focused + enclosing tab active). For
+     * the root nav this stays `true` for the lifetime of the navigator.
+     */
+    readonly _setLocallyFocused: (focused: boolean) => void;
+}
+export interface CreateNavigatorOptions {
+    routes: RouteMap;
+    initial: StackEntry;
+    /**
+     * 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/lynx-testing`
+     * that don't have an MT runtime.
+     */
+    progress?: SharedValue<number>;
+    /**
+     * Parent navigator. Set when this navigator is nested under another
+     * (e.g. a per-tab `<Stack initialRoute>` under root). Drives the
+     * `nav.parent` getter and the modal-escalation behaviour of `push`:
+     * a push of a route whose resolved presentation is not `'card'`
+     * recurses via `parent.push(...)`, walking up the chain until it
+     * lands on a navigator with no parent (the root).
+     *
+     * Leave undefined for the root navigator.
+     */
+    parent?: Nav | null;
+    /**
+     * Whether this navigator is considered "locally focused" at creation
+     * time. Defaults to true for the root nav; nested stacks pass `false`
+     * here and then flip the flag via `_setLocallyFocused` once their
+     * host-entry/tab-active state is computed.
+     */
+    initialLocallyFocused?: boolean;
+}
+/**
+ * Create a navigator. Returns the public `nav` handle plus the routes map.
+ * The transition signal lives on `nav` (via `nav.transition`) so `<Stack>`
+ * can subscribe to it.
+ */
+export declare function createNavigatorState(opts: CreateNavigatorOptions): NavigatorState;