@rangojs/router 0.18.0 → 0.19.0

package/dist/types/browser/event-controller.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { NavigationLocation, NavigateOptions, TrackedActionState, InflightAction, RscMetadata, HandleData, StreamingToken } from "./types.js";
+import type { NavigationLocation, NavigateOptionsInternal, TrackedActionState, InflightAction, RscMetadata, HandleData, StreamingToken } from "./types.js";
 /**
  * Phase of a navigation operation
  */
@@ -16,7 +16,7 @@ export interface NavigationEntry {
     abort: AbortController;
     phase: NavigationPhase;
     startedAt: number;
-    options?: NavigateOptions & {
+    options?: NavigateOptionsInternal & {
         skipLoadingState?: boolean;
     };
 }
@@ -165,7 +165,7 @@ export interface ActionHandle extends Disposable {
  * Event controller interface
  */
 export interface EventController {
-    startNavigation(url: string, options?: NavigateOptions & {
+    startNavigation(url: string, options?: NavigateOptionsInternal & {
         skipLoadingState?: boolean;
     }): NavigationHandle;
     abortNavigation(): void;

package/dist/types/browser/history-state.d.ts

@@ -11,6 +11,8 @@ export declare function buildHistoryState(userState: unknown, routerState?: {
     intercept?: boolean;
     sourceUrl?: string;
 }, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/** Check if a history state object contains location state keys. */
+export declare function hasLocationState(state: unknown): boolean;
 /**
  * Stamp an `idx` on the next history entry's state and call push/replaceState.
  * Push increments the current idx; replace keeps it. Initial entry idx is 0.

package/dist/types/browser/navigation-transaction.d.ts

@@ -1,4 +1,4 @@
-import type { NavigateOptions, NavigationStore, ResolvedSegment, StreamingToken } from "./types.js";
+import type { NavigateOptionsInternal, NavigationStore, ResolvedSegment, StreamingToken } from "./types.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 export { resolveNavigationState } from "./history-state.js";
 /**
@@ -28,6 +28,14 @@ interface CommitOptions {
      * merged in. The page left was saved by handleTraversalStart.
      */
     traversal?: boolean;
+    /** The committed route's name (payload metadata), remembered per history entry. */
+    routeName?: string;
+    /**
+     * transition({ when }) decision already made at this navigation's first
+     * presentation (the optimistic clientUrls() swap). Not a commit input: the
+     * partial updater reuses it instead of deciding again.
+     */
+    transitionGatedOff?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings
@@ -47,12 +55,22 @@ interface BoundCommitOverrides {
     cacheOnly?: boolean;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
+    /** The committed route's name (payload metadata), remembered per history entry. */
+    routeName?: string;
 }
 /**
  * Bound transaction with pre-configured commit options (without segmentIds/segments)
  */
 export interface BoundTransaction {
     readonly currentUrl: string;
+    /** Bound `replace` option (history replace instead of push). */
+    readonly replace?: boolean;
+    /** Bound `traversal` option: a back/forward navigation. */
+    readonly traversal?: boolean;
+    /** Bound user state (resolved), pushed with the entry at commit. */
+    readonly state?: unknown;
+    /** Bound `transitionGatedOff`: the decision made at first presentation. */
+    readonly transitionGatedOff?: boolean;
     /** Start streaming and get a token to end it when the stream completes */
     startStreaming(): StreamingToken;
     /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
@@ -76,6 +94,6 @@ interface NavigationTransaction extends Disposable {
  * Creates a navigation transaction that coordinates with the event controller.
  * Handles loading state transitions and cleanup on completion/abort.
  */
-export declare function createNavigationTransaction(store: NavigationStore, eventController: EventController, url: string, options?: NavigateOptions & {
+export declare function createNavigationTransaction(store: NavigationStore, eventController: EventController, url: string, options?: NavigateOptionsInternal & {
     skipLoadingState?: boolean;
 }): NavigationTransaction;

package/dist/types/browser/partial-update.d.ts

@@ -3,7 +3,13 @@ import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import type { NavigationUpdate } from "./types.js";
-export declare function shouldStartViewTransition(segments: ResolvedSegment[]): boolean;
+import { type TransitionWhenActionInput } from "./transition-when.js";
+/**
+ * Hold/animate decision for a commit: a non-intercept segment carries a
+ * transition, no intercept is presented, and this navigation's
+ * transition({ when }) decision did not gate it off.
+ */
+export declare function shouldStartViewTransition(segments: readonly ResolvedSegment[], transitionGatedOff?: boolean): boolean;
 /**
  * Transition commit. Every held commit announces the loader streams the
  * committed tree is still receiving (loader-store.ts announcePendingStreams)
@@ -38,6 +44,8 @@ export interface CommitOverrides {
     interceptSourceUrl?: string;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
+    /** The committed route's name (payload metadata), remembered per history entry. */
+    routeName?: string;
 }
 /**
  * Discriminated update mode for partial updates.
@@ -61,6 +69,11 @@ export type UpdateMode = {
      * boundaries do not animate the identical repaint.
      */
     optimisticPresented?: boolean;
+    /**
+     * A router.refresh() (or cross-tab refresh) of the current URL:
+     * transition({ when }) sees kind "revalidate", not "replace".
+     */
+    refresh?: boolean;
 } | {
     type: "leave-intercept";
     interceptSourceUrl?: string;
@@ -71,6 +84,8 @@ export type UpdateMode = {
     type: "action";
     interceptSourceUrl?: string;
     actionId?: string;
+    /** The action's FormData and result, for transition({ when }) `action`. */
+    action?: TransitionWhenActionInput;
 };
 /**
  * Type for the fetchPartialUpdate function

package/dist/types/browser/prefetch/cache.d.ts

@@ -15,11 +15,11 @@
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
  *   (so rotation invalidates source-scoped entries too), the source href, and
- *   the exact source segment tree. Populated when the
- *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
- *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
- *   both cases so source-sensitive responses cannot bleed into navigations
- *   from other pages.
+ *   the exact source segment tree. Populated when the server tags a
+ *   response with `X-RSC-Prefetch-Scope: source` (a route an intercept
+ *   targets, matched or not), OR when a Link opts in with
+ *   `prefetchKey=":source"` — in both cases so source-sensitive responses
+ *   cannot bleed into navigations from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
  * decoded prefetch entry (or null), letting navigation adopt a
@@ -122,7 +122,7 @@ export declare function isPrefetchCacheDisabled(): boolean;
  *   rotation invalidates source-scoped entries alongside wildcard ones,
  *   plus the source page href so the key is unique per originating page.
  *   Populated either when the server tags a response with
- *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
+ *   `X-RSC-Prefetch-Scope: source` (a route an intercept targets) or when a
  *   Link opts in via `prefetchKey=":source"`.
  *
  * Source-scoped keys retain `_rsc_segments` because their exact source tree is

package/dist/types/browser/react/Link.d.ts

@@ -1,13 +1,12 @@
 import React, { type ForwardRefExoticComponent, type RefAttributes } from "react";
-import { type LocationStateEntry } from "./location-state.js";
+import type { HistoryState } from "../types.js";
+export type StateOrGetter<T = unknown> = T | (() => T);
 /**
- * State prop type for Link component.
- * - LocationStateEntry[]: Type-safe state entries via createLocationState()
- * - StateOrGetter: Plain state object or click-time getter function
- * - Record<string, unknown>: Plain state object passed to history.pushState
+ * State prop type for Link component: the `router.push()` state type
+ * ({@link HistoryState}: `LocationStateEntry[]` from createLocationState(), or
+ * plain structured-clone-safe state), or a getter for it called at click time.
  */
-export type StateOrGetter<T = unknown> = T | (() => T);
-export type LinkState = LocationStateEntry[] | StateOrGetter<Record<string, unknown>>;
+export type LinkState = StateOrGetter<HistoryState>;
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
@@ -41,6 +40,14 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * @default true
      */
     revalidate?: boolean;
+    /**
+     * Set to `false` to present this navigation without a transition (urgent
+     * commit, `<ViewTransition>` classes `"none"`); no `transition({ when })`
+     * predicate is called. See `NavigateOptions.transition`.
+     *
+     * @default true
+     */
+    transition?: boolean;
     /**
      * Prefetch strategy for the link destination. When omitted, falls back to
      * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
@@ -66,8 +73,11 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * therefore serve the wrong diff to a navigation from a different
      * source.
      *
-     * Intercept responses are auto-scoped to the source via a server-side
-     * tag, so `":source"` is only needed for custom revalidation logic.
+     * A route an intercept targets is scoped to the source automatically
+     * (server-side `x-rsc-prefetch-scope: source`), whether or not the
+     * intercept applies from this page: the modal and the full page are
+     * both source-specific. Every other route stays shared, so `":source"`
+     * is only needed for custom revalidation logic.
      *
      * @example
      * ```tsx

package/dist/types/browser/react/context.d.ts

@@ -1,5 +1,5 @@
 import { type Context } from "react";
-import type { NavigationStore, NavigateOptions } from "../types.js";
+import type { NavigationStore, NavigateOptionsInternal } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 /**
@@ -29,7 +29,7 @@ export interface NavigationStoreContextValue {
      * @param options - Navigation options (replace, scroll)
      * @returns Promise that resolves when navigation is complete
      */
-    navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+    navigate: (url: string, options?: NavigateOptionsInternal) => Promise<void>;
     /**
      * Refresh the current route
      *

package/dist/types/browser/react/location-state-shared.d.ts

@@ -20,16 +20,32 @@ type LocationStateUnsafeFn = (...args: never[]) => unknown;
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
+type UnknownReason = "`unknown` cannot be verified as serializable; give it a concrete type";
+type FunctionReason = "functions cannot be stored in location state";
+type ConstructorReason = "class constructors cannot be stored in location state";
+type SymbolReason = "symbols cannot be stored in location state";
+type ReactReason = "React/RSC content cannot be stored in location state; store plain data and render it on arrival";
+type DepthReason = "nested too deep to locate the unsafe field; it is below this path";
 /**
  * Branded error surfaced when a value that cannot live in location state is
  * used. Location state is written into `history.state`, which uses the
  * structured clone algorithm; React elements, functions, and symbols throw a
- * `DataCloneError` at runtime. Carries a human-readable reason so the compile
- * error explains the fix.
+ * `DataCloneError` at runtime. Carries the reason and the offending field's
+ * path (`items[].info.values`; `<root>` for the value itself) so the compile
+ * error names the field to fix.
  */
-export type LocationStateUnsafe<Reason extends string> = {
+export type LocationStateUnsafe<Reason extends string, Path extends string = "<root>"> = {
     readonly __rango_location_state_unsafe: Reason;
+    readonly __rango_location_state_path: Path;
 };
+/**
+ * Why a value cannot be structured-cloned, for the kinds that fail on their
+ * own (not through something nested in them), or `never`. Distributes over a
+ * union, one reason per unsafe member.
+ */
+type UnsafeReason<T> = T extends LocationStateUnsafeFn ? FunctionReason : T extends LocationStateUnsafeCtor ? ConstructorReason : T extends symbol ? SymbolReason : T extends ReactElement ? ReactReason : never;
+/** Primitives and structured-clone built-ins, stored as-is. */
+type LocationStatePassthrough = string | number | boolean | bigint | null | undefined | Date | RegExp | ArrayBuffer | ArrayBufferView | Blob | File | FormData;
 /**
  * Maps `T` to itself when it is safe to store in location state, or to a branded
  * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
@@ -40,21 +56,56 @@ export type LocationStateUnsafe<Reason extends string> = {
  * definition's value parameter so posting RSC content is a COMPILE error, not a
  * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
  */
-export type LocationStateSafe<T> = IsUnknown<T> extends true ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable"> : T extends LocationStateUnsafeFn ? LocationStateUnsafe<"functions cannot be stored in location state"> : T extends LocationStateUnsafeCtor ? LocationStateUnsafe<"class constructors cannot be stored in location state"> : T extends symbol ? LocationStateUnsafe<"symbols cannot be stored in location state"> : T extends ReactElement ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival"> : T extends string | number | boolean | bigint | null | undefined ? T : T extends Date | RegExp | ArrayBuffer | ArrayBufferView | Blob | File | FormData ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<LocationStateSafe<V>> : T extends readonly unknown[] ? {
+export type LocationStateSafe<T> = IsUnknown<T> extends true ? LocationStateUnsafe<UnknownReason> : T extends unknown ? [UnsafeReason<T>] extends [never] ? T extends LocationStatePassthrough ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<LocationStateSafe<V>> : T extends object ? {
     [K in keyof T]: LocationStateSafe<T[K]>;
-} : T extends object ? {
-    [K in keyof T]: LocationStateSafe<T[K]>;
-} : T;
+} : T : LocationStateUnsafe<UnsafeReason<T>> : never;
+type AtPath<P extends string> = P extends "" ? "<root>" : P;
+/** `a.b` for a named key; `a[string]` / `a[number]` for an index signature. */
+type ChildPath<P extends string, K> = string extends K ? `${P}[string]` : number extends K ? `${P}[number]` : K extends string | number ? P extends "" ? `${K}` : `${P}.${K}` : `${P}[symbol]`;
+type UnsafeAt<R, P extends string> = R extends string ? LocationStateUnsafe<R, AtPath<P>> : never;
+/**
+ * Walks `T` to the fields {@link LocationStateSafe} rejects and returns one
+ * {@link LocationStateUnsafe} brand per offending path (a union when several
+ * fail). Reports the shallowest failures: a value that is itself unsafe stops
+ * the walk, and an object with unsafe fields of its own reports only those, so
+ * a class instance or DOM node stops at its methods instead of walking its
+ * whole object graph (`{ el: HTMLElement }` took 8.4M instantiations and hit
+ * TS2589 before). Descends only into children that fail the cached
+ * `LocationStateSafe` check, and stops at depth 8.
+ */
+type LocateUnsafe<T, P extends string, D extends unknown[]> = D["length"] extends 8 ? LocationStateUnsafe<DepthReason, AtPath<P>> : IsUnknown<T> extends true ? LocationStateUnsafe<UnknownReason, AtPath<P>> : [UnsafeReason<T>] extends [never] ? LocateNested<T, P, D> : UnsafeAt<UnsafeReason<T>, P>;
+type LocateNested<T, P extends string, D extends unknown[]> = T extends LocationStatePassthrough ? never : T extends ReadonlyMap<infer K, infer V> ? LocateChild<K, `${P}<key>`, D> | LocateChild<V, `${P}<value>`, D> : T extends ReadonlySet<infer V> ? LocateChild<V, `${P}[]`, D> : T extends readonly unknown[] ? number extends T["length"] ? LocateChild<T[number], `${P}[]`, D> : {
+    [K in keyof T & `${number}`]-?: LocateChild<T[K], `${P}[${K}]`, D>;
+}[keyof T & `${number}`] : T extends object ? LocateFields<T, P, D, OwnUnsafeKeys<T>> : never;
+/**
+ * Keys whose value is unsafe itself, not through something nested in it.
+ * `any` is never one: it passes LocationStateSafe, so reporting it would
+ * leave nothing to report and hide its siblings' paths.
+ */
+type OwnUnsafeKeys<T> = {
+    [K in keyof T]-?: IsAny<T[K]> extends true ? never : IsUnknown<T[K]> extends true ? K : [UnsafeReason<T[K]>] extends [never] ? never : K;
+}[keyof T];
+type LocateFields<T, P extends string, D extends unknown[], Own extends keyof T> = [Own] extends [never] ? {
+    [K in keyof T]-?: LocateChild<T[K], ChildPath<P, K>, D>;
+}[keyof T] : {
+    [K in Own]-?: LocateChild<T[K], ChildPath<P, K>, D>;
+}[Own];
+type LocateChild<T, P extends string, D extends unknown[]> = [T] extends [
+    LocationStateSafe<T>
+] ? never : LocateUnsafe<T, P, [...D, unknown]>;
+type GenericReason = "location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival";
 /**
  * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
- * branded {@link LocationStateUnsafe} object. Intersected into the value
- * parameter of a definition's call and `write()` so POSTING RSC content (or any
- * non-serializable value) is a compile error whose text carries the reason —
- * without a `TState extends ...` self-constraint, which TypeScript rejects as
- * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
- * so valid usage is unchanged.
+ * branded {@link LocationStateUnsafe} object naming the reason and the path of
+ * each offending field, e.g. `LocationStateUnsafe<"...", "items[].info.values">`.
+ * Intersected into the value parameter of a definition's call and `write()` so
+ * POSTING RSC content (or any non-serializable value) is a compile error whose
+ * text carries the reason and the field — without a `TState extends ...`
+ * self-constraint, which TypeScript rejects as circular (TS2313). For safe `T`,
+ * `value & unknown` collapses back to `value`, so valid usage is unchanged.
  */
-export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>] ? unknown : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>] ? unknown : OrGenericUnsafe<LocateUnsafe<T, "", []>>;
+type OrGenericUnsafe<U> = [U] extends [never] ? LocationStateUnsafe<GenericReason> : U;
 /**
  * Type-safe location state definition
  *
@@ -63,7 +114,10 @@ export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>] ? unkn
  */
 export interface LocationStateDefinition<TArgs extends unknown[], TState> {
     (...args: TArgs): LocationStateEntry;
-    /** Injected by Vite plugin - do not set manually */
+    /**
+     * Injected by Vite plugin - do not set manually. Unit tests without the
+     * plugin use withLocationStateKey() from @rangojs/router/testing.
+     */
     __rsc_ls_key: string;
     /** Whether this state auto-clears after first read */
     readonly __rsc_ls_flash: boolean;
@@ -79,6 +133,15 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
      * want React to manage subscription/hydration for you.
      */
     read(): TState | undefined;
+    /**
+     * Read this definition's slot from a location snapshot instead of the
+     * current entry: a transition({ when }) context's `from` / `to`, or any
+     * `{ state }` holding a `history.state` object. A snapshot read never clears
+     * flash state.
+     */
+    read(location: {
+        readonly state: unknown;
+    }): TState | undefined;
     /**
      * Statically write the value into the current history entry under this
      * definition's key, preserving any other keys already on history.state
@@ -106,51 +169,27 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
     delete(): void;
 }
 /**
- * Create a type-safe location state definition
- *
- * The key is auto-injected by the Vite exposeInternalIds plugin as a property
- * based on file path and export name. No manual key required.
- *
- * @param options Optional configuration
- * @returns A typed state definition for use with Link and useLocationState
- *
- * @example
- * ```typescript
- * // Persistent state (survives back/forward)
- * export const ProductState = createLocationState<{ name: string; price: number }>();
- *
- * // Flash state (cleared after first read)
- * export const FlashMessage = createLocationState<{ text: string }>({ flash: true });
- *
- * // Use in Link
- * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
- *
- * // Just-in-time typed state (getter called at click time, not render time).
- * // Must be in a client component — the getter function can't cross the RSC boundary.
- * <Link
- *   to="/product/123"
- *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
- * >
- *
- * // Read with hook (reactive)
- * const product = useLocationState(ProductState);
- *
- * // Read without hook (snapshot, client-side only)
- * const snap = ProductState.read();
- *
- * // Static write to current history entry (non-reactive, client-side only).
- * // Survives back/forward and hard refresh; useLocationState() readers will
- * // NOT see the new value until the next navigation. Pair with .read() or a
- * // fresh mount.
- * ProductState.write({ name: "Widget", price: 9.99 });
- *
- * // Manually clear the slot (non-reactive, client-side only).
- * ProductState.delete();
- * ```
+ * @internal The navigation store registers here (navigation-store.ts) to
+ * refresh its per-entry memory: back/forward reads the entry being left from
+ * that memory (at popstate history.state already belongs to the destination),
+ * so a write after the entry's commit must reach it.
  */
+export declare function setCurrentHistoryStateListener(listener: (() => void) | undefined): void;
+/** Replace the current entry's history.state in place (same URL). */
+export declare function replaceCurrentHistoryState(state: unknown): void;
 export declare function createLocationState<TState>(options?: LocationStateOptions): LocationStateDefinition<[
     (TState | (() => TState)) & ValidateLocationState<TState>
 ], TState>;
+/**
+ * A definition's key, or undefined when none is set, without the missing-key
+ * throw of the `__rsc_ls_key` getter. For dev checks and test helpers.
+ */
+export declare function peekLocationStateKey(definition: object): string | undefined;
+/**
+ * Check if a value is a LocationStateDefinition (a createLocationState()
+ * result, callable, not an entry).
+ */
+export declare function isLocationStateDefinition(value: unknown): value is LocationStateDefinition<unknown[], unknown>;
 /**
  * Check if a value is a LocationStateEntry
  */

package/dist/types/browser/react/location-state.d.ts

@@ -1,4 +1,4 @@
-import type { LocationStateDefinition } from "./location-state-shared.js";
+import { type LocationStateDefinition } from "./location-state-shared.js";
 export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, type LocationStateEntry, type LocationStateDefinition, type LocationStateOptions, } from "./location-state-shared.js";
 /**
  * Hook to read location state from history.state

package/dist/types/browser/transition-when.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Browser-side transition({ when }) decisions.
+ *
+ * A navigation is decided ONCE, at the first commit that presents its
+ * destination: the canonical commit for a server route, the optimistic swap
+ * for a clientUrls() cross-route navigation (the canonical commit then reuses
+ * the decision carried on its transaction), the history-cache restore or
+ * refetch commit for back/forward, the action commit (error lane included).
+ *
+ * The decision is navigation-wide: every distinct predicate (by function
+ * identity) declared by a committed segment, kept or re-sent (#989), runs, and
+ * any false gates the whole navigation off. It never changes the rendered
+ * tree's shape: every segment keeps its key and its <ViewTransition> element
+ * (segment-system.tsx renders each class "none"), and the commit is urgent
+ * instead of held (partial-update.ts). That is what keeps component state
+ * across when true -> false -> true (#995). A response carries no decision,
+ * so a reused prefetch is decided against the real source.
+ */
+import type { ResolvedSegment, TransitionWhenContext, TransitionWhenFn, TransitionWhenKind } from "../types/segments.js";
+import type { NavigationStore } from "./types.js";
+/** One side of the navigation before it is frozen into a RouteLocation. */
+export interface RouteLocationInput {
+    url: string | URL;
+    params?: Readonly<Record<string, string>>;
+    routeName?: string;
+    state?: unknown;
+}
+/** The action fields of a `kind: "action"` context. */
+export interface TransitionWhenActionInput {
+    id?: string;
+    formData?: FormData;
+    result?: unknown;
+    error?: unknown;
+}
+export interface TransitionDecisionInput {
+    kind: TransitionWhenKind;
+    from: RouteLocationInput;
+    /** The destination; ignored for "action" and "revalidate" (`to` is `from`). */
+    to?: RouteLocationInput;
+    action?: TransitionWhenActionInput;
+}
+export declare function createTransitionWhenContext(input: TransitionDecisionInput): TransitionWhenContext;
+/**
+ * Run one predicate. A throw counts as false (the navigation does not hold)
+ * and is logged; it never fails the navigation.
+ */
+export declare function evaluateTransitionWhen(fn: TransitionWhenFn, ctx: TransitionWhenContext): boolean;
+/** Distinct predicates of the segments that declare one, in segment order. */
+export declare function collectTransitionWhens(segments: readonly ResolvedSegment[]): Set<TransitionWhenFn>;
+/**
+ * Decide a commit: true when the navigation is gated off (some predicate
+ * returned false or threw). The context is built only when a predicate runs.
+ * An intercept commit is not evaluated: it never holds or animates
+ * (partial-update.ts shouldStartViewTransition). `extra` is a predicate not on
+ * a segment yet (the optimistic clientUrls() destination).
+ */
+export declare function decideTransitionGatedOff(segments: readonly ResolvedSegment[], input: () => TransitionDecisionInput, extra?: TransitionWhenFn): boolean;
+/** Merge route params the way popstate restores them (per-segment params). */
+export declare function mergeSegmentParams(segments: readonly ResolvedSegment[]): Record<string, string>;
+export interface CommitDecision {
+    /** Newer params / route name for the committed location (an action response's). */
+    from?: {
+        params?: Record<string, string>;
+        routeName?: string;
+    };
+    /** The destination, from the committed location; omit for "action" / "revalidate". */
+    to?: (from: RouteLocationInput) => RouteLocationInput;
+    action?: TransitionWhenActionInput;
+    extra?: TransitionWhenFn;
+}
+/**
+ * decideTransitionGatedOff with `from` read from the store: call it before
+ * the commit moves the store. `state` is the live history.state, except for
+ * back/forward: at popstate history.state already belongs to the destination,
+ * so the entry being left comes from the store's per-entry memory (undefined
+ * after a reload, never guessed).
+ */
+export declare function decideCommitGatedOff(store: NavigationStore, segments: readonly ResolvedSegment[], kind: TransitionWhenKind, decision?: CommitDecision): boolean;
+/** The FormData argument a server action was called with, if any. */
+export declare function findActionFormData(args: readonly unknown[]): FormData | undefined;