@rangojs/router 0.0.0-experimental.150 → 0.0.0-experimental.151

package/skills/prerender/SKILL.md

@@ -138,6 +138,7 @@ interface BuildContext<TParams> {
     search?: Record<string, unknown>,
   ): string; // URL generation
   passthrough(): PrerenderPassthroughResult; // Skip local artifact (Passthrough routes only)
+  dynamic(): void; // No-op in Prerender/Static handlers; use middleware for PPR shell opt-out
   env: DefaultEnv; // Available when buildEnv is configured in rango() (throws otherwise)
   // NOT available: request, headers, cookies (always throw)
 }
@@ -257,7 +258,7 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 | `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                         |
 | `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                     |
 | `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                             |
-| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                                |
+| `middleware()` | Skipped while collecting build-time Flight payloads (no request). For `Prerender` + `ppr`, producer B replays global and route middleware during build-shell capture with `ctx.build === true`; `ctx.dynamic()` skips that shell. Runs at request time for loaders.      |
 | `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                   |
 | `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
@@ -265,6 +266,48 @@ When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
 implicitly re-run outer prerender-derived handlers/layouts.
 
+## Prerender + PPR Build Shells
+
+A `Prerender` page may also declare `ppr` on the path option. The build still
+stores the Flight payload first. After that, producer B tries to bake the HTML
+shell for each generated URL so the first document request can be an
+`x-rango-shell: HIT`.
+
+That shell capture is request-shaped enough to run middleware safely:
+
+- global and route middleware run before shell capture;
+- middleware sees `ctx.build === true`;
+- `ctx.waitUntil()` is inert during build;
+- `ctx.dynamic()` skips the baked shell for that URL.
+
+Use `ctx.build` inside middleware to avoid runtime-only side effects during
+build shell capture, or call `ctx.dynamic()` to leave that route to runtime
+PPR. Runtime requests still run the normal middleware chain.
+
+### Freshness of a build shell
+
+A build-baked shell is not on a wall clock the way a pure runtime `ppr` shell is.
+It serves from the first request after a deploy and keeps serving until one of:
+
+- **a redeploy** — the `buildVersion` gate retires every build entry (like a
+  React-version bump); the new build re-bakes;
+- **`updateTag`** on a tag the shell carries — drops it, so the next request
+  MISSes and a runtime capture takes over.
+
+`ppr.ttl` / `swr` are staleness-only here, NOT an expiry: past `ttl` the baked
+entry STILL serves and a runtime recapture is scheduled that upgrades it in place
+(SWR is the upgrade path from build entry → fresher runtime entry). Because the
+`Prerender` handler is evicted from the production bundle, that recapture never
+re-runs the handler — it replays the same build-time segments and only refreshes
+`cache()`-scoped data baked into the shell. **If nothing in the shell is
+`cache()`-backed, `ttl` has nothing to refresh** — reach for `updateTag` (or a
+redeploy) instead of a shorter `ttl`.
+
+`ctx.dynamic()` opts a request off the shell axis ONLY. A `Prerender` route has
+no live handler to fall back to (it was evicted), so a `dynamic()` request still
+serves the build-baked B-segments — fresh loaders in their holes, not a fresh
+handler render. There is no "fully dynamic" render for a prerendered route.
+
 ## Dev Mode
 
 In dev mode there is no production-style prerender build pass and no handler

package/src/build/generate-manifest.ts

@@ -107,7 +107,6 @@ async function buildPrefixTreeNode(
   namePrefix: string | undefined,
   patternsOrProvider: UrlPatterns<any> | IncludeProvider<any>,
   routeManifest: Record<string, string>,
-  routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
   mountIndex: number,
   visited: Set<unknown> = new Set(),
   routeTrailingSlash?: Record<string, string>,
@@ -189,9 +188,6 @@ async function buildPrefixTreeNode(
       }
     }
 
-    // Capture ancestry from manifest entries' parent chains
-    captureAncestry(manifest, routeAncestry);
-
     // Collect prerender route names and handler definitions from manifest entries
     if (prerenderRoutes) {
       for (const [name, entry] of manifest) {
@@ -223,7 +219,6 @@ async function buildPrefixTreeNode(
         include.namePrefix,
         include.patterns as UrlPatterns<any> | IncludeProvider<any>,
         routeManifest,
-        routeAncestry,
         mountIndex,
         visited,
         routeTrailingSlash,
@@ -250,32 +245,11 @@ async function buildPrefixTreeNode(
   }
 }
 
-/**
- * Walk parent chains of route entries to extract ancestry shortCodes.
- */
-function captureAncestry(
-  manifest: Map<string, EntryData>,
-  routeAncestry: Record<string, string[]>,
-): void {
-  for (const [routeName, entry] of manifest) {
-    if (entry.type === "route") {
-      const ancestry: string[] = [];
-      let current: EntryData | null = entry;
-      while (current) {
-        ancestry.unshift(current.shortCode);
-        current = current.parent;
-      }
-      routeAncestry[routeName] = ancestry;
-    }
-  }
-}
-
 /**
  * Internal manifest result including build-pipeline-only fields.
  * Not part of the public API — use generateManifest() for the public surface.
  */
 export interface FullManifest extends GeneratedManifest {
-  _routeAncestry: Record<string, string[]>;
   _prerenderDefs?: Record<string, any>;
 }
 
@@ -283,8 +257,7 @@ export interface FullManifest extends GeneratedManifest {
  * Generate manifest from UrlPatterns (public API).
  *
  * Returns only the public GeneratedManifest fields. Internal build pipeline
- * consumers that need _routeAncestry or _prerenderDefs should use
- * generateManifestFull() instead.
+ * consumers that need _prerenderDefs should use generateManifestFull() instead.
  *
  * @example
  * ```typescript
@@ -304,8 +277,10 @@ export async function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
 ): Promise<GeneratedManifest> {
-  const { _routeAncestry, _prerenderDefs, ...publicManifest } =
-    await generateManifestFull(urlpatterns, mountIndex);
+  const { _prerenderDefs, ...publicManifest } = await generateManifestFull(
+    urlpatterns,
+    mountIndex,
+  );
   return publicManifest;
 }
 
@@ -332,7 +307,6 @@ export async function generateManifestFull<TEnv>(
   },
 ): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
-  const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
 
   // Run the root patterns handler with tracking enabled
@@ -392,9 +366,6 @@ export async function generateManifestFull<TEnv>(
     Record<string, string>
   > = Object.fromEntries(searchSchemasMap);
 
-  // Capture ancestry from manifest entries' parent chains
-  captureAncestry(manifest, routeAncestry);
-
   // Collect prerender route names and handler definitions across all levels
   const prerenderRoutes: string[] = [];
   const prerenderDefs: Record<string, any> = {};
@@ -423,7 +394,6 @@ export async function generateManifestFull<TEnv>(
       include.namePrefix,
       include.patterns as UrlPatterns<any> | IncludeProvider<any>,
       routeManifest,
-      routeAncestry,
       mountIndex,
       visited,
       routeTrailingSlash,
@@ -453,7 +423,6 @@ export async function generateManifestFull<TEnv>(
       Object.keys(routeSearchSchemas).length > 0
         ? routeSearchSchemas
         : undefined,
-    _routeAncestry: routeAncestry,
     // Internal: prerender handler definitions for build-time getParams() access
     _prerenderDefs:
       Object.keys(prerenderDefs).length > 0 ? prerenderDefs : undefined,

package/src/build/route-trie.ts

@@ -2,8 +2,7 @@
  * Build-time Route Trie Construction
  *
  * Builds a serializable trie from the route manifest for O(path_length)
- * route matching at runtime. Each trie leaf embeds the route's ancestry
- * shortCodes for layout pruning.
+ * route matching at runtime.
  */
 
 import {
@@ -33,8 +32,6 @@ export interface TrieLeaf {
   n: string;
   /** Static prefix of the entry (e.g., "/site") */
   sp: string;
-  /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
-  a: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
   /** Ordered param names for this route (positional) */
@@ -75,7 +72,6 @@ export interface TrieNode {
  * Build a route trie from build-time manifest data.
  *
  * @param routeManifest - Map of route name to full URL pattern
- * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
  * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
@@ -84,7 +80,6 @@ export interface TrieNode {
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
-  routeAncestry: Record<string, string[]>,
   routeToStaticPrefix: Record<string, string>,
   routeTrailingSlash?: Record<string, string>,
   prerenderRouteNames?: Set<string>,
@@ -94,7 +89,6 @@ export function buildRouteTrie(
   const root: TrieNode = {};
 
   for (const [routeName, pattern] of Object.entries(routeManifest)) {
-    const ancestry = routeAncestry[routeName] || [];
     const staticPrefix = routeToStaticPrefix[routeName] || "";
     const trailingSlash = routeTrailingSlash?.[routeName];
     const responseType = responseTypeRoutes?.[routeName];
@@ -107,7 +101,6 @@ export function buildRouteTrie(
     insertRoute(root, segments, 0, {
       n: routeName,
       sp: staticPrefix,
-      a: ancestry,
       ...(trailingSlash ? { ts: trailingSlash } : {}),
       ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
       ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
@@ -161,15 +154,13 @@ function sortSuffixParams(node: TrieNode): void {
  * construction path shared by build/discovery (discover-routers.ts, serialized
  * into the production chunk) and the dev/HMR runtime rebuild
  * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
- * runtime trie and the production serialized trie are byte-for-byte identical
- * (modulo `leaf.a` ancestry, which embeds the mount index and is debug-only).
+ * runtime trie and the production serialized trie are byte-for-byte identical.
  *
- * Returns null when the manifest has no route ancestry (no routes), matching
- * the prior guard at both call sites.
+ * Returns null when the manifest has no routes, matching the prior guard at
+ * both call sites.
  */
 export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
-  const ancestry = manifest._routeAncestry;
-  if (!ancestry || Object.keys(ancestry).length === 0) {
+  if (Object.keys(manifest.routeManifest).length === 0) {
     return null;
   }
 
@@ -186,7 +177,6 @@ export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
 
   return buildRouteTrie(
     manifest.routeManifest,
-    ancestry,
     routeToStaticPrefix,
     manifest.routeTrailingSlash,
     manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : undefined,
@@ -233,41 +223,6 @@ function insertRoute(
   insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Extract ancestry map from a built trie by visiting all leaf nodes.
- * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
- */
-export function extractAncestryFromTrie(
-  root: TrieNode,
-): Record<string, string[]> {
-  const result: Record<string, string[]> = {};
-
-  function visit(node: TrieNode): void {
-    if (node.r) {
-      result[node.r.n] = node.r.a;
-    }
-    if (node.w) {
-      result[node.w.n] = node.w.a;
-    }
-    if (node.s) {
-      for (const child of Object.values(node.s)) {
-        visit(child);
-      }
-    }
-    if (node.xp) {
-      for (const child of Object.values(node.xp)) {
-        visit(child.c);
-      }
-    }
-    if (node.p) {
-      visit(node.p.c);
-    }
-  }
-
-  visit(root);
-  return result;
-}
-
 /**
  * Merge a new leaf with an existing leaf, handling content negotiation.
  * When an RSC route and response-type routes share the same URL pattern,

package/src/cache/cache-key-utils.ts

@@ -23,7 +23,6 @@ const RESERVED_SEARCH_PARAMS = new Set([
   "__no_cache",
   "__rsc",
   "__html",
-  "__debug_manifest",
   "__prerender_collect",
 ]);
 

package/src/prerender/build-shell-capture.ts

@@ -6,10 +6,11 @@
  * chunk preloads — that only exist post-client-build). The capture core is
  * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
  * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). The differences are only the base
- * context (a synthetic build request created via createRequestContext over the
- * build env — no ambient identity, so the identity guard is trivially
- * satisfied) and the sink (an entry collector instead of a runtime store).
+ * quiesce, tags union, putShell barrier). Build capture first replays global
+ * and route middleware with a synthetic build request context
+ * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
+ * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
+ * of a runtime store.
  *
  * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
  * store seeded from the just-collected Flight payloads, and REPLAYS the
@@ -25,6 +26,7 @@ import {
   createRequestContext,
   runWithRequestContext,
   setRequestContextParams,
+  type RequestContext,
 } from "../server/request-context.js";
 import {
   deriveShellCaptureContext,
@@ -34,9 +36,15 @@ import {
   type ShellCaptureDescriptor,
 } from "../rsc/shell-capture.js";
 import { buildFullPayload } from "../rsc/full-payload.js";
+import { buildRouteMiddlewareEntries } from "../rsc/helpers.js";
 import type { RscPayload, SSRModule } from "../rsc/types.js";
 import type { HandlerContext } from "../rsc/handler-context.js";
 import { renderToReadableStream } from "../deps/rsc.js";
+import { isRouteNotFoundError } from "../errors.js";
+import { createReverseFunction } from "../router/handler-context.js";
+import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
+import type { MiddlewareEntry } from "../router/middleware.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
 import {
   resolvePprConfig,
   type ResolvedPprConfig,
@@ -116,6 +124,8 @@ export interface BuildShellCaptureResult {
     | "no-shell"
     | "redirect"
     | "refused"
+    /** Middleware/handler opted this URL out of PPR shell capture. */
+    | "dynamic"
     /** The router swept does not own this URL — try the next one. */
     | "route-mismatch";
   /** Present iff outcome === "stored". */
@@ -152,16 +162,19 @@ async function attemptBuildCapture(
   const router = opts.router;
   const url = new URL(opts.urlPath, "http://build.invalid");
   const request = new Request(url, { method: "GET" });
+  const env = (opts.buildEnv ?? {}) as any;
+  const variables: Record<string, any> = {};
 
   // Synthetic build request context: same factory the runtime handler uses,
   // so the capture's ALS surface (cookie machinery, variables, waitUntil,
   // theme resolution) is production-shaped. No cookie header → theme resolves
   // to the app default, exactly like a first anonymous visitor's capture.
   const baseCtx = createRequestContext({
-    env: (opts.buildEnv ?? {}) as any,
+    env,
     request,
     url,
-    variables: {},
+    variables,
+    build: true,
     // Fresh empty store per attempt: cache()/"use cache" reads MISS, execute,
     // and are recorded into the snapshot by the derivation's RecordingShell
     // wrapper — the entry pins its own generation, nothing preexisting leaks.
@@ -171,11 +184,6 @@ async function attemptBuildCapture(
     version: opts.buildVersion,
   });
 
-  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
-    ttl: opts.ttl,
-    swr: opts.swr,
-  });
-
   // Entry collector: captureAndStoreShell's sink. putShell never fails here,
   // so a "stored" outcome always carries the entry.
   let collected: { entry: ShellCacheEntry; tags?: string[] } | null = null;
@@ -204,10 +212,177 @@ async function attemptBuildCapture(
   };
 
   let mismatchedRouteName: string | undefined;
+  const result = await runWithRequestContext(baseCtx, async () => {
+    const preview =
+      typeof router.previewMatch === "function"
+        ? await router.previewMatch(request, { env })
+        : undefined;
+    // These preview-based mismatches exit before any middleware/envelope runs,
+    // so nothing consumes a response — only result.outcome is read below.
+    if (preview === null) {
+      return { outcome: "route-mismatch" } as const;
+    }
+    if (preview?.routeKey && preview.routeKey !== opts.routeName) {
+      mismatchedRouteName = preview.routeKey;
+      return { outcome: "route-mismatch" } as const;
+    }
+
+    if (preview?.routeKey) {
+      setRequestContextParams(preview.params ?? {}, preview.routeKey);
+    }
+
+    const routeReverse = createReverseFunction(
+      getGlobalRouteMap(),
+      preview?.routeKey,
+      preview?.params ?? {},
+    );
+
+    const runCapture = () =>
+      runBuildCaptureFinal({
+        baseCtx,
+        descriptor,
+        env,
+        opts,
+        request,
+        router,
+        url,
+        setMismatchedRouteName: (routeName) => {
+          mismatchedRouteName = routeName;
+        },
+      });
+
+    const routeMiddleware =
+      preview?.routeMiddleware && preview.routeMiddleware.length > 0
+        ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+        : [];
+    const runRouteMiddleware = () =>
+      runBuildMiddlewareEnvelope(
+        routeMiddleware,
+        request,
+        env,
+        variables,
+        runCapture,
+        routeReverse,
+        baseCtx,
+      );
+
+    const globalMiddleware = Array.isArray(router.middleware)
+      ? matchMiddleware(url.pathname, router.middleware)
+      : [];
+    return runBuildMiddlewareEnvelope(
+      globalMiddleware,
+      request,
+      env,
+      variables,
+      runRouteMiddleware,
+      routeReverse,
+      baseCtx,
+    );
+  });
+
+  const outcome = result.outcome;
+  if (outcome === "stored" && collected !== null) {
+    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
+    return { outcome, entry: hit.entry, tags: hit.tags };
+  }
+  if (outcome === "route-mismatch") {
+    return { outcome, matchedRouteName: mismatchedRouteName };
+  }
+  return { outcome };
+}
+
+type BuildShellCaptureOutcome = BuildShellCaptureResult["outcome"];
+
+interface BuildCaptureRunResult {
+  outcome: BuildShellCaptureOutcome;
+  response: Response;
+}
+
+interface BuildCaptureFinalOptions {
+  baseCtx: RequestContext<any>;
+  descriptor: ShellCaptureDescriptor;
+  env: any;
+  opts: BuildShellCaptureOptions;
+  request: Request;
+  router: any;
+  url: URL;
+  setMismatchedRouteName(routeName: string | undefined): void;
+}
+
+async function runBuildMiddlewareEnvelope<TEnv>(
+  middlewares: Array<{
+    entry: MiddlewareEntry<TEnv>;
+    params: Record<string, string>;
+  }>,
+  request: Request,
+  env: TEnv,
+  variables: Record<string, any>,
+  finalHandler: () => Promise<BuildCaptureRunResult>,
+  reverse: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string,
+  baseCtx: RequestContext<any>,
+): Promise<BuildCaptureRunResult> {
+  let downstream: BuildCaptureRunResult | undefined;
+  const response = await executeMiddleware(
+    middlewares,
+    request,
+    env,
+    variables,
+    async () => {
+      downstream = baseCtx._dynamic
+        ? {
+            outcome: "dynamic",
+            response: responseForBuildCaptureOutcome("dynamic"),
+          }
+        : await finalHandler();
+      return downstream.response;
+    },
+    reverse,
+  );
+
+  if (baseCtx._dynamic) {
+    return { outcome: "dynamic", response };
+  }
+  if (response.status >= 300 && response.status < 400) {
+    return { outcome: "redirect", response };
+  }
+  return (
+    downstream ?? {
+      outcome: "no-shell",
+      response,
+    }
+  );
+}
+
+async function runBuildCaptureFinal(
+  options: BuildCaptureFinalOptions,
+): Promise<BuildCaptureRunResult> {
+  const { baseCtx, descriptor, env, opts, request, router, url } = options;
+  // No baseCtx._dynamic recheck here: the only caller is the route envelope's
+  // finalHandler wrapper, which already short-circuits to "dynamic" without
+  // invoking this when baseCtx._dynamic is set. A loader/handler opting out
+  // DURING the capture render is caught by the derivedCtx._dynamic check below.
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+    ttl: opts.ttl,
+    swr: opts.swr,
+  });
+
   const outcome = await runWithRequestContext(derivedCtx, async () => {
-    const match = await router.match(request, { env: opts.buildEnv ?? {} });
+    let match;
+    try {
+      match = await router.match(request, { env });
+    } catch (error) {
+      if (isPlainPathMiss(error, opts.urlPath)) {
+        return "route-mismatch" as const;
+      }
+      throw error;
+    }
     if (match.routeName !== opts.routeName) {
-      mismatchedRouteName = match.routeName;
+      options.setMismatchedRouteName(match.routeName);
       return "route-mismatch" as const;
     }
     if (match.redirect) return "redirect" as const;
@@ -233,21 +408,40 @@ async function attemptBuildCapture(
       },
     });
 
-    return captureAndStoreShell(
+    const captureOutcome = await captureAndStoreShell(
       { captureShellHTML: opts.captureShellHTML } as SSRModule,
       rscStream,
       freshHandleStore,
       derivedCtx,
       descriptor,
     );
+    return derivedCtx._dynamic ? "dynamic" : captureOutcome;
   });
 
-  if (outcome === "stored" && collected !== null) {
-    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
-    return { outcome, entry: hit.entry, tags: hit.tags };
-  }
-  if (outcome === "route-mismatch") {
-    return { outcome, matchedRouteName: mismatchedRouteName };
+  return {
+    outcome,
+    response: responseForBuildCaptureOutcome(outcome),
+  };
+}
+
+function responseForBuildCaptureOutcome(
+  outcome: BuildShellCaptureOutcome,
+): Response {
+  if (outcome === "redirect") {
+    return new Response(null, {
+      status: 302,
+      headers: { location: "http://build.invalid/" },
+    });
   }
-  return { outcome };
+  return new Response(null, { status: 204 });
+}
+
+function isPlainPathMiss(error: unknown, pathname: string): boolean {
+  if (!isRouteNotFoundError(error)) return false;
+  const cause = (error as { cause?: unknown }).cause;
+  return (
+    cause !== null &&
+    typeof cause === "object" &&
+    (cause as { pathname?: unknown }).pathname === pathname
+  );
 }

package/src/router/handler-context.ts

@@ -243,7 +243,10 @@ export function createHandlerContext<TEnv>(
 
   ctx = {
     params,
-    build: false,
+    build: requestContext?.build ?? false,
+    dynamic(): void {
+      requestContext?.dynamic();
+    },
     dev: false,
     request,
     searchParams,
@@ -344,6 +347,9 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    // Inert here: prerender/static contexts have no live PPR-shell decision to
+    // gate. dynamic() only reaches the shell axis on a live request or capture.
+    dynamic: () => {},
     dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
@@ -429,6 +435,9 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    // Inert here: prerender/static contexts have no live PPR-shell decision to
+    // gate. dynamic() only reaches the shell axis on a live request or capture.
+    dynamic: () => {},
     dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");

package/src/router/middleware-types.ts

@@ -39,6 +39,23 @@ export interface MiddlewareContext<
 > extends RequestScope<TEnv> {
   params: TParams;
 
+  /**
+   * True for build-time render/capture requests. Live requests use false.
+   * Build-time PPR shell capture sets this while replaying middleware.
+   */
+  readonly build: boolean;
+
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * During middleware this runs before the shell HIT commit point, so it can
+   * force the request onto the dynamic axis.
+   *
+   * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+   * (Prerender/Static) serving — a Prerender() route still replays its
+   * build-baked segments at runtime.
+   */
+  dynamic(): void;
+
   readonly headers: Headers;
 
   get: GetVariableFn;

package/src/router/middleware.ts

@@ -238,6 +238,10 @@ export function createMiddlewareContext<TEnv>(
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
+    build: reqCtx?.build ?? false,
+    dynamic(): void {
+      reqCtx?.dynamic();
+    },
     executionContext: reqCtx?.executionContext,
     waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
     // Getter: re-derives from request context on each access so that global