@react-motion-router/stack 2.0.0-beta.sha-20ff5ff → 2.0.0-beta.sha-112968d

package/build/Anchor.d.ts

@@ -30,5 +30,5 @@ interface UseIntersectionOptions {
     rootMargin?: string;
     threshold?: number | number[];
 }
-export declare function Anchor({ preload, goBack, params, type, href: hrefProp, navigation: navigationProp, onClick: onClickProp, preloadBehaviour, children, ...aProps }: AnchorProps): JSX.Element;
+export declare function Anchor({ preload, goBack, params, type, href: hrefProp, navigation: navigationProp, onClick: onClickProp, preloadBehaviour, children, ...aProps }: AnchorProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/build/GestureRegion.d.ts

@@ -1,5 +1,5 @@
 interface GestureRegionProps extends React.HTMLAttributes<HTMLDivElement> {
     disabled?: boolean;
 }
-export declare function GestureRegion({ disabled, children, ...props }: GestureRegionProps): JSX.Element;
+export declare function GestureRegion({ disabled, children, ...props }: GestureRegionProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/build/HistoryEntry.d.ts

@@ -3,16 +3,16 @@ export declare class HistoryEntry implements Omit<NavigationHistoryEntry, 'url'>
     readonly routerId: string;
     readonly index: number;
     constructor(nativeEntry: NavigationHistoryEntry, routerId: string, index: number);
-    set ondispose(handler: ((this: NavigationHistoryEntry, ev: Event) => any) | null);
-    get ondispose(): ((this: NavigationHistoryEntry, ev: Event) => any) | null;
+    set ondispose(handler: ((this: NavigationHistoryEntry, ev: Event) => void) | null);
+    get ondispose(): ((this: NavigationHistoryEntry, ev: Event) => void) | null;
     get id(): string;
     get globalIndex(): number;
     get url(): URL | null;
     get key(): string;
     get sameDocument(): boolean;
-    addEventListener<K extends keyof NavigationHistoryEntryEventMap>(type: K, listener: (this: NavigationHistoryEntry, ev: NavigationHistoryEntryEventMap[K]) => any, options?: boolean | AddEventListenerOptions): () => void;
+    addEventListener<K extends keyof NavigationHistoryEntryEventMap>(type: K, listener: (this: NavigationHistoryEntry, ev: NavigationHistoryEntryEventMap[K]) => void, options?: boolean | AddEventListenerOptions): () => void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
-    removeEventListener<K extends keyof NavigationHistoryEntryEventMap>(type: K, listener: (this: NavigationHistoryEntry, ev: NavigationHistoryEntryEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof NavigationHistoryEntryEventMap>(type: K, listener: (this: NavigationHistoryEntry, ev: NavigationHistoryEntryEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
     removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
     dispatchEvent(event: Event): boolean;
     getState<T>(): T;

package/build/Navigation.d.ts

@@ -1,10 +1,15 @@
-import { NavigationBase } from '../../core/build';
+import { LoadNavigationTransition, NavigationBase, NavigationBaseConfig, PathPattern } from '../../core/build';
 import { GoBackOptions, GoForwardOptions, NavigateOptions, NavigationBaseOptions, NavigationProps, RouterEventMap } from './common/types';
 import { HistoryEntry } from './HistoryEntry';
-import { Router } from './Router';
+export interface NavigationConfig extends NavigationBaseConfig<RouterEventMap> {
+    preload(pathname: string, props?: NavigationProps, options?: NavigationBaseOptions): Promise<boolean>;
+    getCommitted(): Promise<NavigationHistoryEntry> | null;
+    getTransition(): NavigationTransition | LoadNavigationTransition | null;
+    getPathPatterns(): PathPattern[];
+}
 export declare class Navigation extends NavigationBase<RouterEventMap> {
-    protected readonly router: Router;
-    constructor(router: Router);
+    private readonly config;
+    constructor(config: NavigationConfig);
     preload(route: string, props?: NavigationProps, options?: NavigationBaseOptions): Promise<boolean>;
     replace(route: string, props?: NavigationProps, options?: NavigationBaseOptions): NavigationResult;
     push(route: string, props?: NavigationProps, options?: NavigationBaseOptions): NavigationResult;
@@ -17,9 +22,184 @@ export declare class Navigation extends NavigationBase<RouterEventMap> {
     private createForwardEvent;
     private createNavigateEvent;
     get committed(): Promise<NavigationHistoryEntry> | null;
-    get transition(): NavigationTransition | import('../../core/build').LoadNavigationTransition | null;
+    get transition(): NavigationTransition | LoadNavigationTransition | null;
     get globalEntries(): NavigationHistoryEntry[];
+    /**
+     * Returns the list of history entries **owned by this router**, derived from the
+     * browser’s global navigation history.
+     *
+     * ---
+     *
+     * ### Mental model
+     *
+     * The Web Navigation API exposes a **single, flat history list**.
+     * This router projects a **scoped, ordered view** of that list ensuring the
+     * router can only see entries it created.
+     *
+     * Each global entry is classified as one of:
+     *
+     * - **Owned by this router**
+     * - **Owned by a nested router**
+     * - **Owned by a different (foreign) router**
+     *
+     * The resulting entry list is built by iterating global history **from the
+     * beginning**, applying ownership rules, and stopping when ownership is lost.
+     *
+     * ---
+     *
+     * ### Ownership & contiguity rules
+     *
+     * 1. **Entries owned by this router**
+     *    - Are included
+     *    - Preserve global ordering
+     *
+     * 2. **Entries owned by nested routers**
+     *    - Exactly **one entry is included** (the nested router’s mount point),
+     *      because it must be rendered by the parent router
+     *    - All subsequent entries belonging to that same nested scope are excluded
+     *
+     * 3. **Entries owned by a foreign router**
+     *    - Are excluded
+     *    - **Terminate entry collection** once at least one entry has been matched
+     *
+     * This means contiguity is enforced **only across routers that cannot be
+     * matched by this router at all**.
+     *
+     * ---
+     *
+     * ### Important invariants
+     *
+     * - Returned entries are always in **global history order**
+     * - Local indices are **stable and monotonic**
+     * - Nested router entries never leak into the parent router
+     * - Entry collection stops once navigation leaves this router’s ownership
+     *   after it has begun
+     *
+     * ---
+     *
+     * ### Example
+     *
+     * Global history:
+     * ```
+     * 0: /                     (parent)
+     * 1: /world                (parent)
+     * 2: /world/1              (nested mount point)
+     * 3: /world/2              (nested)
+     * 4: /about                (parent)
+     * 5: /other-router/page    (foreign)
+     * 6: /                     (parent)
+     * ```
+     *
+     * Parent router entries:
+     * ```
+     * /, /world, /world/1, /about
+     * ```
+     *
+     * Collection stops at index 5 because ownership is transferred to a
+     * foreign router.
+     *
+     *
+     * This approach balances correctness, simplicity, and predictable behavior
+     * without requiring global history rewriting or fragile index arithmetic.
+     */
     get entries(): HistoryEntry[];
+    /**
+     * Returns the **local history index** for this router, derived from the
+     * browser’s global navigation state.
+     *
+     * ---
+     *
+     * ### Problem this solves
+     *
+     * The Web Navigation API exposes a **single, flat history list**.
+     * This router exposes a **scoped history view** that:
+     *
+     * - filters out entries owned by nested routers
+     * - preserves global ordering
+     * - reindexes entries locally
+     *
+     * As a result, there is **no arithmetic relationship** between:
+     *
+     * - `window.navigation.currentEntry.index` (global)
+     * - this router’s local `index`
+     *
+     * This getter computes the local index **by identity**, not position.
+     *
+     * ---
+     *
+     * ### High-level behavior
+     *
+     * The returned index is:
+     *
+     * > the index of the **most recent local entry** that appears in the
+     * > browser’s global history **at or before** the current global entry.
+     *
+     * ---
+     *
+     * ### Resolution strategy
+     *
+     * 1. If the current global index is **before** this router’s first entry,
+     *    the index resolves to `0`.
+     *
+     * 2. If the current global index is **after** this router’s last entry,
+     *    the index resolves to `entries.length - 1`.
+     *
+     * 3. Otherwise:
+     *    - A window of global history is sliced from the first local entry
+     *      up to and including the current global entry.
+     *    - Local entries are scanned **from newest to oldest**.
+     *    - The first local entry whose `key` appears in that global slice
+     *      determines the local index.
+     *
+     * Entry identity is determined by **history entry keys**, not URLs or
+     * global indices.
+     *
+     * ---
+     *
+     * ### Why key-based matching is required
+     *
+     * - Global indices are sparse once nested routers are involved
+     * - URLs may repeat or be replaced
+     * - History entries can be inserted between parent entries
+     *
+     * Keys provide the only stable identity that survives these cases.
+     *
+     * ---
+     *
+     * ### Invariant
+     *
+     * The returned index always satisfies:
+     *
+     * ```
+     * 0 ≤ index < entries.length
+     * ```
+     *
+     * and monotonically tracks navigation through global history.
+     *
+     * ---
+     *
+     * ### Example
+     *
+     * Global history:
+     * ```
+     * 0: /
+     * 1: /world
+     * 2: /world/1   (nested)
+     * 3: /about     ← current
+     * ```
+     *
+     * Local router entries:
+     * ```
+     * /        (index 0)
+     * /world   (index 1)
+     * /about   (index 2)
+     * ```
+     *
+     * Result:
+     * ```
+     * index === 2
+     * ```
+     */
     get index(): number;
     get previous(): HistoryEntry | null;
     get next(): HistoryEntry | null;

package/build/__tests__/Navigation/common/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const FIRST_INDEX = 0;
+export declare const SECOND_INDEX = 1;
+export declare const THIRD_INDEX = 2;
+export declare const FOURTH_INDEX = 3;

package/build/__tests__/Navigation/preload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/__tests__/Screen/set-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/__tests__/Screen/set-params.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/common/constants.d.ts

@@ -6,3 +6,4 @@ export declare const DEFAULT_GESTURE_CONFIG: {
     readonly gestureDisabled: false;
 };
 export declare const DEFAULT_PRELOAD_FORCE_THRESHOLD = 0.5;
+export declare const DEFAULT_PLAYBACK_RATE = 1;

package/build/common/events.d.ts

@@ -4,11 +4,11 @@ export declare class NavigateEvent extends Event {
     readonly routerId: string;
     readonly route: string;
     readonly props: NavigationProps;
-    readonly navigationType: NonNullable<NavigateOptions["type"]>;
+    readonly navigationType: NonNullable<NavigateOptions['type']>;
     readonly signal: AbortSignal;
     readonly committed: Promise<NavigationHistoryEntry>;
     readonly transition: NavigationTransition;
-    constructor(routerId: string, route: string, props: NavigationProps, type: NavigateOptions["type"], signal: AbortSignal, committed: Promise<NavigationHistoryEntry>, transition: NavigationTransition);
+    constructor(routerId: string, route: string, props: NavigationProps, type: NavigateOptions['type'], signal: AbortSignal, committed: Promise<NavigationHistoryEntry>, transition: NavigationTransition);
 }
 export declare class BackEvent extends Event {
     readonly routerId: string;

package/build/common/hooks.d.ts

@@ -2,7 +2,11 @@ import { PlainObject } from '../../../core/build';
 import { Navigation } from '../Navigation';
 import { Router } from '../Router';
 import { RouteProp } from './types';
+import { RefObject } from 'react';
 export declare function useNavigation(): Navigation;
 export declare function useRouter(): Router;
 export declare function useRoute<T extends PlainObject = PlainObject>(): RouteProp<T>;
 export declare function useParams<K extends string, S>(key: K, initialParams: S | (() => S)): [S, import('react').Dispatch<import('react').SetStateAction<S>>];
+type EventListenerOptions = boolean | AddEventListenerOptions;
+export declare function useEventListener<K extends keyof HTMLElementEventMap>(ref: RefObject<HTMLElement | null>, eventName: K, handler: (event: HTMLElementEventMap[K]) => void, options?: EventListenerOptions): void;
+export {};

package/build/common/promise-wrapper.d.ts

@@ -1,9 +1,8 @@
 export declare class PromiseWrapper<T> {
+    #private;
     promise: Promise<T>;
     state: 'pending' | 'resolved' | 'rejected';
-    nativeResolve: ((value: T | PromiseLike<T>) => void) | null;
-    nativeReject: ((reason: any) => void) | null;
     constructor();
     resolve(value: T): void;
-    reject(reason: any): void;
+    reject(reason: unknown): void;
 }