@sigx/lynx-navigation 0.4.0 → 0.4.1

package/src/components/Link.d.ts

@@ -1,60 +0,0 @@
-import type { RouteId, RouteParams, RouteSearch } from '../register';
-import type { RoutesWithParams } from '../hooks/use-nav';
-/**
- * Per-route conditional props for `<Link>`.
- *
- * Mapped over `RouteId`, then indexed by `RouteId` to flatten into a union.
- * Each branch enforces the `params`-required-iff-route-has-schema rule:
- *
- *   - `<Link to="profile" />`             → TS error (profile requires params)
- *   - `<Link to="profile" params={...} />` → ok
- *   - `<Link to="home" />`                → ok (home has no params)
- *   - `<Link to="home" params={...} />`   → TS error (home accepts no params)
- *
- * Same per-route discrimination as `nav.push`, expressed as a JSX-friendly
- * union rather than overloads.
- */
-type LinkPropsByRoute = {
-    [K in RouteId]: K extends RoutesWithParams ? {
-        to: K;
-        params: RouteParams<K>;
-        search?: RouteSearch<K>;
-    } : {
-        to: K;
-        params?: undefined;
-        search?: RouteSearch<K>;
-    };
-}[RouteId];
-/**
- * Public type for `<Link>`'s props. The conditional `LinkPropsByRoute` carries
- * the typed `to`/`params`/`search` triple; the rest are simple optionals.
- *
- * `children` is declared explicitly because the public type is exposed via a
- * type-cast (so JSX sees a function-shaped signature). The cast strips sigx's
- * built-in `Define.Slot<'default'>` → JSX-children wiring, so we add a
- * permissive `children?` slot ourselves.
- */
-export type LinkProps = LinkPropsByRoute & {
-    /** Use `replace` instead of `push` (no new history entry). */
-    replace?: boolean;
-    /** Link content rendered inside the tappable container. */
-    children?: unknown;
-};
-/**
- * Declarative navigation. Same typing as `nav.push` — pass `params` only when
- * the route declares a schema. Wraps a `<view>` that fires `nav.push` (or
- * `nav.replace` if `replace` is set) on tap.
- *
- * @example
- * ```tsx
- * <Link to="home">Home</Link>
- * <Link to="profile" params={{ id: '42' }}>View profile</Link>
- * <Link to="profile" params={{ id: '42' }} search={{ tab: 'about' }}>About</Link>
- * <Link to="settings" replace>Settings (no back)</Link>
- * ```
- *
- * The cast widens the inferred prop type from the loose impl to the strict
- * `LinkProps` so JSX usage gets per-route discrimination. Runtime is identical.
- */
-export declare const Link: (props: LinkProps) => unknown;
-export {};

package/src/components/NavigationRoot.d.ts

@@ -1,36 +0,0 @@
-import { type Define } from '@sigx/lynx';
-import type { RouteId } from '../register';
-import type { RouteMap } from '../types';
-type NavigationRootProps = Define.Prop<'routes', RouteMap, true> & Define.Prop<'initialRoute', RouteId> & Define.Prop<'initialParams', Record<string, unknown>> & Define.Prop<'initialSearch', Record<string, unknown>>
-/**
- * Enable slide-from-right transitions on push/pop. Defaults to true.
- * Tests against `@sigx/lynx-testing` (which doesn't have an MT runtime)
- * should pass `animated={false}` so navigations commit synchronously.
- */
- & Define.Prop<'animated', boolean>
-/**
- * Enable the iOS-style edge-swipe-back gesture. Defaults to true. Set
- * to false if it conflicts with screen content on the leftmost 20px,
- * or while debugging gesture issues.
- */
- & Define.Prop<'edgeSwipeEnabled', boolean> & Define.Slot<'default'>;
-/**
- * Root of a navigator subtree.
- *
- * Creates a fresh `NavigatorState` from `routes` and provides it via
- * `defineProvide`, so descendant `<Stack>` / `<Screen>` components and any
- * `useNav()` / `useParams()` calls resolve through this instance.
- *
- * The bottom-of-stack entry is built from `initialRoute` (defaults to the
- * first key in `routes`). For routes that declare a params schema, you must
- * pass `initialParams` matching that schema.
- *
- * Mirrors the install pattern of `@sigx/router` (see
- * `packages/router/src/router.ts:519-528`), but at component scope rather than
- * `app.use(router)` — no app-wide singleton, so multi-navigator apps and
- * tests get isolated state for free.
- */
-export declare const NavigationRoot: import("@sigx/runtime-core").ComponentFactory<NavigationRootProps, void, {
-    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-}>;
-export {};

package/src/components/Screen.d.ts

@@ -1,97 +0,0 @@
-/**
- * `<Screen>` — declarative per-screen options + slot fills.
- *
- * Usage:
- *
- * ```tsx
- * const ProfileScreen = component(() => () => (
- *   <Screen title="Profile" headerShown gestureEnabled>
- *     <Screen.HeaderRight>
- *       <text bindtap={onEdit}>Edit</text>
- *     </Screen.HeaderRight>
- *     <view>body…</view>
- *   </Screen>
- * ));
- * ```
- *
- * `<Screen>` itself renders its `default` slot inline — so the body lives
- * where you'd expect with no extra layout wrapper. The sub-components
- * (`Screen.Header`, `Screen.HeaderLeft`, `Screen.HeaderRight`,
- * `Screen.TabBarItem`) render `null` and write into the entry's
- * `ScreenRegistry`. The navigator's persistent chrome reads from there.
- *
- * Note: `<Screen.TabBarItem>` registers a scoped slot fill on the entry's
- * `ScreenRegistry`, but the built-in `<TabBar>` doesn't read it yet — the
- * fill is exposed for custom tab-bar renderers (pass `renderTab` and look
- * up the active entry's registry yourself).
- *
- * Sub-component placement inside `<Screen>` is conventional — sigx scopes
- * are by component tree, so they work anywhere under the same EntryScope.
- * Placing them as direct children of `<Screen>` keeps the call site
- * declarative and grep-friendly.
- */
-import { type Define } from '@sigx/lynx';
-type ScreenProps = Define.Prop<'title', string | (() => string)> & Define.Prop<'headerShown', boolean> & Define.Prop<'gestureEnabled', boolean> & Define.Slot<'default'>;
-type SimpleSlotProps = Define.Slot<'default'>;
-/**
- * `<Screen.TabBarItem>` — scoped slot. The default slot is a function that
- * receives `{ active }`; whatever it returns is the tab-bar item content.
- *
- * Sigx's `Define.Slot<'default', { active: boolean }>` would express this
- * directly on the component, but since `<Screen.TabBarItem>`'s parent
- * (the user's tree, not the navigator) doesn't actually pass `active`, we
- * accept a plain default slot whose body is itself a function. The
- * navigator's TabBar invokes that function with the active flag.
- */
-type TabBarItemProps = Define.Slot<'default'>;
-/**
- * Compound export. `Screen` is callable as a JSX element and exposes the
- * sub-components as properties (`Screen.Header`, etc.) for the declarative
- * call site shown in the file header.
- */
-export declare const Screen: ((props: {
-    gestureEnabled?: boolean | undefined;
-    headerShown?: boolean | undefined;
-    title?: string | (() => string) | undefined;
-} & {} & {
-    slots?: Partial<{
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }> | undefined;
-} & {} & JSX.IntrinsicAttributes & import("@sigx/runtime-core").ComponentAttributeExtensions & {
-    ref?: import("@sigx/runtime-core").Ref<void> | undefined;
-    children?: any;
-}) => import("@sigx/runtime-core").JSXElement) & {
-    __setup: import("@sigx/runtime-core").SetupFn<{
-        gestureEnabled?: boolean | undefined;
-        headerShown?: boolean | undefined;
-        title?: string | (() => string) | undefined;
-    }, ScreenProps, void, {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }>;
-    __name?: string;
-    __islandId?: string;
-    __props: {
-        gestureEnabled?: boolean | undefined;
-        headerShown?: boolean | undefined;
-        title?: string | (() => string) | undefined;
-    };
-    __events: ScreenProps;
-    __ref: void;
-    __slots: {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    };
-} & {
-    Header: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }>;
-    HeaderLeft: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }>;
-    HeaderRight: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }>;
-    TabBarItem: import("@sigx/runtime-core").ComponentFactory<TabBarItemProps, void, {
-        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-    }>;
-};
-export {};

package/src/components/Stack.d.ts

@@ -1,90 +0,0 @@
-import { type Define } from '@sigx/lynx';
-type StackProps = 
-/**
- * Mint a nested navigator with this route at its base. When set, the
- * `<Stack>` becomes the owner of a new `NavigatorState` and provides
- * `useNav` / `useNavInternals` / `useNavRoutes` to its subtree, so
- * `nav.push('card-route', …)` from inside the stack stays *inside* it
- * (e.g. for per-tab stacks). Routes presented as `modal` / `fullScreen` /
- * `transparent-modal` automatically escalate to the parent navigator
- * via `nav.parent`, walking up until they reach the root — so modals
- * still overlay the whole app.
- *
- * Omit to render the *enclosing* navigator's stack (the default — this
- * is how `<NavigationRoot> → <Stack />` works).
- */
-Define.Prop<'initialRoute', string>
-/** Initial params for the nested-stack base entry. */
- & Define.Prop<'initialParams', Record<string, unknown>>
-/** Initial search for the nested-stack base entry. */
- & Define.Prop<'initialSearch', Record<string, unknown>>
-/**
- * Optional chrome rendered *above* the active screen, **inside this
- * Stack's nav scope**. The intended use is `<Header />`, which needs
- * to resolve `useNav()` to the per-stack nav (not the enclosing one)
- * so it can react to pushes inside this stack — e.g. show a back
- * button when a card is pushed onto a per-tab stack.
- *
- * Without this, a `<Header />` placed as a sibling of `<Stack>`
- * would see the enclosing nav and never update when pushes happen
- * inside the nested stack.
- */
- & Define.Slot<'default'>;
-/**
- * Stack navigator — renders the topmost stack entry's component at rest, or
- * the top + underneath entries during a transition.
- *
- * Two modes:
- *
- * **Bound** (no `initialRoute`): renders the enclosing navigator's stack.
- * This is the shape used directly under `<NavigationRoot>` and is what
- * single-stack apps want.
- *
- * **Nested-owner** (`initialRoute="…"`): mints a fresh `NavigatorState` with
- * its own progress `SharedValue` and edge-back gesture, and provides
- * `useNav` / `useNavInternals` / `useNavRoutes` to its subtree. `useNav()`
- * inside this stack returns the nested nav; `nav.parent` points to the
- * enclosing one. Per-tab stacks are the canonical use case:
- *
- * ```tsx
- * <Tabs initialTab="trips">
- *   <Tabs.Screen name="trips"><Stack initialRoute="tripsHome" /></Tabs.Screen>
- *   <Tabs.Screen name="map"><Stack initialRoute="mapHome" /></Tabs.Screen>
- * </Tabs>
- * ```
- *
- * Modal/fullScreen pushes escalate up the parent chain automatically — so
- * `nav.push('newTrip')` from inside Trips (where `newTrip` is `modal`)
- * walks to root and overlays the whole UI. `replace` stays strictly local
- * (asymmetric with `push`) so a modal `replace` never wipes the root stack.
- *
- * **Render strategy.** Stack always emits the same JSX shape — a
- * relative wrapper containing one `<Layer>` per entry returned by
- * `computeLayers(stack, transition, progress)`. Each Layer is an
- * absolutely-positioned host view with optional MT-bound translate
- * animation. The pure layer-plan function decides:
- *
- *  - **Idle.** Topmost non-overlay base + any overlays above it. All
- *    static (no transform). Overlays (`modal` / `fullScreen` /
- *    `transparent-modal`) keep their underneath mounted; cards
- *    replace their underneath in the base layer.
- *  - **Card transition.** Both top and underneath animate (slide-in
- *    + parallax). After settle, idle rules apply — the underneath
- *    unmounts because the new top is the sole base.
- *  - **Overlay transition.** The full idle layer stack up through
- *    the underneath stays static; only the animated top has a
- *    transform. After settle, the overlay either joins the static
- *    idle stack (push) or unmounts (pop).
- *
- * Layer keys are `layer-${entry.key}-${animationVariant}`. The variant
- * suffix forces a remount when an entry transitions from animated to
- * static (or vice versa) — `useAnimatedStyle` binds once at setup and
- * can't switch its mapper at runtime. Modal underneath layers never
- * animate, so their key is stable across the modal lifecycle and the
- * subtree's state (per-tab Stack navigators, scroll positions,
- * in-flight inputs) survives.
- */
-export declare const Stack: import("@sigx/runtime-core").ComponentFactory<StackProps, void, {
-    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
-}>;
-export {};

package/src/components/TabBar.d.ts

@@ -1,38 +0,0 @@
-/**
- * `<TabBar>` — headless default chrome for `<Tabs>`.
- *
- * Renders the active-tab buttons reading from the enclosing `useTabs()`
- * navigator. Intentionally **unstyled** — this lives in the (theme-less)
- * navigation package, so it ships pure structure + accessibility wiring.
- * Themed chrome belongs in a UI-kit package: see `<NavTabBar />` in
- * `@sigx/lynx-daisyui` for the daisy-themed equivalent.
- *
- * Use this directly only if you want to handle styling yourself via the
- * `renderTab` prop. For a "looks like a tab bar out of the box" component,
- * pull `<NavTabBar />` from `@sigx/lynx-daisyui` (or your own UI kit).
- *
- * Customization:
- *   - `renderTab`: a function `(info, ctx) => JSX` that fully replaces the
- *     default button rendering for each tab. `ctx.active` tells the
- *     consumer whether this tab is currently focused; `ctx.onPress`
- *     activates the tab. **Recommended** for any visual treatment.
- *
- * Accessibility (baked into the default button — the one structural
- * concern this component keeps):
- *   - `accessibility-label` from `info.accessibilityLabel ?? info.label ?? info.name`.
- *   - `accessibility-element="true"` so screen readers see the whole pill.
- *   - `accessibility-trait="button"` and a `selected` flag on the active
- *     one so VoiceOver/TalkBack announces focus state on tab switch.
- */
-import { type JSXElement } from '@sigx/lynx';
-import { type TabInfo } from './Tabs';
-/** Rendering context passed to a `renderTab` consumer. */
-export interface TabRenderContext {
-    /** True when this tab is currently active. Reactive — re-runs render on change. */
-    readonly active: boolean;
-    /** Activates this tab. Use as a `bindtap` handler on the rendered node. */
-    onPress(): void;
-}
-export declare const TabBar: import("@sigx/runtime-core").ComponentFactory<{
-    renderTab?: ((info: TabInfo, ctx: TabRenderContext) => JSXElement) | undefined;
-}, void, {}>;

package/src/components/Tabs.d.ts

@@ -1,109 +0,0 @@
-/**
- * `<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/hooks/use-focus.d.ts

@@ -1,45 +0,0 @@
-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-hardware-back.d.ts

@@ -1,37 +0,0 @@
-/**
- * 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-linking-nav.d.ts

@@ -1,91 +0,0 @@
-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;