@sigx/lynx-navigation 0.1.3 → 0.4.0

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

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

@@ -0,0 +1,111 @@
+import type { RegisteredRoutes, RouteId, RouteParams, RouteSearch } from '../register';
+import type { PopOptions, PushOptions, RouteRequiresParams, StackEntry, TransitionState } from '../types';
+/**
+ * Subset of registered route names that declare a `params` schema (and so
+ * require a `params` argument when navigating).
+ *
+ * Computed via mapped-type filtering rather than a conditional inside the
+ * method signature: when a conditional like `RouteRequiresParams<R[K]>` is
+ * embedded inside a generic method parameter, TS evaluates it at definition
+ * time with K bound to the *whole* union of route ids — which distributes
+ * `RouteRequiresParams` over every route and collapses the result to
+ * `boolean`, breaking the conditional. Filtering once at the type level avoids
+ * the issue and produces clean overload candidates.
+ */
+export type RoutesWithParams = {
+    [K in RouteId]: RouteRequiresParams<RegisteredRoutes[K]> extends true ? K : never;
+}[RouteId];
+/** Routes that don't declare a `params` schema. */
+export type RoutesWithoutParams = Exclude<RouteId, RoutesWithParams>;
+/**
+ * The navigator handle returned by `useNav()`.
+ *
+ * Read access (`current`, `stack`, `canGoBack`) is reactive — these properties
+ * are getters that read from the underlying stack signal, so accessing them
+ * inside a component's render function (or inside `effect` / `computed`) takes
+ * a reactive dependency. Mutating methods (`push`, `pop`, etc.) trigger the
+ * dependents to update.
+ *
+ * `push` and `replace` are split into two overloads — one for routes without a
+ * params schema (no params arg) and one for routes with a params schema
+ * (params required). See `RoutesWithParams` above for why this isn't a single
+ * conditional return type.
+ */
+export interface Nav {
+    /** Push a route that has no params schema. */
+    push<K extends RoutesWithoutParams>(name: K, search?: RouteSearch<K>, options?: PushOptions): void;
+    /** Push a route that requires params. */
+    push<K extends RoutesWithParams>(name: K, params: RouteParams<K>, search?: RouteSearch<K>, options?: PushOptions): void;
+    /** Replace the top entry — same overload pattern as push. */
+    replace<K extends RoutesWithoutParams>(name: K, search?: RouteSearch<K>, options?: PushOptions): void;
+    replace<K extends RoutesWithParams>(name: K, params: RouteParams<K>, search?: RouteSearch<K>, options?: PushOptions): void;
+    /** Pop one or more entries off the top of the stack. */
+    pop(count?: number, options?: PopOptions): void;
+    /** Pop entries until the named route is at the top. */
+    popTo<K extends RouteId>(name: K): void;
+    /** Pop all the way to the root entry. */
+    popToRoot(): void;
+    /** Wholesale-replace the stack. */
+    reset(state: {
+        stack: ReadonlyArray<StackEntry>;
+    }): void;
+    /** Dismiss the topmost modal stack (no-op if none active). */
+    dismiss(): void;
+    /** Currently-focused entry. Reactive via property access. */
+    readonly current: StackEntry;
+    /** Full stack, top last. Reactive. */
+    readonly stack: ReadonlyArray<StackEntry>;
+    /** Whether the user can go back from the current entry. Reactive. */
+    readonly canGoBack: boolean;
+    /**
+     * Parent navigator (e.g. the root nav above a per-tab `<Stack>`), or null
+     * at the root. Set when a `<Stack>` mints its own navigator via
+     * `<Stack initialRoute="…">` — that stack's `useNav()` returns a nav
+     * whose `parent` is the enclosing nav.
+     *
+     * `push` calls for routes whose resolved presentation is non-`card`
+     * (`modal` / `fullScreen` / `transparent-modal`) escalate up the
+     * `parent` chain automatically — you don't normally need to reach
+     * through `parent` to present modals. `parent` is exposed as an escape
+     * hatch for power users (e.g. imperative `parent.pop()` from a child
+     * stack). Avoid pushing card routes onto `parent` directly — that
+     * defeats per-tab stack isolation.
+     */
+    readonly parent: Nav | null;
+    /**
+     * Whether this navigator is part of the currently-focused chain. True
+     * for the root nav at all times; for a nested nav (e.g. a per-tab
+     * stack), true only when its host entry is the top of `parent`, the
+     * parent itself is locally focused, and any extra gate (e.g. the
+     * enclosing tab is active) reports active.
+     *
+     * Reactive. `useIsFocused()` ANDs `nav.current.key === myKey` with
+     * `nav.isLocallyFocused`.
+     */
+    readonly isLocallyFocused: boolean;
+    /**
+     * @internal
+     * Set of child navigators (per-tab `<Stack>` instances) that have
+     * registered themselves under this nav. Used by `useHardwareBack` to
+     * find the deepest currently-focused nav and route the back press
+     * there before falling back up the chain.
+     *
+     * Not part of the public API — leading-underscore marks it as
+     * implementation detail.
+     */
+    readonly _children: Set<Nav>;
+    /**
+     * In-flight transition, or null when navigation is at rest. Reactive —
+     * `<Stack>` reads this to decide whether to render one screen or two
+     * (during a slide transition both the outgoing and incoming screens
+     * stay mounted with `useAnimatedStyle`-driven transforms).
+     */
+    readonly transition: TransitionState | null;
+}
+/**
+ * Access the innermost navigator. Provided by `<NavigationRoot>` via
+ * `defineProvide`. Throws when called outside a NavigationRoot subtree.
+ *
+ * Mirrors `@sigx/router`'s `useRouter` pattern (`packages/router/src/router.ts:30`).
+ */
+export declare const useNav: import("@sigx/runtime-core").InjectableFunction<Nav>;

package/src/hooks/use-nav.ts

@@ -1,12 +1,12 @@
 import { defineInjectable } from '@sigx/lynx';
-import type { RegisteredRoutes, RouteId, RouteParams, RouteSearch } from '../register.js';
+import type { RegisteredRoutes, RouteId, RouteParams, RouteSearch } from '../register';
 import type {
     PopOptions,
     PushOptions,
     RouteRequiresParams,
     StackEntry,
     TransitionState,
-} from '../types.js';
+} from '../types';
 
 /**
  * Subset of registered route names that declare a `params` schema (and so
@@ -93,9 +93,46 @@ export interface Nav {
     /** Whether the user can go back from the current entry. Reactive. */
     readonly canGoBack: boolean;
 
-    /** Parent navigator (e.g. the Tabs above this Stack), or null at the root. */
+    /**
+     * Parent navigator (e.g. the root nav above a per-tab `<Stack>`), or null
+     * at the root. Set when a `<Stack>` mints its own navigator via
+     * `<Stack initialRoute="…">` — that stack's `useNav()` returns a nav
+     * whose `parent` is the enclosing nav.
+     *
+     * `push` calls for routes whose resolved presentation is non-`card`
+     * (`modal` / `fullScreen` / `transparent-modal`) escalate up the
+     * `parent` chain automatically — you don't normally need to reach
+     * through `parent` to present modals. `parent` is exposed as an escape
+     * hatch for power users (e.g. imperative `parent.pop()` from a child
+     * stack). Avoid pushing card routes onto `parent` directly — that
+     * defeats per-tab stack isolation.
+     */
     readonly parent: Nav | null;
 
+    /**
+     * Whether this navigator is part of the currently-focused chain. True
+     * for the root nav at all times; for a nested nav (e.g. a per-tab
+     * stack), true only when its host entry is the top of `parent`, the
+     * parent itself is locally focused, and any extra gate (e.g. the
+     * enclosing tab is active) reports active.
+     *
+     * Reactive. `useIsFocused()` ANDs `nav.current.key === myKey` with
+     * `nav.isLocallyFocused`.
+     */
+    readonly isLocallyFocused: boolean;
+
+    /**
+     * @internal
+     * Set of child navigators (per-tab `<Stack>` instances) that have
+     * registered themselves under this nav. Used by `useHardwareBack` to
+     * find the deepest currently-focused nav and route the back press
+     * there before falling back up the chain.
+     *
+     * Not part of the public API — leading-underscore marks it as
+     * implementation detail.
+     */
+    readonly _children: Set<Nav>;
+
     /**
      * In-flight transition, or null when navigation is at rest. Reactive —
      * `<Stack>` reads this to decide whether to render one screen or two

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

@@ -1,4 +1,4 @@
-import { useNav } from './use-nav.js';
+import type { RouteId, RouteParams } from '../register';
 /**
  * Read the typed params for the current screen, asserted against the named
  * route from the registry.
@@ -15,8 +15,4 @@ import { useNav } from './use-nav.js';
  * update for the same mounted screen" path in v0.1, so a snapshot at setup
  * time is correct.
  */
-export function useParams(_name) {
-    const nav = useNav();
-    return nav.current.params;
-}
-//# sourceMappingURL=use-params.js.map
+export declare function useParams<K extends RouteId>(_name: K): RouteParams<K>;

package/src/hooks/use-params.ts

@@ -1,5 +1,5 @@
-import type { RouteId, RouteParams } from '../register.js';
-import { useNav } from './use-nav.js';
+import type { RouteId, RouteParams } from '../register';
+import { useNav } from './use-nav';
 
 /**
  * Read the typed params for the current screen, asserted against the named

package/src/hooks/use-screen-chrome.d.ts

@@ -0,0 +1,18 @@
+import type { ScreenSlotFills } from '../types';
+export interface ScreenChrome {
+    /** Resolved screen title — `options.title` (string or getter) or the route name as fallback. Reactive. */
+    readonly title: string;
+    /** Whether the header should render. Defaults to true unless the screen set `headerShown: false`. Reactive. */
+    readonly headerShown: boolean;
+    /** True when the current stack has more than one entry — i.e. there's something to pop back to. Reactive. */
+    readonly canGoBack: boolean;
+    /** Pop the top entry. No-op when `!canGoBack`. */
+    pop(): void;
+    /** Full header override slot, if `<Screen.Header>` was set. Render its return value in place of the default layout. */
+    readonly header: ScreenSlotFills['header'] | undefined;
+    /** Left-aligned slot (typically a back button). Reactive. */
+    readonly headerLeft: ScreenSlotFills['headerLeft'] | undefined;
+    /** Right-aligned slot (typically actions). Reactive. */
+    readonly headerRight: ScreenSlotFills['headerRight'] | undefined;
+}
+export declare function useScreenChrome(): ScreenChrome;

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

@@ -0,0 +1,122 @@
+/**
+ * `useScreenChrome` — reactive read of the currently-focused screen's
+ * options + slot fills, plus navigation helpers a header would need
+ * (canGoBack, pop).
+ *
+ * The built-in `<Header />` reads this same data via internal hooks.
+ * `useScreenChrome` exposes it as a public API so theme packages
+ * (`@sigx/lynx-daisyui`, custom designs) can build their own header
+ * components without depending on internal modules.
+ *
+ * Resolution rules:
+ *
+ *  - **Inside a screen body** (i.e. inside an EntryScope whose entry is
+ *    on the nearest `useNav()`'s stack), bind to **this entry's**
+ *    registry. Useful for modal screens that render their own
+ *    NavHeader inside — the chrome slides with the sheet.
+ *  - **Outside any matching EntryScope** (slot of `<Stack>`, persistent
+ *    root-level Header, etc.), bind to the *destination* entry of the
+ *    current nav state — what the navigator is settling on once the
+ *    in-flight transition completes. Push: the new top (already at
+ *    nav.current). Pop: the entry being revealed
+ *    (`transition.underneathEntry`), *not* the one being animated off.
+ *    Using the destination means the bar reflects what the user is
+ *    navigating *to*, immediately, with no end-of-animation snap.
+ *
+ * Every property is a getter — reading inside a render / `computed`
+ * subscribes to the underlying signal, so consumers re-render when
+ * title / slots change.
+ */
+import { useNav } from './use-nav';
+import { useCurrentEntryOptional, useNavInternals } from './use-nav-internal';
+import type { ScreenSlotFills, StackEntry } from '../types';
+
+export interface ScreenChrome {
+    /** Resolved screen title — `options.title` (string or getter) or the route name as fallback. Reactive. */
+    readonly title: string;
+    /** Whether the header should render. Defaults to true unless the screen set `headerShown: false`. Reactive. */
+    readonly headerShown: boolean;
+    /** True when the current stack has more than one entry — i.e. there's something to pop back to. Reactive. */
+    readonly canGoBack: boolean;
+    /** Pop the top entry. No-op when `!canGoBack`. */
+    pop(): void;
+    /** Full header override slot, if `<Screen.Header>` was set. Render its return value in place of the default layout. */
+    readonly header: ScreenSlotFills['header'] | undefined;
+    /** Left-aligned slot (typically a back button). Reactive. */
+    readonly headerLeft: ScreenSlotFills['headerLeft'] | undefined;
+    /** Right-aligned slot (typically actions). Reactive. */
+    readonly headerRight: ScreenSlotFills['headerRight'] | undefined;
+}
+
+export function useScreenChrome(): ScreenChrome {
+    const nav = useNav();
+    const internals = useNavInternals();
+
+    // The candidate "scoped" entry, if we happen to be rendered inside
+    // an EntryScope. May belong to a DIFFERENT nav than `nav` — e.g.
+    // when NavHeader is placed in a per-tab `<Stack>`'s chrome slot,
+    // it sees the outer (root) EntryScope's entry but its `useNav()`
+    // returns the inner per-tab nav. We only honor the pin when the
+    // entry is actually on this nav's stack; otherwise we're crossing
+    // scopes and the destination-entry path is correct.
+    //
+    // `useCurrentEntryOptional` is the soft companion to
+    // `useCurrentEntry` — it returns `null` outside any EntryScope
+    // rather than throwing, which is the right semantic for a chrome
+    // consumer that *might* be a Stack slot.
+    const candidate: StackEntry | null = useCurrentEntryOptional();
+
+    const getDestinationEntry = (): StackEntry => {
+        const t = nav.transition;
+        if (t) {
+            return t.kind === 'pop' ? t.underneathEntry : t.topEntry;
+        }
+        return nav.current;
+    };
+
+    const getEntry = (): StackEntry => {
+        if (candidate) {
+            const stack = nav.stack;
+            if (stack.some((e) => e.key === candidate!.key)) {
+                return candidate;
+            }
+        }
+        return getDestinationEntry();
+    };
+
+    return {
+        get title() {
+            const entry = getEntry();
+            const reg = internals.screens.get(entry.key);
+            const t = reg?.options.title;
+            if (typeof t === 'function') return t();
+            if (typeof t === 'string') return t;
+            return entry.route;
+        },
+        get headerShown() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.options.headerShown !== false;
+        },
+        get canGoBack() {
+            const entry = getEntry();
+            const stack = nav.stack;
+            const idx = stack.findIndex((e) => e.key === entry.key);
+            return idx > 0;
+        },
+        pop() {
+            nav.pop();
+        },
+        get header() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.header;
+        },
+        get headerLeft() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.headerLeft;
+        },
+        get headerRight() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.headerRight;
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { ScreenOptions } from '../types';
+export declare function useScreenOptions(optionsOrFn: ScreenOptions | (() => ScreenOptions)): void;

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

@@ -22,9 +22,9 @@
  * 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';
+import { useScreenRegistry } from './use-nav-internal';
+import { mergeOptions } from '../internal/screen-registry';
+import type { ScreenOptions } from '../types';
 
 export function useScreenOptions(
     optionsOrFn: ScreenOptions | (() => ScreenOptions),

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

@@ -1,4 +1,4 @@
-import { useNav } from './use-nav.js';
+import type { RouteId, RouteSearch } from '../register';
 /**
  * Read the typed search/query params for the current screen, asserted against
  * the named route from the registry.
@@ -7,8 +7,4 @@ import { useNav } from './use-nav.js';
  * reactivity story — each navigation triggers a remount via the entry-keyed
  * Stack, so a setup-time snapshot is sufficient.
  */
-export function useSearch(_name) {
-    const nav = useNav();
-    return nav.current.search;
-}
-//# sourceMappingURL=use-search.js.map
+export declare function useSearch<K extends RouteId>(_name: K): RouteSearch<K>;

package/src/hooks/use-search.ts

@@ -1,5 +1,5 @@
-import type { RouteId, RouteSearch } from '../register.js';
-import { useNav } from './use-nav.js';
+import type { RouteId, RouteSearch } from '../register';
+import { useNav } from './use-nav';
 
 /**
  * Read the typed search/query params for the current screen, asserted against

package/src/href.d.ts

@@ -0,0 +1,54 @@
+import type { RouteId, RouteParams, RouteSearch } from './register';
+import type { RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav';
+/**
+ * A typed reference to a navigation target — what `<Link to={...}>` consumes
+ * and what `hrefFor()` produces.
+ *
+ * Holds both the typed pieces (route name, params, search) and the serialized
+ * URL form (when the route declares a `path` template). Either side can drive
+ * navigation — typed for in-app links, URL for deep links / sharing.
+ */
+export interface Href<K extends RouteId = RouteId> {
+    readonly route: K;
+    readonly params: RouteParams<K>;
+    readonly search: RouteSearch<K>;
+    /** URL form. `null` when the route declares no `path` template. */
+    readonly url: string | null;
+}
+/**
+ * Build a typed Href for a given route. Validates params against the route's
+ * schema at runtime; type-checks them at compile time.
+ *
+ * Overloaded the same way as `nav.push` — one signature for routes without a
+ * 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' }
+ * hrefFor('profile', { id: '42' }, { tab: 'about' });
+ * hrefFor('home');                                // params arg omitted (no schema)
+ * ```
+ */
+export declare function hrefFor<K extends RoutesWithoutParams>(name: K, search?: RouteSearch<K>): Href<K>;
+export declare function hrefFor<K extends RoutesWithParams>(name: K, params: RouteParams<K>, search?: RouteSearch<K>): Href<K>;
+/**
+ * Parse a URL string into a typed Href against the registered routes.
+ * 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 declare function parseHref(url: string): Href | null;

package/src/href.ts

@@ -1,9 +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';
+import type { RouteId, RouteParams, RouteSearch } from './register';
+import type { RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav';
+import { buildUrl } from './url/build';
+import { parseHrefImpl } from './url/parse';
+import { getRouteRegistry } from './url/registry';
+import { validateSync } from './url/validate';
 
 /**
  * A typed reference to a navigation target — what `<Link to={...}>` consumes

package/src/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @sigx/lynx-navigation — type-first native stack router.
+ *
+ * Phase 0.1 (current): typed registry, stack runtime, NavigationRoot + Stack.
+ * Coming next: Screen with slot-based header API, MTS transitions, Tabs.
+ */
+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';
+export type { NavSnapshot, NavStorageAdapter, UseNavSerializerOptions, } from './hooks/use-nav-serializer';
+export { hrefFor, parseHref } from './href';
+export type { Href } from './href';
+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, InferOutput, ParamsOf, PopOptions, Presentation, PushOptions, RouteDefinition, RouteMap, RouteRequiresParams, ScreenOptions, ScreenSlotFills, SearchOf, StackEntry, StandardSchemaV1, TransitionKind, TransitionRole, TransitionState, } from './types';