@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

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

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

package/dist/types/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/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/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/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/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/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/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/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/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/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;

package/dist/types/browser/network-error-handler.d.ts

@@ -0,0 +1,35 @@
+import { NetworkError } from "../errors.js";
+import type { UpdateSubscriber } from "./types.js";
+/**
+ * Convert an unknown error to a NetworkError, or return null if not network-related.
+ *
+ * Pure function: extracts the "is this a network error?" decision from
+ * navigation-bridge and server-action-bridge so it can be unit tested.
+ */
+export declare function toNetworkError(error: unknown, context: {
+    url: string;
+    operation: "action" | "navigation" | "revalidation";
+}): NetworkError | null;
+/**
+ * Emit a NetworkError to the nearest error boundary (offline, failed fetch).
+ */
+export declare function emitNetworkError(onUpdate: UpdateSubscriber, error: NetworkError, pathname: string): void;
+/**
+ * Emit a navigation processing error to the nearest error boundary. Used when a
+ * navigation response cannot be processed (an undecodable Flight body, or any
+ * unanticipated failure while building the response) -- for both fresh and
+ * prefetched responses, since both funnel through the navigation catch. Without
+ * this, such a failure becomes an uncaught rejection that silently aborts the
+ * navigation instead of surfacing the route's error boundary.
+ */
+export declare function emitNavigationError(onUpdate: UpdateSubscriber, error: unknown, pathname: string): void;
+/**
+ * Check if an error is safe to suppress in background operations.
+ *
+ * Background revalidation (SWR, navigated-away refetch) should silently
+ * swallow AbortErrors and network errors since the user has already moved
+ * on and showing an error would be disruptive.
+ *
+ * Pure function, easily unit tested.
+ */
+export declare function isBackgroundSuppressible(error: unknown): boolean;

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

@@ -0,0 +1,61 @@
+import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegment } from "./types.js";
+import type { ReactNode } from "react";
+import type { RenderSegmentsOptions } from "../segment-system.js";
+import type { BoundTransaction } from "./navigation-transaction.js";
+/**
+ * Configuration for creating a partial updater
+ */
+export interface PartialUpdateConfig {
+    store: NavigationStore;
+    client: NavigationClient;
+    onUpdate: UpdateSubscriber;
+    renderSegments: (segments: ResolvedSegment[], options?: RenderSegmentsOptions) => Promise<ReactNode> | ReactNode;
+    /** RSC version getter — returns the current version (may change after HMR) */
+    getVersion?: () => string | undefined;
+}
+/**
+ * Options that can override the pre-configured commit settings
+ */
+export interface CommitOverrides {
+    /** Override scroll behavior (e.g., disable for intercepts) */
+    scroll?: boolean;
+    /** Override replace behavior (e.g., force replace for intercepts) */
+    replace?: boolean;
+    /** Mark this as an intercept route */
+    intercept?: boolean;
+    /** Source URL where intercept was triggered from */
+    interceptSourceUrl?: string;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Discriminated update mode for partial updates.
+ */
+export type UpdateMode = {
+    type: "navigate";
+    /** Cached segments for the target URL. When provided, these are used to build
+     * the segment map instead of the current page's segments. This ensures consistency
+     * when we send cached segment IDs to the server - if the server returns empty diff,
+     * we use the same segments we told the server we have. */
+    targetCacheSegments?: ResolvedSegment[];
+    /** Cached handle data for the target URL. When server returns empty diff and we're
+     * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
+    targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+    /** Source URL for intercept restore (popstate cache miss) */
+    interceptSourceUrl?: string;
+} | {
+    type: "leave-intercept";
+    interceptSourceUrl?: string;
+} | {
+    type: "stale-revalidation";
+    interceptSourceUrl?: string;
+} | {
+    type: "action";
+    interceptSourceUrl?: string;
+};
+/**
+ * Type for the fetchPartialUpdate function
+ */
+export type PartialUpdater = (targetUrl: string, segmentIds: string[] | undefined, isRetry: boolean, signal: AbortSignal | undefined, tx: BoundTransaction, mode?: UpdateMode) => Promise<void>;
+export declare function createPartialUpdater(config: PartialUpdateConfig): PartialUpdater;
+export { createPartialUpdater as default };