@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/src/route-map-builder.ts

@@ -12,11 +12,6 @@ let globalRouteMap: Record<string, string> = {};
 
 let cachedManifest: Record<string, string> | null = null;
 
-let cachedPrecomputedEntries: Array<{
-  staticPrefix: string;
-  routes: Record<string, string>;
-}> | null = null;
-
 /**
  * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
@@ -87,43 +82,6 @@ export function clearCachedManifest(): void {
   cachedManifest = null;
 }
 
-/**
- * Set pre-computed route entries from build-time data.
- *
- * Each entry corresponds to a leaf node in the prefix tree (no nested includes).
- * evaluateLazyEntry() checks these before running the handler, avoiding the
- * 5-50ms cost of handler evaluation for route matching on the first request.
- *
- * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
- */
-export function setPrecomputedEntries(
-  entries: Array<{
-    staticPrefix: string;
-    routes: Record<string, string>;
-  }> | null,
-): void {
-  cachedPrecomputedEntries = entries;
-}
-
-/**
- * Get pre-computed route entries (if available)
- */
-export function getPrecomputedEntries(): typeof cachedPrecomputedEntries {
-  return cachedPrecomputedEntries;
-}
-
-// Route trie for O(path_length) matching at runtime.
-// Built at build time from the route manifest and serialized into the virtual module.
-let cachedRouteTrie: import("./build/route-trie.js").TrieNode | null = null;
-
-export function setRouteTrie(trie: typeof cachedRouteTrie): void {
-  cachedRouteTrie = trie;
-}
-
-export function getRouteTrie(): typeof cachedRouteTrie {
-  return cachedRouteTrie;
-}
-
 // Per-router isolated data: each router gets its own manifest, trie, and
 // precomputed entries so multi-router setups (e.g. site + admin via
 // createHostRouter()) don't see each other's routes.
@@ -146,14 +104,18 @@ const perRouterPrecomputedEntriesMap: Map<
 export function clearAllRouterData(): void {
   globalRouteMap = {};
   cachedManifest = null;
-  cachedPrecomputedEntries = null;
-  cachedRouteTrie = null;
   rootScopeRoutes.clear();
+  perRouterRootScopeRoutes.clear();
   globalSearchSchemas.clear();
+  perRouterSearchSchemas.clear();
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
   authoritativeTrieRouters.clear();
+  // Clear the loader registry too: a loader that survives a clear closes over
+  // a module import whose data predates the clear, and re-running it would
+  // re-install that stale trie as authoritative.
+  routerManifestLoaders.clear();
 }
 
 export function setRouterManifest(
@@ -225,17 +187,17 @@ export function registerRouterManifestLoader(
 }
 
 export async function ensureRouterManifest(routerId: string): Promise<void> {
-  // Check both manifest AND trie. The virtual module's setRouterManifest()
-  // pre-sets the manifest at startup, but the per-router trie is only
-  // available from the lazy loader. Without this, the lazy loader never
-  // runs and findMatch falls back to the global merged trie — which
-  // contains routes from ALL routers and breaks multi-router setups.
-  if (perRouterManifestMap.has(routerId) && perRouterTrieMap.has(routerId))
-    return;
+  // Gate on the trie: it is the only data the lazy loader supplies (the
+  // name->path map is pre-set by the eager virtual module's
+  // setRouterManifest() and never comes from the loader). Gating on the
+  // manifest instead would let the loader be skipped while the per-router
+  // trie is missing, and findMatch would fall back to insertion-order regex
+  // matching — which mishandles wildcard priority (catch-alls match before
+  // specific routes).
+  if (perRouterTrieMap.has(routerId)) return;
   const loader = routerManifestLoaders.get(routerId);
   if (loader) {
     const mod = await loader();
-    if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
     if (mod.trie) {
       perRouterTrieMap.set(routerId, mod.trie);
       // A trie serialized into the build manifest comes from complete
@@ -265,7 +227,16 @@ export function waitForManifestReady(): Promise<void> | null {
 // Tracks whether each route is at root scope (no named include boundary above).
 // Used by dot-local reverse resolution to decide whether bare-name fallback
 // is allowed after scoped lookups are exhausted.
+//
+// Both this and the search-schema registry below are keyed by route NAME and
+// registered by path() at evaluation time. Two routers can legally declare the
+// same route name (per-router manifests keep them apart), so each registry has
+// a per-router tier consulted first; the global tier is the fallback for
+// contexts with no router identity (single-router apps, unit tests, evaluation
+// outside generateManifestFull). Without the per-router tier, the
+// last-evaluated router silently won for BOTH routers.
 const rootScopeRoutes: Map<string, boolean> = new Map();
+const perRouterRootScopeRoutes: Map<string, Map<string, boolean>> = new Map();
 
 /**
  * Register whether a route is at root scope.
@@ -274,29 +245,65 @@ const rootScopeRoutes: Map<string, boolean> = new Map();
 export function registerRouteRootScope(
   routeName: string,
   rootScoped: boolean,
+  routerId?: string,
 ): void {
   rootScopeRoutes.set(routeName, rootScoped);
+  if (routerId) {
+    let perRouter = perRouterRootScopeRoutes.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterRootScopeRoutes.set(routerId, perRouter);
+    }
+    perRouter.set(routeName, rootScoped);
+  }
 }
 
 /**
  * Check if a route is at root scope.
  * Returns undefined if the route has not been registered (e.g. in unit tests).
  */
-export function isRouteRootScoped(routeName: string): boolean | undefined {
+export function isRouteRootScoped(
+  routeName: string,
+  routerId?: string,
+): boolean | undefined {
+  if (routerId) {
+    const scoped = perRouterRootScopeRoutes.get(routerId)?.get(routeName);
+    if (scoped !== undefined) return scoped;
+  }
   return rootScopeRoutes.get(routeName);
 }
 
 import type { SearchSchema } from "./search-params.js";
 
 const globalSearchSchemas: Map<string, SearchSchema> = new Map();
+const perRouterSearchSchemas: Map<
+  string,
+  Map<string, SearchSchema>
+> = new Map();
 
 export function registerSearchSchema(
   routeName: string,
   schema: SearchSchema,
+  routerId?: string,
 ): void {
   globalSearchSchemas.set(routeName, schema);
+  if (routerId) {
+    let perRouter = perRouterSearchSchemas.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterSearchSchemas.set(routerId, perRouter);
+    }
+    perRouter.set(routeName, schema);
+  }
 }
 
-export function getSearchSchema(routeName: string): SearchSchema | undefined {
+export function getSearchSchema(
+  routeName: string,
+  routerId?: string,
+): SearchSchema | undefined {
+  if (routerId) {
+    const schema = perRouterSearchSchemas.get(routerId)?.get(routeName);
+    if (schema !== undefined) return schema;
+  }
   return globalSearchSchemas.get(routeName);
 }

package/src/router/content-negotiation.ts

@@ -76,6 +76,46 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
 
 export const RSC_RESPONSE_TYPE = "__rsc__";
 
+/** RSC wire-format MIME type; explicit-opt-in flight transport. */
+export const RSC_WIRE_MIME = "text/x-component";
+
+/**
+ * The two representations an RSC route serves, in canonical-first order:
+ * text/html (the document) and text/x-component (the flight wire format).
+ * Both register as negotiation candidates in pickNegotiateVariant; without
+ * the wire-format entry, an explicit Accept: text/x-component fell through
+ * to the definition-order fallback — a JSON-first route answered a
+ * wire-format request with JSON. Which representation an RSC win actually
+ * renders is decided by prefersFlightRepresentation below, from the same
+ * Accept header (wired in via isRscRequest, rsc/ssr-setup.ts).
+ */
+const RSC_MIMES: readonly string[] = ["text/html", RSC_WIRE_MIME];
+
+/**
+ * Rank the RSC route's two representations against a parsed Accept list:
+ * true when the flight wire format outranks the HTML document. Wildcard
+ * entries count for the HTML side — they express "anything", and the
+ * canonical representation of anything is the document. Co-located with
+ * RSC_MIMES so the candidate registration and the representation choice
+ * cannot drift.
+ */
+export function prefersFlightRepresentation(
+  acceptEntries: AcceptEntry[],
+): boolean {
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    if (entry.mime === RSC_WIRE_MIME) return true;
+    if (
+      entry.mime === "text/html" ||
+      entry.mime === "text/*" ||
+      entry.mime === "*/*"
+    ) {
+      return false;
+    }
+  }
+  return false;
+}
+
 /**
  * Pick the best negotiate variant by walking the client's sorted Accept list.
  * For each accepted MIME type (in q-value/order priority), check if any
@@ -87,12 +127,14 @@ export function pickNegotiateVariant<
 >(acceptEntries: AcceptEntry[], candidates: T[]): T {
   const byCandidateMime = new Map<string, T>();
   for (const c of candidates) {
-    const mime =
+    const mimes =
       c.responseType === RSC_RESPONSE_TYPE
-        ? "text/html"
-        : RESPONSE_TYPE_MIME[c.responseType];
-    if (mime && !byCandidateMime.has(mime)) {
-      byCandidateMime.set(mime, c);
+        ? RSC_MIMES
+        : [RESPONSE_TYPE_MIME[c.responseType]];
+    for (const mime of mimes) {
+      if (mime && !byCandidateMime.has(mime)) {
+        byCandidateMime.set(mime, c);
+      }
     }
   }
 

package/src/router/handler-context.ts

@@ -14,7 +14,10 @@ import {
   isNonCacheable,
   type ContextSetOptions,
 } from "../context-var.js";
-import { isInsideCacheScope } from "../server/context.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  isInsideCacheScope,
+} from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -93,7 +96,7 @@ function resolveRouteName(
     // Resolution order: explicit param > scope registry > heuristic.
     const isRootScoped =
       rootScoped ??
-      isRouteRootScoped(currentRoutePrefix) ??
+      isRouteRootScoped(currentRoutePrefix, _getRequestContext()?._routerId) ??
       !currentRoutePrefix.includes(".");
     if (isRootScoped) {
       if (routeMap[lookupName] !== undefined) {
@@ -205,7 +208,9 @@ export function createHandlerContext<TEnv>(
   const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
-  const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
+  const searchSchema = routeName
+    ? getSearchSchema(routeName, requestContext?._routerId)
+    : undefined;
   const resolvedSearchParams = searchSchema
     ? parseSearchParams(searchParams, searchSchema)
     : searchParams;
@@ -214,7 +219,9 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
+  // Guard mutating Headers methods so they throw inside "use cache" scope or
+  // cached header-write territory (cache() boundary / ppr route render —
+  // assertCachedHeaderWriteAllowed, the unified #713 guard).
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
   // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
@@ -226,13 +233,7 @@ export function createHandlerContext<TEnv>(
         if (MUTATING_HEADERS_METHODS.has(prop as string)) {
           return (...args: any[]) => {
             assertNotInsideCacheExec(ctx, "headers");
-            if (isInsideCacheScope()) {
-              throw new Error(
-                `ctx.headers.${String(prop)}() cannot be called inside a cache() boundary. ` +
-                  `On cache hit the handler is skipped, so this side effect would be lost. ` +
-                  `Move header mutations to a middleware or layout outside the cache() scope.`,
-              );
-            }
+            assertCachedHeaderWriteAllowed("ctx.headers", prop);
             return value.apply(target, args);
           };
         }
@@ -244,7 +245,10 @@ export function createHandlerContext<TEnv>(
 
   ctx = {
     params,
-    build: false,
+    build: requestContext?.build ?? false,
+    dynamic(): void {
+      requestContext?.dynamic();
+    },
     dev: false,
     request,
     searchParams,
@@ -304,7 +308,9 @@ export function createHandlerContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, requestContext?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(false, isPassthroughRoute),
     _responseType: responseType,
@@ -345,6 +351,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");
@@ -394,7 +403,9 @@ export function createPrerenderContext<TEnv>(
       routeMap,
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     passthrough: createPrerenderPassthroughFn(
       true,
@@ -430,6 +441,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");
@@ -488,7 +502,9 @@ export function createStaticContext<TEnv>(
       routeMap,
       routeName,
       undefined,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName
+        ? isRouteRootScoped(routeName, _getRequestContext()?._routerId)
+        : undefined,
     ),
     _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;

package/src/router/intercept-resolution.ts

@@ -28,7 +28,32 @@ import {
 } from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
-import { runInsideLoaderScope } from "../server/context.js";
+import {
+  RangoContext,
+  latchPprHeaderScopeForEntries,
+  runInsideLoaderScope,
+} from "../server/context.js";
+
+/**
+ * Header-guard latch for the intercept funnels (issue #713). ppr and
+ * intercepts do not compose on the shell path — shells are captured/served
+ * only for document requests and withInterceptResolution skips intercepts on
+ * full matches — so this is defense in depth: a partial nav CAN render an
+ * intercept over a ppr-declared target route, in its own store scope where
+ * the main funnel's latch does not apply. Latch by declaration, off the
+ * target route's manifest entry (same leaf input as the segment funnels).
+ * Called AFTER intercept middleware runs — middleware stays the live lane.
+ */
+function latchPprHeaderScopeForInterceptTarget(
+  interceptEntry: InterceptEntry,
+): void {
+  const targetEntry = RangoContext.getStore()?.manifest.get(
+    interceptEntry.routeName,
+  );
+  if (targetEntry) {
+    latchPprHeaderScopeForEntries([targetEntry], interceptEntry.routeName);
+  }
+}
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -150,6 +175,8 @@ export async function resolveInterceptEntry<TEnv>(
     if (middlewareResponse) throw middlewareResponse;
   }
 
+  latchPprHeaderScopeForInterceptTarget(interceptEntry);
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
@@ -328,6 +355,8 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     return null;
   }
 
+  latchPprHeaderScopeForInterceptTarget(interceptEntry);
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 

package/src/router/lazy-includes.ts

@@ -171,6 +171,7 @@ function runExpansion<TEnv = any>(
       counters: lazyCounters,
       cacheProfiles: lazyContext?.cacheProfiles,
       rootScoped: lazyContext?.rootScoped,
+      routerId: lazyContext?.routerId,
       includeScope: lazyContext?.includeScope,
     },
     () => {

package/src/router/loader-resolution.ts

@@ -430,6 +430,22 @@ function createLoaderExecutor<TEnv>(
     // nested deps inherit isDslLoader=false only when the CHAIN started in a
     // handler; a chain started by the segment funnel stays DSL (the loader
     // scope ALS survives the body's awaits).
+    // Shell fast path eligibility: a HANDLER-invoked loader executing during a
+    // capture is handler-layer dynamism — on a handler-free (replayed) HIT it
+    // would never re-run, freezing its consumption-lane value (#672's "fresh
+    // per serve" slot shape). Mark the capture; the entry declines the fast
+    // path and keeps the full tail. DSL loaders re-run on every HIT and never
+    // set this.
+    if (!isDslLoader) {
+      const captureCtx = _getRequestContext();
+      if (
+        captureCtx?._shellCaptureRun &&
+        captureCtx._shellCaptureHandleLiveness
+      ) {
+        captureCtx._shellCaptureHandleLiveness.handlerInvokedLoader = true;
+      }
+    }
+
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(

package/src/router/match-api.ts

@@ -1,4 +1,8 @@
-import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
+import {
+  CacheScope,
+  createCacheScope,
+  resolveShellImplicitCacheScope,
+} from "../cache/cache-scope.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -180,7 +184,9 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope: snapshot.cacheScope,
+    // Shell fast path: a capture or an eligible document/navigation HIT may
+    // substitute an implicit doc-level scope (a route-derived scope wins).
+    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
@@ -419,7 +425,12 @@ export async function createMatchContextForPartial<TEnv>(
     interceptSelectorContext,
     isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope: snapshot.cacheScope,
+    // A normal-route navigation may replay a PPR shell's canonical segment
+    // snapshot. Intercepts remain source-dependent and always use their normal
+    // cache path.
+    cacheScope: isIntercept
+      ? snapshot.cacheScope
+      : resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept,
     actionContext,
     isAction,

package/src/router/match-middleware/cache-lookup.ts

@@ -112,6 +112,9 @@ let prerenderStoreInstance: PrerenderStore | null | undefined;
 let _deserializeSegments:
   | typeof import("../../cache/segment-codec.js").deserializeSegments
   | undefined;
+let _fragmentSegments:
+  | typeof import("../../cache/segment-codec.js").fragmentSegments
+  | undefined;
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
@@ -135,6 +138,7 @@ async function ensurePrerenderDeps() {
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
+    _fragmentSegments = codec.fragmentSegments;
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
@@ -237,6 +241,7 @@ async function* yieldFromStore<TEnv>(
 
   if (
     !_deserializeSegments ||
+    !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
     !_hashParams ||
@@ -245,7 +250,13 @@ async function* yieldFromStore<TEnv>(
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
 
-  const segments = await _deserializeSegments(entry.segments);
+  // Shell-HIT tail (issue #700): a Prerender+ppr route's tail serves from THIS
+  // store (the prerender lookup runs before the cache scope), so the fragment
+  // splice must apply here too — otherwise producer B entries re-serialize the
+  // whole tree per request while producer A entries do not.
+  const segments = _getRequestContext()?._shellFragmentPayload
+    ? await _fragmentSegments(entry.segments)
+    : await _deserializeSegments(entry.segments);
 
   // Replay handle data (same as runtime cache hit path). entry.handles is a
   // Flight-encoded string ("" when none) — decode before restore so

package/src/router/metrics.ts

@@ -79,6 +79,7 @@ export function appendMetric(
   start: number,
   duration: number,
   depth?: number,
+  desc?: string,
 ): void {
   if (!metricsStore) return;
   metricsStore.metrics.push({
@@ -86,6 +87,7 @@ export function appendMetric(
     duration,
     startTime: start - metricsStore.requestStart,
     depth,
+    desc,
   });
 }
 
@@ -104,6 +106,7 @@ interface DisplayRow {
   startTime: number;
   duration: number;
   depth: number | undefined;
+  desc: string | undefined;
   spans: Span[];
 }
 
@@ -137,6 +140,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
           startTime: m.startTime,
           duration: m.duration + post.duration,
           depth: m.depth,
+          desc: m.desc,
           spans: [
             { startTime: m.startTime, duration: m.duration },
             { startTime: post.startTime, duration: post.duration },
@@ -151,6 +155,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -169,6 +174,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -180,6 +186,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
       startTime: m.startTime,
       duration: m.duration,
       depth: m.depth,
+      desc: m.desc,
       spans: [{ startTime: m.startTime, duration: m.duration }],
     });
   }
@@ -199,7 +206,9 @@ export function logMetrics(
 
   const labels = displayRows.map(
     (r) =>
-      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}${
+        r.desc ? ` (${r.desc})` : ""
+      }`,
   );
   const startValues = displayRows.map((r) => formatMs(r.startTime));
   const durationValues = displayRows.map((r) => formatMs(r.duration));
@@ -247,7 +256,13 @@ export function generateServerTiming(metricsStore: MetricsStore): string {
         .replace(/[^a-zA-Z0-9-]/g, "")
         .toLowerCase();
       const name = m.depth ? `d${m.depth}-${base}` : base;
-      return `${name};dur=${m.duration.toFixed(2)}`;
+      // desc is a quoted-string: backslash-escape the two delimiters; our
+      // producers emit plain printable text, so nothing else needs stripping.
+      const desc =
+        m.desc !== undefined
+          ? `;desc="${m.desc.replace(/[\\"]/g, "\\$&")}"`
+          : "";
+      return `${name};dur=${m.duration.toFixed(2)}${desc}`;
     })
     .join(", ");
 }

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