@rangojs/router 0.1.1 → 0.2.0

package/skills/view-transitions/SKILL.md

@@ -209,9 +209,8 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
-  // Conditional gate, evaluated server-side AFTER the route handler. Return
-  // false to drop this transition for the request, so the navigation streams its
-  // loading() fallback instead of holding. See the gate section below.
+  // Conditional server-side gate. PPR routes run it before route handlers and
+  // on every replay; other routes run it after handlers on fresh resolution.
   when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
@@ -223,14 +222,19 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`transition({ when })` gates the hold per request. The predicate runs **server-side, AFTER the route handler** and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
 
-Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for post-handler reads:
+Timing follows the route's rendering contract:
+
+- On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
+- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers. This is what keeps the handler-free PPR fast path available without a second API.
+
+Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
 
 ```ts
 import type { TransitionWhenContext } from "@rangojs/router";
 
-// Hold only when the handler marked this request (handler sets, gate reads):
+// Ordinary route: hold only when the handler marked this request:
 transition({ when: (ctx) => ctx.get(KeepScroll) === true });
 
 // Hold only when arriving from a specific page (the navigation SOURCE):
@@ -252,13 +256,13 @@ transition({
 | `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
 | `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
 | `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
-| `get` / `env`                                          | read handler/middleware vars + app env       | always                                                                                |
+| `get` / `env`                                          | read request vars + app env                  | always; PPR timing exposes middleware vars, not handler writes                        |
 
 A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
 
 **Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
 
-**Prefetch / cache caveat.** The gate runs during resolution, so a **prefetched** navigation decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source — and a `cache()`/prerender hit replays the stored transition without re-running the predicate. A source-sensitive gate can therefore be frozen to prefetch/store-time state. This covers ~99% of navigations; if yours must reflect the exact click-time source, source-scope the prefetch (`<Link prefetchKey=":source">`) and don't `cache()` that segment.
+**Prefetch / cache caveat.** A **prefetched** navigation still decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source. Non-PPR `cache()`/prerender hits also replay the stored transition without rerunning the predicate. PPR routes rerun it on the server for each cache/prerender/PPR match, but a completed browser prefetch still carries its earlier Flight decision. If the exact click-time source matters, source-scope the prefetch (`<Link prefetchKey=":source">`).
 
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 

package/src/cache/cache-scope.ts

@@ -108,6 +108,8 @@ function getDefaultRouteCacheKey(
 // CacheScope
 // ============================================================================
 
+const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+
 /**
  * CacheScope represents a cache boundary in the route tree.
  *
@@ -348,6 +350,7 @@ export class CacheScope {
         );
       }
 
+      CACHE_HIT_OBSERVERS.get(this)?.();
       return { segments, shouldRevalidate };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -555,9 +558,11 @@ export function resolveShellImplicitCacheScope(
   if (scope) return scope;
   const marker = getRequestContext()?._shellImplicitCache;
   if (!marker) return null;
-  return new CacheScope(
+  const implicitScope = new CacheScope(
     { ttl: marker.ttl, swr: marker.swr, store: marker.store },
     null,
     marker.keyPrefix,
   );
+  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
+  return implicitScope;
 }

package/src/cache/document-cache.ts

@@ -1,7 +1,9 @@
 /**
  * Document-Level Cache Middleware
  *
- * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Caches full HTTP responses in the configured app store based on Cache-Control
+ * headers. A deployment CDN may independently consume the same shared-cache
+ * directives; this middleware itself runs inside the worker/function.
  * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
  *
  * Flow:
@@ -58,7 +60,7 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
 
   // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
   // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
-  // The document cache is a shared edge store, so refuse both regardless of any
+  // The document cache is a shared app store, so refuse both regardless of any
   // s-maxage / stale-while-revalidate also present. Match standalone directive
   // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
   // substring, so a value containing "private" cannot false-veto.

package/src/cache/types.ts

@@ -319,9 +319,10 @@ export interface ShellCacheEntry {
    */
   handlerLiveHoles?: boolean;
   /**
-   * The capture encountered transition({ when }). Its effective hold policy is
-   * request-dependent, so handler-free document and navigation replay must
-   * re-run resolution to collect and evaluate the predicate.
+   * Legacy/fallback marker for a transition({ when }) predicate that was not
+   * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
+   * ineligible for handler-free replay. New PPR matches evaluate known segment
+   * predicates before the pipeline and do not set this marker.
    */
   transitionWhen?: true;
   /** Capture-generation start time; tag invalidations at or after it win. */

package/src/route-definition/helpers-types.ts

@@ -460,11 +460,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * startTransition only when the router sets viewTransition: false.
    *
    * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
-   * request. It runs server-side AFTER the route handler (so it can read state
-   * the handler set via `ctx.get(...)`); returning false drops this transition
-   * for the request, so the navigation streams its loading() skeleton instead of
-   * holding. This is a post-handler predicate — distinct from intercept()'s
-   * match-time `when` config selector (`intercept(slot, route, Comp, { when })`).
+   * request. It normally runs server-side after the route handler. On a `ppr`
+   * route it is automatically hoisted before route handlers and reevaluated on
+   * every replay, so it may read URL/params/action/env and middleware-set context
+   * but not handler-set context. Returning false drops this transition for the
+   * request. This is distinct from intercept()'s match-time `when` selector.
    *
    * ```typescript
    * // Attach to a single route
@@ -491,7 +491,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param config - ViewTransition configuration (enter, exit, update, share,
    *   default, name), `viewTransition: "auto" | false` to toggle the router
    *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
-   *   `when: (ctx) => boolean` to gate the transition per request post-handler
+   *   `when: (ctx) => boolean` to gate the transition per request
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {

package/src/router/match-handlers.ts

@@ -1,12 +1,19 @@
 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 {
-  EntryData,
-  InterceptEntry,
-  InterceptSelectorContext,
-} from "../server/context";
+  ErrorBoundaryHandler,
+  ErrorInfo,
+  ErrorPhase,
+  MatchResult,
+  NotFoundBoundaryHandler,
+} from "../types";
+import {
+  isPprEntry,
+  type EntryData,
+  type InterceptEntry,
+  type InterceptSelectorContext,
+} from "../server/context.js";
 import type { MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
 import { runWithRouterContext } from "./router-context.js";
@@ -30,7 +37,6 @@ import {
   startRevalidationTrace,
   flushRevalidationTrace,
 } from "./logging.js";
-import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
@@ -41,6 +47,7 @@ import {
   buildCacheSignalSegments,
 } from "./telemetry.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { evaluatePprTransitionWhen } from "./transition-when.js";
 
 /**
  * Per-call telemetry lifecycle emitter for match()/matchPartial(). Each method
@@ -227,6 +234,35 @@ export function createMatchHandlers<TEnv = any>(
     if (reqCtx) reqCtx._cacheSignal = segments;
   };
 
+  const evaluatePprTransitionWhenForMatch = (
+    ctx: MatchContext<TEnv>,
+    isPartial: boolean,
+  ): void => {
+    const reqCtx = _getRequestContext();
+    if (!reqCtx) return;
+    reqCtx._pprTransitionDecisions = undefined;
+    if (!isPprEntry(ctx.manifestEntry)) return;
+
+    evaluatePprTransitionWhen(
+      ctx.entries,
+      reqCtx,
+      {
+        params: ctx.matched.params,
+        routeName: ctx.interceptSelectorContext.toRouteName,
+      },
+      (error, segmentId) =>
+        callOnError(error, "rendering", {
+          request: ctx.request,
+          url: ctx.url,
+          env: ctx.env,
+          params: ctx.matched.params,
+          segmentId,
+          isPartial,
+          handledByBoundary: false,
+        }),
+    );
+  };
+
   async function createMatchContextForFull(
     request: Request,
     env: TEnv,
@@ -313,6 +349,7 @@ export function createMatchHandlers<TEnv = any>(
           }
 
           const ctx = result as MatchContext<TEnv>;
+          evaluatePprTransitionWhenForMatch(ctx, false);
 
           try {
             const state = createPipelineState();
@@ -424,6 +461,7 @@ export function createMatchHandlers<TEnv = any>(
               emitter.end(0, false);
               return null;
             }
+            evaluatePprTransitionWhenForMatch(ctx, true);
 
             if (isRouterDebugEnabled()) {
               startRevalidationTrace({

package/src/router/match-middleware/cache-lookup.ts

@@ -460,6 +460,8 @@ export function withCacheLookup<TEnv>(
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
+    const pprTransitionDecisions =
+      _getRequestContext()?._pprTransitionDecisions;
 
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
@@ -533,8 +535,13 @@ export function withCacheLookup<TEnv>(
             reason: "cached-no-rules",
           });
         }
-        segment.component = null;
-        segment.loading = undefined;
+        // A PPR transition decision must reach the client even when this cached
+        // segment otherwise needs no update. Keep its replayed component so the
+        // partial result retains the segment for gateTransitions().
+        if (!pprTransitionDecisions?.has(segment.id)) {
+          segment.component = null;
+          segment.loading = undefined;
+        }
         yield segment;
         continue;
       }
@@ -566,7 +573,7 @@ export function withCacheLookup<TEnv>(
         shouldRevalidate,
       });
 
-      if (!shouldRevalidate) {
+      if (!shouldRevalidate && !pprTransitionDecisions?.has(segment.id)) {
         segment.component = null;
         segment.loading = undefined;
       }

package/src/router/segment-resolution/view-transition-default.ts

@@ -23,10 +23,9 @@ import { getRequestContext } from "../../server/request-context.js";
  * gate, which also avoids needless object allocation and payload growth.
  *
  * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache) and recorded on the request
- * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
- * outside any cache scope — and drop this segment's transition when it returns
- * false. Used by both the fresh and revalidation resolution paths.
+ * function cannot cross Flight or the segment cache). PPR routes evaluate it
+ * from the manifest before the pipeline; other routes record it here for the
+ * existing post-handler gate. Used by both fresh and revalidation resolution.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
@@ -39,7 +38,12 @@ export function applyViewTransitionDefault(
     if (segmentId !== undefined) {
       try {
         const ctx = getRequestContext();
-        (ctx._transitionWhen ??= []).push({ id: segmentId, when: result.when });
+        if (!ctx._pprTransitionDecisions?.has(segmentId)) {
+          (ctx._transitionWhen ??= []).push({
+            id: segmentId,
+            when: result.when,
+          });
+        }
       } catch {
         // No active request context (e.g. a unit test calling this util
         // directly). Skip collection; the strip below still applies so the

package/src/router/transition-when.ts

@@ -0,0 +1,76 @@
+import { getParallelSlotEntries, type EntryData } from "../server/context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+
+export type TransitionWhenErrorReporter = (
+  error: unknown,
+  segmentId: string,
+) => void;
+
+export function createTransitionWhenContext<TEnv>(
+  ctx: RequestContext<TEnv>,
+  target?: {
+    params: Record<string, string>;
+    routeName?: string;
+  },
+): TransitionWhenContext<Record<string, string>, TEnv> {
+  return {
+    currentUrl: ctx._gateCurrentUrl,
+    currentParams: ctx._gateCurrentParams,
+    fromRouteName: ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+    nextUrl: ctx.url,
+    nextParams: target?.params ?? ctx.params,
+    toRouteName: (target?.routeName ??
+      ctx.routeName) as TransitionWhenContext["toRouteName"],
+    actionId: ctx._gateActionId,
+    actionUrl: ctx._gateActionUrl,
+    actionResult: ctx._gateActionResult,
+    formData: ctx._gateFormData,
+    method: ctx.request.method,
+    get: ctx.get,
+    env: ctx.env,
+  };
+}
+
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export function evaluatePprTransitionWhen<TEnv>(
+  entries: EntryData[],
+  ctx: RequestContext<TEnv>,
+  target: {
+    params: Record<string, string>;
+    routeName?: string;
+  },
+  reportError: TransitionWhenErrorReporter,
+): void {
+  const decisions = new Map<string, boolean>();
+  const whenContext = createTransitionWhenContext(ctx, target);
+  const visited = new Set<EntryData>();
+
+  const evaluate = (entry: EntryData, segmentId: string): void => {
+    const when = entry.transition?.when;
+    if (!when) return;
+    try {
+      decisions.set(segmentId, when(whenContext) !== false);
+    } catch (error) {
+      decisions.set(segmentId, false);
+      reportError(error, segmentId);
+    }
+  };
+
+  const visitEntryAndOrphanLayouts = (entry: EntryData): void => {
+    if (visited.has(entry)) return;
+    visited.add(entry);
+    evaluate(entry, entry.shortCode);
+
+    for (const orphan of entry.layout) visitEntryAndOrphanLayouts(orphan);
+    // Rendered parallel slots are leaves identified by their owning segment.
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
+      evaluate(parallelEntry, `${entry.shortCode}.${slot}`);
+    }
+  };
+
+  for (const entry of entries) visitEntryAndOrphanLayouts(entry);
+  ctx._pprTransitionDecisions = decisions.size > 0 ? decisions : undefined;
+}

package/src/rsc/progressive-enhancement.ts

@@ -277,10 +277,15 @@ export async function handleProgressiveEnhancement<TEnv>(
     // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
     // matching — a stale `foregroundOnAction` cache entry must re-execute in the
     // foreground during the re-render, exactly as the JS path's
-    // revalidateAfterAction does. The transition({ when }) gate fields below are
-    // set post-match (the gate reads them after rendering); foregroundOnAction
-    // reads _inActionRevalidation during the match, so it must be set here.
-    getRequestContext()._inActionRevalidation = true;
+    // revalidateAfterAction does. PPR transition({ when }) runs during match,
+    // while foregroundOnAction reads _inActionRevalidation there too, so all
+    // action metadata must be available before matching.
+    const peReqCtx = getRequestContext();
+    peReqCtx._inActionRevalidation = true;
+    peReqCtx._gateActionId = directActionId ?? undefined;
+    peReqCtx._gateActionUrl = new URL(url);
+    peReqCtx._gateActionResult = actionResult;
+    peReqCtx._gateFormData = formData;
 
     const match = await ctx.router.match(renderRequest, { env });
 
@@ -291,16 +296,6 @@ export async function handleProgressiveEnhancement<TEnv>(
       });
     }
 
-    // Expose the no-JS action to the transition({ when }) gate. currentUrl/Params
-    // are absent on this full-render path (no navigation snapshot); useActionState
-    // ids are block-scoped, so only a direct action id is available here.
-    // actionUrl is the page the action was submitted from (this request's url).
-    const peReqCtx = getRequestContext();
-    peReqCtx._gateActionId = directActionId ?? undefined;
-    peReqCtx._gateActionUrl = new URL(url);
-    peReqCtx._gateActionResult = actionResult;
-    peReqCtx._gateFormData = formData;
-
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,