@rangojs/router 0.17.0 → 0.18.0

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

@@ -104,6 +104,40 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _rotateStateCookie(): void;
     /** @internal Set the keepClientCache() directive header on the response. */
     _setKeepCacheDirective(): void;
+    /**
+     * @internal This request carries the fresh-reads cookie: it follows an
+     * updateTag()/revalidateTag() by the same user, so the stores read tag
+     * markers and shells from the store, not from an isolate memo.
+     */
+    _freshReads?: boolean;
+    /**
+     * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+     * (rounded up to whole seconds; the longest stays). Called by
+     * updateTag()/revalidateTag().
+     */
+    _setFreshReadsCookie(maxAgeMs: number): void;
+    /**
+     * @internal The context createRequestContext() returned. A context derived
+     * from it with Object.create (a PPR HIT tail, a shell capture, a background
+     * revalidation render) inherits it, so per-request invalidation state
+     * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
+     * whichever derived object called or read (#973).
+     */
+    _requestRoot?: RequestContext<any, any>;
+    /**
+     * @internal The tags this request invalidated with
+     * updateTag()/revalidateTag(), each with its position in the invalidation
+     * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
+     * "use cache" execution that started before one of its own tags was
+     * invalidated is neither joined nor written (cache-runtime.ts, #973).
+     */
+    _tagInvalidations?: Map<string, number>;
+    /**
+     * @internal The handler has handed the response to the host (rsc/handler.ts
+     * `rango.response`): header and cookie writes after this are lost, as from
+     * a streaming loader or render.
+     */
+    _responseSent?: boolean;
     /**
      * Access loader data or push handle data.
      *
@@ -191,6 +225,44 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * property of the capture's derived context only.
      */
     _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+    /**
+     * @internal Set on a capture's derived context when a loader pushed a
+     * value the record cannot keep (a deferred push, masked nested promises,
+     * or a push outside a loader body): the loader records then carry
+     * `runs: 1`, so a HIT still runs their bodies for those pushes.
+     */
+    _shellCaptureUnrecordedLoaderPush?: true;
+    /**
+     * @internal Record keys resolved for this request (CacheScope
+     * resolveKeyFrom): by the scope's `key()` (one result) or its store's
+     * keyGenerator (one per default key). A shell capture's derived context
+     * reads it through the prototype chain, so the capture reuses the
+     * partition its request resolved instead of running `key()` again.
+     */
+    _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+    /**
+     * @internal The shell store key the PPR serve path resolved for this
+     * document request (rsc-rendering.ts shellServePlan), request partition
+     * included. Read by the testing helper serveShellRequest.
+     */
+    _shellKey?: string;
+    /**
+     * @internal The request carried the forced-MISS reload marker
+     * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+     * request on entry and sets this; the shell gate renders the request like a
+     * cache miss.
+     */
+    _shellForcedMiss?: true;
+    /**
+     * @internal The freshness window of the route cache() records this
+     * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+     * its scope's swr. The narrowest record wins. A shell capture caps its
+     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+     * shell is never fresher, or served longer, than the route cache() entry
+     * it replayed or wrote.
+     */
+    _routeRecordWindow?: RouteRecordWindow;
     /**
      * @internal Loader-family snapshot seed for a shell HIT's tail render:
      * segment-key -> the capture's elided container (already Flight-deserialized
@@ -198,21 +270,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * 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.
+     * and does not run the loader. Two owners: serveShellHit sets it on the
+     * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+     * request context of a PPR partial replay once its doc record hits, and
+     * restores the previous value after the match.
      */
     _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
+     * @internal The doc record marker: makes the next 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
+     * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+     * normal-route partial replay, where `store` is a request-local segment
+     * overlay.
+     * A document HIT tail replays the record even for a route with its own
+     * cache() config (the gate before the commit already evaluated that
+     * scope's opt-outs). Elsewhere the route's scope stays 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
@@ -229,12 +304,17 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * 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 only after the implicit cache hit decodes
+         * successfully; the lookup awaits it before returning the hit, so work
+         * it starts lands before the route's loaders resolve.
+         */
+        onHit?: () => void | Promise<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.
+         * snapshot after serving the fresh fallback. A document HIT tail does not
+         * set it: withCacheLookup throws ShellRecordUnavailableError instead.
          */
         onCorrupt?: () => void;
         /**
@@ -245,6 +325,21 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * require the exact consumable record instead of "any segment record".
          */
         docKey?: string;
+        /**
+         * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+         * scope replaces any route-derived cache() scope for the tail's match
+         * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
+         * ShellRecordUnavailableError instead of resolving segments
+         * (withCacheLookup): a HIT never runs a handler.
+         */
+        docTail?: true;
+        /**
+         * @internal The key a document HIT tail looks the doc record up by: the
+         * entry's own `docKey`. Recomputing it could name another key (a store
+         * keyGenerator folding request data, a build-time capture's synthetic
+         * host) and miss the record.
+         */
+        fixedDocKey?: string;
         /**
          * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
          * serve path. Its presence arms the explicit-scope composition in
@@ -286,30 +381,19 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _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 Set (to the offending fn name) by the cookies()/headers()
-     * capture guard when it throws DURING a capture render. Load-bearing for the
+     * @internal Set by the capture guard (server/context.ts
+     * tripShellCaptureGuard) when it throws DURING a capture render: the read
+     * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+     * refusal warning gives for it. 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;
+    _shellCaptureGuardTripped?: {
+        surface: string;
+        fix: 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
@@ -336,6 +420,21 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * content used and can therefore be invalidated by updateTag()/revalidateTag().
      */
     _requestTags: Set<string>;
+    /**
+     * @internal This request can write a route cache() record: its match
+     * resolved a cache scope (match-api.ts). Arms the record tag owners
+     * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+     * and owned tag sets are skipped entirely. A capture's or background
+     * re-render's derived context (Object.create) inherits it.
+     */
+    _recordTagOwners?: true;
+    /**
+     * @internal This request resolves a loader bound with its own cache()
+     * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+     * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+     * allocates no set and a read links nothing. Derived contexts inherit it.
+     */
+    _recordLoaderTags?: true;
     /** @internal Cache profiles for "use cache" profile resolution (per-router) */
     _cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
     /**
@@ -376,6 +475,11 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * 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.
      *
+     * The visitor's cookie, so it is guarded like `cookies()`: reading it
+     * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+     * `"use cache"` function (#971). A non-enumerable getter: a spread or
+     * `Object.assign` copy of the context does not carry it.
+     *
      * @example
      * ```typescript
      * route("settings", (ctx) => {
@@ -384,7 +488,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * });
      * ```
      */
-    theme?: Theme;
+    readonly theme?: Theme;
     /**
      * Set the theme (only available when theme is enabled in router config)
      *
@@ -405,6 +509,14 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setTheme?: (theme: Theme) => void;
     /** @internal Theme configuration (null if theme not enabled) */
     _themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * @internal The theme cookie (or the default) read with no identity guard.
+     * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
+     * call it after assertThemeReadAllowed; the router's own payload read goes
+     * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+     * theme config.
+     */
+    _readTheme(): Theme | undefined;
     /**
      * Attach location state entries to the current response.
      *
@@ -595,13 +707,27 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+    freshUntil: number;
+    staleUntil: number;
+    ttl: number;
+    swr: number;
+    written: boolean;
+}
 /**
  * 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" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+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" | "_shellCaptureUnrecordedLoaderPush" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_tagInvalidations" | "_responseSent" | "_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:

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

@@ -238,6 +238,15 @@ interface ShellCaptureOptions {
      * refuses to store the shell (issue #915).
      */
     onError?: (error: unknown) => void;
+    /**
+     * Called with React's errorInfo for each task still pending when the
+     * capture's own abort froze the prelude; its componentStack is computed
+     * when read. The dev no-shell warning prints the stacks: one of them is what
+     * suspended above <body> (issue #941).
+     */
+    onAbortedTask?: (errorInfo: {
+        componentStack?: string;
+    } | undefined) => void;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;

package/dist/types/ssr/ssr-root.d.ts

@@ -54,14 +54,15 @@ export interface SsrRootOptions {
     nonce?: string;
     /**
      * Fires once when the Flight payload root settles (resolve OR reject) — the
-     * signal that every client-module load the payload references completed and
-     * fizz can start emitting the tree. The capture pass gates its abort on
-     * this: a fully REPLAYED (prerendered) route's Flight stream goes
-     * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
-     * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
-     * graph), so an abort gated on Flight quiet alone fires first and freezes
-     * a zero-byte prelude. Masked-loader holes do NOT block this signal —
-     * they postpone below the root.
+     * signal that fizz can start emitting the tree. A client component used as
+     * an element type resolves lazily, so its module load can still be in
+     * flight (captureShellHTML waits for those separately, issue #949). The
+     * capture pass gates its abort on this: a fully REPLAYED (prerendered)
+     * route's Flight stream goes byte-quiet in ~1-3ms, but fizz cannot render
+     * even <html> until the module loads finish (real module-runner I/O in dev;
+     * 100ms+ on a cold graph), so an abort gated on Flight quiet alone fires
+     * first and freezes a zero-byte prelude. Masked-loader holes do NOT block
+     * this signal — they postpone below the root.
      */
     onPayloadSettled?: () => void;
     /**

package/dist/types/testing/flight.entry.d.ts

@@ -18,6 +18,11 @@
  * element tree, so you can assert typed prop fidelity across the client boundary
  * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
  * deserialize only — no hydration/interaction (that is the e2e tier).
+ *
+ * `serveShellRequest` serves one request through the router's production
+ * handler, so a `ppr` route's MISS runs the real shell capture and a later
+ * request is a real HIT; only the HTML step is stubbed. `resetShellTestState`
+ * clears the per-isolate PPR state between tests.
  */
 export { renderToFlightString, normalizeFlight, assertFlightRuntimeAvailable, } from "./flight.js";
 export type { RenderToFlightStringOptions } from "./flight.js";
@@ -25,3 +30,5 @@ export { renderServerTree, findClientBoundaries, findElements, textContent, asse
 export type { RenderServerTreeOptions, RenderServerTreeResult, ClientBoundary, BoundarySelector, FoundElement, ElementSelector, } from "./flight-tree.js";
 export { renderHandler } from "./render-handler.js";
 export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateCookieSeed, } from "./render-handler.js";
+export { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
+export type { ServeShellRequestOptions, ServeShellRequestResult, } from "./serve-shell-request.js";

package/dist/types/testing/run-loader.d.ts

@@ -38,6 +38,7 @@ import { type Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
+import type { PartialCacheOptions } from "../types/cache-types.js";
 import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
 /**
  * The loader context surfaced to a `runLoader` body. It mirrors the runtime
@@ -81,9 +82,11 @@ export interface RunLoaderOptions<TEnv = any> {
     basename?: string;
     /**
      * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-     * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
-     * or cache contexts created from this loader observe it. Loaders themselves do
-     * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
+     * or `{ themes: [...] }`). Seeds the request's theme config, so the loader
+     * body reads the visitor's theme (the Cookie on `request`, or the default)
+     * with `getRequestContext().theme`. That read is guarded like `cookies()`: it
+     * throws inside a `"use cache"` function (#971). The loader ctx has no
+     * `theme`/`setTheme` (those are handler/middleware-only).
      */
     theme?: ThemeConfig | true;
     /** Environment bindings surfaced as `ctx.env`. */
@@ -121,6 +124,18 @@ export interface RunLoaderOptions<TEnv = any> {
     cacheStore?: SegmentCacheStore;
     /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
     cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Run the loader through the `cache()` a route binds it with — the options
+     * `loader(Loader, () => [cache({...})])` takes — using the production
+     * read-through against `cache.store`, else `cacheStore`. A HIT returns the
+     * stored value without running the body and records the tags the body
+     * recorded when the entry was written, so `updateTag()` of any of them drops
+     * the entry. The write is a background task the call does not await (spy
+     * on the store's `setItem` to wait for it). A raw loader body is keyed by
+     * its function reference. `handlePushes` lists the body's pushes, so a HIT
+     * reports none: the replay into the page's handle store is not modeled.
+     */
+    cache?: PartialCacheOptions;
     /**
      * Customize the rango state cookie a loader that calls
      * `invalidateClientCache()` rotates (the name is always seeded — default

package/dist/types/testing/serve-shell-request.d.ts

@@ -0,0 +1,132 @@
+/**
+ * serveShellRequest — one request through the production PPR serve path.
+ *
+ * Builds the router's request handler as `router.fetch` does
+ * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * config) and serves one GET through it, so middleware, the shell serve path
+ * and a MISS's background capture all run production code, on real Flight
+ * (the vendored react-server-dom serializer). The call settles every
+ * background task the request scheduled before it returns, so a MISS's
+ * `putShell` has landed.
+ *
+ * The one stub is the SSR module (the HTML step): `react-dom/server` refuses
+ * to load under the react-server condition this project runs with.
+ * - `renderHTML` passes the Flight stream through: a document body is its
+ *   Flight payload.
+ * - `captureShellHTML` returns, as the prelude, the Flight text the capture
+ *   rendered before `quiesce` (plus the post-quiesce task hops the real
+ *   capture takes). `postponed` is always null. A capture that does not
+ *   quiesce within what `ppr.captureTimeout` leaves after the handler output
+ *   settled returns no shell; the real one goes on to its abort and returns
+ *   whatever prelude rendered by then.
+ * - `resumeShellHTML` passes the tail's Flight stream through: a HIT body is
+ *   the stored prelude followed by the tail's Flight payload.
+ * So there is no HTML: the prelude's `<body` sanity gate, SSR render errors
+ * (production refuses the capture on one), fizz resume of the holes,
+ * bootstrap scripts and nonce injection stay e2e-only. A route whose real
+ * capture refuses for a root postpone (a live loader read with no boundary
+ * above it) or an SSR render error is captured here.
+ *
+ * Must run under the `react-server` condition (the rsc Vitest project), with
+ * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
+ * that carries the Flight runtime.
+ */
+import { type Rango } from "../router/router-interfaces.js";
+import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import { type PprReplayStatus, type ShellStatus } from "./shell-status.js";
+/** Options for {@link serveShellRequest}. */
+export interface ServeShellRequestOptions<TEnv = any> {
+    /**
+     * The shell and segment store for this request, in place of the router's
+     * `createRouter({ cache })` store. The rest of that config (`enabled`,
+     * `searchParams`) still applies. Omit it to serve through the router's own
+     * store.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Environment bindings, as `router.fetch(request, { env })` passes them. */
+    env?: TEnv;
+    /**
+     * Request headers. A document request defaults `accept` to `text/html`.
+     */
+    headers?: HeadersInit;
+    /**
+     * Serve the client navigation the browser sends (`?_rsc_partial`) instead
+     * of a document GET: from `from` (default `/`) with `segments` mounted
+     * (default none), advertising fragment passthrough. The replay decision is
+     * `result.replayStatus`.
+     */
+    partial?: true | {
+        from?: string;
+        segments?: readonly string[];
+    };
+}
+/** Result of {@link serveShellRequest}. */
+export interface ServeShellRequestResult {
+    /** The handler's Response. Its body is already read: see `body`. */
+    response: Response;
+    /** The response body text. */
+    body: string;
+    /** `x-rango-shell` (`HIT` | `MISS`), or null when the header is absent. */
+    shellStatus: ShellStatus | null;
+    /** `x-rango-ppr-replay` on a partial request, or null. */
+    replayStatus: PprReplayStatus | null;
+    /**
+     * The prelude a HIT served: the capture's Flight text at quiesce (the
+     * shell as captured). Undefined unless `shellStatus` is `HIT`.
+     */
+    prelude: string | undefined;
+    /**
+     * The Flight payload this request rendered: a HIT's tail, a document's
+     * render, or a Flight response. Undefined when no Flight was rendered (a
+     * redirect or a middleware response).
+     */
+    flight: string | undefined;
+    /**
+     * The shell key production resolved for this request: for a document the
+     * serve path read and captured (a MISS or a HIT), the key it used, request
+     * partition included (a route partitioned by `cache({ key })` or the
+     * store's `keyGenerator`). Otherwise (a route without `ppr`, a request
+     * passed to axis 1 before its key was resolved, a partial request) the
+     * document URL's key without a partition, as `shellCacheKey` builds it.
+     */
+    key: string;
+    /**
+     * Read the document shell entry under `key` from the request's store
+     * (a passive `getShell`), or null. A read, so on a store with a shell memo
+     * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
+     */
+    readEntry(): Promise<ShellCacheEntry | null>;
+}
+/**
+ * Reset the per-isolate PPR state requests leave behind, so the next test
+ * starts as a fresh worker would: the capture's stampede guard, its backoff
+ * (a refused capture backs its URL off for later tests too), the capture's
+ * and the serve path's once-per-key warnings, the build-shell manifest memo,
+ * and CFCacheStore's isolate memos (shells, tag markers, tag hints), which
+ * every CFCacheStore in the process shares by namespace and URL. Call it in
+ * `beforeEach`, never while a request is in flight. VercelCacheStore's memos
+ * live on the `cache` handle it is given: a new handle starts empty.
+ */
+export declare function resetShellTestState(): Promise<void>;
+/**
+ * Serve one GET for `url` through the router's production request handler
+ * and settle the background tasks it scheduled (a MISS's capture and
+ * `putShell` included). The first request for a `ppr` route is a MISS; the
+ * next one with the same store is a HIT from the stored shell. The HTML step
+ * is stubbed (see the module header), so `prelude` and `flight` are Flight
+ * text. The request starts in a later millisecond than the call: a store
+ * refuses a capture that starts in the millisecond of a tag invalidation, so
+ * an `updateTag()` made just before the call never refuses its recapture.
+ * Rejects when the handler throws or the response stream errors (a failing
+ * HIT tail), after settling the tasks scheduled so far.
+ *
+ * @example
+ * const store = new MemorySegmentCacheStore();
+ * const miss = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(miss.shellStatus).toBe("MISS");
+ * const hit = await serveShellRequest(router, "/product/1", { cacheStore: store });
+ * expect(hit.shellStatus).toBe("HIT");
+ * expect(hit.prelude).toContain("Widget"); // captured shell
+ * expect(hit.flight).toContain("in stock"); // live hole, rendered now
+ */
+export declare function serveShellRequest<TEnv = any>(router: Rango<TEnv, any>, url: string | URL, options?: ServeShellRequestOptions<TEnv>): Promise<ServeShellRequestResult>;

package/dist/types/testing/shell-status.d.ts

@@ -18,11 +18,15 @@
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
- * 3. **Stays e2e-only:** live MISS → background capture → HIT (needs real
- *    `captureShellHTML` / React `prerender` + resume fizz), browser resume of
- *    holes, Cloudflare/Vercel live stores, nonce/eligibility fall-open, and
- *    build-time producer B bake. Unit layer dogfoods the **store family + key
- *    identity + header assert**; it must never stub a shell HIT response.
+ * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
+ *    (`@rangojs/router/testing/flight`, serve-shell-request.ts) serves one
+ *    request through the router's production handler and settles its
+ *    background capture; a later request with the same store is a real HIT or
+ *    partial replay. Its only stub is the HTML step (the SSR module).
+ *    **Stays e2e-only:** real HTML (the prelude's `<body` gate, fizz resume of
+ *    holes), browser resume of holes, live Cloudflare/Vercel runtimes (store
+ *    test doubles work in unit), and build-time producer B bake. The unit layer
+ *    must never stub a shell HIT response.
  *
  * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
  * (Playwright — same pure helpers, no Vite virtuals).
@@ -34,7 +38,7 @@ export declare const SHELL_STATUS_HEADER: string;
 export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
-declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
 /** Bounded reasons a PPR partial request can fall open to ordinary matching. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /** Parsed `x-rango-ppr-replay` value. */
@@ -52,15 +56,24 @@ export type ShellStatusTarget = Response | {
 /**
  * Shell store key for a document URL — same formula as production
  * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
- * `:shell`). Kept here so the testing barrel never imports the shell-serve
- * module (it pulls React). A parity test pins the two implementations.
+ * `:shell`), then the production `partitionShellKey` itself (the leaf
+ * `rsc/shell-capture-constants.ts`). The base is kept here so the testing
+ * barrel never imports the shell-serve module (it pulls React). A parity test
+ * pins the two implementations.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
  * config as `searchParams` when the app under test sets one — the production
- * key applies it, so the expected key must too.
+ * key applies it, so the expected key must too. When the route's record is
+ * partitioned by the request — its `cache({ key })`, or the store's
+ * `keyGenerator` — its shell is too: pass the key that function returns for
+ * the request as `partition` (appended URI-encoded; a result equal to the
+ * default key partitions nothing, so pass none). Under nested keyed
+ * `cache()` scopes, pass their `key()` results as an array, outermost first:
+ * they compose as the production record key composes them
+ * (`composeCacheKeys`).
  */
-export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[]): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

package/dist/types/types/handler-context.d.ts

@@ -235,6 +235,12 @@ export type HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch extends Sear
      * Current theme (from cookie or default).
      * Only available when theme is enabled in router config.
      *
+     * The visitor's cookie, so it is guarded like `cookies()`: reading it on a
+     * `ppr` route refuses the shell capture, and inside a `cache()` boundary or
+     * a `"use cache"` function it throws (#971). Read it with `useTheme()` in a
+     * client component, or in a live loader, on those routes. A read-only,
+     * non-enumerable getter: `{ ...ctx }` does not carry it.
+     *
      * @example
      * ```typescript
      * route("settings", (ctx) => {
@@ -243,7 +249,7 @@ export type HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch extends Sear
      * });
      * ```
      */
-    theme?: Theme;
+    readonly theme?: Theme;
     /**
      * Set the theme (only available when theme is enabled in router config).
      * Sets a cookie with the new theme value.
@@ -349,6 +355,13 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * from the page. See setupLoaderAccess.
      */
     _runLoaderIsolated?: (loader: any) => Promise<any>;
+    /**
+     * @internal A loader's cache() binding started with these cache() tags: an
+     * execution of that loader outside the binding (a reader started it first,
+     * or a stale refresh runs it) answers for them too (#964). See
+     * setupLoaderAccess.
+     */
+    _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
 };
 /**
  * Generic params type - flexible object with string keys