@rangojs/router 0.0.0-experimental.39 → 0.0.0-experimental.39528925

package/dist/types/browser/segment-reconciler.d.ts

@@ -0,0 +1,74 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Determines the merging behavior for segment reconciliation.
+ *
+ * - 'action': From server-action-bridge's own merge. Always merges loaders,
+ *   always preserves cached loading (even undefined), never clears cached
+ *   segment loading.
+ * - 'navigation': From partial-update during normal navigation. Does NOT merge
+ *   loaders, preserves cached loading only when defined, clears truthy loading
+ *   on cached segments not in server diff.
+ * - 'stale-revalidation': From partial-update during stale revalidation or
+ *   action-triggered refetch. Merges loaders, always preserves cached loading
+ *   (same as action), clears truthy loading on cached segments not in server diff.
+ */
+export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
+export interface ReconcileInput {
+    actor: ReconcileActor;
+    /** All segment IDs the server expects the client to have (matched array) */
+    matched: string[];
+    /** Segment IDs that changed (diff array) */
+    diff: string[];
+    /** Segments returned from server (raw array, keyed internally by ID) */
+    serverSegments: ResolvedSegment[];
+    /** Cached segments from current page (raw array, keyed internally by ID) */
+    cachedSegments: ResolvedSegment[];
+    /** When true, diff segments not in matched are inserted after their parent
+     *  layout. Used during navigation when consolidation fetch returns loader
+     *  segments that aren't in the matched array. */
+    insertMissingDiff?: boolean;
+}
+export interface ReconcileResult {
+    /** All merged segments in matched order (for caching and committing) */
+    segments: ResolvedSegment[];
+    /** Main segments excluding intercepts (for rendering) */
+    mainSegments: ResolvedSegment[];
+    /** Intercept segments only (passed via render options) */
+    interceptSegments: ResolvedSegment[];
+}
+/**
+ * Single source of truth for merging server segments with cached segments.
+ *
+ * Replaces the duplicated merge loops in server-action-bridge.ts and
+ * partial-update.ts. The actor parameter controls the subtle behavioral
+ * differences between action and navigation merging:
+ *
+ * Loading preservation:
+ * - action/stale-revalidation: Always preserves cached loading value when it
+ *   differs from server (even when cached is undefined). This prevents tree
+ *   structure changes that would remount components and destroy useActionState
+ *   during action revalidation or action-triggered refetch.
+ * - navigation: Preserves cached loading only when the cached value is defined
+ *   (not undefined). When cached is undefined, lets server value through
+ *   because we're building a new tree.
+ *
+ * Loader merging:
+ * - action/stale-revalidation: Merges partial loader data when server returns
+ *   fewer loaders than cached (revalidation only updated some loaders).
+ * - navigation: Does not merge (full navigation fetches complete data).
+ *
+ * Cached segment handling (segments in matched but not in server response):
+ * - action: Returns cached segment as-is (preserve tree structure).
+ * - navigation/stale-revalidation: Clears truthy loading to undefined
+ *   (prevents showing stale skeletons), but preserves loading=false
+ *   (suppressed boundary is structural).
+ */
+export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
+/**
+ * Reconcile error segments with cached segments.
+ *
+ * For error responses, the server returns the error boundary segment.
+ * This function overlays error segments onto the full cached tree,
+ * preserving sibling layouts that aren't in the error parent chain.
+ */
+export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

package/dist/types/browser/segment-structure-assert.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Assert that merging a server segment with a cached segment won't change
+ * the React tree structure. Logs a warning in development when a mismatch
+ * is detected.
+ *
+ * This catches the class of bugs where `loading()` with `{ ssr: false }`
+ * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
+ * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
+ * client state (useActionState, refs, etc.).
+ *
+ * @param cached - The currently cached segment
+ * @param incoming - The new segment from server
+ * @param context - Where this merge is happening (for the warning message)
+ */
+export declare function assertSegmentStructure(cached: ResolvedSegment, incoming: ResolvedSegment, context: string): void;

package/dist/types/browser/server-action-bridge.d.ts

@@ -0,0 +1,29 @@
+import type { ServerActionBridge, ServerActionBridgeConfig } from "./types.js";
+import type { EventController } from "./event-controller.js";
+/**
+ * Extended configuration for server action bridge with event controller
+ */
+export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
+    eventController: EventController;
+    /** Callback to trigger SPA navigation (for action redirects) */
+    onNavigate?: (url: string, options?: {
+        state?: unknown;
+        replace?: boolean;
+        _skipCache?: boolean;
+    }) => Promise<void>;
+}
+/**
+ * Create a server action bridge for handling RSC server actions
+ *
+ * The bridge registers a callback with the RSC runtime that handles:
+ * - Encoding action arguments
+ * - Sending action requests to the server
+ * - Processing responses and updating UI
+ * - Managing concurrent action requests via event controller
+ * - HMR resilience (refetching if segments are missing)
+ *
+ * @param config - Bridge configuration
+ * @returns ServerActionBridge instance
+ */
+export declare function createServerActionBridge(config: ServerActionBridgeConfigWithController): ServerActionBridge;
+export { createServerActionBridge as default };

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

@@ -0,0 +1,524 @@
+import type { ReactNode, ComponentType } from "react";
+import type { ResolvedSegment, SlotState } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import type { RenderSegmentsOptions } from "../segment-system.js";
+/**
+ * RSC payload received from server.
+ * The tree is reconstructed from metadata.segments by the browser bridges.
+ */
+export interface RscPayload<TMetadata = RscMetadata> {
+    metadata?: TMetadata;
+    returnValue?: ActionResult;
+}
+/**
+ * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type HandleData = Record<string, Record<string, unknown[]>>;
+/**
+ * Metadata included in RSC responses
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface RscMetadata {
+    pathname: string;
+    segments: ResolvedSegment[];
+    /** Router instance ID — the current app's identity. A mismatch with the
+     *  client's id (sent as _rsc_rid) is detected server-side and answered with
+     *  X-RSC-Reload (full document load), so the client never swaps apps
+     *  in-session; within a session this always equals the current app. */
+    routerId?: string;
+    isPartial?: boolean;
+    isError?: boolean;
+    matched?: string[];
+    diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
+    /** Merged route params from the matched route */
+    params?: Record<string, string>;
+    /**
+     * State of named slots for this route match
+     * Key is slot name (e.g., "@modal"), value is slot state
+     * Slots are used for intercepting routes during soft navigation
+     */
+    slots?: Record<string, SlotState>;
+    /** Root layout component for browser-side re-renders */
+    rootLayout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Handle data accumulated across route segments (async generator that yields on each push) */
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    /** Cached handle data (for back/forward navigation from cache) */
+    cachedHandleData?: HandleData;
+    /**
+     * RSC version string from the server.
+     * Used to detect version mismatches after HMR/deployment.
+     */
+    version?: string;
+    /** Cloudflare dev worker generation used for stale-document convergence. */
+    devDiscoveryEpoch?: number;
+    /**
+     * TTL in milliseconds for the client-side in-memory prefetch cache.
+     * Sent on initial render so the browser can configure its cache duration.
+     */
+    prefetchCacheTTL?: number;
+    /**
+     * Max entries in the client-side in-memory prefetch cache (FIFO eviction).
+     * Sent on initial render so the browser can configure its cache capacity.
+     */
+    prefetchCacheSize?: number;
+    /**
+     * Max concurrent speculative prefetch requests on the client.
+     * Sent on initial render so the browser can configure its prefetch queue.
+     */
+    prefetchConcurrency?: number;
+    /**
+     * Router-wide default prefetch strategy for Links without a `prefetch` prop.
+     * Sent on initial render; applied once at init (default-strategy.ts).
+     */
+    defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
+    /**
+     * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
+     * reads it verbatim and binds the rango state cookie to it; composition
+     * happens only server-side.
+     */
+    stateCookieName?: string;
+    /**
+     * Theme configuration from router.
+     * Included when theme is enabled in router config.
+     */
+    themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * Initial theme from cookie (for SSR hydration).
+     * Included when theme is enabled in router config.
+     */
+    initialTheme?: Theme;
+    /** URL prefix for all routes (from createRouter({ basename })). */
+    basename?: string;
+    /** Whether connection warmup is enabled */
+    warmupEnabled?: boolean;
+    /**
+     * Whether the client should hydrate inside React.StrictMode. Carried on the
+     * initial full-render payload only; the browser entry reads it once at
+     * hydration. Defaults to true on the client when omitted.
+     */
+    strictMode?: boolean;
+    /**
+     * Server-side redirect with optional state (for partial requests).
+     * `external: true` (from redirect(url, { external: true })) tells the client
+     * to hard-navigate to an off-host target instead of validating same-origin.
+     */
+    redirect?: {
+        url: string;
+        external?: boolean;
+    };
+    /** Server-set location state to include in history.pushState */
+    locationState?: Record<string, unknown>;
+}
+/**
+ * Result from server action execution
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface ActionResult {
+    ok: boolean;
+    data: unknown;
+}
+/**
+ * Location object representing current URL
+ * Uses URL for full URL parsing (origin, host, hostname, port, protocol, searchParams, etc.)
+ */
+export type NavigationLocation = URL;
+/**
+ * Inflight server action being tracked
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InflightAction {
+    /** Unique identifier for this action invocation */
+    id: string;
+    /** Server action function ID */
+    actionId: string;
+    /** Action arguments */
+    payload: unknown[];
+    /** Timestamp when action started */
+    startedAt: number;
+}
+/**
+ * Internal navigation state (includes inflight actions for store use)
+ *
+ * @internal This type is an implementation detail. Use PublicNavigationState instead.
+ */
+export interface NavigationState {
+    /** Navigation lifecycle state (idle or loading during navigation) */
+    state: "idle" | "loading";
+    /** Whether RSC data is currently streaming (initial load or navigation) */
+    isStreaming: boolean;
+    /** Current location */
+    location: NavigationLocation;
+    /** URL being navigated to (null when idle) */
+    pendingUrl: string | null;
+    /** List of inflight server actions (internal use only) */
+    inflightActions: InflightAction[];
+}
+/**
+ * Public navigation state exposed via useNavigation hook
+ * Excludes internal properties like inflightActions
+ */
+export type PublicNavigationState = Omit<NavigationState, "inflightActions">;
+/**
+ * Action lifecycle state
+ */
+export type ActionLifecycleState = "idle" | "loading" | "streaming";
+/**
+ * State for a tracked server action
+ * Used by useAction hook to observe action lifecycle
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface TrackedActionState {
+    /** Current lifecycle state of the action */
+    state: ActionLifecycleState;
+    /** Server action function ID (e.g., "addToCart") */
+    actionId: string | null;
+    /** Action arguments (array for JSON, FormData for form submissions) */
+    payload: unknown[] | FormData | null;
+    /** Error if action failed */
+    error: unknown | null;
+    /** Result data from the action (preserved after completion) */
+    result: unknown | null;
+}
+/**
+ * The value returned by {@link useAction} when called without a selector.
+ *
+ * This is the stable, public name for the action-state shape; consumers can
+ * name it in their own signatures (e.g. a wrapper hook). It aliases the
+ * internal {@link TrackedActionState}.
+ */
+export type ActionState = TrackedActionState;
+/**
+ * Listener for action state changes
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type ActionStateListener = (state: TrackedActionState) => void;
+/**
+ * Cache interface for storing segments
+ * Compatible with Map
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SegmentCache {
+    get(key: string): ResolvedSegment | undefined;
+    set(key: string, value: ResolvedSegment): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    keys(): IterableIterator<string>;
+    readonly size: number;
+}
+/**
+ * Internal segment state managed by the store
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SegmentState {
+    path: string;
+    currentUrl: string;
+    currentSegmentIds: string[];
+}
+/**
+ * Navigation update emitted when UI should re-render
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface NavigationUpdate {
+    root: ReactNode | Promise<ReactNode>;
+    metadata: RscMetadata;
+    /** Scroll behavior to apply after React commits this update */
+    scroll?: {
+        /** For back/forward: restore saved position */
+        restore?: boolean;
+        /** Set to false to disable scrolling entirely */
+        enabled?: boolean;
+        /** Function to check if streaming is in progress */
+        isStreaming?: () => boolean;
+    };
+}
+/**
+ * State value for navigate/Link
+ * - LocationStateEntry[]: Type-safe state entries (recommended)
+ * - unknown: Plain state format (object or getter function)
+ */
+export type HistoryState = import("./react/location-state-shared.js").LocationStateEntry[] | unknown;
+/**
+ * Options for navigation operations
+ */
+export interface NavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    /**
+     * Whether to revalidate server data on navigation.
+     * Set to `false` to skip the RSC server fetch and only update the URL.
+     *
+     * Only takes effect when the pathname stays the same (search param / hash changes).
+     * If the pathname changes, this option is ignored and a full navigation occurs.
+     *
+     * All location-aware hooks (`useSearchParams`, `useNavigation`, etc.) still update.
+     * Server components do not re-render.
+     *
+     * @default true
+     *
+     * @example
+     * ```tsx
+     * router.push("/products?color=blue", { revalidate: false });
+     * router.replace("/products?page=3", { revalidate: false });
+     * ```
+     */
+    revalidate?: boolean;
+    /**
+     * State to pass to history.pushState/replaceState
+     * Accessible via useLocationState() hook.
+     *
+     * @example
+     * ```tsx
+     * // Type-safe state (recommended)
+     * const ProductState = createLocationState<{ name: string }>();
+     * navigate("/product/123", { state: [ProductState({ name: "Widget" })] });
+     *
+     * // Type-safe just-in-time state (getter called at navigation time)
+     * navigate("/product/123", {
+     *   state: [ProductState(() => ({ name: computeName() }))],
+     * });
+     *
+     * // Multiple states
+     * navigate("/checkout", { state: [ProductState(p), CartState(c)] });
+     *
+     * // Plain static state
+     * navigate("/product", { state: { from: "list" } });
+     *
+     * // Plain just-in-time state
+     * navigate("/product", { state: () => ({ from: window.location.pathname }) });
+     * ```
+     */
+    state?: HistoryState;
+}
+/** @internal Extended options used only within the navigation bridge */
+export interface NavigateOptionsInternal extends NavigateOptions {
+    /** Skip segment cache (used by redirect-with-state to force re-render) */
+    _skipCache?: boolean;
+}
+/**
+ * Options for useRouter push/replace methods.
+ * Same as NavigateOptions but without `replace` (implicit in push vs replace).
+ */
+export type RouterNavigateOptions = Omit<NavigateOptions, "replace">;
+/**
+ * Router instance returned by useRouter hook.
+ * Provides stable action methods that never cause re-renders.
+ */
+export interface RouterInstance {
+    /** Navigate to a URL, pushing a new entry to the history stack */
+    push(url: string, options?: RouterNavigateOptions): Promise<void>;
+    /** Navigate to a URL, replacing the current history entry */
+    replace(url: string, options?: RouterNavigateOptions): Promise<void>;
+    /** Refresh the current route (re-fetch server data, preserve client state) */
+    refresh(): Promise<void>;
+    /**
+     * Prefetch a URL for faster client-side transition.
+     *
+     * Pass `{ key: ":source" }` to source-scope the prefetch cache entry (parity
+     * with `<Link prefetchKey=":source">`) when the target's response can differ
+     * by source page.
+     */
+    prefetch(url: string, options?: {
+        key?: ":source";
+    }): void;
+    /** Go back in browser history */
+    back(): void;
+    /** Go forward in browser history */
+    forward(): void;
+}
+/**
+ * URLSearchParams without mutation methods.
+ * Matches Next.js convention for useSearchParams return type.
+ */
+export type ReadonlyURLSearchParams = Omit<URLSearchParams, "append" | "delete" | "set" | "sort">;
+/**
+ * RSC runtime functions from @vitejs/plugin-rsc/browser
+ *
+ * These are injected as dependencies to avoid direct coupling
+ * to the RSC runtime implementation.
+ */
+export interface RscBrowserDependencies {
+    createFromFetch: <T>(response: Promise<Response>, options?: {
+        temporaryReferences?: any;
+        findSourceMapURL?: (filename: string, environmentName: string) => string | null;
+    }) => Promise<T>;
+    createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
+    encodeReply: (args: any[], options?: {
+        temporaryReferences?: any;
+    }) => Promise<FormData | string>;
+    setServerCallback: (callback: (id: string, args: any[]) => Promise<any>) => void;
+    createTemporaryReferenceSet: () => any;
+}
+/**
+ * Update subscriber callback for UI updates
+ */
+export type UpdateSubscriber = (update: NavigationUpdate) => void;
+/**
+ * State change listener for useNavigation hook subscriptions
+ */
+export type StateListener = () => void;
+/**
+ * Navigation store interface
+ *
+ * Owns segment state, history snapshots, and partial-update notifications.
+ * EventController owns the public navigation lifecycle exposed by hooks.
+ */
+export interface NavigationStore {
+    getSegmentState(): SegmentState;
+    setPath(path: string): void;
+    setCurrentUrl(url: string): void;
+    setSegmentIds(ids: string[]): void;
+    getHistoryKey(): string;
+    setHistoryKey(key: string): void;
+    /** Monotonic token of the most recently committed navigation. */
+    getNavInstance(): number;
+    cacheSegmentsForHistory(historyKey: string, segments: ResolvedSegment[], handleData?: HandleData): void;
+    getCachedSegments(historyKey: string): {
+        segments: ResolvedSegment[];
+        stale: boolean;
+        handleData?: HandleData;
+        routerId?: string;
+        /**
+         * True when the entry's handle data is incomplete (a deferred Meta was
+         * still pending at navigate-away). A popstate return must revalidate with
+         * a FULL re-render so the server re-streams handles.
+         */
+        handlesPending?: boolean;
+    } | undefined;
+    hasHistoryCache(historyKey: string): boolean;
+    /**
+     * Update only the handleData (and optionally the stale / handlesPending flags)
+     * of an existing cache entry. When a flag is omitted the entry's current value
+     * is preserved. `stale=true` marks a single entry stale so a popstate return
+     * revalidates it; `handlesPending=true` additionally forces that revalidation
+     * to be a full re-render (so a deferred Meta re-streams).
+     */
+    updateCacheHandleData(historyKey: string, handleData: HandleData, stale?: boolean, handlesPending?: boolean): void;
+    /**
+     * Owner-guarded variant of updateCacheHandleData: writes only when the entry
+     * is still owned by `ownerInstance`. Folds the caller's separate ownership
+     * probe and write into one historyCache scan for the per-yield streaming path.
+     */
+    updateCacheHandleDataIfOwned(historyKey: string, handleData: HandleData, ownerInstance: number, stale?: boolean, handlesPending?: boolean): void;
+    markHistoryCacheStale(): void;
+    markCacheAsStaleAndBroadcast(): void;
+    clearHistoryCache(): void;
+    setCrossTabRefreshCallback(callback: () => void): void;
+    getInterceptSourceUrl(): string | null;
+    setInterceptSourceUrl(url: string | null): void;
+    getRouterId?(): string | undefined;
+    setRouterId?(id: string): void;
+    onUpdate(callback: UpdateSubscriber): () => void;
+    emitUpdate(update: NavigationUpdate): void;
+}
+/**
+ * Options for partial navigation fetch
+ */
+export interface FetchPartialOptions {
+    targetUrl: string;
+    segmentIds: string[];
+    previousUrl: string;
+    signal?: AbortSignal;
+    /** If true, this is a stale cache revalidation request - server should force revalidators */
+    staleRevalidation?: boolean;
+    interceptSourceUrl?: string;
+    /** RSC version for cache invalidation detection */
+    version?: string;
+    /** Current router ID — server detects app switch and returns full response */
+    routerId?: string;
+    /** If true, this is an HMR refetch - server should invalidate manifest cache */
+    hmr?: boolean;
+}
+/**
+ * Result of a partial fetch including stream completion tracking
+ */
+export interface FetchPartialResult {
+    payload: RscPayload;
+    /** Promise that resolves when the response stream is fully consumed */
+    streamComplete: Promise<void>;
+    /**
+     * True only when this payload came from a prefetch-cache hit whose stream had
+     * ALREADY fully drained at fetch time (the route was fully prefetched). The
+     * commit then runs in a startTransition so loading()/Suspense content — already
+     * resolved — swaps in directly without flashing a fallback. A partially-warmed
+     * (still-streaming) prefetch hit and a cold fetch leave this false so their
+     * fallbacks stream as usual.
+     */
+    fullyPrefetched?: boolean;
+}
+/**
+ * Navigation client for fetching RSC payloads
+ */
+export interface NavigationClient {
+    fetchPartial(options: FetchPartialOptions): Promise<FetchPartialResult>;
+}
+/**
+ * Options for link interception
+ */
+export interface LinkInterceptorOptions {
+    shouldIntercept?: (link: HTMLAnchorElement) => boolean;
+}
+/**
+ * Server action bridge for handling server actions
+ */
+export interface ServerActionBridge {
+    register(): void;
+}
+/**
+ * Configuration for server action bridge
+ */
+export interface ServerActionBridgeConfig {
+    store: NavigationStore;
+    client: NavigationClient;
+    deps: RscBrowserDependencies;
+    onUpdate: UpdateSubscriber;
+    renderSegments: (segments: ResolvedSegment[], options?: RenderSegmentsOptions) => Promise<ReactNode> | ReactNode;
+}
+/**
+ * Navigation bridge for handling client-side navigation
+ */
+export interface NavigationBridge {
+    navigate(url: string, options?: NavigateOptions): Promise<void>;
+    refresh(): Promise<void>;
+    handlePopstate(): Promise<void>;
+    registerLinkInterception(): () => void;
+    registerDelegatedPrefetch(): () => void;
+    /** Current RSC version (live, reflects the latest updateVersion). */
+    getVersion(): string | undefined;
+    /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
+    updateVersion(newVersion: string): void;
+}
+/**
+ * Configuration for navigation bridge
+ */
+export interface NavigationBridgeConfig {
+    store: NavigationStore;
+    client: NavigationClient;
+    onUpdate: UpdateSubscriber;
+    renderSegments: (segments: ResolvedSegment[], options?: RenderSegmentsOptions) => Promise<ReactNode> | ReactNode;
+}
+export type { ResolvedSegment };
+/**
+ * Token for tracking an active stream.
+ * Call end() when the stream completes.
+ */
+export interface StreamingToken {
+    end(): void;
+}

package/dist/types/browser/validate-redirect-origin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Validate that a client-consumed redirect URL (from headers or Flight payload)
+ * targets the same origin as the current page. Prevents open-redirect attacks
+ * via crafted responses.
+ *
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
+ * the identical same-origin contract. Adds the client-side `console.error` on a
+ * block; the resolver itself stays pure.
+ *
+ * @returns The canonical (normalized) URL string on success, or null if blocked.
+ */
+export declare function validateRedirectOrigin(url: string, currentOrigin: string): string | null;
+/**
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
+ * the client is about to hard-navigate to via `window.location.assign()`.
+ *
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
+ * identical contract: `external` allows an off-origin target but only an
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
+ * navigation. Adds the client-side `console.error` on a block; the resolver
+ * itself stays pure.
+ *
+ * @returns The normalized URL string on success, or null if blocked.
+ */
+export declare function validateExternalRedirect(url: string, currentOrigin: string): string | null;

package/dist/types/build/collect-fallback-refs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export declare function collectFallbackClientRefs(boundary: unknown, report: (refKey: string) => void): void;