@rangojs/router 0.1.1 → 0.2.0

package/README.md

@@ -38,7 +38,7 @@ Node setup.
 
 ## Using the skills with your coding agent
 
-This package ships 43 agent skills in `node_modules/@rangojs/router/skills/` —
+This package ships agent skills in `node_modules/@rangojs/router/skills/` —
 task-focused guides written for LLM coding agents. Start at
 `skills/rango/SKILL.md` (the mental model + catalog); a machine-readable index
 is at `skills/catalog.json`.
@@ -375,6 +375,7 @@ when the requirement appears:
 | test loaders, middleware, handlers, Flight      | [`/testing`](./skills/testing/SKILL.md)                                                      |
 | see where request time goes                     | [`/observability`](./skills/observability/SKILL.md)                                          |
 | deploy to Vercel (cache store, tracing, output) | [`/vercel`](./skills/vercel/SKILL.md)                                                        |
+| choose in-function vs CDN caching               | [`/deployment-caching`](./skills/deployment-caching/SKILL.md)                                |
 | compare Rango with Next.js / TanStack / Waku    | [`/comparison`](./skills/comparison/SKILL.md)                                                |
 
 The [`/rango` skill](./skills/rango/SKILL.md) is the full catalog and the

package/dist/types/cache/document-cache.d.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:

package/dist/types/cache/types.d.ts

@@ -279,9 +279,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/dist/types/route-definition/helpers-types.d.ts

@@ -349,11 +349,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
@@ -380,7 +380,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/dist/types/router/match-handlers.d.ts

@@ -1,10 +1,9 @@
 import type { ReactNode } from "react";
-import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
-import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type { ErrorBoundaryHandler, ErrorInfo, ErrorPhase, MatchResult } from "../types";
+import { type EntryData, type InterceptEntry, type InterceptSelectorContext } from "../server/context.js";
 import type { MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
 import { type ActionContext } from "./match-context.js";
-import type { ErrorBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import { type TelemetrySink } from "./telemetry.js";
 export interface MatchHandlerDeps<TEnv = any> {

package/dist/types/router/segment-resolution/view-transition-default.d.ts

@@ -20,9 +20,8 @@ import type { EntryData } from "../../server/context";
  * 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 declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];

package/dist/types/router/transition-when.d.ts

@@ -0,0 +1,13 @@
+import { 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 declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
+    params: Record<string, string>;
+    routeName?: string;
+}): TransitionWhenContext<Record<string, string>, TEnv>;
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
+    params: Record<string, string>;
+    routeName?: string;
+}, reportError: TransitionWhenErrorReporter): void;

package/dist/types/rsc/shell-serve.d.ts

@@ -19,6 +19,8 @@ import { type EntryData } from "../server/context.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export declare const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.

package/dist/types/rsc/transition-gate.d.ts

@@ -4,24 +4,20 @@ import type { OnErrorCallback } from "../types/error-types.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 declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

package/dist/types/server/request-context.d.ts

@@ -141,6 +141,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         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;
     /**
@@ -202,6 +204,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * segment record even when the triggering request is partial.
          */
         keyPrefix?: "doc";
+        /** @internal Called only after the implicit cache hit decodes successfully. */
+        onHit?: () => void;
     };
     /**
      * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
@@ -514,7 +518,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_cacheStore" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_cacheStore" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/testing/e2e/index.d.ts

@@ -4,7 +4,7 @@ import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent,
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, type ShellStatus, type ShellStatusTarget, } from "../shell-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";
 export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {

package/dist/types/testing/index.d.ts

@@ -44,8 +44,8 @@ export type { DispatchOptions } from "./dispatch.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
+export type { PprReplayBypassReason, PprReplayStatus, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
 export { collectHandle } from "./collect-handle.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
 export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";

package/dist/types/testing/run-transition-when.d.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
@@ -39,7 +38,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;
@@ -57,6 +56,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;
 }
 /**
  * Result of runTransitionWhen.

package/dist/types/testing/shell-status.d.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.
  *
@@ -27,8 +29,21 @@
  */
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export declare const SHELL_STATUS_HEADER: string;
+/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
+export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["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"];
+/** 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;
@@ -56,3 +71,8 @@ export declare function parseShellStatus(target: ShellStatusTarget): ShellStatus
  * invent a HIT Response in unit tests — that fakes the serve path.
  */
 export declare function assertShellStatus(target: ShellStatusTarget, expected: ShellStatus): void;
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export declare function parsePprReplayStatus(target: ShellStatusTarget): PprReplayStatus | null;
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export declare function assertPprReplayStatus(target: ShellStatusTarget, expected: PprReplayStatus): void;
+export {};

package/dist/types/types/segments.d.ts

@@ -12,11 +12,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
@@ -41,27 +42,30 @@ 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>, TEnv = unknown> = Partial<Pick<RevalidateParams<TParams, TEnv>, "currentUrl" | "currentParams" | "fromRouteName">> & Pick<RevalidateParams<TParams, TEnv>, "nextUrl" | "nextParams" | "toRouteName" | "actionId" | "actionUrl" | "actionResult" | "formData" | "method"> & Pick<HandlerContext<any, TEnv>, "get" | "env">;
 /**
  * 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
@@ -69,10 +73,10 @@ export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unkno
  * 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;
 /**
@@ -105,11 +109,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/dist/types/urls/path-helper-types.d.ts

@@ -183,9 +183,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;

package/dist/vite/index.js

@@ -2530,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.1.1",
+  version: "0.2.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,19 +176,6 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.27",
@@ -204,19 +191,19 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -255,5 +242,17 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/cache-guide/SKILL.md

@@ -131,8 +131,10 @@ recompute for a merely-aging entry.
   layer.
 - **Client forward/back** is SWR after a mutation — see "Correctness &
   invalidation" → Client cache.
-- **Edge / document layer** uses the HTTP `stale-while-revalidate` directive; see
-  `/document-cache`.
+- **Store-backed document layer** uses the HTTP `stale-while-revalidate`
+  directive as policy for `createDocumentCacheMiddleware`; see
+  `/document-cache`. A platform CDN may independently consume the same header
+  and bypass the function on hits; see `/deployment-caching`.
 
 SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
 has no stale entry to serve (see version-segmented store keys above).
@@ -485,5 +487,6 @@ overrides — see `/loader` for the full reference.
 
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
-- `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/document-cache` — store-backed complete-response middleware
+- `/deployment-caching` — in-function versus external CDN cache boundaries
 - `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)

package/skills/catalog.json

@@ -69,9 +69,15 @@
       "argumentHint": "",
       "path": "skills/defer-hydration/SKILL.md"
     },
+    {
+      "name": "deployment-caching",
+      "description": "Choose the deployment cache boundary for a Rango app: in-function segment/prerender/PPR caches, store-backed whole-response caching, or an external CDN cache. Use when comparing Cloudflare, Vercel, and Node deployments; deciding whether Cache-Control can reduce origin work; or reasoning about middleware, live loaders, PPR, and CDN behavior.",
+      "argumentHint": "[cloudflare|vercel|node]",
+      "path": "skills/deployment-caching/SKILL.md"
+    },
     {
       "name": "document-cache",
-      "description": "Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.",
+      "description": "Cache complete HTTP responses in Rango's configured app store with createDocumentCacheMiddleware, using Cache-Control s-maxage as policy. Use when reusing a whole HTML/RSC response, comparing the store-backed middleware with a platform CDN cache, or deciding whether full-response caching is safe.",
       "argumentHint": "[setup]",
       "path": "skills/document-cache/SKILL.md"
     },