@sigx/lynx-navigation 0.2.0 → 0.4.0

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

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

package/src/index.ts

@@ -5,46 +5,48 @@
  * Coming next: Screen with slot-based header API, MTS transitions, Tabs.
  */
 
-export { defineRoutes } from './define-routes.js';
-export type { Register, RegisteredRoutes, RouteId, RouteParams, RouteSearch } from './register.js';
-export { useNav } from './hooks/use-nav.js';
-export type { Nav, RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav.js';
-export { useParams } from './hooks/use-params.js';
-export { useSearch } from './hooks/use-search.js';
-export { useHardwareBack } from './hooks/use-hardware-back.js';
-export { useLinkingNav } from './hooks/use-linking-nav.js';
-export type { UseLinkingNavOptions } from './hooks/use-linking-nav.js';
-export { useIsFocused, useFocusEffect } from './hooks/use-focus.js';
-export { useScreenOptions } from './hooks/use-screen-options.js';
+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.js';
+} from './hooks/use-nav-serializer';
 export type {
     NavSnapshot,
     NavStorageAdapter,
     UseNavSerializerOptions,
-} from './hooks/use-nav-serializer.js';
-export { hrefFor, parseHref } from './href.js';
-export type { Href } from './href.js';
+} from './hooks/use-nav-serializer';
+export { hrefFor, parseHref } from './href';
+export type { Href } from './href';
 // URL bridge internals: `_setRouteRegistry` is a leading-underscore export —
 // intended for tests, deep-link bootstrap before a NavigationRoot mounts, and
 // any other integration that needs to seed the registry imperatively.
-export { _setRouteRegistry, _clearRouteRegistry } from './url/registry.js';
-export { compilePath } from './url/compile.js';
-export type { CompiledPath } from './url/compile.js';
-export { NavigationRoot } from './components/NavigationRoot.js';
-export { Stack } from './components/Stack.js';
-export { Screen } from './components/Screen.js';
-export { Header } from './components/Header.js';
-export { Tabs, useTabs } from './components/Tabs.js';
-export type { TabInfo, TabsNav } from './components/Tabs.js';
-export { TabBar } from './components/TabBar.js';
-export type { TabRenderContext } from './components/TabBar.js';
-export { Drawer, useDrawer } from './components/Drawer.js';
-export type { DrawerNav } from './components/Drawer.js';
-export { Link } from './components/Link.js';
-export type { LinkProps } from './components/Link.js';
+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,
@@ -64,4 +66,4 @@ export type {
     TransitionKind,
     TransitionRole,
     TransitionState,
-} from './types.js';
+} from './types';

package/src/internal/layer-plan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure layer-plan computation for `<Stack>`'s render.
+ *
+ * Given (stack, transition, progress), produces an ordered list of
+ * `Layer`s — each is an entry to render plus an optional transform
+ * spec for animation. The Stack render emits one absolutely-positioned
+ * `<view>` per layer, stacked bottom-to-top in document order.
+ *
+ * Why this is its own module: the layer-selection logic is the only
+ * non-obvious part of the navigator's render path, and the rules are
+ * easier to read (and unit-test) as a pure function over the
+ * navigator's state than as inline render branches.
+ *
+ * Rules:
+ *
+ *  - **Idle (no transition).** Render the topmost non-overlay entry
+ *    as the base, plus every overlay entry above it. Overlays
+ *    (`modal` / `fullScreen` / `transparent-modal`) keep their
+ *    underneath mounted; cards replace their underneath in the base
+ *    layer.
+ *
+ *  - **Card transition.** Two layers: the underneath entry (animated
+ *    with the parallax-card-underneath spec) and the top entry
+ *    (animated with the slide-in-from-right spec). After the
+ *    transition completes, the idle rule kicks in — the underneath
+ *    unmounts because the new top becomes the sole base.
+ *
+ *  - **Overlay transition.** The full idle layer stack up through the
+ *    underneath entry stays static (no transform). The animated top
+ *    is the only layer with a transform. After the transition, the
+ *    overlay either joins the static idle stack (push) or unmounts
+ *    (pop).
+ *
+ * The Layer.key for the Stack render is
+ * `layer-${entry.key}-${animVariant(layer.animation)}`. The variant
+ * suffix forces a remount when an entry transitions from animated to
+ * static (or vice versa) — `useAnimatedStyle` can't re-bind mid-life,
+ * so we get a fresh `useAnimatedStyle` call per animation state.
+ * Modal underneath layers never animate, so they stay statically
+ * keyed across the modal lifecycle and their state (per-tab Stack,
+ * scroll, in-flight inputs) survives.
+ */
+import type { SharedValue } from '@sigx/lynx';
+import type { Presentation, StackEntry, TransitionState } from '../types';
+export type LayerAnimation = {
+    axis: 'translateX' | 'translateY';
+    inputRange: readonly [number, number];
+    outputRange: readonly [number, number];
+    progress: SharedValue<number>;
+};
+export interface Layer {
+    /** The entry whose component renders inside this layer. */
+    readonly entry: StackEntry;
+    /** When non-null, the layer's host view binds a `useAnimatedStyle` mapper. */
+    readonly animation: LayerAnimation | null;
+}
+export declare function isOverlayPresentation(p: Presentation): boolean;
+/**
+ * Suffix used in a layer's render key. Stable for the layer's
+ * lifetime (same entry, same animation kind) and changes when the
+ * animation transitions on/off so the Layer remounts and rebinds.
+ */
+export declare function animationVariant(animation: LayerAnimation | null): string;
+/**
+ * Compute the visible-layer list for one render of `<Stack>`. Pure —
+ * unit-testable independently of the renderer.
+ */
+export declare function computeLayers(stack: readonly StackEntry[], transition: TransitionState | null, progress: SharedValue<number> | null): Layer[];