@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/dist/types/router/intercept-resolution.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Intercept Resolution
+ *
+ * Extracted from createRouter closure. Contains intercept detection and resolution
+ * functions for soft navigation (modals).
+ */
+import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type { HandlerContext, ResolvedSegment } from "../types";
+import type { SegmentResolutionDeps } from "./types.js";
+/**
+ * Check if an intercept's when conditions are satisfied.
+ * All when() functions must return true for the intercept to activate.
+ * If no when() conditions are defined, the intercept always activates.
+ *
+ * During action revalidation, when() is NOT evaluated.
+ */
+export declare function evaluateInterceptWhen(intercept: InterceptEntry, selectorContext: InterceptSelectorContext | null, isAction: boolean): boolean;
+/**
+ * Find an intercept for the target route by walking up the entry chain.
+ * Returns the first (innermost) matching intercept along with the entry that defines it.
+ */
+/**
+ * Collect every intercept TARGET route name reachable from an origin entry —
+ * the same chain walk findInterceptForRoute() performs when this location is
+ * the navigation origin. Shipped in payload metadata so the browser-local
+ * clientUrls matcher can DECLINE its optimistic presentation for targets an
+ * intercept would claim (the committed result keeps the origin page + modal,
+ * so destination loading would flash and revert). Deliberately includes
+ * `when`-conditional intercepts: selectors need the live navigation context,
+ * so the browser stays conservative — worst case a non-intercepted navigation
+ * loses its optimistic loading, never the reverse.
+ */
+export declare function collectInterceptTargetNames(fromEntry: EntryData | null): string[];
+export declare function findInterceptForRoute(targetRouteKey: string, fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean): {
+    intercept: InterceptEntry;
+    entry: EntryData;
+} | null;
+/**
+ * Resolve an intercept entry and emit segment with the slot name.
+ */
+export declare function resolveInterceptEntry<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext?: {
+    clientSegmentIds: Set<string>;
+    prevParams: Record<string, string>;
+    request: Request;
+    prevUrl: URL;
+    nextUrl: URL;
+    routeKey: string;
+    actionContext?: {
+        actionId?: string;
+        actionUrl?: URL;
+        actionResult?: any;
+        formData?: FormData;
+    };
+    stale?: boolean;
+}, options?: {
+    /**
+     * Skip the intercept's middleware execution. Set ONLY by the post-response
+     * background re-render paths (proactive caching, stale background
+     * revalidation), whose sole purpose is to re-render the segment tree to
+     * populate the cache. The foreground request already ran the intercept
+     * middleware before the response was sent — it validated auth, set cookies,
+     * and wrote context vars into the request context's shared `_variables`,
+     * which the background render reuses. Re-running middleware here would fire
+     * its side effects a SECOND time, and a middleware that short-circuits with
+     * a Response would `throw` and silently abort the cache write. Never set on
+     * the foreground path.
+     */
+    skipMiddleware?: boolean;
+}): Promise<ResolvedSegment[]>;
+/**
+ * Resolve only the loaders for a cached intercept segment.
+ * Used on intercept cache hit to get fresh loader data while keeping cached component/layout.
+ */
+export declare function resolveInterceptLoadersOnly<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext: {
+    clientSegmentIds: Set<string>;
+    prevParams: Record<string, string>;
+    request: Request;
+    prevUrl: URL;
+    nextUrl: URL;
+    routeKey: string;
+    actionContext?: {
+        actionId?: string;
+        actionUrl?: URL;
+        actionResult?: any;
+        formData?: FormData;
+    };
+    stale?: boolean;
+}): Promise<{
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+} | null>;

package/dist/types/router/lazy-includes.d.ts

@@ -0,0 +1,26 @@
+import type { UrlPatterns } from "../urls.js";
+import type { AllUseItems } from "../route-types.js";
+import type { RouteEntry } from "../types";
+export interface LazyEvalDeps<TEnv = any> {
+    routesEntries: RouteEntry<TEnv>[];
+    mergedRouteMap: Record<string, string>;
+    nextMountIndex: () => number;
+    getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+    routerId?: string;
+}
+export declare function findLazyIncludes<TEnv = any>(items: AllUseItems[]): Array<{
+    prefix: string;
+    patterns: UrlPatterns<TEnv>;
+    context: {
+        urlPrefix: string;
+        namePrefix: string | undefined;
+        parent: unknown;
+        rootScoped?: boolean;
+    };
+}>;
+/**
+ * Evaluate a lazy entry's patterns and populate its routes
+ * This runs the lazy patterns handler and updates the entry in-place
+ * Also detects nested lazy includes and registers them as new entries
+ */
+export declare function evaluateLazyEntry<TEnv = any>(entry: RouteEntry<TEnv>, deps: LazyEvalDeps<TEnv>): void | Promise<void>;

package/dist/types/router/loader-resolution.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Router Loader Resolution
+ *
+ * Loader execution, memoization, and error handling utilities.
+ */
+import type { ReactNode } from "react";
+import type { EntryData } from "../server/context";
+import type { HandlerContext, LoaderDataResult, ErrorBoundaryHandler, ErrorInfo, NotFoundBoundaryHandler } from "../types";
+/**
+ * Internal callback signature for loader error notifications.
+ * This is a simplified callback for internal use in wrapLoaderWithErrorHandling.
+ * The caller (wrapLoaderPromise in router.ts) bridges this to the full OnErrorCallback.
+ */
+export type LoaderErrorCallback = (error: unknown, context: {
+    segmentId: string;
+    loaderName: string;
+    handledByBoundary: boolean;
+}) => void;
+/**
+ * Wrap a loader promise with error handling for deferred client-side resolution.
+ * Catches errors and converts them to LoaderDataResult objects that include
+ * error info and pre-rendered fallback UI when an error boundary is available.
+ *
+ * Loader-thrown SIGNALS are routed before error handling — they are control
+ * flow, not failures (onError is not invoked for them):
+ * - notFound(): the not-found UI is resolved and rendered HERE, server-side
+ *   (nearest notFoundBoundary → router notFound option → default), exactly
+ *   like the consumption lane (segment-resolution/helpers.ts), and rides the
+ *   envelope's `fallback` — the client swaps with zero extra fetches. The
+ *   response status is opportunistically set to 404 via the request stub: if
+ *   the rejection settles before the document Response is constructed the
+ *   status is a real 404; after, the stub write is inert (streamed fix-up
+ *   only). Nav-lane payloads are 200 either way — the client owns 404
+ *   presentation there.
+ * - redirect() (thrown 3xx Response): the target is resolved through the
+ *   soft-redirect same-origin rules NOW so unsafe targets never leave the
+ *   server; the client navigates when the entry decodes. No document-lane
+ *   302 — pre-stream redirect authority belongs to middleware (doctrine);
+ *   a loader redirect is always a client-side navigate.
+ *
+ * @param onError - Optional callback invoked when loader errors occur.
+ *   This has a simplified signature for internal use - the caller (typically
+ *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
+ *   OnErrorCallback with complete request context (request, url, env, etc.).
+ */
+export declare function wrapLoaderWithErrorHandling<T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null, createErrorInfo: (error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]) => ErrorInfo, onError?: LoaderErrorCallback, notFoundDeps?: {
+    findNearestNotFoundBoundary: (entry: EntryData | null) => ReactNode | NotFoundBoundaryHandler | null;
+    notFoundComponent?: ReactNode | ((props: {
+        pathname: string;
+    }) => ReactNode);
+}): Promise<LoaderDataResult<T>>;
+/**
+ * Set up the use() method on handler context to access loaders and handles.
+ *
+ * For loaders: Lazily runs loaders, memoizes results per request.
+ * For handles: Returns a push function bound to the current segment.
+ *
+ * Includes cycle detection: tracks dependency edges between loaders and
+ * throws on circular dependencies to prevent deadlocks.
+ */
+export declare function setupLoaderAccess<TEnv>(ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>): void;
+/**
+ * Set up ctx.use() for pre-rendering (build-time).
+ * Handles push to HandleStore; loaders throw with a clear error.
+ */
+export declare function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void;
+/**
+ * Set up ctx.use() for proactive caching (silent mode).
+ * Handles are silently ignored (no push to HandleStore).
+ * Loaders work normally but with fresh memoization and cycle detection.
+ *
+ * This prevents duplicate handle data (breadcrumbs, meta) from being
+ * pushed to the response stream during background proactive caching.
+ */
+export declare function setupLoaderAccessSilent<TEnv>(ctx: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>): void;
+/**
+ * Conditional execution based on revalidation
+ * Evaluates revalidation logic lazily, then executes appropriate callback
+ *
+ * @param shouldRevalidate - Async function that determines if revalidation is needed
+ * @param onRevalidate - Callback executed if revalidation returns true
+ * @param onSkip - Callback executed if revalidation returns false
+ * @returns Result from either onRevalidate or onSkip
+ */
+export declare function revalidate<T>(shouldRevalidate: () => Promise<boolean>, onRevalidate: () => Promise<T>, onSkip: () => T): Promise<T>;

package/dist/types/router/logging.d.ts

@@ -0,0 +1,41 @@
+export interface RevalidationTraceEntry {
+    segmentId: string;
+    segmentType: string;
+    belongsToRoute: boolean;
+    source: "segment-resolution" | "cache-hit" | "loader" | "parallel" | "orphan-layout" | "route-handler" | "layout-handler" | "intercept-loader";
+    defaultShouldRevalidate: boolean;
+    finalShouldRevalidate: boolean;
+    reason: string;
+    customRevalidators?: number;
+}
+export interface RevalidationTraceMeta {
+    method: string;
+    prevUrl: string;
+    nextUrl: string;
+    routeKey: string;
+    isAction: boolean;
+    stale?: boolean;
+}
+export interface RevalidationTrace {
+    meta: RevalidationTraceMeta;
+    entries: RevalidationTraceEntry[];
+}
+interface RouterLogOptions {
+    request: Request;
+    transaction: string;
+}
+interface LogDetails {
+    [key: string]: unknown;
+}
+export declare function getOrCreateRequestId(request: Request): string;
+export declare function runWithRouterLogContext<T>(options: RouterLogOptions, fn: () => T): T;
+export declare function withRouterLogScope<T>(label: string, fn: () => Promise<T>): Promise<T>;
+export declare function withRouterLogScope<T>(label: string, fn: () => T): T;
+export declare function isRouterDebugEnabled(): boolean;
+export declare function debugLog(scope: string, message: string, details?: LogDetails): void;
+export declare function debugWarn(scope: string, message: string, details?: LogDetails): void;
+export declare function isTraceActive(): boolean;
+export declare function startRevalidationTrace(meta: RevalidationTraceMeta): void;
+export declare function pushRevalidationTraceEntry(entry: RevalidationTraceEntry): void;
+export declare function flushRevalidationTrace(): RevalidationTrace | null;
+export {};

package/dist/types/router/manifest.d.ts

@@ -0,0 +1,8 @@
+import { type EntryData, type MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+/**
+ * Clear the module-level manifest cache.
+ * Called on HMR to ensure stale handler references are discarded.
+ */
+export declare function clearManifestCache(): void;
+export declare function loadManifest(entry: RouteEntry<any>, routeKey: string, path: string, metricsStore?: MetricsStore, isSSR?: boolean): Promise<EntryData>;

package/dist/types/router/match-api.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
+import type { ReactNode } from "react";
+import type { MatchContext } from "./match-context.js";
+import type { MatchApiDeps, ActionContext } from "./types.js";
+/**
+ * Create match context for full requests (document/SSR).
+ */
+export declare function createMatchContextForFull<TEnv>(request: Request, env: TEnv, deps: MatchApiDeps<TEnv>, findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"]): Promise<MatchContext<TEnv> | {
+    type: "redirect";
+    redirectUrl: string;
+}>;
+/**
+ * Create match context for partial requests (navigation/actions).
+ */
+export declare function createMatchContextForPartial<TEnv>(request: Request, env: TEnv, deps: MatchApiDeps<TEnv>, findInterceptForRoute: MatchApiDeps<TEnv>["findInterceptForRoute"], actionContext?: ActionContext): Promise<MatchContext<TEnv> | null>;
+/**
+ * Match an error to the nearest error boundary and return error segments.
+ */
+export declare function matchError<TEnv>(request: Request, _context: TEnv, error: unknown, deps: MatchApiDeps<TEnv>, defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined, segmentType?: ErrorInfo["segmentType"]): Promise<MatchResult | null>;

package/dist/types/router/match-context.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Match Context for Router Pipeline
+ *
+ * Encapsulates all state needed by the match pipeline middleware.
+ * Created once at the start of match()/matchPartial() and passed through the pipeline.
+ *
+ * DATA FLOW ARCHITECTURE
+ * ======================
+ *
+ * The router uses two complementary data structures:
+ *
+ *   MatchContext (ctx)        - Immutable request state
+ *   MatchPipelineState (state) - Mutable pipeline state
+ *
+ *
+ *   Request
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Create Context    |  ctx = immutable snapshot of request
+ *   +-------------------+
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Create State      |  state = mutable accumulator
+ *   +-------------------+
+ *      |
+ *      +---> [Pipeline Middleware]
+ *      |           |
+ *      |     ctx: read-only
+ *      |     state: read/write
+ *      |           |
+ *      +<----------+
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Build Result      |  Merge ctx + state into MatchResult
+ *   +-------------------+
+ *
+ *
+ * MATCHCONTEXT FIELDS
+ * ===================
+ *
+ * Request Info:
+ *   - request, url, pathname: The incoming HTTP request
+ *
+ * Environment:
+ *   - env: Server environment (Cloudflare bindings, etc.)
+ *
+ * Client State (from RSC request headers):
+ *   - clientSegmentIds: Segments the client currently has
+ *   - clientSegmentSet: Set version for O(1) lookup
+ *   - stale: Whether client considers its cache stale
+ *
+ * Navigation State:
+ *   - prevUrl, prevParams, prevMatch: Previous navigation for comparison
+ *
+ * Current Match:
+ *   - matched: Route match result (params, route key)
+ *   - manifestEntry: Resolved manifest data
+ *   - entries: All route entries (layouts, loaders, etc.)
+ *   - routeKey, localRouteName: Route identifiers
+ *
+ * Handler Context:
+ *   - handlerContext: Context passed to loaders
+ *   - loaderPromises: Memoized loader promises
+ *
+ * Intercepts:
+ *   - interceptResult: Detected intercept (if soft navigation)
+ *   - interceptSelectorContext: Context for intercept matching
+ *
+ * Cache:
+ *   - cacheScope: Cache configuration and methods
+ *   - isIntercept: Whether this is an intercept request
+ *
+ * Flags:
+ *   - isAction: POST/mutation request
+ *   - isFullMatch: Document request vs navigation
+ *
+ *
+ * MATCHPIPELINESTATE FIELDS
+ * =========================
+ *
+ * State flags (set by middleware, read by others):
+ *   - cacheHit: Cache lookup succeeded
+ *   - shouldRevalidate: SWR revalidation needed
+ *
+ * Segment accumulation:
+ *   - segments: Resolved segments from pipeline
+ *   - matchedIds: All segment IDs in match order
+ *   - cachedSegments: Segments from cache (if hit)
+ *
+ * Intercept data:
+ *   - interceptSegments: Segments for modal slots
+ *   - slots: Named slot data for client
+ *
+ *
+ * IMMUTABILITY CONTRACT
+ * =====================
+ *
+ * MatchContext is treated as immutable after creation.
+ * Middleware should NEVER modify ctx properties.
+ *
+ * MatchPipelineState is explicitly mutable.
+ * Middleware communicate by setting state flags.
+ *
+ * This separation ensures:
+ *   - Request data is consistent across all middleware
+ *   - Pipeline state changes are explicit and trackable
+ *   - No hidden side effects in request handling
+ */
+import type { CacheScope } from "../cache/cache-scope.js";
+import type { EntryData, InterceptSelectorContext, MetricsStore } from "../server/context.js";
+import type { HandlerContext, ResolvedSegment } from "../types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { InterceptResult } from "./router-context.js";
+/**
+ * Action context passed to matchPartial
+ */
+export interface ActionContext {
+    actionId?: string;
+    actionUrl?: URL;
+    actionResult?: any;
+    formData?: FormData;
+}
+/**
+ * Match context containing all state for the match pipeline
+ */
+export interface MatchContext<TEnv = any> {
+    request: Request;
+    url: URL;
+    pathname: string;
+    env: TEnv;
+    clientSegmentIds: string[];
+    clientSegmentSet: Set<string>;
+    stale: boolean;
+    prevUrl: URL;
+    prevParams: Record<string, string>;
+    prevMatch: RouteMatchResult | null;
+    matched: RouteMatchResult;
+    manifestEntry: EntryData;
+    entries: EntryData[];
+    routeKey: string;
+    localRouteName: string;
+    handlerContext: HandlerContext<any, TEnv>;
+    loaderPromises: Map<string, Promise<any>>;
+    routeMap: Record<string, string>;
+    metricsStore: MetricsStore | undefined;
+    Store: any;
+    interceptContextMatch: RouteMatchResult | null;
+    interceptSelectorContext: InterceptSelectorContext;
+    isSameRouteNavigation: boolean;
+    interceptResult: InterceptResult | null;
+    cacheScope: CacheScope | null;
+    isIntercept: boolean;
+    actionContext?: ActionContext;
+    isAction: boolean;
+    routeMiddleware: Array<{
+        handler: any;
+        params: Record<string, string>;
+    }>;
+    isFullMatch: boolean;
+}
+/**
+ * Mutable state that flows through the pipeline
+ */
+export interface MatchPipelineState {
+    cacheHit: boolean;
+    cachedSegments?: ResolvedSegment[];
+    cachedMatchedIds?: string[];
+    shouldRevalidate?: boolean;
+    cacheSource?: "runtime" | "prerender";
+    segments: ResolvedSegment[];
+    matchedIds: string[];
+    interceptSegments: ResolvedSegment[];
+    slots: Record<string, {
+        active: boolean;
+        segments: ResolvedSegment[];
+    }>;
+}
+/**
+ * Create initial pipeline state
+ */
+export declare function createPipelineState(): MatchPipelineState;

package/dist/types/router/match-handlers.d.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+import type { ErrorBoundaryHandler, ErrorInfo, ErrorPhase, MatchResult } from "../types";
+import { type EntryData, type InterceptEntry, type InterceptSelectorContext } from "../server/context.js";
+import type { MatchApiDeps } from "./types.js";
+import type { RouterContext } from "./router-context.js";
+import { type ActionContext } from "./match-context.js";
+import type { MiddlewareFn } from "./middleware.js";
+import { type TelemetrySink } from "./telemetry.js";
+export interface MatchHandlerDeps<TEnv = any> {
+    buildRouterContext: () => RouterContext<TEnv>;
+    callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+    matchApiDeps: MatchApiDeps<TEnv>;
+    defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
+    findMatch: (pathname: string, ms?: any) => any;
+    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean) => {
+        intercept: InterceptEntry;
+        entry: EntryData;
+    } | null;
+    telemetry?: TelemetrySink;
+    /**
+     * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
+     * match/matchPartial stash a coarse route-level cache signal on the request
+     * context for the response-finalization path to emit. Default off.
+     */
+    cacheSignalEnabled?: boolean;
+}
+export interface MatchHandlers<TEnv = any> {
+    match: (request: Request, env: TEnv) => Promise<MatchResult>;
+    matchPartial: (request: Request, context: TEnv, actionContext?: ActionContext) => Promise<MatchResult | null>;
+    matchError: (request: Request, _context: TEnv, error: unknown, segmentType?: ErrorInfo["segmentType"]) => Promise<MatchResult | null>;
+    previewMatch: (request: Request, _context: TEnv) => Promise<{
+        routeMiddleware?: Array<{
+            handler: MiddlewareFn;
+            params: Record<string, string>;
+        }>;
+        responseType?: string;
+        handler?: Function;
+        params?: Record<string, string>;
+        negotiated?: boolean;
+        manifestEntry?: EntryData;
+    } | null>;
+}
+/**
+ * Create match handler functions bound to router closure state.
+ * These are the main request-handling entry points for SSR, navigation,
+ * error recovery, and preview matching.
+ */
+export declare function createMatchHandlers<TEnv = any>(deps: MatchHandlerDeps<TEnv>): MatchHandlers<TEnv>;

package/dist/types/router/match-middleware/background-revalidation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Background Revalidation Middleware
+ *
+ * Implements SWR (stale-while-revalidate) pattern.
+ * Triggers background refresh when cached data is stale.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from cache-store)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | yield* source            |  Pure pass-through
+ *   | (no modifications)       |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Should revalidate?  |
+ *   | - shouldRevalidate  |──no───> return
+ *   | - cacheHit          |
+ *   | - cacheScope        |
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +---------------------------+
+ *   | requestCtx.waitUntil()   |  Non-blocking background task
+ *   +---------------------------+
+ *         |
+ *         v (async, doesn't block response)
+ *   +---------------------------+
+ *   | Create fresh context     |  Fresh handleStore, handlerContext,
+ *   | (full isolation)         |  and loaderPromises map
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | + resolveIntercepts()   |  Ensures complete components
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | cacheScope.cacheRoute()  |  Update cache with fresh data
+ *   +---------------------------+
+ *
+ *
+ * SWR PATTERN
+ * ===========
+ *
+ * Stale-While-Revalidate provides fast responses with eventual consistency:
+ *
+ *   Timeline:
+ *   ---------
+ *   T0: Request arrives
+ *   T1: Cache lookup finds stale entry
+ *   T2: Return stale data immediately (fast!)
+ *   T3: Response sent to client
+ *   T4: waitUntil() triggers background revalidation
+ *   T5: Fresh data resolved
+ *   T6: Cache updated with fresh data
+ *   T7: Next request gets fresh data from cache
+ *
+ * Benefits:
+ *   - Fast initial response (cached data)
+ *   - Eventually consistent (background refresh)
+ *   - No blocking on revalidation
+ *
+ *
+ * WHEN IS CACHE STALE?
+ * ====================
+ *
+ * The cache-lookup middleware sets state.shouldRevalidate based on:
+ *   - TTL (time-to-live) expiration
+ *   - Cache entry metadata
+ *   - Configured staleness rules
+ *
+ * This middleware only acts on the flag, it doesn't determine staleness.
+ *
+ *
+ * ISOLATION FROM RESPONSE
+ * =======================
+ *
+ * Background revalidation creates fully isolated context:
+ *   - Fresh handleStore (prevents polluting the response stream)
+ *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
+ *     loader results from the foreground pass)
+ *   - handleStore is saved/restored in try/finally
+ *
+ * This matches the proactive caching pattern in cache-store.ts.
+ *
+ *
+ * FRESH RESOLUTION (NO REVALIDATION)
+ * ===================================
+ *
+ * Both full and partial requests use resolveAllSegments() (without
+ * revalidation logic) to ensure all segments have complete components.
+ * Using revalidation-aware resolution would produce null components
+ * for skipped segments, which would corrupt the cache entry.
+ */
+import type { ResolvedSegment } from "../../types.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import type { GeneratorMiddleware } from "./cache-lookup.js";
+/**
+ * Creates background revalidation middleware
+ *
+ * If cache was stale (state.shouldRevalidate === true):
+ * - Triggers background resolution via waitUntil
+ * - Observes segments but doesn't modify them
+ * - Updates cache with fresh segments after revalidation completes
+ */
+export declare function withBackgroundRevalidation<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;