@sigx/lynx-navigation 0.1.3 → 0.4.0

package/src/components/Tabs.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `<Tabs>` — Lynx tab navigator.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <NavigationRoot routes={routes} initialRoute="root">
+ *   <Stack />
+ * </NavigationRoot>
+ *
+ * // The route "root" component renders:
+ * <Tabs initialTab="feed">
+ *   <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
+ *     <Stack initialRoute="feedHome" />
+ *   </Tabs.Screen>
+ *   <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
+ *     <Stack initialRoute="profileHome" />
+ *   </Tabs.Screen>
+ *   <TabBar />
+ * </Tabs>
+ * ```
+ *
+ * Tab bodies stay mounted across switches (the inactive ones render with
+ * `display: 'none'`), so each tab's nested `<Stack>` keeps its history when
+ * the user flips back to it. The active tab is reactive via `useTabs()`.
+ *
+ * Per-tab stacks: each `<Tabs.Screen>` can host a `<Stack initialRoute="…">`
+ * which mints its own navigator. `useNav()` inside that subtree resolves to
+ * the tab's stack, so `nav.push('card-route', …)` stays inside the tab.
+ * Routes presented as `modal` / `fullScreen` / `transparent-modal` escalate
+ * up `nav.parent` to the root navigator automatically — they overlay the
+ * tabs UI (TabBar included) and dismiss back into the originating tab.
+ */
+import { type Define, type JSXElement } from '@sigx/lynx';
+/** Metadata about a registered `<Tabs.Screen>`. */
+export interface TabInfo {
+    /** Stable tab id, used by `setActive`. */
+    readonly name: string;
+    /** Optional icon node — passed through to the default tab bar. */
+    readonly icon?: JSXElement;
+    /** Optional human-readable label. Defaults to `name`. */
+    readonly label?: string;
+    /**
+     * Accessibility label announced by screen readers. Falls back to
+     * `label`, then `name`. Surfaced as `accessibility-label` on the
+     * default `<TabBar>` button.
+     */
+    readonly accessibilityLabel?: string;
+}
+/** Reactive controller exposed by `useTabs()`. */
+export interface TabsNav {
+    /** Currently-active tab name. Reactive — accessing inside render/effect tracks. */
+    readonly active: string;
+    /** Switch the active tab. Triggers reactive updates in any consumer. */
+    setActive(name: string): void;
+    /** Snapshot of registered tabs in registration order. Reactive. */
+    readonly tabs: ReadonlyArray<TabInfo>;
+}
+/**
+ * Access the enclosing Tabs navigator. Throws when called outside `<Tabs>`.
+ */
+export declare const useTabs: import("@sigx/runtime-core").InjectableFunction<TabsNav>;
+/**
+ * @internal
+ * Provided by each `<Tabs.Screen>` so a nested `<Stack initialRoute>` can
+ * discover *which* tab it's hosted by, and gate its focus state on that
+ * tab being active. Throws when called outside a `<Tabs.Screen>` body so
+ * the gate degrades to "always active" via the caller's try/catch.
+ */
+export declare const useTabScreenName: import("@sigx/runtime-core").InjectableFunction<string>;
+type TabsProps = Define.Prop<'initialTab', string> & Define.Slot<'default'>;
+type TabsScreenProps = Define.Prop<'name', string, true> & Define.Prop<'icon', JSXElement> & Define.Prop<'label', string> & Define.Prop<'accessibilityLabel', string> & Define.Slot<'default'>;
+/**
+ * Compound export. `Tabs` is the parent component; `Tabs.Screen` registers
+ * an individual tab. Matches the `Screen` / `Screen.Header` shape used
+ * elsewhere in this package and the daisyui `Modal` / `Modal.Header`
+ * convention.
+ */
+export declare const Tabs: ((props: {
+    initialTab?: string | undefined;
+} & {} & {
+    slots?: Partial<{
+        default: () => JSXElement | JSXElement[] | null;
+    }> | undefined;
+} & {} & JSX.IntrinsicAttributes & import("@sigx/runtime-core").ComponentAttributeExtensions & {
+    ref?: import("@sigx/runtime-core").Ref<void> | undefined;
+    children?: any;
+}) => JSXElement) & {
+    __setup: import("@sigx/runtime-core").SetupFn<{
+        initialTab?: string | undefined;
+    }, TabsProps, void, {
+        default: () => JSXElement | JSXElement[] | null;
+    }>;
+    __name?: string;
+    __islandId?: string;
+    __props: {
+        initialTab?: string | undefined;
+    };
+    __events: TabsProps;
+    __ref: void;
+    __slots: {
+        default: () => JSXElement | JSXElement[] | null;
+    };
+} & {
+    Screen: import("@sigx/runtime-core").ComponentFactory<TabsScreenProps, void, {
+        default: () => JSXElement | JSXElement[] | null;
+    }>;
+};
+export {};

package/src/components/Tabs.tsx

@@ -4,31 +4,32 @@
  * Usage:
  *
  * ```tsx
- * <NavigationRoot routes={routes}>
- *   <Tabs initialTab="feed">
- *     <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
- *       <FeedView />
- *     </Tabs.Screen>
- *     <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
- *       <ProfileView />
- *     </Tabs.Screen>
- *   </Tabs>
+ * <NavigationRoot routes={routes} initialRoute="root">
+ *   <Stack />
  * </NavigationRoot>
- * ```
  *
- * Scope of this slice (v0.1): pure UI primitive. Each tab's body stays
- * mounted for state preservation (the inactive ones render with
- * `display: 'none'`). Active tab is reactive via `useTabs()`.
+ * // The route "root" component renders:
+ * <Tabs initialTab="feed">
+ *   <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
+ *     <Stack initialRoute="feedHome" />
+ *   </Tabs.Screen>
+ *   <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
+ *     <Stack initialRoute="profileHome" />
+ *   </Tabs.Screen>
+ *   <TabBar />
+ * </Tabs>
+ * ```
  *
- * Out of scope (deferred to a nested-navigators slice):
- *   - Per-tab `<Stack>` with its own navigator state machine
- *   - `nav.parent` chain into the Tabs nav
- *   - Named navigators (`useNav('root')`)
+ * Tab bodies stay mounted across switches (the inactive ones render with
+ * `display: 'none'`), so each tab's nested `<Stack>` keeps its history when
+ * the user flips back to it. The active tab is reactive via `useTabs()`.
  *
- * Those build on multi-navigator-state plumbing that isn't ready yet.
- * For now, the inner content of a `<Tabs.Screen>` shares the same nav as
- * its outer `<NavigationRoot>` — usable for shallow tab apps, but full
- * nested routing comes later.
+ * Per-tab stacks: each `<Tabs.Screen>` can host a `<Stack initialRoute="…">`
+ * which mints its own navigator. `useNav()` inside that subtree resolves to
+ * the tab's stack, so `nav.push('card-route', …)` stays inside the tab.
+ * Routes presented as `modal` / `fullScreen` / `transparent-modal` escalate
+ * up `nav.parent` to the root navigator automatically — they overlay the
+ * tabs UI (TabBar included) and dismiss back into the originating tab.
  */
 import {
     component,
@@ -98,6 +99,19 @@ const useTabsRegistrar = defineInjectable<TabsRegistrar>(() => {
     );
 });
 
+/**
+ * @internal
+ * Provided by each `<Tabs.Screen>` so a nested `<Stack initialRoute>` can
+ * discover *which* tab it's hosted by, and gate its focus state on that
+ * tab being active. Throws when called outside a `<Tabs.Screen>` body so
+ * the gate degrades to "always active" via the caller's try/catch.
+ */
+export const useTabScreenName = defineInjectable<string>(() => {
+    throw new Error(
+        '[lynx-navigation] useTabScreenName() called outside a <Tabs.Screen> body.',
+    );
+});
+
 type TabsProps =
     & Define.Prop<'initialTab', string>
     & Define.Slot<'default'>;
@@ -186,17 +200,35 @@ const TabsScreen = component<TabsScreenProps>(({ props, slots }) => {
     });
     onUnmounted(() => registrar.unregister(name));
 
+    // Expose this screen's tab name so a nested `<Stack initialRoute>` body
+    // can gate its locally-focused state on `tabs.active === name`.
+    defineProvide(useTabScreenName, () => name);
+
     return () => {
         // `display: none` keeps the body mounted so per-tab state survives
         // tab switches. Read activeSignal here so re-activating triggers a
         // re-render with display restored.
+        //
+        // Flex-fill long-form (`flex-grow/shrink/basis`) instead of
+        // `height: '100%'`. The percentage form only resolves against an
+        // explicit parent height, which means consumers had to wrap us
+        // in a `flexFill + height: '100%'` view to make us visible — and
+        // every Lynx app got that wrong (myself included) until we hit
+        // it on the showcase. With flex-fill we just take whatever space
+        // our parent flex container gives us; the parent only needs to
+        // be a flex column with a known height (e.g. SafeAreaView, which
+        // now defaults to that).
         const active = registrar.activeSignal.value === name;
         return (
             <view
                 style={{
                     display: active ? 'flex' : 'none',
+                    flexDirection: 'column',
                     width: '100%',
-                    height: '100%',
+                    flexGrow: 1,
+                    flexShrink: 1,
+                    flexBasis: 0,
+                    minHeight: 0,
                 }}
             >
                 {slots.default?.()}

package/{dist/define-routes.js → src/define-routes.d.ts}

@@ -1,3 +1,4 @@
+import type { RouteMap } from './types';
 /**
  * Define a typed route registry.
  *
@@ -26,7 +27,4 @@
  * }
  * ```
  */
-export function defineRoutes(routes) {
-    return routes;
-}
-//# sourceMappingURL=define-routes.js.map
+export declare function defineRoutes<const T extends RouteMap>(routes: T): T;

package/src/define-routes.ts

@@ -1,4 +1,4 @@
-import type { RouteMap } from './types.js';
+import type { RouteMap } from './types';
 
 /**
  * Define a typed route registry.

package/{dist/hooks/use-focus.js → src/hooks/use-focus.d.ts}

@@ -1,6 +1,4 @@
-import { computed, effect, onUnmounted, untrack, } from '@sigx/lynx';
-import { useNav } from './use-nav.js';
-import { useCurrentEntry } from './use-nav-internal.js';
+import { type Computed } from '@sigx/lynx';
 /**
  * Reactive "is this screen the focused entry?" signal.
  *
@@ -21,14 +19,7 @@ import { useCurrentEntry } from './use-nav-internal.js';
  * });
  * ```
  */
-export function useIsFocused() {
-    const nav = useNav();
-    // Capture the entry's key once at setup. The entry object provided
-    // through `defineProvide` may carry reactive dependencies; we only care
-    // about the immutable key of the entry this screen was mounted for.
-    const myKey = useCurrentEntry().key;
-    return computed(() => nav.current.key === myKey);
-}
+export declare function useIsFocused(): Computed<boolean>;
 /**
  * Run `cb` whenever this screen gains focus; run the returned cleanup when it
  * loses focus or unmounts. Mirrors React Navigation's `useFocusEffect`.
@@ -51,31 +42,4 @@ export function useIsFocused() {
  * });
  * ```
  */
-export function useFocusEffect(cb) {
-    const isFocused = useIsFocused();
-    let cleanup;
-    const runner = effect(() => {
-        const focused = isFocused.value;
-        // Always tear down any previous focus session before starting a new
-        // one (or before going dormant on blur). Wrap `cb` in `untrack` so
-        // signals read inside the user-provided callback can't retrigger the
-        // outer effect and stack subscriptions.
-        if (typeof cleanup === 'function') {
-            const fn = cleanup;
-            cleanup = undefined;
-            fn();
-        }
-        if (focused) {
-            cleanup = untrack(() => cb());
-        }
-    });
-    onUnmounted(() => {
-        if (typeof cleanup === 'function') {
-            const fn = cleanup;
-            cleanup = undefined;
-            fn();
-        }
-        runner.stop();
-    });
-}
-//# sourceMappingURL=use-focus.js.map
+export declare function useFocusEffect(cb: () => void | (() => void)): void;

package/src/hooks/use-focus.ts

@@ -5,8 +5,8 @@ import {
     untrack,
     type Computed,
 } from '@sigx/lynx';
-import { useNav } from './use-nav.js';
-import { useCurrentEntry } from './use-nav-internal.js';
+import { useNav } from './use-nav';
+import { useCurrentEntry } from './use-nav-internal';
 
 /**
  * Reactive "is this screen the focused entry?" signal.
@@ -34,7 +34,13 @@ export function useIsFocused(): Computed<boolean> {
     // through `defineProvide` may carry reactive dependencies; we only care
     // about the immutable key of the entry this screen was mounted for.
     const myKey = useCurrentEntry().key;
-    return computed(() => nav.current.key === myKey);
+    // AND in `nav.isLocallyFocused` so a screen in a nested stack (e.g. a
+    // per-tab `<Stack>`) reports unfocused when its enclosing tab is
+    // inactive, or when a modal on the root nav covers everything — even
+    // though it's still the top of its own (paused) stack. Root nav's
+    // `isLocallyFocused` is permanently true, so this reduces to the
+    // previous behavior for un-nested apps.
+    return computed(() => nav.current.key === myKey && nav.isLocallyFocused);
 }
 
 /**

package/src/hooks/use-hardware-back.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Wire the Android hardware back button to the active navigator.
+ *
+ * Listens for `hardwareBackPress` events from `@sigx/lynx-linking`'s
+ * `BackHandler` (which the native side dispatches from
+ * `MainActivity.onBackPressed`). On press the handler walks to the
+ * deepest currently-focused navigator (per-tab `<Stack>`s register with
+ * their parent), then walks back up the `parent` chain looking for the
+ * first nav that `canGoBack`:
+ *
+ *   - If any nav in the chain can go back → `nav.pop()` on that nav.
+ *   - Otherwise → `BackHandler.exitApp()` (Android: `moveTaskToBack(true)`,
+ *     keeps the bundle warm; iOS: rejects, since iOS doesn't permit
+ *     programmatic termination).
+ *
+ * The traversal means you only need to call this once at the root — a
+ * back press from inside a tab pops that tab's nested stack first, only
+ * exiting the app once every level is at its base entry.
+ *
+ * Call this once in any component under `<NavigationRoot>` (typically a
+ * thin wrapper sibling to `<Stack />`). iOS doesn't fire the event so the
+ * hook is a no-op there.
+ *
+ * @example
+ * ```tsx
+ * const BackHandlerWiring = component(() => {
+ *     useHardwareBack();
+ *     return () => null;
+ * });
+ *
+ * <NavigationRoot routes={routes}>
+ *     <BackHandlerWiring />
+ *     <Stack />
+ * </NavigationRoot>
+ * ```
+ */
+export declare function useHardwareBack(): void;

package/src/hooks/use-hardware-back.ts

@@ -1,19 +1,26 @@
 import { onMounted } from '@sigx/lynx';
 import { BackHandler } from '@sigx/lynx-linking';
-import { useNav } from './use-nav.js';
+import { useNav, type Nav } from './use-nav';
 
 /**
  * Wire the Android hardware back button to the active navigator.
  *
  * Listens for `hardwareBackPress` events from `@sigx/lynx-linking`'s
  * `BackHandler` (which the native side dispatches from
- * `MainActivity.onBackPressed`). On press:
+ * `MainActivity.onBackPressed`). On press the handler walks to the
+ * deepest currently-focused navigator (per-tab `<Stack>`s register with
+ * their parent), then walks back up the `parent` chain looking for the
+ * first nav that `canGoBack`:
  *
- *   - If `nav.canGoBack` → `nav.pop()`.
+ *   - If any nav in the chain can go back → `nav.pop()` on that nav.
  *   - Otherwise → `BackHandler.exitApp()` (Android: `moveTaskToBack(true)`,
  *     keeps the bundle warm; iOS: rejects, since iOS doesn't permit
  *     programmatic termination).
  *
+ * The traversal means you only need to call this once at the root — a
+ * back press from inside a tab pops that tab's nested stack first, only
+ * exiting the app once every level is at its base entry.
+ *
  * Call this once in any component under `<NavigationRoot>` (typically a
  * thin wrapper sibling to `<Stack />`). iOS doesn't fire the event so the
  * hook is a no-op there.
@@ -35,13 +42,40 @@ export function useHardwareBack(): void {
     const nav = useNav();
     onMounted(() => {
         const sub = BackHandler.addEventListener(() => {
-            if (nav.canGoBack) {
-                nav.pop();
-                return true;
+            // Walk down to the deepest focused nav. Per-tab `<Stack>`s
+            // register themselves via `parent._children.add(nav)`; only one
+            // child per level is `isLocallyFocused` at a time, so the
+            // traversal is unambiguous. Falls back to the starting nav if
+            // no nested stacks are wired up.
+            let active: Nav = nav;
+            // Loop instead of recursion so a deeply-nested tree doesn't blow
+            // the stack on a synchronous back press.
+            outer: while (active._children.size > 0) {
+                for (const child of active._children) {
+                    if (child.isLocallyFocused) {
+                        active = child;
+                        continue outer;
+                    }
+                }
+                // No focused child at this level — stop drilling.
+                break;
+            }
+            // Walk back up the chain looking for the first nav that has
+            // something to pop. This is what makes "back press in trips
+            // tab with empty inner stack" fall through to root (which might
+            // have a modal on top) before exiting.
+            let cur: Nav | null = active;
+            while (cur) {
+                if (cur.canGoBack) {
+                    cur.pop();
+                    return true;
+                }
+                cur = cur.parent;
             }
-            // At the root — leave the app. Promise is fire-and-forget; we
-            // don't await because we want the back press to feel instant
-            // (Android starts the move-to-back transition immediately).
+            // At the root with nothing to pop — leave the app. Promise is
+            // fire-and-forget; we don't await because we want the back
+            // press to feel instant (Android starts the move-to-back
+            // transition immediately).
             void BackHandler.exitApp();
             return true;
         });

package/src/hooks/use-linking-nav.d.ts

@@ -0,0 +1,91 @@
+import { type Href } from '../href';
+import { type Nav } from './use-nav';
+import type { RouteMap } from '../types';
+export interface UseLinkingNavOptions {
+    /**
+     * Schemes/prefixes to strip before parsing. Matched in order; the first
+     * match wins. Example: `['myapp://', 'https://myapp.com']` lets
+     * `https://myapp.com/users/42` parse against the same routes as
+     * `/users/42`.
+     *
+     * After stripping, a leading `/` is added if missing so the result is a
+     * valid pathname.
+     */
+    prefixes?: string[];
+    /**
+     * Custom handler invoked instead of the default dispatch. Use this when
+     * you need to intercept (e.g. for auth callbacks, analytics) before
+     * routing. If you call `nav.push` / `nav.replace` from here, the default
+     * dispatch is skipped — return `void`.
+     */
+    onURL?: (url: string, nav: Nav) => void;
+    /**
+     * Called when an incoming URL doesn't match any registered route's `path`
+     * template (or fails schema validation). Defaults to a no-op so unknown
+     * URLs are dropped silently. Use this to surface "page not found" UX or
+     * to forward to a catch-all route.
+     */
+    onUnmatched?: (url: string) => void;
+    /**
+     * Whether to use `nav.replace` instead of `nav.push` for the cold-start
+     * initial URL. Defaults to `true` — restoring an app into a deep link
+     * shouldn't leave a stray "initial route" entry beneath it that the back
+     * button can return to.
+     *
+     * Runtime URLs (from `addEventListener`) always `push`.
+     */
+    replaceInitial?: boolean;
+}
+/**
+ * Bridge `@sigx/lynx-linking` URL events into a `@sigx/lynx-navigation`
+ * navigator. Call once inside a `<NavigationRoot>` subtree.
+ *
+ * Handles both delivery modes:
+ *   - **cold start** — `Linking.getInitialURL()` is read on mount and, if
+ *     present, dispatched (replacing the initial route by default).
+ *   - **warm start** — `Linking.addEventListener('url', ...)` subscribes for
+ *     URLs delivered while the app is already running; each one is pushed.
+ *
+ * URL → route dispatch goes through `parseHref`, which matches the URL's
+ * pathname against the route registry seeded by `<NavigationRoot>`. Routes
+ * without a `path` template are never matched by deep links — only typed
+ * `<Link>` / `nav.push` calls reach them.
+ *
+ * @example
+ * ```tsx
+ * import { useLinkingNav } from '@sigx/lynx-navigation';
+ *
+ * const DeepLinks = component(() => {
+ *     useLinkingNav({
+ *         prefixes: ['myapp://', 'https://myapp.com'],
+ *         onUnmatched: (url) => console.warn('Unknown deep link:', url),
+ *     });
+ *     return () => null;
+ * });
+ *
+ * <NavigationRoot routes={routes}>
+ *     <DeepLinks />
+ *     <Stack />
+ * </NavigationRoot>
+ * ```
+ */
+export declare function useLinkingNav(opts?: UseLinkingNavOptions): void;
+/**
+ * Strip the first matching prefix from `url`, returning a pathname-like
+ * string. If no prefixes are provided, or none match, the original URL is
+ * returned unchanged so `parseHref` can still handle scheme-prefixed forms
+ * via `@sigx/lynx-linking`'s `parse`.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export declare function _stripPrefix(url: string, prefixes?: string[]): string;
+/**
+ * Call the right `nav.push` / `nav.replace` overload for `href`. The
+ * overloads differ in positional layout: routes with a params schema take
+ * `(name, params, search?, options?)`; routes without take `(name, search?,
+ * options?)`. Calling the wrong shape silently shifts `search` into the
+ * `options` slot, so we look the route up in the registry and branch.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export declare function _navigateToHref(nav: Nav, routes: RouteMap, href: Href, kind: 'push' | 'replace'): void;

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

@@ -1,9 +1,9 @@
 import { onMounted } from '@sigx/lynx';
 import { Linking } from '@sigx/lynx-linking';
-import { parseHref, type Href } from '../href.js';
-import { useNav, type Nav } from './use-nav.js';
-import { useNavRoutes } from './use-nav-internal.js';
-import type { RouteMap } from '../types.js';
+import { parseHref, type Href } from '../href';
+import { useNav, type Nav } from './use-nav';
+import { useNavRoutes } from './use-nav-internal';
+import type { RouteMap } from '../types';
 
 export interface UseLinkingNavOptions {
     /**

package/src/hooks/use-nav-internal.d.ts

@@ -0,0 +1,91 @@
+import { type SharedValue } from '@sigx/lynx';
+import type { ScreenRegistry } from '../internal/screen-registry';
+import type { RouteMap, StackEntry } from '../types';
+/**
+ * Internal injectable: the `StackEntry` the calling screen was rendered for.
+ *
+ * Provided by `<EntryScope>` which `<Stack>` and `<ScreenContainer>` wrap
+ * around each screen component mount. Screens use this to derive their own
+ * focus state (`useIsFocused`, `useFocusEffect`) without having to track
+ * `entry.key` themselves.
+ *
+ * Default throws so calling `useIsFocused()` outside a screen mounted by a
+ * navigator surfaces a clear error rather than silently returning `false`.
+ */
+export declare const useCurrentEntry: import("@sigx/runtime-core").InjectableFunction<StackEntry<string, unknown, unknown>>;
+/**
+ * Soft companion to {@link useCurrentEntry} — returns the current scope's
+ * entry if any, `null` when called outside an `<EntryScope>` instead of
+ * throwing. Provided alongside the strict version by `<EntryScope>`.
+ *
+ * Used by chrome consumers (`useScreenChrome`) where "no scoped entry"
+ * is a legitimate state (a Stack chrome slot lives outside the screen's
+ * EntryScope) and the caller wants to soft-fallback to the navigator's
+ * destination entry rather than crash.
+ */
+export declare const useCurrentEntryOptional: import("@sigx/runtime-core").InjectableFunction<StackEntry<string, unknown, unknown> | null>;
+/**
+ * Internal injectable: the route registry passed into `<NavigationRoot>`.
+ * Components (Stack, Screen) read this to look up route definitions by name.
+ *
+ * Not exported from the package barrel — use `useNav()` for navigation, and
+ * the registry is implicit from `<NavigationRoot routes={...}>`.
+ */
+export declare const useNavRoutes: import("@sigx/runtime-core").InjectableFunction<RouteMap>;
+/**
+ * Internal injectable: low-level navigator handles used by the edge-back
+ * gesture. Holds the progress SharedValue (so gesture worklets can write it
+ * directly on MT) plus BG-side begin/commit/cancel functions invoked via
+ * `runOnBackground` from gesture worklets.
+ *
+ * `progress` is `null` when the navigator was created with `animated={false}`
+ * (e.g. tests). `beginBackGesture` is also a no-op in that case.
+ */
+export interface NavInternals {
+    /** MT-driven transition progress; null when animations are disabled. */
+    readonly progress: SharedValue<number> | null;
+    /**
+     * Set transition state for a gesture-driven pop. Does not start any
+     * automatic animation — the gesture worklet writes `progress` directly
+     * per frame, then animates to the commit/cancel endpoint on release.
+     */
+    beginBackGesture(): void;
+    /** Commit the back gesture: pop top entry + clear transition. */
+    commitBackGesture(): void;
+    /** Cancel the back gesture: clear transition without popping. */
+    cancelBackGesture(): void;
+    /** Whether the user opted into the edge-swipe-back gesture. */
+    readonly edgeSwipeEnabled: boolean;
+    /**
+     * Cross-entry screen registry controller. `<EntryScope>` calls
+     * `register` on mount and `unregister` on unmount. Persistent chrome
+     * (HeaderBar / TabBar — later slices) calls `get(entryKey)` to read
+     * the focused screen's options + slot fills without remounting itself.
+     */
+    readonly screens: {
+        register(registry: ScreenRegistry): void;
+        /**
+         * Identity-checked: only removes the entry if `registry` is the
+         * one currently registered under its `entry.key`. A no-op when
+         * a newer registry has already taken that slot (which happens
+         * at the transition→idle handoff, where a fresh `<EntryScope>`
+         * for the same entry mounts before the old one's unmount fires).
+         */
+        unregister(registry: ScreenRegistry): void;
+        get(entryKey: string): ScreenRegistry | undefined;
+    };
+}
+export declare const useNavInternals: import("@sigx/runtime-core").InjectableFunction<NavInternals>;
+/**
+ * Internal injectable: the calling screen's `ScreenRegistry`.
+ *
+ * Provided by `<EntryScope>` alongside `useCurrentEntry`. The `<Screen>`
+ * component and its slot-filling sub-components write options and slot
+ * fills here; the navigator's persistent chrome (HeaderBar, TabBar — later
+ * slices) reads from this registry via `getScreenRegistry(key)` on the
+ * navigator state, which keys into a cross-entry map.
+ *
+ * Throws when used outside an EntryScope so calling `<Screen>` at the app
+ * root surfaces a clear error rather than silently no-op'ing.
+ */
+export declare const useScreenRegistry: import("@sigx/runtime-core").InjectableFunction<ScreenRegistry>;