@rangojs/router 0.1.1 → 0.4.0

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

package/src/testing/shell-status.ts

@@ -2,7 +2,8 @@
  * PPR shell-status testing primitives for @rangojs/router consumers.
  *
  * Companion to `cache-status.ts` (segment/document cache): this module covers
- * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`).
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`) and
+ * partial-navigation segment replay (`x-rango-ppr-replay: HIT`).
  *
  * ## Spike conclusions (plan 009)
  *
@@ -11,8 +12,9 @@
  *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
  *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
  *
- * 2. **Smallest HIT signal:** response header `x-rango-shell` (`HIT` | `MISS`),
- *    always on document GETs to a ppr route that the serve path considered.
+ * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
+ *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
+ *    HIT is reported only when matching consumes the captured segment record.
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
@@ -31,9 +33,37 @@ import { sortedSearchString } from "../cache/cache-key-utils.js";
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export const SHELL_STATUS_HEADER: string = "x-rango-shell";
 
+/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
+export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
+
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
 
+const PPR_REPLAY_BYPASS_REASONS = [
+  "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",
+] as const;
+
+/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+
+/** Parsed `x-rango-ppr-replay` value. */
+export type PprReplayStatus =
+  | { outcome: "HIT"; freshness: "fresh" | "stale" }
+  | { outcome: "BYPASS"; reason: PprReplayBypassReason };
+
 /** A target carrying response headers (a Response or a `{ headers }` object). */
 export type ShellStatusTarget = Response | { headers: Headers };
 
@@ -58,6 +88,8 @@ function getHeaders(target: ShellStatusTarget): Headers {
   return target.headers;
 }
 
+const PPR_REPLAY_BYPASS_REASON_SET = new Set<string>(PPR_REPLAY_BYPASS_REASONS);
+
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).
@@ -98,3 +130,60 @@ export function assertShellStatus(
     );
   }
 }
+
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export function parsePprReplayStatus(
+  target: ShellStatusTarget,
+): PprReplayStatus | null {
+  const raw = getHeaders(target).get(PPR_REPLAY_STATUS_HEADER)?.trim();
+  if (!raw) return null;
+
+  const [outcome, detail, ...extra] = raw.split(";").map((part) => part.trim());
+  if (extra.length > 0 || !detail) return null;
+
+  if (outcome === "HIT") {
+    const freshness = detail.match(/^freshness=(fresh|stale)$/)?.[1];
+    if (freshness === "fresh" || freshness === "stale") {
+      return { outcome, freshness };
+    }
+    return null;
+  }
+
+  if (outcome === "BYPASS") {
+    const reason = detail.match(/^reason=(.+)$/)?.[1] as
+      | PprReplayBypassReason
+      | undefined;
+    if (reason && PPR_REPLAY_BYPASS_REASON_SET.has(reason)) {
+      return { outcome, reason };
+    }
+  }
+
+  return null;
+}
+
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export function assertPprReplayStatus(
+  target: ShellStatusTarget,
+  expected: PprReplayStatus,
+): void {
+  const raw = getHeaders(target).get(PPR_REPLAY_STATUS_HEADER);
+  if (raw === null) {
+    throw new Error(
+      `assertPprReplayStatus: response has no ${PPR_REPLAY_STATUS_HEADER} header. ` +
+        "The header is set on partial requests to ppr-declared routes.",
+    );
+  }
+
+  const actual = parsePprReplayStatus(target);
+  if (!actual) {
+    throw new Error(
+      `assertPprReplayStatus: unrecognized ${PPR_REPLAY_STATUS_HEADER} value "${raw}".`,
+    );
+  }
+
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(
+      `assertPprReplayStatus: expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}.`,
+    );
+  }
+}

package/src/types/segments.ts

@@ -14,11 +14,12 @@ export type ViewTransitionClass = Record<string, string> | string;
  *
  * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
  * gets — the same navigation/action metadata — so the two read the same shape,
- * plus `get`/`env` for post-handler reads. There is no full `HandlerContext`
+ * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
  * here: the gate runs at the RSC-payload layer with the request context, not a
  * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
- * absent by design. `get` is the way to read what the handler/middleware set
- * via `ctx.set(...)` this request.
+ * absent by design. On ordinary routes, `get` can read what handlers or
+ * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
+ * handlers, so only middleware-established values are available.
  *
  * Field availability (all source fields are optional — never fabricated):
  * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
@@ -43,11 +44,12 @@ export type ViewTransitionClass = Record<string, string> | string;
  * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
  * prefetch fired from, NOT necessarily the page the user actually navigates from
  * — the decision is baked into the stored Flight payload and replayed verbatim.
- * A `cache()`/prerender hit replays the stored transition with the predicate NOT
- * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
- * or store-time state. This is accepted (~99% of navigations match), but if your
- * gate must reflect the exact click-time source, source-scope the prefetch
- * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ * A non-PPR `cache()`/prerender hit replays the stored transition with the
+ * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
+ * handlers on every match, including cache, prerender, and PPR replay. Prefetch
+ * still freezes the server decision into its Flight payload. If the gate must
+ * reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`).
  */
 export type TransitionWhenContext<
   TParams = Record<string, string>,
@@ -74,17 +76,19 @@ export type TransitionWhenContext<
 /**
  * Predicate that gates whether a transition() applies for the current request.
  *
- * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
- * handler/middleware-set state) and outside any cache scope. Return false to
- * drop this segment's transition for the request; return true to apply it. The
+ * Evaluated server-side outside any cache scope. On ordinary routes it runs
+ * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
+ * route with `ppr` automatically hoists it before route handlers and reevaluates
+ * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
+ * state, but not values set by route handlers. Return false to drop this
+ * segment's transition for the request; return true to apply it. The
  * context ({@link TransitionWhenContext}) carries the same navigation/action
  * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
  * error is reported to the router's onError (phase "rendering") and the
  * transition is dropped (the navigation does not hold).
  *
  * Distinct from intercept()'s `when` config selector, which runs at MATCH time
- * over `{ from, to, params, segments, … }`; a transition `when` runs
- * post-handler over the resolved payload.
+ * over `{ from, to, params, segments, … }`.
  *
  * Scope: dropping a transition removes only THIS segment's contribution to the
  * navigation's hold. The startTransition hold is navigation-wide — it engages if
@@ -92,10 +96,10 @@ export type TransitionWhenContext<
  * navigation stream its loading fallback only when no other matched segment
  * keeps a transition (the common case: a single transition on the route).
  *
- * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
- * segment is replayed from the runtime cache or a build-time prerender, and a
- * prefetched navigation freezes it to prefetch-time state — see the caveat on
- * {@link TransitionWhenContext}.
+ * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
+ * before handlers for every match, including runtime cache, build-time
+ * prerender, and PPR segment replay. A prefetched navigation still freezes the
+ * result to prefetch time; see {@link TransitionWhenContext}.
  */
 export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
 
@@ -129,11 +133,12 @@ export interface TransitionConfig {
   viewTransition?: "auto" | false;
   /**
    * Optional server-side predicate that gates this transition per request. When
-   * present and it returns false (evaluated post-handler), the router drops this
-   * segment's transition for the request, so the navigation streams its loading
-   * fallback instead of holding. The predicate is server-only and never
-   * serialized to the client; only its resolved effect (transition kept or
-   * dropped) crosses. See {@link TransitionWhenFn}.
+   * present and it returns false, the router drops this segment's transition for
+   * the request, so the navigation streams its loading fallback instead of
+   * holding. PPR routes evaluate it before route handlers and on every replay;
+   * other routes evaluate it after handlers on fresh resolution. The predicate
+   * is server-only and never serialized to the client; only its resolved effect
+   * crosses. See {@link TransitionWhenFn}.
    */
   when?: TransitionWhenFn;
 }

package/src/urls/path-helper-types.ts

@@ -394,9 +394,10 @@ export type PathHelpers<TEnv> = {
    * transition cannot fire without a startTransition. See
    * skills/view-transitions for the startTransition x ViewTransition matrix.
    *
-   * Pass `when: (ctx) => boolean` to gate the transition per request: it runs
-   * server-side after the route handler (can read `ctx.get(...)`), and returning
-   * false drops the transition so the navigation streams its loading() skeleton.
+   * Pass `when: (ctx) => boolean` to gate the transition per request. It normally
+   * runs after the route handler; `ppr` routes automatically run it before route
+   * handlers and on every replay, where `ctx.get(...)` sees middleware state but
+   * not handler-set values.
    */
   transition: {
     (): TransitionItem;