@rangojs/router 0.17.0 → 0.19.0

package/src/rsc/shell-serve.ts

@@ -18,20 +18,32 @@
 
 import React from "react";
 import { isPprEntry, type EntryData } from "../server/context.js";
-import { sortedSearchString } from "../cache/cache-key-utils.js";
-import type { SearchParamsFilter } from "../cache/search-params-filter.js";
+import { base64ToBytes } from "../cache/cf/cf-base64.js";
 import type {
   DocumentShellCacheEntry,
   ShellCacheEntry,
+  ShellDocumentRead,
+  ShellEntryHead,
+  ShellReadStats,
+  ShellSnapshotFailure,
+  ShellSnapshotRecord,
   SegmentCacheStore,
 } from "../cache/types.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
+import {
+  SHELL_CAPTURE_MAX_WAIT_MS,
+  hasWarnedOnce,
+  resetShellWarningsForTests,
+  warnOnce,
+} from "./shell-capture-constants.js";
 
-/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
-export const SHELL_STATUS_HEADER = "x-rango-shell";
-
-/** Partial-navigation status header set only after captured PPR segments are consumed. */
-export const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+export {
+  PPR_REPLAY_STATUS_HEADER,
+  SHELL_STATUS_HEADER,
+  buildShellKey,
+  navigationShellKey,
+  partitionShellKey,
+  shellSearchSeed,
+} from "./shell-capture-constants.js";
 
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
@@ -115,36 +127,59 @@ export function resolvePprConfig(
 }
 
 /**
- * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
- * (so it can never collide with a document-cache key; the store further isolates
- * the shell family internally).
- *
- * The key includes the request HOST: in a multi-tenant host-router deployment
- * (one worker, one shared KV/runtime-cache store) a host-less key would serve
- * tenant A's captured shell to tenant B's users.
- *
- * `filter` is the request's compiled `cache.searchParams` config
- * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
- * Callers on the serve/capture path MUST pass it -- key drift between capture
- * and lookup makes every shell request a permanent miss.
+ * The forced-MISS query marker. A document HIT that cannot finish its tail
+ * reloads the page with it (shellReloadScript); the serve gate renders a
+ * request carrying it on axis 1, with no shell read and no capture, so the
+ * reload can never be a HIT that degrades again. The handler drops it from
+ * the request on entry (withoutShellMissMarker) and keeps only the flag
+ * (RequestContext._shellForcedMiss), so nothing else sees it.
+ */
+export const SHELL_MISS_PARAM: string = "_rsc_shell";
+
+/**
+ * The request without the forced-MISS marker, or undefined when it carries
+ * none. The handler calls it before anything reads the request: left in, the
+ * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
+ * built from the request URL was never read again. GET and HEAD only: the
+ * reload is a navigation, and a request with a body cannot be re-created
+ * without re-streaming it. The substring test keeps the URL parse off every
+ * other request.
+ */
+export function withoutShellMissMarker(request: Request): Request | undefined {
+  if (!request.url.includes(SHELL_MISS_PARAM)) return undefined;
+  if (request.method !== "GET" && request.method !== "HEAD") return undefined;
+  const url = new URL(request.url);
+  if (!url.searchParams.has(SHELL_MISS_PARAM)) return undefined;
+  url.searchParams.delete(SHELL_MISS_PARAM);
+  return new Request(url, request);
+}
+
+/**
+ * The inline script a degraded document HIT ends with: reload once into a
+ * forced MISS. The marker in the URL is the loop bound — a request carrying
+ * it is never a HIT, so this script never runs on the reload, and if it ever
+ * did (a server that ignores the marker) it would return without touching
+ * the page. window.stop() runs only when it reloads: it keeps the half-sent
+ * Flight stream from being closed by DOMContentLoaded, which would throw
+ * React's "Connection closed" (#412) before the reload lands.
  */
-export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
-  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+export function shellReloadScript(): string {
+  return inlineShellScript(
+    "(function(){var u=new URL(location.href);" +
+      `if(u.searchParams.has(${JSON.stringify(SHELL_MISS_PARAM)}))return;` +
+      `u.searchParams.set(${JSON.stringify(SHELL_MISS_PARAM)},"miss");` +
+      "try{window.stop()}catch(e){}location.replace(u.href)})()",
+  );
 }
 
 /**
- * The shell key's search portion (`?`-prefixed sorted search with the
- * cache.searchParams filter applied, or "") — ALSO the string the capture and
- * resume SSR renders seed their store location with (SSRRenderOptions.search
- * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
- * of shell identity, so static-part `useSearchParams` reads render exactly
- * what the key names; deriving seed and key from this one helper is what
- * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
- * permanent MISS).
+ * An inline script a shell HIT's tail appends. It carries no CSP nonce: a
+ * request with an active per-request nonce never reaches a HIT
+ * (rsc-rendering.ts shellServePlan serves it on axis 1).
  */
-export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
-  const sorted = sortedSearchString(url.searchParams, filter);
-  return sorted ? `?${sorted}` : "";
+export function inlineShellScript(body: string): string {
+  return `<script>${body}</script>`;
 }
 
 /**
@@ -153,12 +188,10 @@ export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
  * one exact tree, so resuming it under a different React OR a different app
  * build tree-mismatches inside resume() — after the 200 + prelude committed,
  * with no recovery. Either mismatch is a miss: the recapture overwrites the
- * same key (self-healing) and the entry otherwise ages out via TTL. An entry
- * with no buildVersion (stored before the field existed) is a miss for the
- * same reason — its build is unknown, so it cannot be proven resumable.
+ * same key (self-healing) and the entry otherwise ages out via TTL.
  */
 export function isValidShellHit(
-  entry: ShellCacheEntry,
+  entry: Pick<ShellCacheEntry, "reactVersion" | "buildVersion">,
   buildVersion: string,
 ): boolean {
   return (
@@ -166,17 +199,25 @@ export function isValidShellHit(
   );
 }
 
+/** The postponed blob is stored and parses (null is the DATA variant). */
+function hasParseablePostponed<T extends ShellEntryHead>(
+  entry: T,
+): entry is T & { postponed: string | null } {
+  if (entry.postponed === undefined) return false;
+  try {
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
- * DOCUMENT-half integrity gate and type narrowing, run BEFORE the HIT response
- * commits: a stored entry whose prelude is not decodable base64 or whose
- * postponed blob is not parseable JSON would otherwise throw AFTER the 200 +
- * full static prelude flushed (`serveShellHit` decodes at stream construction,
- * `resumeShellHTML` parses in the tail) — the client gets a visually complete
- * page that never hydrates, re-served on every request until the entry ages
- * out (no eviction path exists; failure schedules no recapture by itself).
- * Checking here turns a corrupt entry (store-layer fault) into a plain MISS
- * the recapture overwrites. Cost: one duplicate decode/parse per HIT, sub-ms
- * against a prelude flush that dominates the path.
+ * DOCUMENT-half structural gate and type narrowing, without decoding the
+ * prelude: the prelude is a string and the postponed blob parses. Partial
+ * replay (which never serves the prelude) and the build-manifest read-through
+ * use it as-is; the document HIT path runs it inside
+ * {@link openShellDocument}, whose single decode is the prelude's check.
  *
  * navigationOnly entries store no document half (prelude/postponed absent) and
  * therefore never pass. The partial-replay path skips this gate for them
@@ -187,25 +228,92 @@ export function isValidShellHit(
 export function hasIntactShellPayload(
   entry: ShellCacheEntry,
 ): entry is DocumentShellCacheEntry {
-  if (typeof entry.prelude !== "string" || entry.postponed === undefined) {
-    return false;
+  return typeof entry.prelude === "string" && hasParseablePostponed(entry);
+}
+
+/** A document shell ready to serve: its prelude decoded exactly once. */
+export interface ShellDocument {
+  entry: ShellEntryHead;
+  prelude: Uint8Array;
+  /** React's postponed state, parse-checked (null = DATA variant). */
+  postponed: string | null;
+  /**
+   * The capture snapshot: on the entry, or still arriving on its own promise
+   * after a prelude-first read (SegmentCacheStore.readShellDocument), which
+   * only the tail awaits.
+   */
+  snapshot: ShellSnapshotRecord[] | Promise<ShellSnapshotRecord[] | undefined>;
+  /** Why a prelude-first read's snapshot is missing (ShellDocumentRead). */
+  snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+  /** The prelude-first read's stats, when perf metrics are on. */
+  stats?: ShellReadStats;
+}
+
+/**
+ * Pre-commit integrity gate for a document HIT, and its only prelude decode.
+ * A stored entry whose prelude is not decodable base64 or whose postponed blob
+ * is not parseable JSON would otherwise throw AFTER the 200 + full static
+ * prelude flushed (`resumeShellHTML` parses in the tail) — the client gets a
+ * visually complete page that never hydrates, re-served on every request
+ * until the entry ages out. Returning null here turns a corrupt entry
+ * (store-layer fault) into a plain MISS the recapture overwrites. The decoded
+ * bytes are what serveShellHit enqueues, so the check costs no second decode.
+ * A prelude-first `read` (SegmentCacheStore.readShellDocument) already carries
+ * the raw bytes and a pending snapshot, so only its postponed blob is checked.
+ */
+export function openShellDocument(entry: ShellCacheEntry): ShellDocument | null;
+export function openShellDocument(
+  entry: ShellEntryHead,
+  read: Pick<
+    ShellDocumentRead,
+    "prelude" | "snapshot" | "snapshotFailure" | "stats"
+  >,
+): ShellDocument | null;
+export function openShellDocument(
+  entry: ShellEntryHead | ShellCacheEntry,
+  read?: Pick<
+    ShellDocumentRead,
+    "prelude" | "snapshot" | "snapshotFailure" | "stats"
+  >,
+): ShellDocument | null {
+  if (read) {
+    if (!hasParseablePostponed(entry)) return null;
+    return {
+      entry,
+      postponed: entry.postponed,
+      prelude: read.prelude,
+      snapshot: read.snapshot,
+      ...(read.snapshotFailure && { snapshotFailure: read.snapshotFailure }),
+      ...(read.stats && { stats: read.stats }),
+    };
   }
+  // The read-less overload takes a whole entry (getShell, a build shell).
+  const whole = entry as ShellCacheEntry;
+  if (!hasIntactShellPayload(whole)) return null;
+  let prelude: Uint8Array;
   try {
-    base64ToBytes(entry.prelude);
-    if (entry.postponed !== null) JSON.parse(entry.postponed);
-    return true;
+    prelude = base64ToBytes(whole.prelude);
   } catch {
-    return false;
+    return null;
   }
+  return {
+    entry: whole,
+    postponed: whole.postponed,
+    prelude,
+    snapshot: whole.snapshot,
+  };
 }
 
-/** Decode a base64 prelude back into bytes for stream composition. */
-export function base64ToBytes(b64: string): Uint8Array {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
+/**
+ * Prelude enqueue granularity. A streaming compressor in front of the worker
+ * emits its first byte only after compressing the whole write it was handed:
+ * one 629 KB enqueue delayed the first compressed byte by the full prelude's
+ * compression time (brotli-6 5.1 ms, gzip-6 1.1 ms in Node zlib with a flush
+ * per write; workerd's CompressionStream emits nothing until the whole write is
+ * compressed), while 32 KB chunks emit within 0.1 ms and cost slightly more
+ * in total compression (0.55-0.70 ms) than one write (issue #941).
+ */
+export const SHELL_PRELUDE_CHUNK_BYTES: number = 32 * 1024;
 
 /** True when the store implements the shell entry family. */
 export function hasShellFamily(
@@ -227,8 +335,22 @@ export function hasShellFamily(
 export interface ShellTailTiming {
   key: string;
   outcome: "complete" | "redirect" | "error";
+  /** The capture snapshot available to the tail (read and parsed). */
+  snapshotMs?: number;
+  /** Snapshot bytes read after the commit (prelude-first stores). */
+  snapshotBytes?: number;
+  /** Snapshot bytes read after the commit, excluding the parse. */
+  snapshotReadMs?: number;
+  /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
+  snapshotParseMs?: number;
+  /** Snapshot records by family, e.g. `segment:1/loader:2` (no commas: it rides a Server-Timing desc). */
+  snapshotRecords?: string;
+  /** Records the capture pruned from the snapshot, same format (ShellCacheEntry.prunedRecords). */
+  snapshotPruned?: string;
   /** Loader-family seed decode (only when the entry carried a snapshot). */
   seedMs?: number;
+  /** The seed decode's own duration: Flight deserialization, CPU only. */
+  seedCpuMs?: number;
   /** Tail router.match() settled. */
   matchMs?: number;
   /** Tail stream (resume output) handed to the response stream. */
@@ -244,13 +366,35 @@ export interface ShellTailTiming {
 }
 
 /**
- * Compact single-line form for the console log and the dev Server-Timing
- * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
- * escaping needed.
+ * Compact single-line form for the console log and the Server-Timing mirror's
+ * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1/loader:2 pruned=loader:1),
+ * so no quoted-string escaping is needed. Offsets are from the commit; the
+ * `-cpu` fields are CPU-only durations.
  */
 export function describeShellTailTiming(timing: ShellTailTiming): string {
   const parts: string[] = [timing.outcome];
+  if (timing.snapshotMs !== undefined) {
+    parts.push(`snapshot=${timing.snapshotMs}ms`);
+  }
+  if (timing.snapshotReadMs !== undefined) {
+    parts.push(`snapshot-read=${timing.snapshotReadMs}ms`);
+  }
+  if (timing.snapshotBytes !== undefined) {
+    parts.push(`snapshot-bytes=${timing.snapshotBytes}b`);
+  }
+  if (timing.snapshotParseMs !== undefined) {
+    parts.push(`snapshot-parse-cpu=${timing.snapshotParseMs}ms`);
+  }
+  if (timing.snapshotRecords !== undefined) {
+    parts.push(`records=${timing.snapshotRecords}`);
+  }
+  if (timing.snapshotPruned !== undefined) {
+    parts.push(`pruned=${timing.snapshotPruned}`);
+  }
   if (timing.seedMs !== undefined) parts.push(`seed=${timing.seedMs}ms`);
+  if (timing.seedCpuMs !== undefined) {
+    parts.push(`seed-cpu=${timing.seedCpuMs}ms`);
+  }
   if (timing.matchMs !== undefined) parts.push(`match=${timing.matchMs}ms`);
   if (timing.handoverMs !== undefined) {
     parts.push(`handover=${timing.handoverMs}ms`);
@@ -269,19 +413,19 @@ export function describeShellTailTiming(timing: ShellTailTiming): string {
 }
 
 /**
- * Dev-only last-tail-per-key buffer backing the `ppr:tail` Server-Timing
- * mirror: a HIT's tail finishes after its own headers are long gone, so its
- * per-stage numbers ride the NEXT ppr GET for the key when the metrics
- * surface is active (debugPerformance). Same shape and FIFO cap as the
- * capture mirror (shell-capture.ts lastCaptureEventsForTiming); dev-only so
- * production isolates never grow the map.
+ * Last-tail-per-key buffer backing the `ppr:tail` Server-Timing mirror: a
+ * HIT's tail finishes after its own headers are long gone, so its per-stage
+ * numbers ride the NEXT ppr GET for the key when the metrics surface is
+ * active (debugPerformance). Same shape and FIFO cap as the capture mirror
+ * (shell-capture.ts lastCaptureEventsForTiming). serveShellHit collects and
+ * publishes a timing only in dev or when the HIT itself collected metrics, so
+ * a production isolate without debugPerformance never grows the map.
  */
 const lastTailTimingsForServerTiming = new Map<string, ShellTailTiming>();
 const MAX_TAIL_TIMING_KEYS = 100;
 
-/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+/** Buffer one terminal tail timing for the Server-Timing mirror. */
 export function publishShellTailTiming(timing: ShellTailTiming): void {
-  if (process.env.NODE_ENV === "production") return;
   lastTailTimingsForServerTiming.delete(timing.key);
   if (lastTailTimingsForServerTiming.size >= MAX_TAIL_TIMING_KEYS) {
     const oldest = lastTailTimingsForServerTiming.keys().next().value;
@@ -302,9 +446,6 @@ export function takeShellTailTimingForServerTiming(
   return timing;
 }
 
-/** Keys already warned about a missing shell store family (once per key). */
-const warnedMissingStore = new Set<string>();
-
 /**
  * Warn once per key that a route declared `ppr` but the app-level cache store
  * does not implement the shell family (getShell/putShell), so the route stays on
@@ -312,10 +453,11 @@ const warnedMissingStore = new Set<string>();
  * honored deserves a diagnostic.
  */
 export function warnShellStoreMissingOnce(key: string): void {
-  if (warnedMissingStore.has(key)) return;
-  warnedMissingStore.add(key);
-  console.warn(
-    `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
+  warnOnce(
+    "store-missing",
+    key,
+    () =>
+      `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
       "cache store does not implement the shell family (getShell/putShell), so " +
       "the route is served on axis 1 without a shell. Use MemorySegmentCacheStore, " +
       "CFCacheStore, or VercelCacheStore (or add the family to your custom store) " +
@@ -323,9 +465,6 @@ export function warnShellStoreMissingOnce(key: string): void {
   );
 }
 
-/** Keys already warned about an active per-request nonce (once per key). */
-const warnedNonceActive = new Set<string>();
-
 /**
  * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
  * active for the request, so the route stays on axis 1 (a shared shell would
@@ -337,10 +476,11 @@ const warnedNonceActive = new Set<string>();
  * the missing-store warning above (an undeclared route stays silent).
  */
 export function warnPprNonceActiveOnce(key: string): void {
-  if (warnedNonceActive.has(key)) return;
-  warnedNonceActive.add(key);
-  console.warn(
-    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+  warnOnce(
+    "nonce-active",
+    key,
+    () =>
+      `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
       "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
       "ctx.set(nonce, …) token write in middleware), so the route is served on " +
       "axis 1 without a shell. A shell is shared per host+URL; baking one " +
@@ -348,3 +488,109 @@ export function warnPprNonceActiveOnce(key: string): void {
       "ppr option on this route, or stop setting a per-request nonce for it.",
   );
 }
+
+/**
+ * Dev only (the caller gates on NODE_ENV): warn once per route that the
+ * route's cache() entry reduces an explicit `ppr.ttl` or `ppr.swr`. `shell`
+ * is what the capture stores for a record written just now
+ * (shell-capture.ts capShellWindow), so the message states the values the
+ * shell actually gets. A ppr value the cap leaves whole (or raises: the
+ * cap can move a record's stale time into the shell's swr) is silent, and
+ * so is a ppr config that sets no ttl/swr.
+ */
+export function warnPprWindowCappedOnce(
+  routeName: string,
+  ppr: { ttl?: number; swr?: number },
+  shell: { ttl: number; swr: number },
+  cache: { ttl: number; swr: number },
+): void {
+  if (hasWarnedOnce("ppr-window-capped", routeName)) return;
+  const reduced: string[] = [];
+  for (const field of ["ttl", "swr"] as const) {
+    const own = ppr[field];
+    if (own !== undefined && shell[field] < own) {
+      reduced.push(`ppr.${field} ${own}`);
+    }
+  }
+  if (reduced.length === 0) return;
+  warnOnce(
+    "ppr-window-capped",
+    routeName,
+    () =>
+      `[rango] Route "${routeName}": its shell is stored with ttl ${shell.ttl} ` +
+      `and swr ${shell.swr}, below its ${reduced.join(" and ")}. A shell ` +
+      `never outlives the route cache() entry (ttl ${cache.ttl}, swr ` +
+      `${cache.swr}) it was captured from, so a document request and a ` +
+      "client navigation show the same handler output. Keep ppr.ttl within " +
+      "the cache() ttl, and ppr.ttl + ppr.swr within the cache() ttl + swr, " +
+      "to silence this.",
+  );
+}
+
+/**
+ * Paths a partitioned request found without a build shell. Build shells are
+ * per path (a param route prerenders some of its paths), so a negative is
+ * kept per path, not per route; cleared when full, so it stays bounded.
+ */
+const pathsWithoutBuildShell = new Set<string>();
+const PATHS_WITHOUT_BUILD_SHELL_MAX = 1_000;
+
+/**
+ * Whether a partitioned request needs no build-shell probe: its route was
+ * already warned, or its path was already found without one.
+ */
+export function partitionBuildShellCheckDone(
+  pathname: string,
+  routeName: string | undefined,
+): boolean {
+  return (
+    hasWarnedOnce("partition-build-shell", routeName ?? pathname) ||
+    pathsWithoutBuildShell.has(pathname)
+  );
+}
+
+/**
+ * Record a partitioned request's build-shell probe, and warn once per route
+ * when it found one: the route has a build-time shell its requests cannot
+ * read. The route's request partition (a `cache({ key })` enclosing it, at
+ * any depth (#970), or the store's keyGenerator) keys the shell per
+ * partition, and the build captured only
+ * the default one, so each partition captures at runtime. Same
+ * declared-intent-cannot-be-honored doctrine as the warnings above; a path
+ * with no build shell stays silent.
+ */
+export function notePartitionBuildShellCheck(
+  pathname: string,
+  routeName: string | undefined,
+  found: boolean,
+): void {
+  if (!found) {
+    if (pathsWithoutBuildShell.size >= PATHS_WITHOUT_BUILD_SHELL_MAX) {
+      pathsWithoutBuildShell.clear();
+    }
+    pathsWithoutBuildShell.add(pathname);
+    return;
+  }
+  // Concurrent first requests can both probe; one of them warns.
+  warnOnce(
+    "partition-build-shell",
+    routeName ?? pathname,
+    () =>
+      `[rango] Route ${routeName ? `"${routeName}" ` : ""}("${pathname}") has a ` +
+      "build-time shell, but its request partition (a cache({ key }) enclosing the route, " +
+      "or the store's keyGenerator) keys its shell per partition, so the build " +
+      "shell is not served and each partition captures its own at runtime. A " +
+      "keyGenerator that returns the default key unchanged keeps the build shell.",
+  );
+}
+
+/**
+ * @internal Reset the serve path's once-per-key warnings (the shell path's
+ * one registry), its build-shell probe memo and buffered tail timings. Tests
+ * only (testing/serve-shell-request.ts resetShellTestState).
+ */
+export function resetShellServeStateForTests(): void {
+  resetShellWarningsForTests();
+  pathsWithoutBuildShell.clear();
+  lastTailTimingsForServerTiming.clear();
+}

package/src/rsc/ssr-setup.ts

@@ -6,6 +6,7 @@
  * matching, so they can run in parallel with segment resolution.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { SSRModule, SSRRenderOptions } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
@@ -183,7 +184,7 @@ export function getSSRSetup<TEnv>(
  */
 function acceptsFlightExplicitly(request: Request, url: URL): boolean {
   if (url.searchParams.has("__html")) return false;
-  const accept = request.headers.get("accept");
+  const accept = requestHeaders(request).get("accept");
   if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
   return prefersFlightRepresentation(parseAcceptTypes(accept));
 }
@@ -206,7 +207,7 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
   if (
     url.searchParams.has("_rsc_partial") ||
     url.searchParams.has("_rsc_action") ||
-    request.headers.has("rsc-action") ||
+    requestHeaders(request).has("rsc-action") ||
     url.searchParams.has("_rsc_loader") ||
     url.searchParams.has("__rsc")
   ) {

package/src/rsc/types.ts

@@ -34,6 +34,8 @@ export interface RscPayload {
     resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
+    /** Matched route name, when named (transition({ when }) route names). */
+    routeName?: string;
     slots?: Record<string, SlotState>;
     /**
      * Intercept TARGET route names reachable from this location as a
@@ -228,6 +230,13 @@ export interface SSRModule {
       origin?: string;
       /** Each component error the prerender reports (never the capture's own abort). */
       onError?: (error: unknown) => void;
+      /**
+       * React's errorInfo for each task still pending at the capture's abort
+       * (its componentStack is computed when read).
+       */
+      onAbortedTask?: (
+        errorInfo: { componentStack?: string } | undefined,
+      ) => void;
     },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 

package/src/segment-system.tsx

@@ -125,6 +125,14 @@ export interface RenderSegmentsOptions {
   /** Seeded descendant client-route pending state for testing. */
   outletPending?: boolean;
 
+  /**
+   * This commit's transition({ when }) decision was false
+   * (browser/transition-when.ts): the navigation is urgent, so no segment
+   * animates. Every router <ViewTransition> stays in the tree with each class
+   * "none", so the element type never changes; keys never read this (#995).
+   */
+  transitionGatedOff?: boolean;
+
   /**
    * Intercept segments to inject into the tree.
    * These are parallel segments from intercept routes that need to be
@@ -143,13 +151,31 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+/**
+ * On a gated-off commit every segment keeps its <ViewTransition> so the
+ * element type never changes with a per-navigation `transition({ when })`
+ * decision (#995), but animates nothing: "none" for every class, whatever the
+ * transition type.
+ */
+const GATED_OFF_CLASSES = {
+  enter: "none",
+  exit: "none",
+  update: "none",
+  share: "none",
+  default: "none",
+} as const;
+
 function createViewTransitionBoundary(
   transition: NonNullable<ResolvedSegment["transition"]>,
   children: ReactNode,
 ): ReactNode {
-  // `viewTransition` is a router-specific flag (boundary opt-out), not a React
-  // <ViewTransition> prop — strip it so it never reaches React.
-  const { viewTransition: _viewTransition, ...vtProps } = transition;
+  // `viewTransition` (boundary opt-out) and `when` (the browser-run gate) are
+  // router fields, not React <ViewTransition> props — strip them.
+  const {
+    viewTransition: _viewTransition,
+    when: _when,
+    ...vtProps
+  } = transition;
   return createElement(ReactViewTransition, {
     ...vtProps,
     // The commit after an optimistic clientUrls() presentation repaints the
@@ -306,6 +332,7 @@ export async function renderSegments(
     forceAwait,
     outletPending = false,
     rootLayout: RootLayout,
+    transitionGatedOff,
   } = options || {};
 
   const segDebug = INTERNAL_RANGO_DEBUG;
@@ -358,8 +385,11 @@ export async function renderSegments(
   // same-route navigation reconciles (holds content) instead of remounting. The
   // value is a static property of the route's position in the tree, so it is the
   // same on every render of that route (SSR, navigation, action) — the keys
-  // never drift. Cross-route navigation still remounts: different routes have
-  // different segment ids regardless of transition scope.
+  // never drift. It reads the static `transition` config only, never the
+  // per-navigation `when` decision (transitionGatedOff): a server-side `when`
+  // used to delete `transition`, which flipped this value and remounted the
+  // route twice (#995). Cross-route navigation still remounts: different routes
+  // have different segment ids regardless of transition scope.
   const inTransitionScope = normalizedSegments.some(
     (s) =>
       s.transition != null &&
@@ -522,10 +552,13 @@ export async function renderSegments(
       transition &&
       transition.viewTransition !== false
     ) {
+      const boundary = transitionGatedOff
+        ? { ...transition, ...GATED_OFF_CLASSES }
+        : transition;
       if (node.segment.type === "layout") {
-        outletContent = wrapDefaultOutletContent(outletContent, transition);
+        outletContent = wrapDefaultOutletContent(outletContent, boundary);
       } else {
-        nodeContent = createViewTransitionBoundary(transition, nodeContent);
+        nodeContent = createViewTransitionBoundary(boundary, nodeContent);
       }
     }