@sigx/lynx-navigation 0.1.3 → 0.4.0

package/src/navigator/core.ts

@@ -7,8 +7,8 @@ import {
 } from '@sigx/lynx';
 import { isLazyComponent } from '@sigx/lynx';
 import { withTiming } from '@sigx/lynx-motion';
-import type { Nav } from '../hooks/use-nav.js';
-import type { ScreenRegistry } from '../internal/screen-registry.js';
+import type { Nav } from '../hooks/use-nav';
+import type { ScreenRegistry } from '../internal/screen-registry';
 import type {
     PopOptions,
     Presentation,
@@ -16,7 +16,7 @@ import type {
     RouteMap,
     StackEntry,
     TransitionState,
-} from '../types.js';
+} from '../types';
 
 /**
  * The reactive backing state for one navigator instance.
@@ -61,9 +61,18 @@ export interface NavigatorState {
      */
     readonly _screens: {
         register(registry: ScreenRegistry): void;
-        unregister(entryKey: string): void;
+        /** Identity-checked: no-op when a newer registry has taken the slot. */
+        unregister(registry: ScreenRegistry): void;
         get(entryKey: string): ScreenRegistry | undefined;
     };
+    /**
+     * Internal: set `nav.isLocallyFocused` from outside.
+     *
+     * `<Stack>` calls this when its host entry's locally-focused state
+     * changes (top of parent + parent focused + enclosing tab active). For
+     * the root nav this stays `true` for the lifetime of the navigator.
+     */
+    readonly _setLocallyFocused: (focused: boolean) => void;
 }
 
 /**
@@ -146,6 +155,24 @@ export interface CreateNavigatorOptions {
      * that don't have an MT runtime.
      */
     progress?: SharedValue<number>;
+    /**
+     * Parent navigator. Set when this navigator is nested under another
+     * (e.g. a per-tab `<Stack initialRoute>` under root). Drives the
+     * `nav.parent` getter and the modal-escalation behaviour of `push`:
+     * a push of a route whose resolved presentation is not `'card'`
+     * recurses via `parent.push(...)`, walking up the chain until it
+     * lands on a navigator with no parent (the root).
+     *
+     * Leave undefined for the root navigator.
+     */
+    parent?: Nav | null;
+    /**
+     * Whether this navigator is considered "locally focused" at creation
+     * time. Defaults to true for the root nav; nested stacks pass `false`
+     * here and then flip the flag via `_setLocallyFocused` once their
+     * host-entry/tab-active state is computed.
+     */
+    initialLocallyFocused?: boolean;
 }
 
 /**
@@ -154,9 +181,13 @@ export interface CreateNavigatorOptions {
  * can subscribe to it.
  */
 export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorState {
-    const { routes, initial, progress } = opts;
+    const { routes, initial, progress, parent = null } = opts;
 
     const stackSignal: Signal<StackEntry[]> = signal<StackEntry[]>([initial]);
+    const focusedBox: Signal<{ value: boolean }> = signal<{ value: boolean }>({
+        value: opts.initialLocallyFocused ?? true,
+    });
+    const children = new Set<Nav>();
     // `signal(null)` would wrap as a primitive (no `$set`), so wrap in an
     // object to get the standard `{ value }`-style API. Reading `.value`
     // tracks; writing triggers re-render of `<Stack>`.
@@ -231,14 +262,33 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
     }
 
     const push: Nav['push'] = ((name: string, ...args: unknown[]) => {
-        if (isTransitioning()) return;
-        const { params, search, options } = unpackArgs(name, args, routes);
         if (!routes[name]) {
             throw new Error(
                 `[lynx-navigation] push('${name}'): route is not registered. ` +
                     `Known routes: ${Object.keys(routes).join(', ') || '(none)'}`,
             );
         }
+        const { params, search, options } = unpackArgs(name, args, routes);
+
+        // Escalate non-card presentations up the parent chain. Modals,
+        // fullScreen, and transparent-modal routes belong on the root
+        // navigator so they overlay tab UI and persistent chrome. We resolve
+        // the presentation the same way `makeEntry` does so the escalation
+        // decision matches what would actually be shown.
+        const resolvedPresentation =
+            (options?.presentation ?? routes[name].presentation ?? 'card') as Presentation;
+        if (resolvedPresentation !== 'card' && parent) {
+            // Walk straight to the root — every navigator with a parent
+            // delegates non-card pushes upward, so a chain of any depth
+            // collapses to a single push on the topmost nav.
+            // Forward original args verbatim so overloads (`push(name)`,
+            // `push(name, params)`, `push(name, params, search)`,
+            // `push(name, params, search, options)`) keep their meaning.
+            (parent.push as (n: string, ...a: unknown[]) => void)(name, ...args);
+            return;
+        }
+
+        if (isTransitioning()) return;
         preloadRouteComponent(routes[name].component);
         const newEntry = makeEntry(name, params, search, options, routes);
         const cur = getStack();
@@ -411,18 +461,38 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
             return stackSignal.length > 1;
         },
         get parent() {
-            return null;
+            return parent;
+        },
+        get isLocallyFocused() {
+            return focusedBox.value;
+        },
+        get _children() {
+            return children;
         },
         get transition() {
             return transitionBox.value;
         },
     };
 
+    if (parent) {
+        // Register with parent so root-level traversals (hardware back,
+        // future deepest-focused queries) can reach this nav. The matching
+        // `_children.delete(nav)` happens when the owning `<Stack>` unmounts;
+        // see Stack.tsx.
+        parent._children.add(nav);
+    }
+
+    function setLocallyFocused(focused: boolean): void {
+        if (focusedBox.value === focused) return;
+        focusedBox.value = focused;
+    }
+
     return {
         nav,
         routes,
         _gesture: { beginBackGesture, commitBackGesture, cancelBackGesture },
         _screens: createScreenRegistries(),
+        _setLocallyFocused: setLocallyFocused,
     };
 }
 
@@ -451,8 +521,18 @@ function createScreenRegistries(): NavigatorState['_screens'] {
             // would self-loop, so we untrack the bump.
             untrack(() => { version.v = version.v + 1; });
         },
-        unregister(key: string) {
-            byKey.delete(key);
+        // Identity-checked unregister: deletes the entry only if the
+        // currently-registered registry is the *same instance* the caller
+        // holds. Without this, the transition→idle handoff (which can
+        // mount a new `<EntryScope>` for the same entry-key before the
+        // old one unmounts) would let the old scope's `onUnmounted` wipe
+        // out the fresh registry — leaving `screens.get(key)` returning
+        // undefined and chrome consumers (NavHeader) falling back to the
+        // route-name as title with all slot fills gone.
+        unregister(reg: ScreenRegistry) {
+            const cur = byKey.get(reg.entry.key);
+            if (cur !== reg) return;
+            byKey.delete(reg.entry.key);
             untrack(() => { version.v = version.v + 1; });
         },
         get(key: string) {

package/src/register.d.ts

@@ -0,0 +1,37 @@
+import type { ParamsOf, RouteMap, SearchOf } from './types';
+/**
+ * Module-augmentation surface for the user's typed route map.
+ *
+ * Apps register their routes by augmenting this interface — the rest of the
+ * library's typed APIs (useNav, useParams, useSearch, <Link>) read from
+ * `RegisteredRoutes` so all inference is global.
+ *
+ * @example
+ * ```ts
+ * // In your app's main.ts (or a routes.ts that's imported early):
+ * import type { routes } from './routes';
+ *
+ * declare module '@sigx/lynx-navigation' {
+ *     interface Register { routes: typeof routes }
+ * }
+ * ```
+ *
+ * If `Register.routes` is not augmented the library falls back to a permissive
+ * `RouteMap` so non-augmented usage still type-checks (just without precise
+ * inference). The recommended pattern is always to augment.
+ */
+export interface Register {
+}
+/**
+ * The user's registered route map, or a permissive fallback when not
+ * augmented. All higher-level types derive from this.
+ */
+export type RegisteredRoutes = Register extends {
+    routes: infer R;
+} ? R : RouteMap;
+/** Union of registered route names (string literal union when registered). */
+export type RouteId = keyof RegisteredRoutes & string;
+/** Params type for a registered route name. */
+export type RouteParams<K extends RouteId> = ParamsOf<RegisteredRoutes[K]>;
+/** Search type for a registered route name. */
+export type RouteSearch<K extends RouteId> = SearchOf<RegisteredRoutes[K]>;

package/src/register.ts

@@ -1,4 +1,4 @@
-import type { ParamsOf, RouteMap, SearchOf } from './types.js';
+import type { ParamsOf, RouteMap, SearchOf } from './types';
 
 /**
  * Module-augmentation surface for the user's typed route map.

package/src/types.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Core types for @sigx/lynx-navigation.
+ *
+ * The type machinery here is the differentiating DX: route names, params, and
+ * search are all inferred end-to-end from the user's `defineRoutes` call so
+ * `nav.push('profile', { id: 42 })` is a TS error if `id` is typed as string.
+ */
+/**
+ * Minimal Standard Schema spec subset — see https://standardschema.dev.
+ * Inlined so we don't depend on `@standard-schema/spec` for the type spike.
+ * Compatible with Zod, Valibot, ArkType, etc.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/**
+ * Infer the validated output type of a Standard Schema, falling back to
+ * `unknown` for non-schema values.
+ */
+export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : unknown;
+/** Empty record — what `ParamsOf` returns when a route declares no schema. */
+export type EmptyParams = Record<string, never>;
+/**
+ * How a route entry is presented on the stack.
+ * `card` is the default push; `modal`/`fullScreen` slide up; `transparent-modal`
+ * preserves the underlying screen visible (e.g. for popovers).
+ */
+export type Presentation = 'card' | 'modal' | 'fullScreen' | 'transparent-modal';
+/**
+ * A route definition entry.
+ *
+ * Users construct this via `defineRoutes({...})`. The `params` and `search`
+ * schemas drive runtime validation AND TS inference for `useParams`,
+ * `useSearch`, `nav.push`, `<Link>`, etc.
+ *
+ * `component` accepts an eager component factory or a lazy import — both shapes
+ * resolve through sigx's `<Suspense>` boundary at render time.
+ */
+export interface RouteDefinition<Params extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, Search extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined> {
+    /** Component factory or lazy importer. */
+    component: ComponentLike;
+    /**
+     * Fallback shown while a lazy `component` is loading.
+     *
+     * Set this only on routes whose `component` was created with `lazy(...)`.
+     * The fallback is rendered inside a `<Suspense>` boundary wrapping the
+     * screen mount, so the user sees this UI while the screen's chunk is
+     * being fetched. When omitted, lazy routes still work — the caller is
+     * responsible for placing its own `<Suspense>` boundary (e.g. above the
+     * `<NavigationRoot>` or inside the screen component).
+     *
+     * Accepts a component factory (`MyLoadingScreen`) or a function returning
+     * JSX (`() => <Spinner />`). Eager routes ignore this field.
+     */
+    fallback?: ComponentLike | (() => unknown);
+    /** Standard-Schema validator for path params. Optional. */
+    params?: Params;
+    /** Standard-Schema validator for query/search params. Optional. */
+    search?: Search;
+    /** Optional URL pattern for deep-link serialization (e.g. `/users/:id`). */
+    path?: string;
+    /** Default presentation when this route is pushed. */
+    presentation?: Presentation;
+    /** Nested routes — share the URL/path namespace and may inherit options. */
+    children?: Record<string, RouteDefinition>;
+}
+/**
+ * The component shape we accept on a route. Kept structural so we don't pull
+ * `ComponentFactory` from sigx at type level (avoids a hard dep on sigx purely
+ * for types in the spike). Refined to a real ComponentFactory in Phase 0.1
+ * runtime work.
+ */
+export type ComponentLike = ((...args: any[]) => unknown) | (() => Promise<{
+    default: (...args: any[]) => unknown;
+}>);
+/**
+ * Map of route definitions, as returned by `defineRoutes`. Keys are route
+ * names; values are typed RouteDefinitions.
+ */
+export type RouteMap = Record<string, RouteDefinition>;
+/**
+ * Extract params type from a single RouteDefinition.
+ * Falls back to `EmptyParams` when the route declares no schema.
+ *
+ * We use a structural `params: infer S` match (without an `extends
+ * StandardSchemaV1` constraint on `S`) because TS conditional types treat the
+ * generic-defaulted `StandardSchemaV1<unknown, unknown>` as invariant in this
+ * position — a schema typed `StandardSchemaV1<{id:string}>` does not match
+ * `extends StandardSchemaV1` reliably under `<const T>` inference. `InferOutput`
+ * gracefully handles non-schema `S` by returning `unknown`.
+ */
+export type ParamsOf<R> = R extends {
+    params: infer S;
+} ? InferOutput<S> : EmptyParams;
+/**
+ * Extract search type from a single RouteDefinition.
+ * Falls back to `EmptyParams` when the route declares no schema.
+ */
+export type SearchOf<R> = R extends {
+    search: infer S;
+} ? InferOutput<S> : EmptyParams;
+/**
+ * Whether a route requires a `params` argument when calling `nav.push` etc.
+ * True iff the route definition has a `params` field.
+ */
+export type RouteRequiresParams<R> = R extends {
+    params: object;
+} ? true : false;
+/**
+ * Per-entry state stored on the stack signal.
+ *
+ * `key` is unique per entry — needed because the same route can appear more
+ * than once (e.g. profile A → message → profile A again). Focus state and
+ * scroll position are keyed by `key`, not by route name.
+ */
+export interface StackEntry<R extends string = string, P = unknown, S = unknown> {
+    readonly key: string;
+    readonly route: R;
+    readonly params: P;
+    readonly search: S;
+    /** User state — survives suspend/restore. */
+    state: unknown;
+    readonly presentation: Presentation;
+}
+/** Options accepted by `nav.push` / `nav.replace`. */
+export interface PushOptions {
+    /** Override the route's default presentation for this navigation. */
+    presentation?: Presentation;
+    /** User state to attach to the new entry. Survives suspend/restore. */
+    state?: unknown;
+    /**
+     * Skip the slide animation (instant swap). Defaults to true on platforms
+     * where `useAnimatedStyle` isn't available (test renderer); defaults to
+     * false on real Lynx. Tests can force `false` to keep assertions
+     * deterministic.
+     */
+    animated?: boolean;
+}
+/** Options accepted by `nav.pop`. */
+export interface PopOptions {
+    /** Skip the slide animation (instant swap). See `PushOptions.animated`. */
+    animated?: boolean;
+}
+/**
+ * Direction of an in-flight transition.
+ *  - `push`: a new entry is animating in (progress 0 → 1).
+ *  - `pop`:  the current top is animating out (progress 0 → 1, then committed).
+ */
+export type TransitionKind = 'push' | 'pop';
+/** Role of a screen during a transition — determines its transform formula. */
+export type TransitionRole = 'top' | 'underneath';
+/**
+ * Snapshot of an in-flight transition. Stored on the navigator state so the
+ * `<Stack>` component knows to render two entries (`topEntry` above
+ * `underneathEntry`) and bind their transforms to `progress`.
+ *
+ * `progress` is a `SharedValue<number>` (re-exported as `unknown` here to
+ * avoid a hard dep on `@sigx/lynx`'s SharedValue type at the contract level —
+ * the runtime `<Stack>` casts as needed). The value runs 0 → 1 in both push
+ * and pop, with the role/kind pair determining the visual direction.
+ */
+export interface TransitionState {
+    readonly kind: TransitionKind;
+    readonly topEntry: StackEntry;
+    readonly underneathEntry: StackEntry;
+    /** Animation progress signal — typed loosely; cast at the runtime boundary. */
+    readonly progress: unknown;
+}
+/**
+ * Per-screen display options written by `<Screen>` into its entry's registry.
+ *
+ * Read by persistent navigator chrome (the `<HeaderBar>` shipped in the
+ * `header` slice; `<TabBar>` later). All fields are optional — consumers
+ * apply sensible defaults (headerShown defaults to true, gestureEnabled to
+ * true, title falls back to the route name).
+ *
+ * `title` accepts a function so the header can be derived from reactive
+ * state (e.g. a user's display name signal). Plain strings are wrapped in
+ * a thunk by consumers when read.
+ */
+export interface ScreenOptions {
+    /** Header title. Either a static string or a getter (re-tracked each render). */
+    title?: string | (() => string);
+    /** When false, the navigator's header is hidden for this screen. Default true. */
+    headerShown?: boolean;
+    /** When false, the iOS edge-swipe-back gesture is disabled for this screen. Default true. */
+    gestureEnabled?: boolean;
+}
+/**
+ * Slot fills written by `<Screen.Header>` / `<Screen.HeaderLeft>` /
+ * `<Screen.HeaderRight>` / `<Screen.TabBarItem>`.
+ *
+ * Each fill is the rendered output of that sub-component's `default` slot,
+ * captured as a thunk so the navigator's persistent chrome can call it at
+ * render time. `tabBarItem` is a scoped slot — the consumer passes
+ * `{ active }` so the same screen's tab-bar item can style itself
+ * differently when focused vs. not.
+ */
+export interface ScreenSlotFills {
+    /** Full header replacement. When set, takes precedence over title + headerLeft/Right. */
+    header?: () => unknown;
+    /** Left-side header content (typically back arrow override). */
+    headerLeft?: () => unknown;
+    /** Right-side header content (typically action buttons). */
+    headerRight?: () => unknown;
+    /** Tab-bar item — scoped slot receives `{ active }` indicating focus. */
+    tabBarItem?: (ctx: {
+        active: boolean;
+    }) => unknown;
+}

package/src/url/build.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed → URL: build the `url` field of an Href from a route's params/search.
+ *
+ * Mirror of parse.ts. Used by `hrefFor()` after schema validation succeeds.
+ */
+/**
+ * Build the URL form of a route + params + search, or `null` if the route
+ * declares no `path` template (typed navigation still works — only deep-link
+ * serialization is unavailable).
+ *
+ * Params must already be valid for the route's schema (callers run this after
+ * `validateSync`). Search values are stringified as-is — schema-validated
+ * inputs survive round-tripping because `parseHref` re-runs the same schema.
+ */
+export declare function buildUrl(routeName: string, params: Record<string, unknown> | undefined, search: Record<string, unknown> | undefined): string | null;

package/src/url/build.ts

@@ -4,8 +4,8 @@
  * Mirror of parse.ts. Used by `hrefFor()` after schema validation succeeds.
  */
 
-import { formatSearch } from './format.js';
-import { getCompiledPath, getRouteRegistry } from './registry.js';
+import { formatSearch } from './format';
+import { getCompiledPath, getRouteRegistry } from './registry';
 
 /**
  * Build the URL form of a route + params + search, or `null` if the route

package/src/url/compile.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Path template compiler.
+ *
+ * Turns a route's `path` (e.g. `/users/:id/posts/:postId`) into a compiled
+ * object that can both match a URL pathname against it and format a typed
+ * params object back into a URL.
+ *
+ * Supported syntax (intentionally minimal for v1):
+ *   - Literal segments:  `/users`, `/users/me`
+ *   - Named params:      `:id` (matches `[^/]+`)
+ *   - Trailing slashes tolerated on match
+ *
+ * Out of scope for v1 (future-compatible — additions won't break v1 paths):
+ *   - Wildcards `*`
+ *   - Optional params `:id?`
+ *   - Typed/constrained params `:id<number>` or `:id(\\d+)`
+ */
+/** Result of compiling a path template — used by parse + format. */
+export interface CompiledPath {
+    readonly source: string;
+    readonly paramNames: readonly string[];
+    /** Regex that matches a URL pathname. Captures are param values in order. */
+    readonly regex: RegExp;
+    /**
+     * Render a URL pathname for this template given param values. Each value
+     * is `encodeURIComponent`-encoded. Throws if a required `:name` is missing.
+     */
+    format(params: Record<string, string | number>): string;
+}
+/**
+ * Compile a path template. Throws on malformed input (duplicate param names,
+ * unexpected `:` syntax). Pure — safe to memoize.
+ */
+export declare function compilePath(template: string): CompiledPath;

package/src/url/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Format helpers: typed params/search → URL string.
+ *
+ * Used by `hrefFor()` to render the `url` field of an Href.
+ */
+/**
+ * Serialize an object as a `key=value&key=value` querystring.
+ *
+ * Keys are sorted to make the output deterministic (useful for tests and
+ * persistence diffs). `undefined`/`null` values are skipped. Non-primitive
+ * values are JSON-stringified on the way out — `parseSearch` returns the
+ * raw string and leaves any JSON decoding to the route's `search` schema
+ * (e.g. a Zod `transform`), so the round-trip is intentionally one-way at
+ * this layer.
+ *
+ * Returns `''` (empty string) when there are no entries — callers join with
+ * `?` only when the result is non-empty.
+ */
+export declare function formatSearch(search: Record<string, unknown> | undefined): string;
+/**
+ * Parse a `key=value&key=value` querystring into a string-keyed bag. Values
+ * are decoded but kept as strings — typed coercion happens in the route's
+ * `search` schema (e.g. Zod's `z.coerce.number()`).
+ *
+ * Multiple occurrences of the same key produce an array. Schemas that don't
+ * expect arrays will reject this — that's the right failure mode.
+ */
+export declare function parseSearch(query: string): Record<string, string | string[]>;

package/src/url/index.ts

@@ -5,14 +5,14 @@
  * `parseHref` in ../href.ts plus `_setRouteRegistry` for tests/bootstrap.
  */
 
-export { compilePath, type CompiledPath } from './compile.js';
-export { buildUrl } from './build.js';
-export { parseHrefImpl } from './parse.js';
-export { formatSearch, parseSearch } from './format.js';
+export { compilePath, type CompiledPath } from './compile';
+export { buildUrl } from './build';
+export { parseHrefImpl } from './parse';
+export { formatSearch, parseSearch } from './format';
 export {
     _setRouteRegistry,
     _clearRouteRegistry,
     getRouteRegistry,
     getCompiledPath,
-} from './registry.js';
-export { validateSync, type ValidateOutcome } from './validate.js';
+} from './registry';
+export { validateSync, type ValidateOutcome } from './validate';

package/src/url/parse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * URL → typed Href parser.
+ *
+ * Walks every registered route with a `path`, tries to match its compiled
+ * regex against the URL's pathname, and on a hit validates the extracted
+ * params + search through the route's Standard Schema. First match wins;
+ * iteration order follows `Object.keys` of the registered routes map.
+ *
+ * Validation failures return `null` rather than throwing — deep-link handlers
+ * fall back to the initial route on a bad URL instead of crashing the app.
+ */
+import type { Href } from '../href';
+/**
+ * Parse a URL string against the active route registry.
+ *
+ * Accepts both absolute URLs (`myapp://host/users/42?tab=about`) and
+ * pathname-only forms (`/users/42?tab=about`). Returns `null` if no route's
+ * `path` matches the URL or if schema validation rejects the extracted bits.
+ */
+export declare function parseHrefImpl(url: string): Href | null;

package/src/url/parse.ts

@@ -10,13 +10,13 @@
  * fall back to the initial route on a bad URL instead of crashing the app.
  */
 
-import type { Href } from '../href.js';
-import type { RouteId } from '../register.js';
+import type { Href } from '../href';
+import type { RouteId } from '../register';
 import { parse as parseUrl } from '@sigx/lynx-linking';
-import type { CompiledPath } from './compile.js';
-import { parseSearch } from './format.js';
-import { getCompiledPath, getRouteRegistry } from './registry.js';
-import { validateSync } from './validate.js';
+import type { CompiledPath } from './compile';
+import { parseSearch } from './format';
+import { getCompiledPath, getRouteRegistry } from './registry';
+import { validateSync } from './validate';
 
 /**
  * Parse a URL string against the active route registry.

package/{dist/url/registry.js → src/url/registry.d.ts}

@@ -11,8 +11,13 @@
  * directly. The leading underscore is a convention: not part of the supported
  * public API (test/integration use only).
  */
-import { compilePath } from './compile.js';
-let current = null;
+import type { CompiledPath } from './compile';
+import type { RouteMap } from '../types';
+interface RegistryState {
+    readonly routes: RouteMap;
+    /** Lazy-compiled paths keyed by route name. */
+    readonly compiled: Map<string, CompiledPath>;
+}
 /**
  * Set the active route registry. Called by `<NavigationRoot>` on setup and
  * available to tests/bootstrap code as `_setRouteRegistry`.
@@ -22,35 +27,14 @@ let current = null;
  * specific registry for a one-off call, pass it explicitly to the helper
  * (parseHrefWithRoutes / hrefForWithRoutes — currently internal).
  */
-export function _setRouteRegistry(routes) {
-    current = { routes, compiled: new Map() };
-}
+export declare function _setRouteRegistry(routes: RouteMap): void;
 /** Clear the registry. Mainly for tests that want to assert the unset path. */
-export function _clearRouteRegistry() {
-    current = null;
-}
+export declare function _clearRouteRegistry(): void;
 /** Get the active registry or throw a friendly error if none is set. */
-export function getRouteRegistry() {
-    if (!current) {
-        throw new Error('[lynx-navigation] No route registry set — render a <NavigationRoot> first, or call _setRouteRegistry() for tests.');
-    }
-    return current;
-}
+export declare function getRouteRegistry(): RegistryState;
 /**
  * Look up (or lazily compile) the path template for a route name. Returns
  * `null` when the route exists but declares no `path`.
  */
-export function getCompiledPath(registry, name) {
-    const def = registry.routes[name];
-    if (!def)
-        return null;
-    if (!def.path)
-        return null;
-    let compiled = registry.compiled.get(name);
-    if (!compiled) {
-        compiled = compilePath(def.path);
-        registry.compiled.set(name, compiled);
-    }
-    return compiled;
-}
-//# sourceMappingURL=registry.js.map
+export declare function getCompiledPath(registry: RegistryState, name: string): CompiledPath | null;
+export {};

package/src/url/registry.ts

@@ -12,9 +12,9 @@
  * public API (test/integration use only).
  */
 
-import type { CompiledPath } from './compile.js';
-import { compilePath } from './compile.js';
-import type { RouteMap } from '../types.js';
+import type { CompiledPath } from './compile';
+import { compilePath } from './compile';
+import type { RouteMap } from '../types';
 
 interface RegistryState {
     readonly routes: RouteMap;