@rangojs/router 0.18.0 → 0.19.0

package/src/rsc/shell-serve.ts

@@ -18,26 +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 { getNonceAttribute } from "../theme/theme-script.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";
-
-/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
-export const SHELL_STATUS_HEADER = "x-rango-shell";
+import {
+  SHELL_CAPTURE_MAX_WAIT_MS,
+  hasWarnedOnce,
+  resetShellWarningsForTests,
+  warnOnce,
+} from "./shell-capture-constants.js";
 
-/** 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
@@ -120,29 +126,6 @@ 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.
- */
-export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
-  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
-}
-
-export {
-  navigationShellKey,
-  partitionShellKey,
-} from "./shell-capture-constants.js";
-
 /**
  * The forced-MISS query marker. A document HIT that cannot finish its tail
  * reloads the page with it (shellReloadScript); the serve gate renders a
@@ -179,38 +162,24 @@ export function withoutShellMissMarker(request: Request): Request | undefined {
  * 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. `nonce` is the
- * request's CSP nonce; a ppr route with an active nonce is axis 1
- * (rsc-rendering.ts shellServePlan), so on a HIT it is normally absent.
+ * React's "Connection closed" (#412) before the reload lands.
  */
-export function shellReloadScript(nonce?: string): string {
+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)})()",
-    nonce,
   );
 }
 
-/** An inline script a shell HIT's tail appends, carrying the CSP nonce if any. */
-export function inlineShellScript(body: string, nonce?: string): string {
-  return `<script${getNonceAttribute(nonce)}>${body}</script>`;
-}
-
 /**
- * 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>`;
 }
 
 /**
@@ -219,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 (
@@ -233,9 +200,9 @@ export function isValidShellHit(
 }
 
 /** The postponed blob is stored and parses (null is the DATA variant). */
-function hasParseablePostponed(
-  entry: ShellCacheEntry,
-): entry is ShellCacheEntry & { postponed: string | null } {
+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);
@@ -266,7 +233,7 @@ export function hasIntactShellPayload(
 
 /** A document shell ready to serve: its prelude decoded exactly once. */
 export interface ShellDocument {
-  entry: ShellCacheEntry;
+  entry: ShellEntryHead;
   prelude: Uint8Array;
   /** React's postponed state, parse-checked (null = DATA variant). */
   postponed: string | null;
@@ -275,10 +242,7 @@ export interface ShellDocument {
    * after a prelude-first read (SegmentCacheStore.readShellDocument), which
    * only the tail awaits.
    */
-  snapshot:
-    | ShellSnapshotRecord[]
-    | undefined
-    | Promise<ShellSnapshotRecord[] | undefined>;
+  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. */
@@ -297,8 +261,16 @@ export interface ShellDocument {
  * 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: ShellCacheEntry,
+  entry: ShellEntryHead,
+  read: Pick<
+    ShellDocumentRead,
+    "prelude" | "snapshot" | "snapshotFailure" | "stats"
+  >,
+): ShellDocument | null;
+export function openShellDocument(
+  entry: ShellEntryHead | ShellCacheEntry,
   read?: Pick<
     ShellDocumentRead,
     "prelude" | "snapshot" | "snapshotFailure" | "stats"
@@ -315,18 +287,20 @@ export function openShellDocument(
       ...(read.stats && { stats: read.stats }),
     };
   }
-  if (!hasIntactShellPayload(entry)) return null;
+  // 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 {
-    prelude = base64ToBytes(entry.prelude);
+    prelude = base64ToBytes(whole.prelude);
   } catch {
     return null;
   }
   return {
-    entry,
-    postponed: entry.postponed,
+    entry: whole,
+    postponed: whole.postponed,
     prelude,
-    snapshot: entry.snapshot,
+    snapshot: whole.snapshot,
   };
 }
 
@@ -369,7 +343,7 @@ export interface ShellTailTiming {
   snapshotReadMs?: number;
   /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
   snapshotParseMs?: number;
-  /** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+  /** 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;
@@ -393,7 +367,7 @@ export interface ShellTailTiming {
 
 /**
  * Compact single-line form for the console log and the Server-Timing mirror's
- * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1 pruned=item:5),
+ * `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.
  */
@@ -472,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
@@ -482,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) " +
@@ -493,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
@@ -507,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 " +
@@ -519,9 +489,6 @@ export function warnPprNonceActiveOnce(key: string): void {
   );
 }
 
-/** Routes already warned about a ppr window the route cache() caps. */
-const warnedPprWindowCapped = new Set<string>();
-
 /**
  * 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`
@@ -537,7 +504,7 @@ export function warnPprWindowCappedOnce(
   shell: { ttl: number; swr: number },
   cache: { ttl: number; swr: number },
 ): void {
-  if (warnedPprWindowCapped.has(routeName)) return;
+  if (hasWarnedOnce("ppr-window-capped", routeName)) return;
   const reduced: string[] = [];
   for (const field of ["ttl", "swr"] as const) {
     const own = ppr[field];
@@ -546,9 +513,11 @@ export function warnPprWindowCappedOnce(
     }
   }
   if (reduced.length === 0) return;
-  warnedPprWindowCapped.add(routeName);
-  console.warn(
-    `[rango] Route "${routeName}": its shell is stored with ttl ${shell.ttl} ` +
+  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 ` +
@@ -558,9 +527,6 @@ export function warnPprWindowCappedOnce(
   );
 }
 
-/** Routes (or paths) already warned that a partition skips their build shell. */
-const partitionBuildShellWarned = new Set<string>();
-
 /**
  * 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
@@ -578,7 +544,7 @@ export function partitionBuildShellCheckDone(
   routeName: string | undefined,
 ): boolean {
   return (
-    partitionBuildShellWarned.has(routeName ?? pathname) ||
+    hasWarnedOnce("partition-build-shell", routeName ?? pathname) ||
     pathsWithoutBuildShell.has(pathname)
   );
 }
@@ -606,11 +572,11 @@ export function notePartitionBuildShellCheck(
     return;
   }
   // Concurrent first requests can both probe; one of them warns.
-  const route = routeName ?? pathname;
-  if (partitionBuildShellWarned.has(route)) return;
-  partitionBuildShellWarned.add(route);
-  console.warn(
-    `[rango] Route ${routeName ? `"${routeName}" ` : ""}("${pathname}") has a ` +
+  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 " +
@@ -619,14 +585,12 @@ export function notePartitionBuildShellCheck(
 }
 
 /**
- * @internal Reset the serve path's once-per-key warnings and buffered tail
- * timings. Tests only (testing/serve-shell-request.ts resetShellTestState).
+ * @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 {
-  warnedMissingStore.clear();
-  warnedNonceActive.clear();
-  partitionBuildShellWarned.clear();
+  resetShellWarningsForTests();
   pathsWithoutBuildShell.clear();
-  warnedPprWindowCapped.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

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);
       }
     }