@sigx/lynx-navigation 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sigx/lynx-navigation",
+  "version": "0.1.0",
+  "description": "Type-first native stack router for sigx-lynx",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {
+    "@sigx/lynx": "^0.1.0",
+    "@sigx/lynx-linking": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@sigx/lynx-linking": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@sigx/lynx": "^0.1.0",
+    "@sigx/lynx-linking": "^0.1.0",
+    "@sigx/testing-lynx": "^0.2.4"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly",
+    "dev": "tsc --emitDeclarationOnly --watch",
+    "test": "vitest run",
+    "test:types": "tsc --noEmit"
+  }
+}

package/src/components/EdgeBackHandle.tsx

@@ -0,0 +1,161 @@
+import {
+    component,
+    Gesture,
+    runOnBackground,
+    useGestureDetector,
+    useMainThreadRef,
+    type MainThread,
+} from '@sigx/lynx';
+import { withTiming } from '@sigx/motion';
+import { useNavInternals } from '../hooks/use-nav-internal.js';
+import { SCREEN_WIDTH } from '../internal/screen-width.js';
+
+/**
+ * Edge-pan recognizer for iOS-style swipe-back. Mounts as an absolutely-
+ * positioned 20px-wide strip on the left edge of the active screen; only
+ * exists when `nav.canGoBack && !transition`.
+ *
+ * `Gesture.Pan().minDistance(MIN_DISTANCE)` lets quick taps pass through to
+ * whatever's behind the strip (back button, screen header, etc.). Only
+ * horizontal drags past the threshold activate the gesture.
+ *
+ * MT/BG split:
+ *   - All gesture handlers run on MT. They write `progress.current.value`
+ *     directly per frame (no per-frame bridge crossing) and dispatch
+ *     `runOnBackground(...)` only at start/commit/cancel — three BG hops
+ *     per gesture max.
+ *   - The transition state machine on BG mounts the underneath
+ *     `<ScreenContainer>` once `beginBackGesture` lands; the gesture's
+ *     in-flight progress writes are picked up the moment the binding
+ *     registers (Phase 0.5 polish: pre-mount underneath when canGoBack to
+ *     eliminate the brief pre-mount latency).
+ *
+ * Implementation notes (matching `<Draggable>`):
+ *   - Single `useMainThreadRef` holding an object — primitive refs don't
+ *     survive worklet capture cleanly in some Lynx versions, while object
+ *     refs do (the worklet runtime resolves the ref via the
+ *     `_workletRefMap`).
+ *   - `e: any` rather than `e: unknown` — type annotations are erased, but
+ *     SWC's worklet transform has been observed to behave better with the
+ *     looser annotation. Keeps us aligned with Draggable verbatim.
+ *   - Empty `onBegin`: load-bearing on iOS — without a registered onBegin
+ *     callback, `LynxPanGestureHandler` skips the begin path and onStart/
+ *     onEnd never fire (per Draggable's notes).
+ */
+
+/** Fraction of screen width past which a release commits the back nav. */
+const COMMIT_TRANSLATION = 0.33;
+/** px/sec horizontal speed past which a release commits, regardless of distance. */
+const COMMIT_VELOCITY = 300;
+/** Width of the touchable strip on the left edge of every screen. */
+const EDGE_ZONE_WIDTH = 20;
+/** Minimum movement before the gesture activates (lets taps pass through). */
+const MIN_DISTANCE = 8;
+const SNAP_DURATION_SEC = 0.18;
+/**
+ * Pre-computed milliseconds for the BG-side `setTimeout`. Module-level so
+ * it's in scope for both the MT worklet (`withTiming` argument) and the BG
+ * callback wrapped by `runOnBackground` (`setTimeout` argument). Locals
+ * declared inside an MT worklet body are MT-only — the BG callback's
+ * closure can't see them, hence "ReferenceError: snapMs is not defined".
+ */
+const SNAP_DURATION_MS = Math.round(SNAP_DURATION_SEC * 1000);
+
+export const EdgeBackHandle = component(() => {
+    const ref = useMainThreadRef<MainThread.Element | null>(null);
+    // Per-gesture transient state — captured as a plain closure object
+    // rather than a `useMainThreadRef`. Lynx's SWC worklet transform deep-
+    // copies plain objects into `_c` once at register time; mutations on MT
+    // persist across calls because the same `_c` is bound for the lifetime
+    // of the gesture registration. Using a `useMainThreadRef` here was
+    // crashing on iOS with `cannot read property 'current' of undefined`
+    // — the resolved-ref capture path looked up an empty
+    // `_workletRefMap` entry under a race I haven't fully tracked down.
+    // Plain object avoids that path entirely.
+    const state = {
+        startPageX: 0,
+        prevPageX: 0,
+        prevTime: 0,
+        velocity: 0,
+    };
+
+    const internals = useNavInternals();
+    const progress = internals.progress;
+    const beginBackGesture = internals.beginBackGesture;
+    const commitBackGesture = internals.commitBackGesture;
+    const cancelBackGesture = internals.cancelBackGesture;
+
+    const pan = Gesture.Pan()
+        .minDistance(MIN_DISTANCE)
+        .onBegin(() => {
+            'main thread';
+        })
+        .onStart((e: any) => {
+            'main thread';
+            const p = e && e.params;
+            const pageX = (p && p.pageX) || 0;
+            state.startPageX = pageX;
+            state.prevPageX = pageX;
+            state.prevTime = Date.now();
+            state.velocity = 0;
+            runOnBackground(() => {
+                beginBackGesture();
+            })();
+        })
+        .onUpdate((e: any) => {
+            'main thread';
+            if (!progress) return;
+            const p = e && e.params;
+            const pageX = (p && p.pageX) || 0;
+            const dx = pageX - state.startPageX;
+            const prog = Math.max(0, Math.min(1, dx / SCREEN_WIDTH));
+            progress.current.value = prog;
+
+            const now = Date.now();
+            const dt = now - state.prevTime;
+            if (dt > 0) {
+                state.velocity =
+                    ((pageX - state.prevPageX) / dt) * 1000;
+            }
+            state.prevPageX = pageX;
+            state.prevTime = now;
+        })
+        .onEnd((e: any) => {
+            'main thread';
+            if (!progress) return;
+            const p = e && e.params;
+            const pageX = (p && p.pageX) || 0;
+            const dx = pageX - state.startPageX;
+            const fraction = dx / SCREEN_WIDTH;
+            const commit =
+                fraction > COMMIT_TRANSLATION ||
+                state.velocity > COMMIT_VELOCITY;
+
+            if (commit) {
+                withTiming(progress, 1, { duration: SNAP_DURATION_SEC });
+                runOnBackground(() => {
+                    setTimeout(() => commitBackGesture(), SNAP_DURATION_MS);
+                })();
+            } else {
+                withTiming(progress, 0, { duration: SNAP_DURATION_SEC });
+                runOnBackground(() => {
+                    setTimeout(() => cancelBackGesture(), SNAP_DURATION_MS);
+                })();
+            }
+        });
+
+    useGestureDetector(ref, pan);
+
+    return () => (
+        <view
+            main-thread:ref={ref}
+            style={{
+                position: 'absolute',
+                top: '0',
+                left: '0',
+                width: `${EDGE_ZONE_WIDTH}px`,
+                bottom: '0',
+            }}
+        />
+    );
+});

package/src/components/Link.tsx

@@ -0,0 +1,113 @@
+import { component, type Define } from '@sigx/lynx';
+import { useNav } from '../hooks/use-nav.js';
+import { useNavRoutes } from '../hooks/use-nav-internal.js';
+import type { RouteId, RouteParams, RouteSearch } from '../register.js';
+import type { RoutesWithParams } from '../hooks/use-nav.js';
+
+/**
+ * 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;
+};
+
+/**
+ * Loose internal props used by the component implementation. The runtime
+ * doesn't enforce the per-route conditional — that's a TS-only constraint
+ * surfaced via the public `LinkProps` type. The cast at the bottom of this
+ * file rewires the export to the strict type.
+ */
+type LinkPropsLoose =
+    & Define.Prop<'to', string, true>
+    & Define.Prop<'params', Record<string, unknown> | undefined>
+    & Define.Prop<'search', Record<string, unknown> | undefined>
+    & Define.Prop<'replace', boolean>
+    & Define.Slot<'default'>;
+
+const LinkImpl = component<LinkPropsLoose>(({ props, slots }) => {
+    const nav = useNav();
+    const routes = useNavRoutes();
+
+    const handlePress = (): void => {
+        const route = props.to;
+        const routeDef = routes[route];
+        if (!routeDef) {
+            // Defensive: prop was typed against the registry, so this shouldn't
+            // happen at runtime — but if it does (e.g. a stale Link survived a
+            // route removal), surface a clear error rather than crashing on
+            // the navigator's lookup.
+            throw new Error(
+                `[lynx-navigation] <Link to='${route}'>: route is not registered.`,
+            );
+        }
+        const hasParams = !!routeDef.params;
+        const action = props.replace ? nav.replace : nav.push;
+        // Branch on whether the route declares a params schema so positional
+        // args land correctly: routes-with-params shift everything one slot
+        // (push/replace overload signatures `(name, params, search?, options?)`
+        // vs `(name, search?, options?)`). Calling the wrong shape silently
+        // puts `search` into the `options` slot.
+        if (hasParams) {
+            (action as (n: string, p: unknown, s?: unknown) => void)(
+                route,
+                props.params,
+                props.search,
+            );
+        } else {
+            (action as (n: string, s?: unknown) => void)(route, props.search);
+        }
+    };
+
+    return () => (
+        // `bindtap` is correct here because the underlying element is a Lynx
+        // native `<view>` — sigx component-level events would use `onPress`.
+        <view bindtap={handlePress}>{slots.default?.()}</view>
+    );
+}, { name: 'Link' });
+
+/**
+ * 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 const Link = LinkImpl as unknown as (props: LinkProps) => unknown;

package/src/components/NavigationRoot.tsx

@@ -0,0 +1,85 @@
+import { component, defineProvide, useSharedValue, type Define } from '@sigx/lynx';
+import { createNavigatorState } from '../navigator/core.js';
+import { useNav } from '../hooks/use-nav.js';
+import { useNavInternals, useNavRoutes } from '../hooks/use-nav-internal.js';
+import type { RouteId } from '../register.js';
+import type { Presentation, RouteMap, StackEntry } from '../types.js';
+
+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/testing-lynx` (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 const NavigationRoot = component<NavigationRootProps>(({ props, slots }) => {
+    const routes = props.routes;
+    const initialName: string = props.initialRoute ?? Object.keys(routes)[0];
+    if (!routes[initialName]) {
+        throw new Error(
+            `[lynx-navigation] <NavigationRoot> initialRoute='${initialName}' is not in the routes registry.`,
+        );
+    }
+    const initialPresentation: Presentation = routes[initialName].presentation ?? 'card';
+    const initial: StackEntry = {
+        key: 'root',
+        route: initialName,
+        params: props.initialParams ?? {},
+        search: props.initialSearch ?? {},
+        state: undefined,
+        presentation: initialPresentation,
+    };
+
+    // SharedValue driving the slide-from-right push/pop transition. Created
+    // unconditionally (hooks must be) but only forwarded into the navigator
+    // when animations are enabled — `createNavigatorState` falls back to
+    // instant swaps when `progress` is undefined.
+    const progressSv = useSharedValue(0);
+    const animationsEnabled = props.animated !== false;
+    const navState = createNavigatorState({
+        routes,
+        initial,
+        progress: animationsEnabled ? progressSv : undefined,
+    });
+
+    defineProvide(useNav, () => navState.nav);
+    defineProvide(useNavRoutes, () => navState.routes);
+    const edgeSwipeEnabled = props.edgeSwipeEnabled !== false;
+    defineProvide(useNavInternals, () => ({
+        progress: animationsEnabled ? progressSv : null,
+        beginBackGesture: navState._gesture.beginBackGesture,
+        commitBackGesture: navState._gesture.commitBackGesture,
+        cancelBackGesture: navState._gesture.cancelBackGesture,
+        edgeSwipeEnabled,
+    }));
+
+    return () => slots.default?.();
+});

package/src/components/ScreenContainer.tsx

@@ -0,0 +1,101 @@
+import {
+    component,
+    useMainThreadRef,
+    useAnimatedStyle,
+    type ComponentFactory,
+    type Define,
+    type MainThread,
+    type SharedValue,
+} from '@sigx/lynx';
+import type { MapperParams } from '@sigx/lynx';
+import { SCREEN_WIDTH } from '../internal/screen-width.js';
+import type { RouteMap, StackEntry, TransitionKind, TransitionRole } from '../types.js';
+
+/**
+ * Slide-from-right transition geometry. `SCREEN_WIDTH` is read from
+ * `lynx.SystemInfo` at module load so the animation lands the screen at
+ * exactly translateX=0 (centered) at progress=1, rather than overshooting
+ * into the parent's clip region. `<EdgeBackHandle>` reads the same
+ * constant — they have to agree, otherwise the gesture commit threshold
+ * and the animation geometry don't line up.
+ */
+const PARALLAX_FACTOR = 0.3;
+
+/**
+ * Compute the `translateX` range for a given (role, kind) pair. Progress
+ * always runs 0 → 1; the role and kind decide what visual state each end of
+ * the progress represents.
+ *
+ * Slide-from-right semantics:
+ *  - PUSH: new top slides in from the right; old top parallaxes left.
+ *  - POP:  current top slides out to the right; underneath returns from the
+ *    parallax-left position.
+ */
+function getRangeParams(
+    role: TransitionRole,
+    kind: TransitionKind,
+): MapperParams['translateX'] {
+    if (kind === 'push') {
+        if (role === 'top') {
+            return { inputRange: [0, 1], outputRange: [SCREEN_WIDTH, 0] };
+        }
+        return { inputRange: [0, 1], outputRange: [0, -PARALLAX_FACTOR * SCREEN_WIDTH] };
+    }
+    // pop
+    if (role === 'top') {
+        return { inputRange: [0, 1], outputRange: [0, SCREEN_WIDTH] };
+    }
+    return { inputRange: [0, 1], outputRange: [-PARALLAX_FACTOR * SCREEN_WIDTH, 0] };
+}
+
+type ScreenContainerProps =
+    & Define.Prop<'entry', StackEntry, true>
+    & Define.Prop<'routes', RouteMap, true>
+    & Define.Prop<'role', TransitionRole, true>
+    & Define.Prop<'kind', TransitionKind, true>
+    & Define.Prop<'progress', SharedValue<number>, true>;
+
+/**
+ * Animated screen slot — absolutely positioned, MT-bound translateX driven by
+ * the navigator's progress SharedValue. Used during transitions to render the
+ * top + underneath entries together.
+ *
+ * Each instance is keyed by `${entry.key}-${role}-${kind}` in the parent so a
+ * role/kind change forces a fresh mount with a fresh `useAnimatedStyle`
+ * binding (the binding is set at setup and can't be re-keyed mid-life). State
+ * loss across transition boundaries is accepted in v0.2; persistent screen
+ * state (scroll position, input fields surviving navigations) is a polish
+ * item for Phase 0.5+.
+ */
+export const ScreenContainer = component<ScreenContainerProps>(({ props }) => {
+    const ref = useMainThreadRef<MainThread.Element | null>(null);
+    const params = getRangeParams(props.role, props.kind);
+    useAnimatedStyle(ref, props.progress, 'translateX', params);
+
+    return () => {
+        const route = props.routes[props.entry.route];
+        if (!route) return null;
+        const Comp = route.component as unknown as ComponentFactory<
+            Record<string, unknown>,
+            unknown,
+            unknown
+        >;
+        if (typeof Comp !== 'function') return null;
+        const entryParams = props.entry.params as Record<string, unknown>;
+        return (
+            <view
+                main-thread:ref={ref}
+                style={{
+                    position: 'absolute',
+                    top: '0',
+                    left: '0',
+                    right: '0',
+                    bottom: '0',
+                    backgroundColor: '#0f172a',
+                }}
+            >
+                <Comp key={props.entry.key} {...entryParams} />
+            </view>
+        );
+    };
+});

package/src/components/Stack.tsx

@@ -0,0 +1,99 @@
+import { component, type ComponentFactory, type SharedValue } from '@sigx/lynx';
+import { useNav } from '../hooks/use-nav.js';
+import { useNavInternals, useNavRoutes } from '../hooks/use-nav-internal.js';
+import { ScreenContainer } from './ScreenContainer.js';
+import { EdgeBackHandle } from './EdgeBackHandle.js';
+
+/**
+ * Stack navigator — renders the topmost stack entry's component at rest, or
+ * the top + underneath entries during a transition.
+ *
+ * **Idle**: just the top entry, full-bleed, no transform. The screen
+ * component mounts directly so it can use its own layout (no extra absolute
+ * positioning that would break percentage heights).
+ *
+ * **Transitioning**: two `<ScreenContainer>` instances stacked absolutely,
+ * each with an MT-driven `translateX` that reads from the navigator's
+ * progress `SharedValue`. The host's BG thread doesn't tick per frame —
+ * `useAnimatedStyle` runs the interpolation entirely on MT.
+ *
+ * `key={top.key}` keeps the idle render's component instance stable across
+ * unrelated re-renders. During transitions, composite keys
+ * (`${entry.key}-${role}-${kind}`) ensure a fresh mount per role/kind pair so
+ * the `useAnimatedStyle` binding is set with the right input/output ranges.
+ */
+export const Stack = component(() => {
+    const nav = useNav();
+    const routes = useNavRoutes();
+    const internals = useNavInternals();
+
+    return () => {
+        const transition = nav.transition;
+        const top = nav.current;
+
+        if (!transition) {
+            const route = routes[top.route];
+            if (!route) return null;
+            const Comp = route.component as unknown as ComponentFactory<
+                Record<string, unknown>,
+                unknown,
+                unknown
+            >;
+            if (typeof Comp !== 'function') return null;
+            const params = top.params as Record<string, unknown>;
+            // When canGoBack and edge-swipe is enabled, overlay the gesture
+            // handle so the user can pan from the left edge to start a back
+            // transition. `position: absolute` doesn't disturb the screen's
+            // own layout — the handle only intercepts touches in the leftmost
+            // 20px, and only when they pan rightward past `MIN_DISTANCE`.
+            if (nav.canGoBack && internals.edgeSwipeEnabled) {
+                return (
+                    <view
+                        style={{
+                            position: 'relative',
+                            width: '100%',
+                            height: '100%',
+                        }}
+                    >
+                        <Comp key={top.key} {...params} />
+                        <EdgeBackHandle key="edge-back" />
+                    </view>
+                );
+            }
+            return <Comp key={top.key} {...params} />;
+        }
+
+        // Cast progress: TransitionState carries it as `unknown` to avoid
+        // pinning the contract to `@sigx/lynx`'s SharedValue at the type
+        // level; here at the runtime boundary we know it's a SharedValue<number>.
+        const progress = transition.progress as SharedValue<number>;
+
+        return (
+            <view
+                style={{
+                    position: 'relative',
+                    width: '100%',
+                    height: '100%',
+                    overflow: 'hidden',
+                }}
+            >
+                <ScreenContainer
+                    key={`${transition.underneathEntry.key}-underneath-${transition.kind}`}
+                    entry={transition.underneathEntry}
+                    routes={routes}
+                    role="underneath"
+                    kind={transition.kind}
+                    progress={progress}
+                />
+                <ScreenContainer
+                    key={`${transition.topEntry.key}-top-${transition.kind}`}
+                    entry={transition.topEntry}
+                    routes={routes}
+                    role="top"
+                    kind={transition.kind}
+                    progress={progress}
+                />
+            </view>
+        );
+    };
+});

package/src/define-routes.ts

@@ -0,0 +1,33 @@
+import type { RouteMap } from './types.js';
+
+/**
+ * Define a typed route registry.
+ *
+ * Returns the input verbatim at runtime — the function exists for TypeScript
+ * inference. The returned type is narrowed to the literal route map so that
+ * downstream APIs (`useNav`, `useParams`, `<Link>`) can extract route names
+ * and params/search schemas precisely.
+ *
+ * @example
+ * ```ts
+ * import { defineRoutes } from '@sigx/lynx-navigation';
+ * import { z } from 'zod';
+ *
+ * export const routes = defineRoutes({
+ *     home: { component: lazy(() => import('./Home')) },
+ *     profile: {
+ *         params: z.object({ id: z.string() }),
+ *         component: lazy(() => import('./Profile')),
+ *         path: '/users/:id',
+ *     },
+ * });
+ *
+ * // Then in app entry:
+ * declare module '@sigx/lynx-navigation' {
+ *     interface Register { routes: typeof routes }
+ * }
+ * ```
+ */
+export function defineRoutes<const T extends RouteMap>(routes: T): T {
+    return routes;
+}

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

@@ -0,0 +1,50 @@
+import { onMounted } from '@sigx/lynx';
+import { BackHandler } from '@sigx/lynx-linking';
+import { useNav } from './use-nav.js';
+
+/**
+ * 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:
+ *
+ *   - If `nav.canGoBack` → `nav.pop()`.
+ *   - Otherwise → `BackHandler.exitApp()` (Android: `moveTaskToBack(true)`,
+ *     keeps the bundle warm; iOS: rejects, since iOS doesn't permit
+ *     programmatic termination).
+ *
+ * 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 function useHardwareBack(): void {
+    const nav = useNav();
+    onMounted(() => {
+        const sub = BackHandler.addEventListener(() => {
+            if (nav.canGoBack) {
+                nav.pop();
+                return true;
+            }
+            // 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).
+            void BackHandler.exitApp();
+            return true;
+        });
+        return () => sub.remove();
+    });
+}