@rangojs/router 0.1.1 → 0.2.0

package/src/rsc/rsc-rendering.ts

@@ -40,6 +40,7 @@ import {
   type ShellCaptureDescriptor,
 } from "./shell-capture.js";
 import {
+  PPR_REPLAY_STATUS_HEADER,
   SHELL_STATUS_HEADER,
   resolvePprConfig,
   buildShellKey,
@@ -69,6 +70,42 @@ import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type { ShellCacheEntry, ShellSnapshotRecord } from "../cache/types.js";
 
+type PprReplayBypassReason =
+  | "method"
+  | "dynamic"
+  | "nonce"
+  | "store-unavailable"
+  | "passive-read-unsupported"
+  | "read-error"
+  | "no-entry"
+  | "invalid-version"
+  | "corrupt-entry"
+  | "handler-live-holes"
+  | "transition-when"
+  | "no-segment-snapshot"
+  | "snapshot-miss"
+  | "stale-build-entry";
+
+type PprReplayStatus =
+  | { outcome: "HIT"; freshness: "fresh" | "stale" }
+  | { outcome: "BYPASS"; reason: PprReplayBypassReason };
+
+type ShellReplayDecision =
+  | { snapshot: ShellSnapshotRecord[] }
+  | { reason: PprReplayBypassReason };
+
+function serializePprReplayStatus(status: PprReplayStatus): string {
+  return status.outcome === "HIT"
+    ? `HIT; freshness=${status.freshness}`
+    : `BYPASS; reason=${status.reason}`;
+}
+
+function describePprReplayStatus(status: PprReplayStatus): string {
+  return status.outcome === "HIT"
+    ? status.freshness
+    : `bypass:${status.reason}`;
+}
+
 function resolveDevShellLookup(
   reqCtx: RequestContext<any>,
   pprConfig: ResolvedPprConfig,
@@ -86,17 +123,15 @@ function resolveDevShellLookup(
 }
 
 function replayableShellSnapshot(
-  entry: ShellCacheEntry | undefined,
+  entry: ShellCacheEntry,
   buildVersion: string,
-): ShellSnapshotRecord[] | undefined {
-  if (
-    !entry ||
-    !isValidShellHit(entry, buildVersion) ||
-    entry.handlerLiveHoles ||
-    entry.transitionWhen
-  ) {
-    return undefined;
+): ShellReplayDecision {
+  if (!isValidShellHit(entry, buildVersion)) {
+    return { reason: "invalid-version" };
   }
+  if (!hasIntactShellPayload(entry)) return { reason: "corrupt-entry" };
+  if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
+  if (entry.transitionWhen) return { reason: "transition-when" };
   const snapshot = entry.snapshot;
   const hasSegments = snapshot?.some((record) => {
     if (
@@ -111,7 +146,9 @@ function replayableShellSnapshot(
     const segments = (record.value as { segments?: unknown }).segments;
     return Array.isArray(segments) && segments.length > 0;
   });
-  return hasSegments ? snapshot : undefined;
+  return hasSegments && snapshot
+    ? { snapshot }
+    : { reason: "no-segment-snapshot" };
 }
 
 export function handleRscRendering<TEnv>(
@@ -156,6 +193,7 @@ async function handleRscRenderingInner<TEnv>(
 
   let payload: RscPayload;
   let hasInterceptSlots = false;
+  let pprReplayStatus: PprReplayStatus | undefined;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -359,7 +397,7 @@ async function handleRscRenderingInner<TEnv>(
 
   if (isPartial) {
     // Partial render (navigation)
-    const result = await matchPartialWithPprReplay(
+    const replay = await matchPartialWithPprReplay(
       ctx,
       request,
       env,
@@ -367,6 +405,8 @@ async function handleRscRenderingInner<TEnv>(
       reqCtx,
       nonce,
     );
+    const result = replay.result;
+    pprReplayStatus = replay.status;
 
     if (!result) {
       // Fall back to full render
@@ -378,10 +418,17 @@ async function handleRscRenderingInner<TEnv>(
         // perform SPA navigation. A raw 308 would be auto-followed by
         // fetch, hitting the target without _rsc_partial. Resolve the
         // target server-side (same open-redirect policy as 3xx).
-        return createSimpleRedirectResponse(match.redirect, {
+        const redirectResponse = createSimpleRedirectResponse(match.redirect, {
           requestOrigin: url.origin,
           basename: ctx.router.basename,
         });
+        if (pprReplayStatus) {
+          redirectResponse.headers.set(
+            PPR_REPLAY_STATUS_HEADER,
+            serializePprReplayStatus(pprReplayStatus),
+          );
+        }
+        return redirectResponse;
       }
 
       payload = buildFullPayload(match, ctx, url, reqCtx, handleStore);
@@ -484,6 +531,10 @@ async function handleRscRenderingInner<TEnv>(
     // are deliberately NOT stamped. See browser/response-adapter.ts.
     "X-RSC-Router-Id": ctx.router.id,
   };
+  if (pprReplayStatus) {
+    rscHeaders[PPR_REPLAY_STATUS_HEADER] =
+      serializePprReplayStatus(pprReplayStatus);
+  }
   // Tell the client's prefetch cache to scope this response to its source
   // URL (instead of the default source-agnostic wildcard). Intercept
   // responses depend on the source page matching an intercept rule, so
@@ -575,20 +626,45 @@ async function matchPartialWithPprReplay<TEnv>(
   reqCtx: RequestContext<any>,
   nonce: string | undefined,
 ) {
-  const runMatch = () => ctx.router.matchPartial(request, { env });
+  const replayStart = reqCtx._metricsStore ? performance.now() : 0;
+  const recordReplayStatus = (status: PprReplayStatus): void => {
+    if (!reqCtx._metricsStore) return;
+    appendMetric(
+      reqCtx._metricsStore,
+      "ppr:navigation-replay",
+      replayStart,
+      performance.now() - replayStart,
+      undefined,
+      describePprReplayStatus(status),
+    );
+  };
+  const runMatch = async (status?: PprReplayStatus) => {
+    const result = await ctx.router.matchPartial(request, { env });
+    if (status) recordReplayStatus(status);
+    return { result, status };
+  };
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
   const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
   const store = reqCtx._cacheStore;
 
-  if (
-    request.method !== "GET" ||
-    !pprConfig ||
-    reqCtx._dynamic ||
-    activeNonce !== undefined ||
-    !hasShellFamily(store) ||
-    store.supportsPassiveShellReads !== true
-  ) {
-    return runMatch();
+  if (!pprConfig) return runMatch();
+  if (request.method !== "GET") {
+    return runMatch({ outcome: "BYPASS", reason: "method" });
+  }
+  if (reqCtx._dynamic) {
+    return runMatch({ outcome: "BYPASS", reason: "dynamic" });
+  }
+  if (activeNonce !== undefined) {
+    return runMatch({ outcome: "BYPASS", reason: "nonce" });
+  }
+  if (!hasShellFamily(store)) {
+    return runMatch({ outcome: "BYPASS", reason: "store-unavailable" });
+  }
+  if (store.supportsPassiveShellReads !== true) {
+    return runMatch({
+      outcome: "BYPASS",
+      reason: "passive-read-unsupported",
+    });
   }
 
   const key = buildShellKey(url);
@@ -597,35 +673,70 @@ async function matchPartialWithPprReplay<TEnv>(
     cached = await store.getShell(key, { claimRevalidation: false });
   } catch (error) {
     reportCacheError(error, "cache-read", "[NavigationPPR] getShell");
-    return runMatch();
+    return runMatch({ outcome: "BYPASS", reason: "read-error" });
   }
 
-  let snapshot = cached?.shouldRevalidate
-    ? undefined
-    : replayableShellSnapshot(cached?.entry, ctx.version);
+  let bypassReason: PprReplayBypassReason | undefined;
+  let snapshot: ShellSnapshotRecord[] | undefined;
+  let freshness: "fresh" | "stale" = "fresh";
+  if (cached) {
+    const decision = replayableShellSnapshot(cached.entry, ctx.version);
+    if ("snapshot" in decision) {
+      snapshot = decision.snapshot;
+      freshness = cached.shouldRevalidate ? "stale" : "fresh";
+    } else {
+      bypassReason = decision.reason;
+    }
+  }
 
   if (!snapshot) {
     // Production build manifests are local module data. In dev, resolving a
     // missing build shell would foreground-fetch /__rsc_shell and block an
     // otherwise ordinary navigation on capture, so replay remains runtime-only.
     const buildHit = await lookupBuildShell(url, ctx.version, store);
-    if (!buildHit?.stale) {
-      snapshot = replayableShellSnapshot(buildHit?.entry, ctx.version);
+    if (buildHit?.stale) {
+      bypassReason ??= "stale-build-entry";
+    } else if (buildHit) {
+      const buildDecision = replayableShellSnapshot(
+        buildHit.entry,
+        ctx.version,
+      );
+      if ("snapshot" in buildDecision) {
+        snapshot = buildDecision.snapshot;
+      } else {
+        bypassReason ??= buildDecision.reason;
+      }
     }
   }
 
-  if (!snapshot) return runMatch();
+  if (!snapshot) {
+    return runMatch({
+      outcome: "BYPASS",
+      reason: bypassReason ?? "no-entry",
+    });
+  }
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
+  let segmentReplayHit = false;
   reqCtx._shellImplicitCache = {
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
-    store: new SeededShellStore(store, snapshot, { segmentsOnly: true }),
+    store: new SeededShellStore(store, snapshot, {
+      segmentsOnly: true,
+    }),
     keyPrefix: "doc",
+    onHit: () => {
+      segmentReplayHit = true;
+    },
   };
 
   try {
-    return await runMatch();
+    const result = await ctx.router.matchPartial(request, { env });
+    const status: PprReplayStatus = segmentReplayHit
+      ? { outcome: "HIT", freshness }
+      : { outcome: "BYPASS", reason: "snapshot-miss" };
+    recordReplayStatus(status);
+    return { result, status };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
   }

package/src/rsc/shell-serve.ts

@@ -24,6 +24,9 @@ import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.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";
+
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.

package/src/rsc/transition-gate.ts

@@ -1,41 +1,58 @@
 import type { MatchResult } from "../types.js";
-import type { TransitionWhenContext } from "../types/segments.js";
 import type { getRequestContext } from "../server/request-context.js";
 import { invokeOnError } from "../router/error-handling.js";
 import type { OnErrorCallback } from "../types/error-types.js";
+import { createTransitionWhenContext } from "../router/transition-when.js";
 
 /**
  * Apply transition({ when }) gates to a payload's segments.
  *
- * The predicates were collected during resolution (keyed by segment id) and
- * stripped from the serialized config; here — after handlers ran and outside any
- * cache scope — we evaluate each and drop the segment's transition when the
- * predicate does not hold, so the navigation streams its loading fallback
- * instead of holding the previous content. A predicate that throws is reported
- * to the router's onError (phase "rendering") and then treated as "do not hold"
- * (conservative), so a buggy predicate degrades to no transition rather than
- * failing the response.
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
  *
  * Mutating the segments here is safe: the segment cache stores a serialized copy
  * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. The flip side is that a cache hit
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
  * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate) — combining transition({ when })
- * with cache() on the same segment freezes the gate to its cached state, so
- * avoid caching a route whose transition decision is request-dependent.
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
  *
- * Returns the same array (mutated) for inline use at the payload's `segments`
- * field.
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
  */
 export function gateTransitions(
   segments: MatchResult["segments"],
   ctx: ReturnType<typeof getRequestContext>,
   onError?: OnErrorCallback,
 ): MatchResult["segments"] {
+  const pprDecisions = ctx._pprTransitionDecisions;
+  let gatedSegments = segments;
+
+  const dropTransition = (id: string): void => {
+    const index = gatedSegments.findIndex((segment) => segment.id === id);
+    if (index === -1) return;
+    if (!pprDecisions) {
+      gatedSegments[index].transition = undefined;
+      return;
+    }
+    if (gatedSegments === segments) gatedSegments = [...segments];
+    gatedSegments[index] = {
+      ...gatedSegments[index],
+      transition: undefined,
+    };
+  };
+
+  if (pprDecisions) {
+    for (const [id, keep] of pprDecisions) {
+      if (!keep) dropTransition(id);
+    }
+  }
   const predicates = ctx._transitionWhen;
-  if (predicates && predicates.length) {
+  if (predicates) {
     for (const { id, when } of predicates) {
-      let drop: boolean;
       try {
         // Assemble the ShouldRevalidateFn-shaped predicate context from the
         // request context. Source fields (currentUrl/currentParams/fromRouteName)
@@ -44,28 +61,11 @@ export function gateTransitions(
         // method/get/env come straight off ctx (setRequestContextParams ran
         // before the gate). Source/action fields are undefined when absent —
         // never fabricated (see TransitionWhenContext).
-        const whenCtx: TransitionWhenContext = {
-          currentUrl: ctx._gateCurrentUrl,
-          currentParams: ctx._gateCurrentParams,
-          fromRouteName:
-            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
-          nextUrl: ctx.url,
-          nextParams: ctx.params,
-          toRouteName: ctx.routeName,
-          actionId: ctx._gateActionId,
-          actionUrl: ctx._gateActionUrl,
-          actionResult: ctx._gateActionResult,
-          formData: ctx._gateFormData,
-          method: ctx.request.method,
-          get: ctx.get,
-          env: ctx.env,
-        };
-        drop = when(whenCtx) === false;
+        if (when(createTransitionWhenContext(ctx)) !== false) continue;
       } catch (error) {
         // A throwing predicate must not fail the response: report it and treat
         // the transition as gated off (do not hold). invokeOnError no-ops when
         // onError is undefined.
-        drop = true;
         invokeOnError(
           onError,
           error,
@@ -79,11 +79,8 @@ export function gateTransitions(
           "RSC",
         );
       }
-      if (drop) {
-        const seg = segments.find((s) => s.id === id);
-        if (seg) seg.transition = undefined;
-      }
+      dropTransition(id);
     }
   }
-  return segments;
+  return gatedSegments;
 }

package/src/server/request-context.ts

@@ -208,6 +208,9 @@ export interface RequestContext<
    */
   _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
 
+  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+  _pprTransitionDecisions?: Map<string, boolean>;
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
@@ -276,6 +279,8 @@ export interface RequestContext<
      * segment record even when the triggering request is partial.
      */
     keyPrefix?: "doc";
+    /** @internal Called only after the implicit cache hit decodes successfully. */
+    onHit?: () => void;
   };
 
   /**
@@ -650,6 +655,7 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_transitionWhen"
+  | "_pprTransitionDecisions"
   | "_cacheStore"
   | "_shellCaptureRun"
   | "_shellImplicitCache"

package/src/testing/e2e/index.ts

@@ -41,10 +41,15 @@ export {
   type CacheStatusTarget,
 } from "../cache-status.js";
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
+  type PprReplayBypassReason,
+  type PprReplayStatus,
   type ShellStatus,
   type ShellStatusTarget,
 } from "../shell-status.js";

package/src/testing/index.ts

@@ -77,12 +77,20 @@ export type {
 } from "../router/telemetry.js";
 
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
 } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export type {
+  PprReplayBypassReason,
+  PprReplayStatus,
+  ShellStatus,
+  ShellStatusTarget,
+} from "./shell-status.js";
 
 export { collectHandle } from "./collect-handle.js";
 

package/src/testing/run-transition-when.ts

@@ -1,10 +1,9 @@
 /**
  * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
  *
- * Runs the SAME two server functions the router uses — applyViewTransitionDefault
- * (strips the `when` function from the serialized config and records the
- * predicate on the request context) and gateTransitions (assembles the
- * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
  * predicate sees exactly the navigation/action metadata it would at runtime
  * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
  * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
@@ -33,6 +32,9 @@ import type {
   TransitionWhenContext,
 } from "../types/segments.js";
 import type { OnErrorCallback } from "../types/error-types.js";
+import type { EntryData } from "../server/context.js";
+import { evaluatePprTransitionWhen } from "../router/transition-when.js";
+import { invokeOnError } from "../router/error-handling.js";
 
 const toURL = (v: string | URL, base: URL): URL =>
   typeof v === "string" ? new URL(v, base.origin) : v;
@@ -53,7 +55,7 @@ export interface RunTransitionWhenOptions<TEnv = any> {
   toRouteName?: string;
   /** Environment bindings surfaced as `env` (and `ctx.env`). */
   env?: TEnv;
-  /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+  /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
   vars?: VarsInit;
   /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
   currentUrl?: string | URL;
@@ -71,6 +73,8 @@ export interface RunTransitionWhenOptions<TEnv = any> {
   formData?: FormData;
   /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
   onError?: OnErrorCallback;
+  /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+  ppr?: boolean;
 }
 
 /**
@@ -138,8 +142,37 @@ export function runTransitionWhen<TEnv = any>(
     : config;
 
   return runWithRequestContext(reqCtx, () => {
-    // The real resolution-time collection + post-handler gate, so the predicate
-    // sees the production-assembled TransitionWhenContext.
+    if (opts.ppr) {
+      const entry = {
+        type: "route",
+        id: "tx-when-entry",
+        shortCode: "tx-when-seg",
+        parent: null,
+        transition: configForGate,
+        layout: [],
+        parallel: {},
+      } as unknown as EntryData;
+      evaluatePprTransitionWhen(
+        [entry],
+        reqCtx,
+        { params: reqCtx.params, routeName: opts.toRouteName },
+        (error, segmentId) =>
+          invokeOnError(
+            opts.onError,
+            error,
+            "rendering",
+            {
+              request: reqCtx.request,
+              url: reqCtx.url,
+              params: reqCtx.params,
+              segmentId,
+            },
+            "RSC",
+          ),
+      );
+    }
+    // Ordinary predicates are collected here and evaluated by the gate. PPR
+    // predicates keep the decision already evaluated before this step.
     const serialized = applyViewTransitionDefault(
       configForGate,
       undefined,
@@ -153,12 +186,12 @@ export function runTransitionWhen<TEnv = any>(
       component: null,
       transition: serialized,
     } as ResolvedSegment;
-    gateTransitions(
+    const [gatedSegment] = gateTransitions(
       [segment],
       reqCtx as Parameters<typeof gateTransitions>[1],
       opts.onError,
     );
-    const kept = segment.transition !== undefined;
+    const kept = gatedSegment.transition !== undefined;
     return { kept, dropped: !kept, whenContext, ctx: reqCtx };
   });
 }