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

package/dist/types.backup/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.backup/router/loader-resolution.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 } 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.
+ *
+ * @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): 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.backup/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.backup/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.backup/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.backup/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.backup/router/match-handlers.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
+import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type { MatchApiDeps } from "./types.js";
+import type { RouterContext } from "./router-context.js";
+import { type ActionContext } from "./match-context.js";
+import type { ErrorBoundaryHandler } from "../types";
+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.backup/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>;

package/dist/types.backup/router/match-middleware/cache-lookup.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Cache Lookup Middleware
+ *
+ * First middleware in the pipeline. Checks cache before segment resolution.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (empty)
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Is action request?  |──yes──> yield* source (pass through)
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +---------------------+
+ *   | Cache enabled?      |──no───> yield* source (pass through)
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +---------------------+
+ *   | Lookup cache        |
+ *   | (pathname, params)  |
+ *   +---------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  miss        hit
+ *   |           |
+ *   v           v
+ * yield*    Set state.cacheHit = true
+ * source    Set state.shouldRevalidate
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | For each cached segment:  |
+ *   |    |  - Apply revalidation     |
+ *   |    |  - Set component = null   |
+ *   |    |    if client has it       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | Resolve fresh loaders     |  <-- Loaders are NEVER cached
+ *   |    | (always fresh data)       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    yield cached segments
+ *   |    yield fresh loader segments
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * CACHE BEHAVIOR
+ * ==============
+ *
+ * Cache HIT:
+ *   - state.cacheHit = true signals downstream middleware to skip
+ *   - Cached segments have their components nullified if client already has them
+ *   - Loaders are always re-resolved for fresh data
+ *   - state.shouldRevalidate triggers background SWR if cache was stale
+ *
+ * Cache MISS:
+ *   - Passes through to segment-resolution middleware
+ *   - No segments yielded from this middleware
+ *
+ * Loaders:
+ *   - NEVER cached in the segment cache
+ *   - Always resolved fresh on every request
+ *   - Ensures data freshness even with cached UI components
+ *   - Segment cache staleness does NOT propagate to loader revalidation;
+ *     loaders use their own revalidation rules (actionId, user-defined)
+ *
+ *
+ * REVALIDATION RULES
+ * ==================
+ *
+ * Each cached segment is evaluated against its revalidation rules:
+ *
+ *   1. No rules defined -> use default (skip if client has segment)
+ *   2. Rules return false -> skip re-render (nullify component)
+ *   3. Rules return true -> re-render (keep component)
+ *
+ * Revalidation context includes:
+ *   - Previous/next URL and params
+ *   - Request object
+ *   - Action context (if POST)
+ */
+import type { ResolvedSegment } from "../../types.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+/**
+ * Async generator middleware type
+ */
+export type GeneratorMiddleware<T> = (source: AsyncGenerator<T>) => AsyncGenerator<T>;
+/**
+ * Creates cache lookup middleware
+ *
+ * Checks cache for segments. If cache hit:
+ * - Applies revalidation to determine which segments need re-rendering
+ * - Resolves loaders fresh (loaders are NOT cached by design)
+ * - Sets state.cacheHit = true
+ * - Sets state.shouldRevalidate if SWR needed
+ * - Yields cached segments + fresh loader segments
+ *
+ * If cache miss:
+ * - Passes through to next middleware
+ */
+export declare function withCacheLookup<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;