@rangojs/router 0.5.0 → 0.5.1

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

@@ -0,0 +1,221 @@
+import type { ReactNode } from "react";
+import type { NavigationLocation, NavigateOptions, TrackedActionState, InflightAction, RscMetadata, HandleData, StreamingToken } from "./types.js";
+/**
+ * Phase of a navigation operation
+ */
+export type NavigationPhase = "fetching" | "streaming";
+/**
+ * Phase of an action operation
+ */
+export type ActionPhase = "fetching" | "streaming" | "settling";
+/**
+ * Entry tracking an in-flight navigation
+ */
+export interface NavigationEntry {
+    url: string;
+    abort: AbortController;
+    phase: NavigationPhase;
+    startedAt: number;
+    options?: NavigateOptions & {
+        skipLoadingState?: boolean;
+    };
+}
+/**
+ * Entry tracking an in-flight action
+ */
+export interface ActionEntry {
+    /** Unique instance ID for this action invocation */
+    id: string;
+    /** Server action function ID (normalized name like "addToCart") */
+    actionId: string;
+    /** Abort controller for this action */
+    abort: AbortController;
+    /** Current phase of the action */
+    phase: ActionPhase;
+    /** Action arguments */
+    payload: unknown[];
+    /** Result from action (set on completion) */
+    result?: unknown;
+    /** Error from action (set on failure) */
+    error?: unknown;
+    /** Segment IDs that were revalidated by this action */
+    revalidatedSegments: string[];
+    /** Timestamp when action started */
+    startedAt: number;
+    /** Whether action processing is complete (may still be streaming) */
+    completed?: boolean;
+}
+/**
+ * Derived navigation state (computed from source of truth)
+ */
+export interface DerivedNavigationState {
+    /** Navigation lifecycle state */
+    state: "idle" | "loading";
+    /** Whether any operation is streaming */
+    isStreaming: boolean;
+    /** Whether a navigation is active (fetching or streaming, before commit) */
+    isNavigating: boolean;
+    /** Current committed location */
+    location: NavigationLocation;
+    /** URL being navigated to (null if idle) */
+    pendingUrl: string | null;
+    /** List of inflight actions (for compatibility) */
+    inflightActions: InflightAction[];
+}
+/**
+ * Callback for UI updates when root should re-render
+ */
+export type UpdateCallback = (update: {
+    root: ReactNode | Promise<ReactNode>;
+    metadata: RscMetadata;
+}) => void;
+/**
+ * State change listener
+ */
+export type StateListener = () => void;
+/**
+ * Action state listener
+ */
+export type ActionStateListener = (state: TrackedActionState) => void;
+/**
+ * Handle state listener
+ */
+export type HandleListener = () => void;
+/**
+ * Internal handle state stored in controller.
+ *
+ * Two segment lists are exposed because they serve different consumers:
+ *
+ * - `segmentOrder` drives handle collection (collectHandleData). Includes
+ *   parallel slot ids and reorders them after their parent so later-wins
+ *   collect functions (e.g. Meta) get the right precedence.
+ * - `routeSegmentIds` is the layouts-and-routes-only list documented by
+ *   `useSegments().segmentIds`. Parallels and loader sub-ids are stripped;
+ *   raw matched order is preserved.
+ *
+ * Both are derived from the same `matched` input on each setHandleData call
+ * so they stay in sync.
+ */
+export interface HandleState {
+    data: HandleData;
+    segmentOrder: string[];
+    routeSegmentIds: string[];
+}
+/**
+ * Result from starting a navigation
+ * Implements Disposable for use with `using` keyword
+ */
+export interface NavigationHandle extends Disposable {
+    /** Abort controller for this navigation */
+    abort: AbortController;
+    /** Signal for this navigation */
+    signal: AbortSignal;
+    /** Start streaming and get a token to end it later */
+    startStreaming(): StreamingToken;
+    /** Complete the navigation successfully */
+    complete(location: NavigationLocation): void;
+    /** Whether navigation was completed successfully */
+    readonly completed: boolean;
+}
+/**
+ * Result from starting an action
+ * Implements Disposable for use with `using` keyword
+ */
+export interface ActionHandle extends Disposable {
+    /** Unique instance ID */
+    id: string;
+    /** Abort controller for this action */
+    abort: AbortController;
+    /** Signal for this action */
+    signal: AbortSignal;
+    /** Start streaming and get a token to end it later */
+    startStreaming(): StreamingToken;
+    /** Record segments that were revalidated */
+    recordRevalidatedSegments(segmentIds: string[]): void;
+    /**
+     * Claim the subset of a location-state payload this action may write. A key
+     * is claimed only if no later-initiated action in the SAME cohort has already
+     * claimed it, so same-key concurrent writes resolve to the last-initiated
+     * action while distinct keys from every action survive. Recording the claim
+     * stops a later-settling earlier action from overwriting it. Arbitration is
+     * scoped to the action's cohort (its originating history entry, captured at
+     * startAction), so an action on one entry cannot suppress an action on
+     * another that happens to write the same slot.
+     *
+     * Contract: this guarantees the FINAL value is the last-initiated action's,
+     * not that the loser is never momentarily visible. When an earlier-initiated
+     * action settles first, its value is merged and observable until the
+     * later-initiated winner's response lands and overwrites it.
+     */
+    claimLocationState(state: Record<string, unknown>): Record<string, unknown>;
+    /** Complete the action with result */
+    complete(result?: unknown): void;
+    /** Fail the action with error */
+    fail(error: unknown): void;
+    /** Whether action was completed (success or failure) */
+    readonly settled: boolean;
+    /** Check if any concurrent actions were started */
+    hadConcurrentActions: boolean;
+    /** Get raw set of segments revalidated by concurrent actions */
+    getRevalidatedSegments(): Set<string>;
+    /** Clear consolidation tracking */
+    clearConsolidation(): void;
+}
+/**
+ * Event controller interface
+ */
+export interface EventController {
+    startNavigation(url: string, options?: NavigateOptions & {
+        skipLoadingState?: boolean;
+    }): NavigationHandle;
+    abortNavigation(): void;
+    startAction(actionId: string, args: unknown[], 
+    /** Originating history entry key; scopes location-state arbitration. */
+    cohort?: string): ActionHandle;
+    abortAllActions(): void;
+    getState(): DerivedNavigationState;
+    getActionState(actionId: string): TrackedActionState;
+    getLocation(): NavigationLocation;
+    setLocation(location: NavigationLocation): void;
+    subscribe(listener: StateListener): () => void;
+    subscribeToAction(actionId: string, listener: ActionStateListener): () => void;
+    subscribeToHandles(listener: HandleListener): () => void;
+    setHandleData(data: HandleData, matched?: string[], isPartial?: boolean, 
+    /**
+     * Segment ids that were re-resolved on the server this request (the
+     * partial response's `diff`). On a partial update, any existing bucket
+     * keyed under one of these ids that has no incoming entry is treated as
+     * stale and cleared. Without this, a parallel slot that revalidates but
+     * pushes nothing leaves its previous bucket in place forever.
+     */
+    resolvedIds?: string[]): void;
+    getHandleState(): HandleState;
+    /**
+     * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
+     * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
+     * Used while a deferred handle is resolving: the route has changed (so
+     * `useSegments` must reflect the new segment ids) but `useHandle` still holds
+     * its previous value until the deferred snapshot is applied.
+     */
+    setRouteSegmentIds(matched: string[]): void;
+    setParams(params: Record<string, string>): void;
+    getParams(): Record<string, string>;
+    getCurrentNavigation(): NavigationEntry | null;
+    getInflightActions(): Map<string, ActionEntry>;
+    /** Whether any concurrent actions have occurred (shared across all handles) */
+    hadAnyConcurrentActions(): boolean;
+}
+export interface EventControllerConfig {
+    initialLocation?: NavigationLocation;
+}
+/**
+ * Create an event controller for managing navigation and action state
+ *
+ * The controller uses a reactive model where:
+ * - Source of truth: currentNavigation, inflightActions, location
+ * - Derived state: navState, isStreaming computed from source
+ *
+ * Navigation uses switchMap semantics (new nav cancels previous).
+ * Actions use mergeMap semantics (all run concurrently, consolidate at end).
+ */
+export declare function createEventController(config?: EventControllerConfig): EventController;

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

@@ -0,0 +1,26 @@
+/**
+ * Resolve navigation state - handles both LocationStateEntry[] and plain formats
+ */
+export declare function resolveNavigationState(state: unknown): unknown;
+/**
+ * Build history state object from user state
+ * - Typed state: spread directly into history.state
+ * - Plain state: store in history.state.state
+ */
+export declare function buildHistoryState(userState: unknown, routerState?: {
+    intercept?: boolean;
+    sourceUrl?: string;
+}, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * 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.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export declare function pushHistoryWithIdx(state: Record<string, unknown> | null, url: string, replace: boolean): void;
+/**
+ * Merge server-set location state into the current history entry.
+ * Replaces the current history state and dispatches notification event
+ * so useLocationState hooks re-read from history.state.
+ */
+export declare function mergeLocationState(locationState: Record<string, unknown>): void;

package/dist/types.backup/browser/index.d.ts

@@ -0,0 +1 @@
+export { initBrowserApp, Rango, type InitBrowserAppOptions, } from "./rsc-router.js";

package/dist/types.backup/browser/intercept-utils.d.ts

@@ -0,0 +1,30 @@
+import type { ResolvedSegment } from "./types.js";
+import type { SlotState } from "../types.js";
+/**
+ * Check if a segment is an intercept segment.
+ * Intercept segments have namespace starting with "intercept:" — both the
+ * parallel container (@modal) and its content children receive this namespace
+ * from intercept-resolution.ts. Regular parallel segments like @sidebar do not.
+ */
+export declare function isInterceptSegment(s: ResolvedSegment): boolean;
+/**
+ * Split an array of segments into main and intercept groups.
+ * Intercept segments are separated for explicit injection into the render tree
+ * via the interceptSegments render option.
+ */
+export declare function splitInterceptSegments(segments: ResolvedSegment[]): {
+    main: ResolvedSegment[];
+    intercept: ResolvedSegment[];
+};
+/**
+ * Check if any slot is currently active (has content to render).
+ * Active slots indicate an intercept response where a parallel segment
+ * (e.g., @modal) has matched and should be rendered.
+ */
+export declare function hasActiveIntercept(slots?: Record<string, SlotState>): boolean;
+/**
+ * Check if cached segments contain any intercept segments.
+ * Intercept caches shouldn't be used for cached SWR rendering since
+ * whether interception happens depends on the current page context.
+ */
+export declare function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean;

package/dist/types.backup/browser/invalidate-client-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Client seat of `invalidateClientCache()` (the `default` export condition).
+ *
+ * Makes the current client behave as if a server action had just completed:
+ * the history cache is marked stale (SWR), the prefetch map is flushed, the
+ * state rotates, and sibling tabs are broadcast to — the same
+ * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
+ * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
+ * entry instantly and revalidates.
+ */
+export declare function invalidateClientCache(): void;
+/**
+ * Client no-op for `keepClientCache()`. It is a server action directive (the
+ * `react-server` condition sets a response header the action bridge reads);
+ * there is nothing to suppress from the client side.
+ */
+export declare function keepClientCache(): void;

package/dist/types.backup/browser/link-interceptor.d.ts

@@ -0,0 +1,43 @@
+import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
+/**
+ * Check if an anchor points to the same page with only a hash change.
+ * Used by both Link component and link-interceptor to let the browser
+ * handle anchor scrolling natively.
+ */
+export declare function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean;
+/**
+ * Default link interception predicate
+ *
+ * Returns true if the link should be intercepted for SPA navigation.
+ * Filters out:
+ * - Cross-origin links
+ * - Links with download attribute
+ * - Links with target other than _self
+ * - Links with data-no-intercept attribute
+ *
+ * @param link - The anchor element to check
+ * @returns true if the link should be intercepted
+ */
+export declare function defaultShouldIntercept(link: HTMLAnchorElement): boolean;
+/**
+ * Set up link interception for SPA navigation
+ *
+ * Attaches a global click handler to intercept clicks on anchor elements
+ * and call the onNavigate callback instead of performing a full page load.
+ *
+ * @param onNavigate - Callback when a link should navigate via SPA
+ * @param options - Configuration options
+ * @returns Cleanup function to remove the event listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = setupLinkInterception((url) => {
+ *   window.history.pushState({}, "", url);
+ *   fetchPartialUpdate(url);
+ * });
+ *
+ * // Later, to clean up:
+ * cleanup();
+ * ```
+ */
+export declare function setupLinkInterception(onNavigate: (url: string, options?: NavigateOptions) => void, options?: LinkInterceptorOptions): () => void;

package/dist/types.backup/browser/logging.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Module-level debug flag for guarding call sites whose debug arguments do
+ * non-trivial work (joins, maps, spreads, object literals). Because the Vite
+ * transform folds INTERNAL_RANGO_DEBUG to a literal, an `if (IS_BROWSER_DEBUG)`
+ * guard is minifier-DCE-able — the whole block drops from the production bundle.
+ * Prefer this over isBrowserDebugEnabled() at hot call sites: a const guard folds
+ * where a function call may not.
+ */
+export declare const IS_BROWSER_DEBUG: boolean;
+interface BrowserLogContext {
+    requestId: string;
+    txId: string;
+    operation: string;
+}
+export declare function isBrowserDebugEnabled(): boolean;
+export declare function startBrowserTransaction(operation: string): BrowserLogContext;
+export declare function browserDebugLog(ctx: BrowserLogContext, message: string, details?: Record<string, unknown>): void;
+/**
+ * Simple gated console.log for browser-side debug output.
+ * Unlike browserDebugLog, this doesn't require a transaction context -
+ * use it for standalone debug messages in partial-update, navigation-bridge, etc.
+ */
+export declare function debugLog(msg: string, ...args: unknown[]): void;
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export declare function bootLog(step: string, details?: Record<string, unknown>): void;
+export {};

package/dist/types.backup/browser/merge-segment-loaders.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Merge partial loader data from server with cached loader data.
+ *
+ * During partial revalidation (stale or action), the server may return only
+ * some loaders that pass the revalidation check. The component still needs
+ * all loader data, so we merge fresh data with cached data.
+ *
+ * @param fromServer - Segment returned from server with partial loaders
+ * @param fromCache - Cached segment with full loader data
+ * @returns Merged segment with complete loader data
+ */
+export declare function mergeSegmentLoaders(fromServer: ResolvedSegment, fromCache: ResolvedSegment): ResolvedSegment;
+/**
+ * Check if segments need loader merging during partial revalidation.
+ *
+ * Returns true when:
+ * - Server returned fewer loaders than cached (partial revalidation)
+ * - Both segments have loader data promises
+ */
+export declare function needsLoaderMerge(fromServer: ResolvedSegment, fromCache: ResolvedSegment | undefined): fromCache is ResolvedSegment;
+/**
+ * Insert diff segments that aren't in the matched array into allSegments.
+ *
+ * During consolidation fetch for concurrent actions, loader segments may be
+ * excluded from the request. The server returns them in the diff but not in
+ * the matched array. This function inserts them at the correct position
+ * (after their parent layout segment).
+ *
+ * Loader segment IDs follow the pattern: {parentLayoutId}D{index}.{loaderId}
+ * Example: M9L0L1D0.actionCounter has parent layout M9L0L1
+ *
+ * @param allSegments - Mutable array of segments to insert into
+ * @param diff - Array of segment IDs that changed (from server response)
+ * @param matchedIdSet - Set of segment IDs from matched array
+ * @param newSegmentMap - Map of segment ID to segment data from server
+ */
+export declare function insertMissingDiffSegments(allSegments: ResolvedSegment[], diff: string[] | undefined, matchedIdSet: Set<string>, newSegmentMap: Map<string, ResolvedSegment>): void;

package/dist/types.backup/browser/navigation-bridge.d.ts

@@ -0,0 +1,27 @@
+import type { NavigationBridge, NavigationBridgeConfig } from "./types.js";
+import { createNavigationTransaction } from "./navigation-transaction.js";
+import type { EventController } from "./event-controller.js";
+export { createNavigationTransaction };
+/**
+ * Extended configuration for navigation bridge with event controller
+ */
+export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
+    eventController: EventController;
+    /** RSC version from initial payload metadata. */
+    version?: string;
+}
+/**
+ * Create a navigation bridge for handling client-side navigation
+ *
+ * The bridge coordinates all navigation operations:
+ * - Link click interception
+ * - Browser back/forward (popstate)
+ * - Programmatic navigation
+ *
+ * Uses the event controller for reactive state management.
+ *
+ * @param config - Bridge configuration
+ * @returns NavigationBridge instance
+ */
+export declare function createNavigationBridge(config: NavigationBridgeConfigWithController): NavigationBridge;
+export { createNavigationBridge as default };

package/dist/types.backup/browser/navigation-client.d.ts

@@ -0,0 +1,17 @@
+import type { NavigationClient, RscBrowserDependencies } from "./types.js";
+/**
+ * Create a navigation client for fetching RSC payloads
+ *
+ * The client handles building URLs with RSC parameters and
+ * deserializing the response using the RSC runtime.
+ *
+ * Checks the in-memory prefetch cache before making a network request.
+ * Tries the source-scoped key first (populated when the server tagged
+ * the response as source-sensitive via `X-RSC-Prefetch-Scope: source`)
+ * and falls back to the Rango-state-keyed wildcard slot used for the
+ * common source-agnostic case.
+ *
+ * @param deps - RSC browser dependencies (createFromFetch)
+ * @returns NavigationClient instance
+ */
+export declare function createNavigationClient(deps: Pick<RscBrowserDependencies, "createFromFetch">): NavigationClient;

package/dist/types.backup/browser/navigation-store-handle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A module-level handle to the active navigation store.
+ *
+ * The boot path (`rsc-router.tsx`) calls `createNavigationStore()` directly;
+ * there is no global store singleton. This handle is the live reference for
+ * code that needs the store but does not
+ * receive it by argument: the jar-divergence observer (below) and the client
+ * seat of `invalidateClientCache()` (added later).
+ *
+ * Dependency-light on purpose: it imports only `setRangoStateObserver` and the
+ * store type, so pulling it into the default root entry does not drag the
+ * navigation store into bundles that previously lacked it.
+ */
+import type { NavigationStore } from "./types.js";
+/**
+ * Register the active navigation store at boot, and wire the jar-divergence
+ * observer: when a per-request cookie read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear), mark this tab's
+ * history cache stale. The history cache is not state-keyed, so the value
+ * rotation alone does not reach it. No broadcast, no prefetch clear, no
+ * re-rotation — the value already changed externally.
+ */
+export declare function registerNavigationStore(store: NavigationStore): void;
+/** The active navigation store, or null before boot has registered it. */
+export declare function getRegisteredStore(): NavigationStore | null;

package/dist/types.backup/browser/navigation-store.d.ts

@@ -0,0 +1,95 @@
+import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
+/**
+ * Clone the handleData CONTAINERS (the handle-name map and each segment map) so
+ * a cache entry is decoupled from the live map that eventController mutates — it
+ * adds/deletes segment keys and REPLACES bucket arrays in place. The bucket
+ * arrays themselves are shared by reference, NOT copied: a bucket array is only
+ * ever replaced wholesale (eventController.setHandleData reassigns it,
+ * resolveDeferredHandleValues builds a fresh one) and collect functions read it
+ * without mutating, so sharing is safe and skips an O(elements) copy on every
+ * cache write — the per-yield streaming hot path. This also preserves any
+ * non-serializable bucket contents (React elements, functions, etc.).
+ */
+export declare function cloneHandleData(handleData: HandleData): HandleData;
+/**
+ * Options for generating a history key
+ */
+export interface HistoryKeyOptions {
+    /** If true, append :intercept suffix to differentiate intercept entries */
+    intercept?: boolean;
+}
+/**
+ * Generate a cache key from a URL.
+ * Uses pathname + search (query params) directly as the key.
+ * Hash fragments (#) are excluded since they don't affect server data.
+ *
+ * For intercept routes, append `:intercept` suffix to cache them separately
+ * from non-intercept versions of the same URL.
+ */
+export declare function generateHistoryKey(url?: string, options?: HistoryKeyOptions): string;
+/**
+ * Configuration for creating a navigation store
+ */
+export interface NavigationStoreConfig {
+    initialLocation?: {
+        href: string;
+    };
+    initialSegmentIds?: string[];
+    initialHistoryKey?: string;
+    initialSegments?: ResolvedSegment[];
+    /**
+     * Maximum number of history entries to cache (default: 20)
+     * Older entries are evicted when limit is reached
+     */
+    cacheSize?: number;
+    /**
+     * Enable cross-tab cache invalidation via BroadcastChannel (default: true)
+     * When cache is cleared (via server actions or invalidateClientCache()),
+     * other tabs will also clear their cache
+     */
+    crossTabSync?: boolean;
+    /**
+     * Auto-refresh when another tab mutates data on the same path (default: true)
+     * Triggered when cache is cleared via server actions or invalidateClientCache()
+     * Requires crossTabSync to be enabled
+     */
+    crossTabAutoRefresh?: boolean;
+    /**
+     * Callback to invoke when cross-tab refresh is triggered
+     * Called when another tab invalidates the cache for a related route
+     */
+    onCrossTabRefresh?: () => void;
+}
+/**
+ * Create a navigation store for managing browser-side navigation state
+ *
+ * The store manages two types of state:
+ * - NavigationState: Public state exposed via useNavigation hook
+ * - SegmentState: Internal segment management for partial RSC updates
+ *
+ * @param config - Initial configuration
+ * @returns NavigationStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createNavigationStore({
+ *   initialLocation: window.location,
+ *   initialSegmentIds: [],
+ * });
+ *
+ * // Subscribe to state changes (for useNavigation hook)
+ * const unsubscribe = store.subscribe(() => {
+ *   const state = store.getState();
+ *   console.log('Navigation state:', state);
+ * });
+ *
+ * // Update state
+ * store.setState({ state: 'loading' });
+ *
+ * // Subscribe to UI updates (for re-rendering)
+ * store.onUpdate((update) => {
+ *   console.log('New root:', update.root);
+ * });
+ * ```
+ */
+export declare function createNavigationStore(config?: NavigationStoreConfig): NavigationStore;

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

@@ -0,0 +1,75 @@
+import type { NavigateOptions, NavigationStore, ResolvedSegment, StreamingToken } from "./types.js";
+import type { EventController, NavigationHandle } from "./event-controller.js";
+export { resolveNavigationState } from "./history-state.js";
+/**
+ * Options for committing a navigation transaction
+ */
+interface CommitOptions {
+    url: string;
+    segmentIds: string[];
+    segments: ResolvedSegment[];
+    replace?: boolean;
+    scroll?: boolean;
+    /** User-provided state to store in history.state */
+    state?: unknown;
+    /** If true, only update store without changing URL/history (for server actions) */
+    storeOnly?: boolean;
+    /** If true, this is an intercept route - store in history.state for popstate handling */
+    intercept?: boolean;
+    /** Source URL where the intercept was triggered from (stored in history.state) */
+    interceptSourceUrl?: string;
+    /** If true, only update cache without touching store or history (for background stale revalidation) */
+    cacheOnly?: boolean;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Options that can override the pre-configured commit settings
+ */
+interface BoundCommitOverrides {
+    /** Override scroll behavior (e.g., disable for intercepts) */
+    scroll?: boolean;
+    /** Override replace behavior (e.g., force replace for intercepts) */
+    replace?: boolean;
+    /** Override user-provided state */
+    state?: unknown;
+    /** Mark this as an intercept route */
+    intercept?: boolean;
+    /** Source URL where intercept was triggered from */
+    interceptSourceUrl?: string;
+    /** If true, only update cache (for stale revalidation) */
+    cacheOnly?: boolean;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Bound transaction with pre-configured commit options (without segmentIds/segments)
+ */
+export interface BoundTransaction {
+    readonly currentUrl: string;
+    /** 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. */
+    commit(segmentIds: string[], segments: ResolvedSegment[], overrides?: BoundCommitOverrides): {
+        scroll?: boolean;
+    };
+}
+/**
+ * Navigation transaction for managing state during navigation
+ * Uses the event controller handle for lifecycle management
+ */
+interface NavigationTransaction extends Disposable {
+    commit(options: CommitOptions): {
+        scroll?: boolean;
+    };
+    with(options: Omit<CommitOptions, "segmentIds" | "segments">): BoundTransaction;
+    /** The navigation handle from the event controller */
+    handle: NavigationHandle;
+}
+/**
+ * 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 & {
+    skipLoadingState?: boolean;
+}): NavigationTransaction;