@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/src/redirect-origin.ts

@@ -2,12 +2,13 @@
  * Runtime-neutral same-origin redirect rule.
  *
  * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
- * which validates redirect targets the client JS is about to navigate to) and
- * the server outgoing-redirect guard (`rsc/redirect-guard.ts`, which validates
- * every browser-followed `Location` header before it leaves the handler). Kept
- * at the `src/` root so both layers import the ONE rule and cannot drift -- a
+ * which validates redirect targets the client JS is about to navigate to), the
+ * server outgoing 3xx guard (`rsc/redirect-guard.ts`, which validates every
+ * browser-followed `Location` header before it leaves the handler), and soft
+ * Flight / `X-RSC-Redirect` construction (`resolveSoftRedirectUrl`). Kept at
+ * the `src/` root so every layer imports the ONE rule and cannot drift -- a
  * cross-origin target blocked on the JS/fetch path is blocked identically on the
- * no-JS (PE) and full-page document paths.
+ * no-JS (PE), full-page document, and soft SPA channels.
  */
 
 /**
@@ -66,14 +67,42 @@ export function resolveExternalRedirect(
  * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
  * browser here instead: the app's basename root, or `"/"` when unset. Kept
  * beside the resolvers so the "where does a blocked redirect go" answer lives
- * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`) and the
- * shell-HIT degradation path (`rsc/rsc-rendering.ts`) must agree, or a blocked
- * redirect lands differently depending on which exit it took.
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`), the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`), and soft Flight/
+ * X-RSC-Redirect construction must agree, or a blocked redirect lands
+ * differently depending on which exit it took.
  */
 export function safeSameOriginLanding(basename: string | undefined): string {
   return basename && basename !== "/" ? basename : "/";
 }
 
+/**
+ * Resolve a soft (SPA/Flight) redirect target before it leaves the server.
+ *
+ * Soft redirects are 200/204 (`X-RSC-Redirect` / `metadata.redirect`), not 3xx,
+ * so they never hit `guardOutgoingRedirect`. This applies the same policy the
+ * 3xx guard uses: same-origin by default, `external` opts into http(s)-only
+ * off-host, anything else lands on {@link safeSameOriginLanding}. Returns the
+ * URL that should be written into the soft-redirect wire fields.
+ */
+export function resolveSoftRedirectUrl(
+  url: string,
+  requestOrigin: string,
+  basename: string | undefined,
+  external?: boolean,
+): string {
+  if (external) {
+    return (
+      resolveExternalRedirect(url, requestOrigin) ??
+      safeSameOriginLanding(basename)
+    );
+  }
+  return (
+    resolveSameOriginRedirect(url, requestOrigin) ??
+    safeSameOriginLanding(basename)
+  );
+}
+
 /**
  * Out-of-band brand for `redirect(url, { external: true })`.
  *

package/src/route-map-builder.ts

@@ -225,17 +225,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 the global merged
+  // trie — which contains routes from ALL routers and breaks multi-router
+  // setups.
+  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

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";
@@ -214,7 +217,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 +231,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 +243,10 @@ export function createHandlerContext<TEnv>(
 
   ctx = {
     params,
-    build: false,
+    build: requestContext?.build ?? false,
+    dynamic(): void {
+      requestContext?.dynamic();
+    },
     dev: false,
     request,
     searchParams,
@@ -345,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");
@@ -430,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/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/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,10 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope: snapshot.cacheScope,
+    // Shell fast path: a capture or an eligible HIT tail may substitute an
+    // implicit doc-level scope (marker-gated; a route-derived scope wins).
+    // Full matches only — partial navigations never serve a shell.
+    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
     isAction: false,

package/src/router/match-handlers.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { sanitizeError } from "../errors";
 import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
 import type {
@@ -291,7 +292,13 @@ export function createMatchHandlers<TEnv = any>(
           });
           emitter.start();
 
+          const ctxBuildStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
           const result = await createMatchContextForFull(request, env);
+          if (INTERNAL_RANGO_DEBUG) {
+            console.log(
+              `[Server][match] context built +${Math.round(performance.now() - ctxBuildStart)}ms (abs ${Math.round(performance.now())})`,
+            );
+          }
 
           if ("type" in result && result.type === "redirect") {
             emitter.end(0, false);
@@ -310,7 +317,13 @@ export function createMatchHandlers<TEnv = any>(
           try {
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
+            const pipeStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (INTERNAL_RANGO_DEBUG) {
+              console.log(
+                `[Server][match] pipeline collected +${Math.round(performance.now() - pipeStart)}ms (abs ${Math.round(performance.now())})`,
+              );
+            }
             if (hasTelemetry || cacheSignalEnabled) {
               const signalSegments = buildSignal(ctx.routeKey, state);
               recordSignalIfEnabled(signalSegments);

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

package/src/router/prerender-match.ts

@@ -21,6 +21,7 @@ import type { RouterContext } from "./router-context.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
+import type { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -74,6 +75,13 @@ export async function matchForPrerender<TEnv = any>(
    *  the sinks store it as-is (no longer merge raw records). */
   interceptHandles?: string;
   passthrough?: true;
+  /**
+   * The matched route entry's `ppr` path option, surfaced so the build
+   * collection can flag Prerender+ppr routes as build-time shell candidates
+   * (issue #699 producer B). Runtime-only today; the build otherwise never
+   * sees the option (it lives on EntryData, not the trie).
+   */
+  ppr?: boolean | PartialPrerenderProps;
 } | null> {
   // 1. Find the matching route entry
   const matched = await deps.findMatch(pathname);
@@ -198,6 +206,11 @@ export async function matchForPrerender<TEnv = any>(
       pathname,
       searchParams: new URLSearchParams(),
       _variables: variables,
+      build: true,
+      // Inert here: the prerender-collect / static-render pass has no live
+      // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
+      // live request or a shell capture.
+      dynamic: () => {},
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -306,6 +319,18 @@ export async function matchForPrerender<TEnv = any>(
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
 
+      // Surface the matched route entry's ppr option for the build collection
+      // (leaf-first: the deepest type:"route" entry in the ancestor chain is
+      // the matched page route; ancestors are layouts/includes).
+      let routePpr: boolean | PartialPrerenderProps | undefined;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i]!;
+        if (e.type === "route") {
+          routePpr = e.ppr;
+          break;
+        }
+      }
+
       // 14. Resolve intercept segments for this route (if any ancestor defines
       //     an intercept targeting this route). At build time we skip when()
       //     evaluation -- we pre-render all intercepts unconditionally and let
@@ -420,6 +445,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });
@@ -455,6 +481,8 @@ export async function renderStaticSegment<TEnv = any>(
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     _variables: {},
+    build: true,
+    dynamic: () => {},
     get: () => undefined as any,
     set: () => {},
     params: {},

package/src/router/router-interfaces.ts

@@ -6,6 +6,7 @@ import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
+import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
@@ -344,6 +345,12 @@ export interface RangoInternal<
    */
   readonly debugPerformance?: boolean;
 
+  /**
+   * PPR shell-capture debug sink (createRouter({ debugShellCapture })), read
+   * by rsc-rendering when it builds the capture descriptor for a ppr route.
+   */
+  readonly debugShellCapture?: ShellCaptureDebug;
+
   /**
    * Resolved platform phase-span tracing (Cloudflare custom spans or OTel), or
    * undefined when off. Threaded onto the request context and read at each
@@ -359,12 +366,6 @@ export interface RangoInternal<
    */
   readonly telemetry?: TelemetrySink;
 
-  /**
-   * Whether ?__debug_manifest is allowed in production.
-   * Always enabled in development.
-   */
-  readonly allowDebugManifest: boolean;
-
   /**
    * Resolved timeout configuration (merged from shorthand + structured).
    */

package/src/router/router-options.ts

@@ -6,6 +6,7 @@ import type {
   OnErrorCallback,
 } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
+import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
@@ -125,14 +126,6 @@ export interface RangoOptions<TEnv = any> {
    */
   debugPerformance?: boolean;
 
-  /**
-   * Allow the `?__debug_manifest` query parameter to return route manifest data as JSON.
-   * In development mode this is always enabled regardless of this setting.
-   * Defaults to false. Set to true to enable in production.
-   * @internal
-   */
-  allowDebugManifest?: boolean;
-
   /**
    * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
    * the cache status of the matched route, for use by testing primitives such
@@ -148,6 +141,18 @@ export interface RangoOptions<TEnv = any> {
    */
   debugCacheSignal?: boolean;
 
+  /**
+   * Debug sink for the PPR shell-capture pipeline (routes with the `ppr` path
+   * option). `true` logs one structured line per capture attempt/skip to
+   * console (visible via `wrangler tail`); a function receives each
+   * `ShellCaptureDebugEvent` (outcome per attempt, snapshot bytes,
+   * write-barrier wait, backoff state) for programmatic capture. Off by
+   * default; the events also mirror into the dev Server-Timing surface when
+   * `debugPerformance` is on. Intended for validating capture behavior on a
+   * real deployment, not steady-state production.
+   */
+  debugShellCapture?: ShellCaptureDebug;
+
   /**
    * Document component that wraps the entire application.
    *