@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/src/testing/dispatch.ts

@@ -20,10 +20,10 @@
  * - Response routes (non-RSC)                         -> serialized Response
  *   - json:           JSON.stringify(result) (bare value) with application/json
  *   - text/html/xml/md: String(result) with the mapped MIME type
- *   - handler returning a Response:                     re-wrapped like
+ *   - handler returning or throwing a Response:         re-wrapped like
  *     handleResponseRoute (stub headers/cookies merged, Set-Cookie preserved,
  *     WebSocket upgrade passed through without reconstruction)
- *   - handler throwing an error:                        typed 500 / RouterError
+ *   - handler throwing a non-Response error:            typed 500 / RouterError
  *     status, matching handleResponseRoute (RFC 9457 problem+json body with
  *     application/problem+json for json routes, text/plain message otherwise)
  *   - content-negotiated route:                         Vary: Accept appended
@@ -53,7 +53,7 @@
  *   cache({ key })/cache({ tags }), or a custom store whose keyGenerator/
  *   getResponse/putResponse throws) fires onError with phase "cache" and
  *   metadata.category, while the request still degrades-to-miss exactly as before.
- *   (A thrown response-route HANDLER error is the one onError path NOT covered —
+ *   (A thrown non-Response route HANDLER error is the one onError path NOT covered —
  *   see "DOES NOT support" below.)
  * - createRouter({ telemetry }) match-transaction lifecycle: request.start opens
  *   the transaction before the global middleware chain, request.end closes it
@@ -63,6 +63,10 @@
  *   (getRequestId). Emission is gated entirely on a configured sink; with none,
  *   dispatch does zero new work and stays byte-identical for existing callers.
  *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
+ * - Response-route `renderStartMs` timeouts and `onTimeout`: dispatch races the
+ *   same terminal response work, reports the timeout through onError/telemetry,
+ *   and invokes the configured callback. `context.render` is absent because this
+ *   primitive deliberately does not run the Flight/HTML render driver.
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -70,7 +74,7 @@
  *   This includes partial requests that resolve to a component route.
  * - Server actions (?_rsc_action) — RSC protocol concerns handled by
  *   router.fetch().
- * - createRouter({ onError }) on a thrown response-route HANDLER error: the
+ * - createRouter({ onError }) on a thrown non-Response route HANDLER error: the
  *   error is serialized into the same typed 500 / RouterError Response as
  *   production, but onError is NOT invoked for that path here. Cover handler-error
  *   onError side effects with an e2e test. (This is the unchanged boundary; cache
@@ -129,21 +133,22 @@ import {
   createSimpleRedirectResponse,
   finalizeResponse,
   interceptRedirectForPartial,
-  mergeStubHeadersAndFinalize,
+  rewrapResponseRouteResponse,
 } from "../rsc/helpers.js";
 import { guardOutgoingRedirect } from "../rsc/redirect-guard.js";
 import { stringifyJsonRouteResult } from "../rsc/json-route-result.js";
-import {
-  EXTERNAL_REDIRECT_MARKER,
-  isExternalRedirect,
-  markExternalRedirect,
-} from "../redirect-origin.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import { invokeOnError } from "../router/error-handling.js";
 import type { OnErrorCallback } from "../types/error-types.js";
 import type { Rango } from "../router/router-interfaces.js";
 import { getRequestId, resolveSink, safeEmit } from "../router/telemetry.js";
 import type { TelemetrySink } from "../router/telemetry.js";
+import {
+  RouterTimeoutError,
+  createDefaultTimeoutResponse,
+  withTimeout,
+} from "../router/timeout.js";
+import type { OnTimeoutCallback, ResolvedTimeouts } from "../router/timeout.js";
 
 /**
  * The internal subset of the router surface dispatch depends on. The public
@@ -164,6 +169,8 @@ interface DispatchableRouter<TEnv> {
    * byte-identical for every existing caller.
    */
   telemetry?: TelemetrySink;
+  timeouts?: ResolvedTimeouts;
+  onTimeout?: OnTimeoutCallback<TEnv>;
   findMatch(pathname: string): Promise<{
     redirectTo?: string;
     routeKey?: string;
@@ -296,51 +303,6 @@ function serializeResponseRouteError(
   });
 }
 
-/**
- * Re-wrap a handler-returned Response, byte-identical to handleResponseRoute's
- * rewrapResponse:
- * - A WebSocket upgrade (status 101 or a `webSocket` property) is returned via
- *   mergeStubHeadersAndFinalize WITHOUT reconstruction — the Response
- *   constructor rejects status 101, and an upgrade response's headers/socket
- *   must not be rebuilt.
- * - Otherwise headers are copied into a fresh Headers (Set-Cookie appended to
- *   preserve duplicates, others set) and the Response is rebuilt through
- *   createResponseWithMergedHeaders so stub headers/cookies, the ctx.setStatus
- *   override, and onResponse callbacks merge exactly as in production. statusText
- *   is intentionally dropped (production does not carry it across the re-wrap).
- *
- * Must run inside runWithRequestContext (reads the ambient request context via
- * the helpers), which callHandler guarantees.
- */
-function rewrapHandlerResponse(result: Response): Response {
-  if (isWebSocketUpgradeResponse(result)) {
-    return mergeStubHeadersAndFinalize(result);
-  }
-  const headers = new Headers();
-  result.headers.forEach((value, key) => {
-    // Mirror production: never copy the reserved external-redirect marker off a
-    // handler result (it is not a trust signal; the opt-in is the out-of-band
-    // brand transferred below).
-    if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
-    if (key.toLowerCase() === "set-cookie") {
-      headers.append(key, value);
-    } else {
-      headers.set(key, value);
-    }
-  });
-  const rewrapped = createResponseWithMergedHeaders(result.body, {
-    status: result.status,
-    headers,
-  });
-  // Mirror production's rewrapResponse: transfer the out-of-band external brand
-  // only from a genuinely branded result (a real redirect(url, { external:
-  // true })), never from a proxied upstream's forged header.
-  if (isExternalRedirect(result)) {
-    markExternalRedirect(rewrapped);
-  }
-  return rewrapped;
-}
-
 /**
  * Run a request through the router in-process and return the Response.
  *
@@ -539,13 +501,15 @@ export async function dispatch<TEnv = any>(
       const callHandler = async (): Promise<Response> => {
         let merged: Response;
         try {
-          const result = await (handler as Function)(responseHandlerCtx);
+          let result: unknown;
+          try {
+            result = await (handler as Function)(responseHandlerCtx);
+          } catch (error) {
+            if (!(error instanceof Response)) throw error;
+            result = error;
+          }
           if (result instanceof Response) {
-            // Handler returned a Response: mirror handleResponseRoute's
-            // rewrapResponse (WebSocket-upgrade bypass + Set-Cookie-preserving
-            // header rebuild, statusText dropped) rather than the generic
-            // createResponseWithMergedHeaders re-wrap below.
-            merged = rewrapHandlerResponse(result);
+            merged = rewrapResponseRouteResponse(result);
           } else {
             // Route the serialized (json/text/...) body through the SAME
             // production finalizer the RSC handler uses, so ctx.onResponse()
@@ -671,6 +635,89 @@ export async function dispatch<TEnv = any>(
       return executeHandler().then(finalizeResponse);
     };
 
+    // The renderStartMs deadline wraps ONLY the response-route unit, mirroring
+    // handler.ts:845 where withTimeout(handleResponseRoute(...)) runs INSIDE
+    // coreRequestHandler — after the global middleware chain has already
+    // entered. Wrapping the outer chain (as an earlier version did) counted
+    // global middleware time toward the deadline, so a slow global auth
+    // middleware could 504 a request production serves. On timeout the 504/
+    // onTimeout Response is RETURNED from coreHandler so it flows back out
+    // through the global chain and finalizeResponse, identical to production
+    // (handler.ts:857 returns handleTimeoutResponse into the same next() path).
+    const runResponseRoute = async (): Promise<Response> => {
+      const responseWork = callResponseRoute();
+      const renderOutcome = await withTimeout(
+        responseWork,
+        router.timeouts?.renderStartMs,
+        "render-start",
+      );
+      if (!renderOutcome.timedOut) return renderOutcome.result;
+
+      // The race's losing side keeps executing after the timeout wins; its
+      // eventual Response is dropped. Swallow any rejection (no
+      // unhandled-rejection surfacing) and cancel the orphaned body stream so,
+      // under vitest, the abandoned handler cannot leak into the next test.
+      // Production abandons it too (handler.ts:845); this is a runner-scoped
+      // cleanup, not an observable-behavior change.
+      void responseWork
+        .then(
+          (orphan) => orphan.body?.cancel(),
+          () => {},
+        )
+        .catch(() => {});
+
+      const durationMs = renderOutcome.durationMs;
+      const timeoutError = new RouterTimeoutError("render-start", durationMs);
+      // Field-for-field parity with handleTimeoutResponse's callOnError
+      // (handler.ts:254): env is passed through (was previously dropped). render
+      // is always absent — dispatch runs no Flight/HTML driver, so there is no
+      // foreground cursor to snapshot.
+      invokeOnError(
+        router.onError,
+        timeoutError,
+        "handler",
+        {
+          request: req,
+          url,
+          env,
+          routeKey,
+          handledByBoundary: false,
+          metadata: { timeout: true, phase: "render-start", durationMs },
+        },
+        "RSC",
+      );
+      if (sink) {
+        safeEmit(resolveSink(sink), {
+          type: "request.timeout",
+          timestamp: performance.now(),
+          requestId: telemetryRequestId,
+          phase: "render-start",
+          pathname: url.pathname,
+          routeKey,
+          durationMs,
+          customHandler: router.onTimeout !== undefined,
+        });
+      }
+      if (router.onTimeout) {
+        try {
+          return await router.onTimeout({
+            phase: "render-start",
+            request: req,
+            url,
+            env,
+            routeKey,
+            durationMs,
+          });
+        } catch (error) {
+          if (process.env.NODE_ENV !== "production") {
+            console.error("[dispatch] onTimeout callback error:", error);
+          }
+          return createDefaultTimeoutResponse("render-start");
+        }
+      }
+      return createDefaultTimeoutResponse("render-start");
+    };
+
     // coreHandler is the single terminal the global middleware chain wraps,
     // mirroring production's coreHandler (handler.ts): a trailing-slash/redirect
     // 308, an unmatched-path 404, or the response route. Both the 308 and the
@@ -678,7 +725,9 @@ export async function dispatch<TEnv = any>(
     // cookies/headers merge onto them, identical to production's
     // rsc-rendering.ts redirect path — and because they sit inside the chain, a
     // global middleware that short-circuits (e.g. an auth 401) runs first and
-    // wins, never reaching the 308/404.
+    // wins, never reaching the 308/404. The renderStartMs deadline lives inside
+    // runResponseRoute (below the chain), never covering the 308/404 paths —
+    // production only wraps the response-route plan (handler.ts:834-856).
     const coreHandler = async (): Promise<Response> => {
       if (redirectTo) {
         return createResponseWithMergedHeaders(null, {
@@ -692,7 +741,7 @@ export async function dispatch<TEnv = any>(
           headers: { "content-type": "text/plain;charset=utf-8" },
         });
       }
-      return callResponseRoute();
+      return runResponseRoute();
     };
 
     // request.start opens the match transaction, mirroring match-handlers.ts.
@@ -712,7 +761,11 @@ export async function dispatch<TEnv = any>(
 
     try {
       // Global (pattern-matched) middleware wraps coreHandler, exactly as
-      // production wraps coreHandler with executeMiddleware (handler.ts).
+      // production wraps coreHandler with executeMiddleware (handler.ts:568).
+      // The renderStartMs deadline is deliberately NOT applied here — it wraps
+      // only the response-route unit inside coreHandler (see runResponseRoute),
+      // mirroring handler.ts:845 so global middleware time is never counted
+      // toward the deadline.
       const globalMatches = matchMiddleware(url.pathname, router.middleware);
       const mwResponse =
         globalMatches.length === 0
@@ -734,9 +787,22 @@ export async function dispatch<TEnv = any>(
       // 204 + X-RSC-Redirect (see the location-state divergence in the header).
       let finalResponse: Response;
       if (isPartial || isAction) {
+        const softOpts = {
+          requestOrigin: url.origin,
+          basename: router.basename,
+        };
+        // Pass `external` through: interceptRedirectForPartial forwards the
+        // out-of-band brand as the third callback arg (helpers.ts). Dropping it
+        // would neutralize redirect(url, { external: true }) to "/" in dispatch
+        // while production preserves it via createRedirectFlightResponse.
         const intercepted = interceptRedirectForPartial(
           mwResponse,
-          (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
+          (redirectUrl, _locationState, external) =>
+            createSimpleRedirectResponse(redirectUrl, {
+              ...softOpts,
+              external,
+            }),
+          softOpts,
         );
         finalResponse = finalizeResponse(intercepted ?? mwResponse);
       } else {
@@ -768,8 +834,7 @@ export async function dispatch<TEnv = any>(
       // browser-followed (3xx + Location) redirect is same-origin guarded before
       // it leaves -- a cross-origin Location is rewritten to the basename root
       // unless redirect(url, { external: true }) opted out. Soft partial/action
-      // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
-      // validates them), so this is a no-op for them.
+      // redirects are already resolved at createSimpleRedirectResponse time.
       return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
     } catch (error) {
       if (sink) {

package/src/testing/e2e/index.ts

@@ -40,6 +40,14 @@ export {
   type ExpectedCacheStatus,
   type CacheStatusTarget,
 } from "../cache-status.js";
+export {
+  assertShellStatus,
+  parseShellStatus,
+  shellCacheKey,
+  SHELL_STATUS_HEADER,
+  type ShellStatus,
+  type ShellStatusTarget,
+} from "../shell-status.js";
 export {
   testId,
   waitForHydration,

package/src/testing/index.ts

@@ -28,7 +28,7 @@
  * Layers:
  * - Unit:        runMiddleware, runLoader
  * - Integration: dispatch (request -> Response)
- * - Cross-cut:   assertCacheStatus, assertGeneratedRoutesMatch
+ * - Cross-cut:   assertCacheStatus, assertShellStatus, assertGeneratedRoutesMatch
  * - Component:   see @rangojs/router/testing/dom (renderRoute)
  * - E2E:         see @rangojs/router/testing/e2e
  * - RSC:         see @rangojs/router/testing/flight
@@ -76,6 +76,14 @@ export type {
   CacheSegmentStatus,
 } from "../router/telemetry.js";
 
+export {
+  assertShellStatus,
+  parseShellStatus,
+  shellCacheKey,
+  SHELL_STATUS_HEADER,
+} from "./shell-status.js";
+export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+
 export { collectHandle } from "./collect-handle.js";
 
 export {

package/src/testing/internal/context.ts

@@ -55,6 +55,14 @@ export interface CreateTestContextOptions<TEnv> {
   routeMap?: Record<string, string>;
   routeName?: string;
   params?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false). Set `true` to unit-test middleware or a
+   * handler that branches on the build-time PPR shell-capture pass — e.g.
+   * `if (ctx.build) ctx.dynamic()`. Mirrors the synthetic build request the
+   * shell-capture producer creates; also makes `ctx.waitUntil()` inert, as at
+   * build time.
+   */
+  build?: boolean;
   /**
    * Router basename for this request (what the RSC handler stores on the
    * context). Drives redirect() prefixing. Normalized exactly like
@@ -150,6 +158,7 @@ export function createTestRequestContext<TEnv>(
     request,
     url,
     variables,
+    build: opts.build,
     themeConfig:
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
     cacheStore: opts.cacheStore,

package/src/testing/render-handler.ts

@@ -62,7 +62,7 @@ const DEFAULT_URL = "http://localhost/";
 /** A route handler under test: the `(ctx) => RSC | Response` function you pass to `path(...)`. */
 export type TestableHandler<TEnv = any> = (
   ctx: HandlerContext<any, TEnv>,
-) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+) => ReactNode | Response | Promise<ReactNode | Response>;
 
 /** Options for {@link renderHandler}. */
 export interface RenderHandlerOptions<TEnv = any> {
@@ -80,6 +80,12 @@ export interface RenderHandlerOptions<TEnv = any> {
   routeName?: string;
   /** Route name -> pattern map enabling `ctx.reverse()`. */
   routeMap?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false) so a handler that branches on the
+   * build-time pass — including calling `ctx.dynamic()` on a MISS — is
+   * unit-testable. Assert a `ctx.dynamic()` call via `result.dynamic`.
+   */
+  build?: boolean;
   /**
    * Seed the data `ctx.use(SomeLoader)` returns — NO real loader runs (same model
    * as `runLoader`'s `loaders`). Matched by loader reference, so a real
@@ -163,6 +169,12 @@ export interface RenderHandlerResult {
   locationState: Record<string, unknown>;
   /** What the handler pushed via `ctx.use(Handle)(...)` (e.g. Meta, Breadcrumbs), keyed by handle. */
   handles: Map<Handle<any, any>, unknown[]>;
+  /**
+   * Whether the handler called `ctx.dynamic()` (the PPR shell opt-out). The
+   * public way to assert the opt-out without reading the `@internal`
+   * `ctx._dynamic`.
+   */
+  dynamic: boolean;
 }
 
 /**
@@ -239,6 +251,7 @@ export async function renderHandler<TEnv = any>(
     request,
     url,
     variables: seedVariables({}, opts.vars),
+    build: opts.build,
     stateCookieName,
     version: opts.stateCookie?.version,
     cacheStore: opts.cacheStore,
@@ -353,5 +366,6 @@ export async function renderHandler<TEnv = any>(
     stateCookieName,
     locationState,
     handles: handlePushes,
+    dynamic: (reqCtx as RequestContext<TEnv>)._dynamic === true,
   };
 }

package/src/testing/run-middleware.ts

@@ -49,6 +49,13 @@ export interface RunMiddlewareOptions<TEnv = any> {
   env?: TEnv;
   /** Route params surfaced as `ctx.params`. */
   params?: Record<string, string>;
+  /**
+   * Seed `ctx.build` (default false) so a middleware that branches on the
+   * build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`) is
+   * unit-testable. With `build: true`, `ctx.waitUntil()` is inert, matching the
+   * build producer. Assert a `ctx.dynamic()` call via `result.dynamic`.
+   */
+  build?: boolean;
   /** Variables a prior middleware would have set (object or [key, value] list). */
   vars?: VarsInit;
   /** Route name -> pattern map enabling `ctx.reverse()`. */
@@ -102,6 +109,11 @@ export interface RunMiddlewareResult<TEnv = any> {
   ctx: RequestContext<TEnv>;
   /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
   nextCalled: number;
+  /**
+   * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
+   * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
+   */
+  dynamic: boolean;
   /**
    * The effective cookie view after the chain ran: request cookies merged with
    * anything the chain set or deleted (last-write-wins), as `{ name: value }`.
@@ -146,6 +158,7 @@ export async function runMiddleware<TEnv = any>(
     routeMap: opts.routeMap,
     routeName: opts.routeName,
     params: opts.params,
+    build: opts.build,
     basename: opts.basename,
     theme: opts.theme,
     cacheStore: opts.cacheStore,
@@ -197,6 +210,7 @@ export async function runMiddleware<TEnv = any>(
     response,
     ctx,
     nextCalled,
+    dynamic: ctx._dynamic === true,
     cookies,
     headers,
     locationState,

package/src/testing/shell-status.ts

@@ -0,0 +1,100 @@
+/**
+ * PPR shell-status testing primitives for @rangojs/router consumers.
+ *
+ * Companion to `cache-status.ts` (segment/document cache): this module covers
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`).
+ *
+ * ## Spike conclusions (plan 009)
+ *
+ * 1. **`dispatch` cannot exercise PPR.** It is deliberately RSC-free: no Flight,
+ *    no SSR, no `handleRscRendering` commit point. Seeding `MemorySegmentCacheStore`
+ *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
+ *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
+ *
+ * 2. **Smallest HIT signal:** response header `x-rango-shell` (`HIT` | `MISS`),
+ *    always on document GETs to a ppr route that the serve path considered.
+ *    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.
+ *
+ * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
+ * (Playwright — same pure helpers, no Vite virtuals).
+ */
+
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+
+/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
+export const SHELL_STATUS_HEADER: string = "x-rango-shell";
+
+/** Values the serve path writes on `x-rango-shell`. */
+export type ShellStatus = "HIT" | "MISS";
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type ShellStatusTarget = Response | { headers: Headers };
+
+/**
+ * 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.
+ *
+ * Accepts a `URL` or an absolute/relative request URL string (relative strings
+ * resolve against `http://localhost`).
+ */
+export function shellCacheKey(url: URL | string): string {
+  const resolved =
+    typeof url === "string" ? new URL(url, "http://localhost") : url;
+  const sorted = sortedSearchString(resolved.searchParams);
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${resolved.host}${resolved.pathname}${searchSuffix}:shell`;
+}
+
+function getHeaders(target: ShellStatusTarget): Headers {
+  return target.headers;
+}
+
+/**
+ * Read `x-rango-shell` from a response. Returns `null` when the header is
+ * absent (axis-1 / non-ppr / ineligible request).
+ */
+export function parseShellStatus(
+  target: ShellStatusTarget,
+): ShellStatus | null {
+  const raw = getHeaders(target).get(SHELL_STATUS_HEADER);
+  if (raw === null) return null;
+  const value = raw.trim();
+  if (value === "HIT" || value === "MISS") return value;
+  return null;
+}
+
+/**
+ * Assert a document response's `x-rango-shell` header equals `expected`.
+ * Throws when the header is missing, unrecognized, or mismatched.
+ *
+ * Use on real document GETs (e2e `page.request.get` / `router.fetch`). Do not
+ * invent a HIT Response in unit tests — that fakes the serve path.
+ */
+export function assertShellStatus(
+  target: ShellStatusTarget,
+  expected: ShellStatus,
+): void {
+  const headerValue = getHeaders(target).get(SHELL_STATUS_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertShellStatus: response has no ${SHELL_STATUS_HEADER} header. ` +
+        `The header is only set on document GETs to a ppr-declared route that ` +
+        `the serve path considered (axis-1 fall-open and non-ppr routes omit it).`,
+    );
+  }
+  const actual = headerValue.trim();
+  if (actual !== expected) {
+    throw new Error(
+      `assertShellStatus: expected "${expected}" but got "${actual}".`,
+    );
+  }
+}

package/src/types/handler-context.ts

@@ -155,7 +155,7 @@ export type Handler<
       : ExtractSearchFromEntry<DefaultHandlerRouteMap, T>,
     TRouteMap extends DefaultHandlerRouteMap ? never : TRouteMap
   >,
-) => ReactNode | Promise<ReactNode> | Response | Promise<Response>) & {
+) => ReactNode | Response | Promise<ReactNode | Response>) & {
   /** Composable default DSL items merged when the handler is mounted. */
   use?: () => UseItems<HandlerUseItem>;
 };
@@ -202,7 +202,18 @@ export type HandlerContext<
    * Build-time collection and dev on-demand prerender use `true`.
    * Live request rendering, including passthrough fallback, uses `false`.
    */
-  build: boolean;
+  readonly build: boolean;
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * Middleware can call this before a shell HIT commits. Handlers run after
+   * that commit point, so they only prevent scheduling a new capture on MISS.
+   *
+   * Scope: this gates the PPR SHELL axis only. It does NOT disable prerender
+   * B-segment (Prerender/Static) serving — a Prerender() route's build-baked
+   * segments still replay at runtime — and it is inert in the prerender-collect
+   * and static-render contexts, which have no live shell decision to influence.
+   */
+  dynamic(): void;
   /**
    * True when running in Vite dev mode, false during production build or
    * live request rendering. Use this to branch on runtime mode without

package/src/urls/path-helper-types.ts

@@ -69,7 +69,7 @@ export type PathFn<TEnv> = <
     | ReactNode
     | ((
         ctx: HandlerContext<TParams, TEnv, TSearch>,
-      ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
+      ) => ReactNode | Response | Promise<ReactNode | Response>)
     | PrerenderHandlerDefinition<TParams>
     | PassthroughHandlerDefinition<TParams, TEnv>
     | StaticHandlerDefinition<TParams>,

package/src/urls/pattern-types.ts

@@ -62,6 +62,35 @@ export interface PartialPrerenderProps {
    * capture render auto-collects (the shell's own non-loader request tags).
    */
   tags?: string[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it to tighten the budget below the
+   * default or when a route's shell material takes longer than 15s to
+   * settle. A budget that expires with pushes still pending REFUSES the
+   * capture (the route stays MISS with the once-per-key warning) — a shell
+   * with missing head material is never stored. Capture is background work
+   * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
+   * response; the platform waitUntil lifetime (workerd: ~30s past response
+   * completion) is the physical ceiling — the default's derivation lives in
+   * docs/design/ppr-shell-resume.md (Cost model). Build-time captures
+   * (Prerender+ppr, producer B) honor the same budget with no platform
+   * ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
 }
 
 export interface PathOptions<