@sigx/lynx-navigation 0.2.0 → 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

@@ -208,13 +208,27 @@ const TabsScreen = component<TabsScreenProps>(({ props, slots }) => {
         // `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/src/hooks/use-focus.d.ts

@@ -0,0 +1,45 @@
+import { type Computed } from '@sigx/lynx';
+/**
+ * Reactive "is this screen the focused entry?" signal.
+ *
+ * Must be called from inside a component rendered as a route by `<Stack>` (or
+ * any other navigator that uses `<EntryScope>`); throws otherwise. The
+ * returned `Computed` reads `nav.current.key` and compares it to the entry
+ * the calling screen was mounted for, so any nav mutation that changes the
+ * top entry flips the value.
+ *
+ * Note: screens stay mounted when something is pushed on top of them — they
+ * just lose focus. Pop the new top off and they regain focus.
+ *
+ * @example
+ * ```tsx
+ * const Profile = component(() => {
+ *     const isFocused = useIsFocused();
+ *     return () => <text>{isFocused.value ? 'visible' : 'hidden'}</text>;
+ * });
+ * ```
+ */
+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`.
+ *
+ * Lifecycle:
+ *  - cb runs immediately if the screen is already focused at mount.
+ *  - When the screen loses focus (something pushed on top), cleanup runs.
+ *  - When focus returns (the cover is popped), `cb` runs again — yielding a
+ *    fresh cleanup for the next blur.
+ *  - On unmount, cleanup runs once if still focused.
+ *
+ * Common uses: subscribe to a data source while visible, track an analytics
+ * "screen view" event, start/stop a polling loop.
+ *
+ * @example
+ * ```tsx
+ * useFocusEffect(() => {
+ *     const id = setInterval(refresh, 5000);
+ *     return () => clearInterval(id);
+ * });
+ * ```
+ */
+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.

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,6 +1,6 @@
 import { onMounted } from '@sigx/lynx';
 import { BackHandler } from '@sigx/lynx-linking';
-import { useNav, type Nav } from './use-nav.js';
+import { useNav, type Nav } from './use-nav';
 
 /**
  * Wire the Android hardware back button to the active navigator.

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>;

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

@@ -1,6 +1,6 @@
 import { defineInjectable, type SharedValue } from '@sigx/lynx';
-import type { ScreenRegistry } from '../internal/screen-registry.js';
-import type { RouteMap, StackEntry } from '../types.js';
+import type { ScreenRegistry } from '../internal/screen-registry';
+import type { RouteMap, StackEntry } from '../types';
 
 /**
  * Internal injectable: the `StackEntry` the calling screen was rendered for.
@@ -19,6 +19,20 @@ export const useCurrentEntry = defineInjectable<StackEntry>(() => {
     );
 });
 
+/**
+ * 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 const useCurrentEntryOptional = defineInjectable<StackEntry | null>(
+    () => null,
+);
+
 /**
  * Internal injectable: the route registry passed into `<NavigationRoot>`.
  * Components (Stack, Screen) read this to look up route definitions by name.
@@ -64,7 +78,14 @@ export interface NavInternals {
      */
     readonly screens: {
         register(registry: ScreenRegistry): void;
-        unregister(entryKey: string): 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;
     };
 }

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

@@ -0,0 +1,82 @@
+import type { StackEntry } from '../types';
+/**
+ * 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 declare 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 declare function useNavSerializer(options: UseNavSerializerOptions): void;

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

@@ -1,7 +1,7 @@
 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';
+import { useNav } from './use-nav';
+import { useNavRoutes } from './use-nav-internal';
+import type { StackEntry } from '../types';
 
 /**
  * Plain JSON snapshot of a navigator. The whole point of holding navigation