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

package/dist/types/server/request-context.d.ts

@@ -0,0 +1,707 @@
+/**
+ * Request Context - AsyncLocalStorage for passing request-scoped data throughout rendering
+ *
+ * This is the unified context used everywhere:
+ * - Middleware execution
+ * - Route handlers and loaders
+ * - Server components during rendering
+ * - Error boundaries and streaming
+ *
+ * Available via getRequestContext() anywhere in the request lifecycle.
+ */
+import { parseCookiesFromHeader } from "./cookie-parse.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
+import type { CookieOptions } from "../router/middleware.js";
+import type { LoaderDefinition } from "../types.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type { DefaultEnv, DefaultReverseRouteMap, DefaultRouteName } from "../types/global-namespace.js";
+import type { Handle } from "../handle.js";
+import { type ContextVar } from "../context-var.js";
+import { type HandleStore, type HandleData } from "./handle-store.js";
+import { type MetricsStore } from "./context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import type { TransitionWhenFn } from "../types/segments.js";
+import type { ResolvedTracing } from "../router/tracing.js";
+import type { RenderMode, RenderPhase } from "../router/timeout.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RoutineTrace } from "../rsc/routine-plan.js";
+export interface RenderForegroundCursor {
+    mode: RenderMode;
+    phase: RenderPhase;
+    state: "paused" | "running";
+    completed: number;
+    total: number;
+    pipelineStartedAt: number;
+    phaseStartedAt?: number;
+    routeKey?: string;
+    actionId?: string;
+}
+/**
+ * Unified request context available via getRequestContext()
+ *
+ * This is the same context passed to middleware and handlers.
+ * Use this when you need access to request data outside of route handlers.
+ */
+export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> extends RequestScope<TEnv> {
+    /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+    _variables: Record<string, any>;
+    /** Get a variable set by middleware */
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        <K extends string>(key: K): any;
+    };
+    /** Set a variable (shared with middleware and handlers) */
+    set: {
+        <T>(contextVar: ContextVar<T>, value: T, options?: {
+            cache?: boolean;
+        }): void;
+        <K extends string>(key: K, value: any, options?: {
+            cache?: boolean;
+        }): void;
+    };
+    /**
+     * Route params (populated after route matching)
+     * Initially empty, then set to matched params
+     */
+    params: TParams;
+    /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
+    readonly res: Response;
+    /**
+     * True for build-time render/capture requests. Live requests use false.
+     * Build-time shell capture sets this while replaying middleware so apps can
+     * skip side-effectful runtime work.
+     */
+    readonly build: boolean;
+    /**
+     * Opt this request out of PPR shell serving/capture.
+     * Runtime middleware can call this before the PPR commit point; handlers can
+     * call it on a MISS to prevent the follow-up capture.
+     *
+     * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+     * (Prerender/Static) serving, and it is inert in the prerender-collect /
+     * static-render contexts (no live shell decision to influence there).
+     */
+    dynamic(): void;
+    /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
+    _dynamic?: boolean;
+    /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
+    cookie(name: string): string | undefined;
+    /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
+    cookies(): Record<string, string>;
+    /** @internal Set a cookie on the response. Use cookies().set() instead. */
+    setCookie(name: string, value: string, options?: CookieOptions): void;
+    /** @internal Delete a cookie. Use cookies().delete() instead. */
+    deleteCookie(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+    /** Set a response header */
+    header(name: string, value: string): void;
+    /** Set the response status code */
+    setStatus(status: number): void;
+    /** @internal Set status bypassing cache-exec guard (for framework error handling) */
+    _setStatus(status: number): void;
+    /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
+    _rotateStateCookie(): void;
+    /** @internal Set the keepClientCache() directive header on the response. */
+    _setKeepCacheDirective(): void;
+    /**
+     * Access loader data or push handle data.
+     *
+     * For loaders: Returns a promise that resolves to the loader data.
+     * Loaders are executed in parallel and memoized per request.
+     *
+     * For handles: Returns a push function to add data for this segment.
+     * Handle data accumulates across all matched route segments.
+     *
+     * @example
+     * ```typescript
+     * // Loader usage
+     * const cart = await ctx.use(CartLoader);
+     *
+     * // Handle usage
+     * const push = ctx.use(Breadcrumbs);
+     * push({ label: "Shop", href: "/shop" });
+     * ```
+     */
+    use: {
+        <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+    };
+    /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
+    method: string;
+    /** @internal Handle store for tracking handle data across segments */
+    _handleStore: HandleStore;
+    /**
+     * @internal transition({ when }) predicates for segments matched this request,
+     * keyed by segment id. Collected during resolution (the function is stripped
+     * from the serialized segment config), then evaluated post-handler in
+     * rsc-rendering — outside any cache scope — to drop the transition of any
+     * segment whose predicate returns false.
+     */
+    _transitionWhen?: Array<{
+        id: string;
+        when: TransitionWhenFn;
+    }>;
+    /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+    _pprTransitionDecisions?: Map<string, boolean>;
+    /**
+     * @internal Post-match serve-source truth for the PPR replay reporter.
+     * Stamped from the match context as `intercept`, then overwritten as
+     * `prerender-store` if that lookup actually serves. The latter wins because
+     * it identifies the response source. matchPartialWithPprReplay reads this
+     * AFTER matching to reclassify its pre-match guess and suppress pointless
+     * heal captures.
+     */
+    _pprReplayPostMatchReason?: "prerender-store" | "intercept";
+    /** @internal Cache store for segment caching (optional, used by CacheScope) */
+    _cacheStore?: SegmentCacheStore;
+    /**
+     * @internal Compiled `cache.searchParams` filter for default cache-key
+     * generation (undefined = "all", the byte-stable unfiltered format). Set
+     * once per request by handler.ts; every URL-keyed tier (segment, document,
+     * response, shell, "use cache") reads it so the tiers cannot drift.
+     */
+    _searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
+    /**
+     * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
+     * capture task's derived request context (built by shell-capture.ts). This is
+     * the switch every capture-specific behavior reads: loader masking
+     * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
+     * cookies()/headers() capture guard (cookie-store.ts
+     * assertNotInsideShellCapture). The foreground render never sets it, so the
+     * served response is byte-identical to axis 1. The capture descriptor itself
+     * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+     * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+     * locally and passes it to scheduleShellCapture directly.
+     */
+    _shellCaptureRun?: boolean;
+    /**
+     * @internal Bake-lane loader containers collected DURING a shell capture:
+     * segment-key -> the loader's (pre-wrap) result promise. Populated by
+     * resolveLoaderData for loaders on entries with no renderable loading() (the
+     * bake lane — they execute at capture instead of being masked; see
+     * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
+     * after the shell quiesces: settled containers are promise-elided,
+     * Flight-serialized, and pinned into the snapshot's loader family; a
+     * REJECTED container refuses the capture (error UI must never bake into the
+     * shared shell). Own property of the capture's derived context only.
+     */
+    _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+    /**
+     * @internal Loader-family snapshot seed for a shell HIT's tail render:
+     * segment-key -> the capture's elided container (already Flight-deserialized
+     * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
+     * overlays it onto the fresh run's container (recorded paths pinned,
+     * hole-marker paths keep the fresh nested promises) so the payload's baked
+     * bytes match the frozen prelude; a hole-free entry resolves pin-first
+     * without gating on the fresh run. Own property of the HIT tail's derived
+     * context only.
+     */
+    _shellLoaderSeed?: Map<string, import("../cache/shell-snapshot.js").ShellLoaderSeedEntry>;
+    /**
+     * @internal Shell fast-path marker: makes the next eligible match treat the
+     * whole matched route as an implicit doc-level cache() boundary (see
+     * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
+     * (a) the capture's derived context — with a record-only store so the
+     * capture's cacheRoute write lands in the snapshot, never the real store —
+     * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
+     * replay, where `store` is a request-local segment overlay. Handler-live holes
+     * and conditional transitions decline replay.
+     * Routes with their own cache() config are never overridden — their scope's
+     * store/key/ttl/swr/condition semantics stay authoritative. On the
+     * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
+     * such a scope instead of being ignored: the seeded doc record supplies the match
+     * only when the explicit tier misses (withCacheLookup). cache(false) and a
+     * false condition() stay absolute opt-outs — replay bypasses before any
+     * shell read (`cache-disabled`).
+     */
+    _shellImplicitCache?: {
+        ttl?: number;
+        swr?: number;
+        store?: SegmentCacheStore;
+        /**
+         * @internal Override the implicit scope's default cache namespace. Shell
+         * captures and navigation replay both consume the canonical document
+         * segment record even when the triggering request is partial.
+         */
+        keyPrefix?: "doc";
+        /** @internal Called only after the implicit cache hit decodes successfully. */
+        onHit?: () => void;
+        /**
+         * @internal Called when the seeded document record fails server-side
+         * deserialization. Partial replay uses it to replace the enclosing shell
+         * snapshot after serving the fresh fallback.
+         */
+        onCorrupt?: () => void;
+        /**
+         * @internal The resolved key of the canonical document segment record.
+         * Written during a CAPTURE render by CacheScope.cacheRoute when a
+         * doc-namespaced scope records the matched segments; captureAndStoreShell
+         * stamps it onto the ShellCacheEntry (`docKey`) so replay eligibility can
+         * require the exact consumable record instead of "any segment record".
+         */
+        docKey?: string;
+        /**
+         * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
+         * serve path. Its presence arms the explicit-scope composition in
+         * withCacheLookup: a route-derived cache() scope stays authoritative, and
+         * only when its lookup MISSes does the seeded doc record supply the match.
+         * A capture render must never set this (its match must re-run handlers so
+         * SWR recapture stays fresh), which is why the fallback keys off this
+         * field and not off the marker itself. Fired when the route-derived
+         * scope's own lookup supplied the match — the header then reports
+         * `BYPASS; reason=explicit-cache-hit`, never a false replay HIT.
+         */
+        onExplicitHit?: () => void;
+        /**
+         * @internal Companion to onExplicitHit, same lifecycle: fired when the
+         * route-derived scope's lookup REFUSED the read (`bypass` outcome — a
+         * false condition() or no store). The gate only pre-decides the static
+         * cache(false) case; a predicate refusal is known only at lookup time and
+         * reports `BYPASS; reason=cache-disabled` post-match.
+         */
+        onExplicitBypass?: () => void;
+    };
+    /**
+     * @internal Fragment-passthrough marker: cache/prerender-store hits during
+     * THIS render emit stored segment fragments VERBATIM into the payload
+     * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
+     * per request; the payload consumers (SSR resume, browser hydration, and
+     * the client partial-navigation decode chokepoints) expand them
+     * (segment-fragments.ts, issue #700). Partial requests arm only after the
+     * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+     * retries without it so CacheScope can evict the bad record. Two arming sites,
+     * both scoped to a
+     * render/match window: serveShellHit's derived tail context (document
+     * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+     * match (matchPartialForReplay). It must never be visible to a capture
+     * render: the capture SSR-prerenders the payload AND serializes segments
+     * into records (cacheRoute), and an envelope reaching serializeSegments
+     * would store a double-encoded fragment — deriveShellCaptureContext resets
+     * it as an own property for exactly that reason.
+     */
+    _shellFragmentPayload?: boolean;
+    /**
+     * @internal Handler-layer liveness observed DURING a shell capture, from
+     * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
+     * when a push made OUTSIDE a DSL loader scope carries a nested thenable
+     * (masked to a never-filling hole); (b) still-pending top-level handler
+     * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
+     * executing during the capture (loader-resolution.ts — its consumption-lane
+     * value would freeze on a handler-free HIT). captureAndStoreShell folds it
+     * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
+     * property of the capture's derived context only.
+     */
+    _shellCaptureHandleLiveness?: {
+        holes: boolean;
+        pendingPushes: number;
+        handlerInvokedLoader: boolean;
+    };
+    /**
+     * @internal Handle values pushed from a DSL loader scope DURING a shell
+     * capture (identity set; populated by the capture push wrapper in
+     * shell-capture.ts). cacheRoute threads it into captureHandles so those
+     * values stay out of cache-write handle records — loaders re-run fresh on
+     * every HIT, so replaying their captured (masked) values would duplicate
+     * the fresh push and stall the Flight handle encode. Own property of the
+     * capture's derived context only; render-time handle consumers are
+     * unaffected (the exclusion applies only at the captureHandles call site).
+     */
+    _shellCaptureLoaderHandleValues?: WeakSet<object>;
+    /**
+     * @internal Set (to the offending fn name) by the cookies()/headers()
+     * capture guard when it throws DURING a capture render. Load-bearing for the
+     * bake lane: a guard throw inside an executing loader is swallowed by
+     * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+     * silently into the shared shell — the capture checks this flag after the
+     * render and refuses instead. Deterministic, so the capture does not retry.
+     */
+    _shellCaptureGuardTripped?: string;
+    /**
+     * @internal The loader $$id whose BODY was executing when the capture guard
+     * tripped (read off the loader-body ALS scope at trip time), or undefined
+     * when the read came from handler/render code. Only used to make the
+     * once-per-key refusal warning name the real source — the old text
+     * hardcoded "a bake-lane loader", which misattributed handler-land reads
+     * and sent users debugging the wrong lane (issue #672, secondary).
+     */
+    _shellCaptureGuardTrippedLoaderId?: string;
+    /**
+     * @internal Handler-owned registry of explicit per-scope stores from
+     * cache({ store }). Created once per createRSCHandler() and threaded into
+     * every request context, so it accumulates every explicit store the handler
+     * resolves. updateTag()/revalidateTag() iterate this set plus _cacheStore to
+     * reach every store that may hold tagged entries. The app-level store is not
+     * added here (it is always reachable via _cacheStore).
+     */
+    _explicitTaggedStores?: Set<SegmentCacheStore>;
+    /**
+     * @internal Union of every cache tag resolved while producing this request's
+     * response (from cache({ tags }), runtime cacheTag(), and loader cache tags).
+     * Populated at the tag-resolution sites via recordRequestTags(). Read by the
+     * document cache middleware so a full-page entry is tagged with everything its
+     * content used and can therefore be invalidated by updateTag()/revalidateTag().
+     */
+    _requestTags: Set<string>;
+    /** @internal Cache profiles for "use cache" profile resolution (per-router) */
+    _cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
+    /**
+     * Register a callback to run when the response is created.
+     * Callbacks are sync and receive the response. They can:
+     * - Inspect response status/headers
+     * - Return a modified response
+     * - Schedule async work via waitUntil
+     *
+     * @example
+     * ```typescript
+     * ctx.onResponse((res) => {
+     *   if (res.status === 200) {
+     *     ctx.waitUntil(async () => await cacheIt());
+     *   }
+     *   return res;
+     * });
+     * ```
+     */
+    onResponse(callback: (response: Response) => Response): void;
+    /** @internal Registered onResponse callbacks */
+    _onResponseCallbacks: Array<(response: Response) => Response>;
+    /**
+     * @internal Promises of the background tasks scheduled via this context's
+     * waitUntil (deferred cache writes, revalidations, consumer tasks). The PPR
+     * shell capture drains this list BEFORE its match/render as an ORDERING EDGE:
+     * every foreground deferred cache write is scheduled here before the capture
+     * task is, so settling the list first guarantees the capture's cache reads
+     * observe the foreground's generation instead of racing it (see
+     * shell-capture.ts). Tasks whose scheduling fn carries
+     * UNTRACKED_BACKGROUND_TASK are not tracked (the capture task itself —
+     * tracking it would make that drain await its own promise).
+     */
+    _pendingBackgroundTasks?: Array<Promise<unknown>>;
+    /**
+     * Current theme setting (only available when theme is enabled in router config)
+     *
+     * Returns the theme value from the cookie, or the default theme if not set.
+     * This is the user's preference ("light", "dark", or "system"), not the resolved value.
+     *
+     * @example
+     * ```typescript
+     * route("settings", (ctx) => {
+     *   const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
+     *   return <SettingsPage theme={currentTheme} />;
+     * });
+     * ```
+     */
+    theme?: Theme;
+    /**
+     * Set the theme (only available when theme is enabled in router config)
+     *
+     * Sets a cookie with the new theme value. The change takes effect on the next request.
+     *
+     * @example
+     * ```typescript
+     * route("settings", (ctx) => {
+     *   if (ctx.method === "POST") {
+     *     const formData = await ctx.request.formData();
+     *     const newTheme = formData.get("theme") as Theme;
+     *     ctx.setTheme(newTheme);
+     *   }
+     *   return <SettingsPage />;
+     * });
+     * ```
+     */
+    setTheme?: (theme: Theme) => void;
+    /** @internal Theme configuration (null if theme not enabled) */
+    _themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * Attach location state entries to the current response.
+     *
+     * For partial (SPA) requests, the state is included in the RSC payload
+     * metadata and merged into history.pushState on the client. For redirect
+     * responses, the state travels through the redirect payload so the target
+     * page can read it via useLocationState.
+     *
+     * Multiple calls accumulate entries.
+     *
+     * @example
+     * ```typescript
+     * ctx.setLocationState(Flash({ text: "Item saved!" }));
+     * ```
+     */
+    setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+    /** @internal Accumulated location state entries */
+    _locationState?: LocationStateEntry[];
+    /**
+     * The matched route name, if the route has an explicit name.
+     * Undefined before route matching or for unnamed routes.
+     * Includes the namespace prefix from include() (e.g., "blog.post").
+     */
+    routeName?: DefaultRouteName;
+    /**
+     * Generate URLs from route names.
+     * Uses the global route map. After route matching, scoped (`.name`) resolution
+     * works within the matched include() scope.
+     */
+    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+    /** @internal Route name from route matching, used for scoped reverse resolution */
+    _routeName?: string;
+    /** @internal Previous route key (from the navigation source), used for revalidation */
+    _prevRouteKey?: string;
+    /**
+     * @internal Navigation/action source data the transition({ when }) gate reads
+     * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
+     * come from the navigation snapshot (set at match time); action* are stashed
+     * at the action-bearing gate call sites. All undefined when there is no source
+     * (initial full load) or no action (plain navigation).
+     */
+    _gateCurrentUrl?: URL;
+    _gateCurrentParams?: Record<string, string>;
+    _gateActionId?: string;
+    _gateActionUrl?: URL;
+    _gateActionResult?: unknown;
+    _gateFormData?: FormData;
+    /**
+     * @internal True while the post-action revalidation render is running (set by
+     * revalidateAfterAction). The "use cache" runtime reads this to prefer
+     * freshness over a fast stale response during an action: a stale entry
+     * re-executes in the foreground (so the action response reflects the refreshed
+     * value) with only the store write deferred, instead of serving stale and
+     * revalidating in the background. A plain navigation (flag unset) keeps SWR.
+     */
+    _inActionRevalidation?: boolean;
+    /**
+     * @internal Render barrier for experimental `rendered()` API.
+     * Resolves when all non-loader segments have settled and handle data
+     * is available. Used by DSL loaders that call `ctx.rendered()`.
+     */
+    _renderBarrier: Promise<void>;
+    /**
+     * @internal Resolve the render barrier. Accepts resolved segments, filters
+     * out loaders, and captures non-loader segment IDs as the handle ordering.
+     * Called after segment resolution (fresh) or handle replay (cache/prerender).
+     */
+    _resolveRenderBarrier: (segments: Array<{
+        type: string;
+        id: string;
+    }>) => void;
+    /**
+     * @internal Segment order at barrier resolution time, used by loader
+     * ctx.use(handle) to collect handle data in correct order.
+     */
+    _renderBarrierSegmentOrder?: string[];
+    /**
+     * @internal Set to true when the matched entry tree contains any `loading()`
+     * entries (streaming). On a streaming tree rendered() waits for the streaming
+     * handlers to settle (via handleStore.settled) before resolving, and the
+     * deadlock guard state is kept live until that wait completes.
+     */
+    _treeHasStreaming?: boolean;
+    /**
+     * @internal Loader IDs that have called rendered() and are waiting for the
+     * barrier. Used to detect deadlocks when a handler tries to await the same
+     * loader via ctx.use(Loader).
+     */
+    _renderBarrierWaiters?: Set<string>;
+    /**
+     * @internal Loader IDs that handlers have started awaiting via ctx.use().
+     * Used for bidirectional deadlock detection: if a loader later calls
+     * rendered() and a handler already awaits it, we can detect the deadlock.
+     */
+    _handlerLoaderDeps?: Set<string>;
+    /**
+     * @internal Cached HandleData snapshot built at barrier resolution time.
+     * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+     */
+    _renderBarrierHandleSnapshot?: HandleData;
+    /**
+     * @internal The deadlock guard window is closed (no further handler-awaits-
+     * loader cycle is possible). For non-streaming trees this is set when the
+     * barrier resolves. For streaming trees the window stays open until
+     * handleStore.settled — rendered() keeps waiting past the barrier and a
+     * loading() handler can still resume and await a still-waiting loader — so it
+     * is set only after settled. The guard (loader-resolution `setupLoaderAccess`)
+     * reads this instead of `_renderBarrierSegmentOrder` so it does not go blind
+     * during the streaming settle wait.
+     */
+    _renderBarrierGuardClosed?: boolean;
+    /** @internal Per-request error dedup set for onError reporting */
+    _reportedErrors: WeakSet<object>;
+    /**
+     * @internal Report a non-fatal background error through the router's
+     * onError callback. Wired by the RSC handler / router during request
+     * creation. Cache-runtime and other subsystems call this to surface
+     * errors without failing the response. `category` is surfaced to consumers as
+     * `metadata.category` on the onError context (phase `cache`).
+     */
+    _reportBackgroundError?: (error: unknown, category: CacheErrorCategory) => void;
+    /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
+    _debugPerformance?: boolean;
+    /** @internal Request-scoped performance metrics store */
+    _metricsStore?: MetricsStore;
+    /**
+     * @internal Foreground response-construction cursor. It reports only the
+     * generator driver's current Flight/HTML/response operation; concurrent
+     * loaders and post-commit stream work have separate lifetimes.
+     */
+    _renderForeground?: RenderForegroundCursor;
+    /** @internal Request routine currently executing, used by timeout diagnostics. */
+    _activeRoutine?: RoutineTrace;
+    /** @internal Keep the render cursor active for timeout support. */
+    _renderDiagnosticsEnabled?: boolean;
+    /**
+     * @internal True request entry timestamp (performance.now() at handler entry).
+     * Set once at request-context creation (rsc/handler.ts) so a metrics store
+     * created MID-request — ctx.debugPerformance() or the getMetricsStore wrapper —
+     * anchors its timeline to the real request start instead of the opt-in moment,
+     * keeping phases that began before the opt-in at their true (non-negative) offset.
+     */
+    _handlerStart?: number;
+    /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
+    _tracing?: ResolvedTracing;
+    /** @internal Router basename for this request (used by redirect()) */
+    _basename?: string;
+    /** @internal Owning router id; scopes the search-schema/root-scope registry
+     *  lookups per router (route-map-builder.ts) */
+    _routerId?: string;
+    /**
+     * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
+     * to avoid a second resolveRoute call. Cleared on HMR invalidation.
+     */
+    _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+    /**
+     * @internal Classified request mode from classifyRequest, read by the
+     * rango.response span tail (rsc/handler.ts) for the rango.response.mode
+     * attribute. Unset when middleware short-circuits before core execution.
+     */
+    _requestMode?: import("../router/request-classification.js").RequestPlan["mode"];
+    /**
+     * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+     * header. Populated by match/matchPartial only when the debug cache signal
+     * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+     * the response-finalization path (createResponseWithMergedHeaders). Undefined
+     * when the gate is off, so no header is emitted.
+     */
+    _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
+}
+/**
+ * Public view of RequestContext, without internal methods and fields.
+ *
+ * This is the type exported to library consumers. Internal code should
+ * use the full RequestContext interface directly.
+ */
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+/**
+ * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
+ * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
+ * the capture's pre-render write barrier settles that list, so tracking the
+ * capture itself would make the drain wait on its own (still-running) promise.
+ * @internal
+ */
+export declare const UNTRACKED_BACKGROUND_TASK: unique symbol;
+/**
+ * Run a function within a request context
+ * Used by the RSC handler to provide context to server actions
+ */
+export declare function runWithRequestContext<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/**
+ * Get the current request context
+ * Throws if called outside of a request context
+ */
+export declare function getRequestContext<TEnv = DefaultEnv>(): RequestContext<TEnv>;
+/**
+ * @internal Get the request context without throwing — for internal code that
+ * may run outside a request context (cache stores, optional handle lookups, etc.)
+ */
+export declare function _getRequestContext<TEnv = DefaultEnv>(): RequestContext<TEnv> | undefined;
+/**
+ * Update params on the current request context
+ * Called after route matching to populate route params and route name
+ */
+export declare function setRequestContextParams(params: Record<string, string>, routeName?: string, routeMap?: Record<string, string>): void;
+/**
+ * Store the previous route key on the request context.
+ * Called during partial-match context creation to make the navigation source
+ * route key available for revalidation and intercept evaluation.
+ * @internal
+ */
+export declare function setRequestContextPrevRouteKey(prevRouteKey: string | undefined, currentUrl?: URL, currentParams?: Record<string, string>): void;
+/**
+ * Get accumulated location state entries from the current request context.
+ * Returns undefined if no state has been set.
+ *
+ * @internal Used by the RSC handler to include state in payload metadata.
+ */
+export declare function getLocationState(): LocationStateEntry[] | undefined;
+export type { ExecutionContext };
+/**
+ * Options for creating a request context
+ */
+export interface CreateRequestContextOptions<TEnv> {
+    env: TEnv;
+    request: Request;
+    url: URL;
+    variables: Record<string, any>;
+    /** Optional initial response stub headers/status to seed effective cookie reads */
+    initialResponse?: Response;
+    /** Optional cache store for segment caching (used by CacheScope) */
+    cacheStore?: SegmentCacheStore;
+    /**
+     * Compiled `cache.searchParams` filter from the resolved handler cache
+     * config (handler.ts). Stored as _searchParamsFilter.
+     */
+    searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
+    /**
+     * Handler-owned registry of explicit per-scope stores for cross-store tag
+     * invalidation. Created once per handler, reused across requests.
+     */
+    explicitTaggedStores?: Set<SegmentCacheStore>;
+    /** Optional cache profiles for "use cache" resolution (per-router) */
+    cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
+    /** Optional Cloudflare execution context for waitUntil support */
+    executionContext?: ExecutionContext;
+    /** Build-time render/capture request marker. Defaults to false. */
+    build?: boolean;
+    /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
+    themeConfig?: ResolvedThemeConfig | null;
+    /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
+    stateCookieName?: string;
+    /** Build version, used as the prefix of a server-rotated rango state value. */
+    version?: string;
+}
+/**
+ * Create a full request context with all methods implemented
+ *
+ * This is used by the RSC handler to create the unified context that's:
+ * - Available via getRequestContext() throughout the request
+ * - Passed to middleware as ctx
+ * - Passed to handlers as ctx
+ */
+export declare function createRequestContext<TEnv>(options: CreateRequestContextOptions<TEnv>): RequestContext<TEnv>;
+/**
+ * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
+ * handle store. Called by createRequestContext for every fresh context, and by
+ * deriveShellCaptureContext (rsc/shell-capture.ts) for the PPR capture's
+ * derived context.
+ *
+ * The derived-context call is load-bearing (issue #684, plan 009): the capture
+ * context is `Object.create(reqCtx)`, so without its own wiring every
+ * `_renderBarrier*` read fell through the prototype to the FOREGROUND
+ * request's barrier — whose getter and resolver are closure-bound to the
+ * foreground ctx and its handle store, and whose resolver no-ops once
+ * resolved. A bake-lane loader's `await ctx.rendered()` during capture then
+ * resolved instantly against the foreground's barrier and `ctx.use(handle)`
+ * read the foreground's handle snapshot; the capture's fresh `_handleStore`
+ * was invisible, so foreground per-request handle data could bake into the
+ * shared shell.
+ */
+export declare function wireRenderBarrier(ctx: RequestContext<any, any>, handleStore: HandleStore): void;
+export { parseCookiesFromHeader };
+export declare function serializeCookieValue(name: string, value: string, options?: CookieOptions): string;
+/**
+ * Options for creating the use() function
+ */
+export interface CreateUseFunctionOptions<TEnv> {
+    handleStore: HandleStore;
+    loaderPromises: Map<string, Promise<any>>;
+    getContext: () => RequestContext<TEnv>;
+}
+export declare function createUseFunction<TEnv>(options: CreateUseFunctionOptions<TEnv>): RequestContext["use"];