@rangojs/router 0.17.0 → 0.19.0

package/skills/testing/server-actions.md

@@ -64,11 +64,16 @@ Low-level building blocks (all from `@rangojs/router/testing`):
 
 ```ts
 import { it, expect } from "vitest";
-import { runInRequestContext } from "@rangojs/router/testing";
-import { loginAction } from "../src/actions/login"; // sets a session cookie + flash, then throw redirect("/app")
+import {
+  runInRequestContext,
+  withLocationStateKey,
+} from "@rangojs/router/testing";
+import { loginAction } from "../src/actions/login"; // sets a session cookie, then throw redirect("/app", { state: [Flash({ text: "Welcome back" })] })
 import { logoutAction, dismissBannerAction } from "../src/actions/session"; // invalidateClientCache() / keepClientCache()
+import { Flash } from "../src/location-states"; // createLocationState<{ text: string }>({ flash: true })
 
 const env = { DB: fakeDb }; // your binding double (see ./bindings.md)
+withLocationStateKey(Flash, "Flash"); // no Vite plugin here: key -> "__rsc_ls_Flash"
 
 it("sets the session cookie + flash and redirects", async () => {
   const { thrown, cookies, locationState } = await runInRequestContext(
@@ -82,7 +87,7 @@ it("sets the session cookie + flash and redirects", async () => {
   );
   expect((thrown as Response).headers.get("Location")).toBe("/app"); // redirected
   expect(cookies.session).toBeDefined(); // cookie set before the throw, no @internal cast
-  expect(locationState).toEqual({ flash: { text: "Welcome back" } });
+  expect(locationState).toEqual({ __rsc_ls_Flash: { text: "Welcome back" } });
 });
 
 it("asserts the client-cache directives an action issued", async () => {
@@ -105,6 +110,7 @@ it("asserts the client-cache directives an action issued", async () => {
 ## Caveats
 
 - The snapshot fires whether `fn` RETURNS or THROWS. A `throw redirect("/app")` on the success path is captured on `thrown` (NOT re-thrown), so no try/catch is needed; assert on `thrown` for a throwing action.
+- Location state needs a key. A `createLocationState()` definition gets it from the Vite plugin, which a unit-test project does not run, and outside production an unkeyed `Flash(value)` throws before `redirect()` runs: `thrown` is that missing-key error, not the redirect. Call `withLocationStateKey(Flash, "Flash")` once per definition; `locationState` then holds `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix; `{ [Flash.__rsc_ls_key]: value }` works for any key).
 - There is no cookies / headers option. Seed a request cookie by passing a full `Request` with the `Cookie` header (as in the recipe).
 - An action has no loader context, so `runLoader` is the wrong shape for it even when the action reads cookies or vars; use `runInRequestContext`.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).

package/skills/theme/SKILL.md

@@ -86,10 +86,13 @@ from `@rangojs/router/theme` in `<head>` instead. It takes the resolved config
 are rejected with a console warning. Both are typed optional because they only
 exist when `theme` is configured.
 
+`ctx.theme` is the visitor's theme cookie, so a handler reads it only on a
+route whose output is rendered per request:
+
 ```typescript
 import type { Middleware } from "@rangojs/router";
 
-// In a handler
+// In a handler on a route without ppr or cache()
 path("/settings", (ctx) => {
   const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
   return <SettingsPage theme={currentTheme} />;
@@ -105,9 +108,45 @@ export const themeFromQuery: Middleware = async (ctx, next) => {
 };
 ```
 
-Loaders do not get `ctx.theme` or `ctx.setTheme`. A loader that needs the
-theme reads the cookie directly (loaders run fresh on every request, so the
-read is safe):
+### On `ppr` and `cache()` routes
+
+A `ppr` shell and a `cache()` entry are shared by every visitor, so a handler
+there must not read the visitor's theme. `ctx.theme` (handler and middleware)
+and `getRequestContext().theme` are guarded like `cookies()`:
+
+| Where the theme is read                                    | What happens                                                                                          |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| a handler on a `ppr` route                                 | The shell capture is refused (warned once per URL); every request stays a MISS                        |
+| inside a `cache()` boundary                                | Throws on a cache miss, like `cookies()`                                                              |
+| inside a `"use cache"` function (handler or middleware)    | Throws; read it outside and pass it in as an argument                                                 |
+| after `ctx.dynamic()` on `ppr`                             | Allowed: that render is never captured                                                                |
+| middleware `ctx.set()` of the theme, read by a handler     | Not guarded: the first visitor's theme bakes into the shell or `cache()` entry, like a session object |
+| a route with no `ppr` or `cache()` above it, or middleware | Allowed: rendered per request                                                                         |
+| a loader with its own `cache()` and no `key()`             | The miss fails and stores nothing (#972), like a `cookies()` read there; key the theme                |
+| a handler on a document-cached route (`s-maxage`)          | Not guarded: the stored document shows that visitor's theme to everyone                               |
+
+The theme getters are read-only and non-enumerable: `{ ...ctx }` and
+`Object.assign({}, ctx)` do not carry `theme`, and assigning it throws.
+
+`ctx.setTheme()` throws in a handler on these routes too, like any response
+write there; call it from middleware.
+
+Read the theme where it is per request instead:
+
+- `useTheme()` in a client component. The `<html>` class is right before
+  paint (the theme script sets it). A render that other visitors may be
+  served starts `useTheme()` at the no-cookie default (`defaultTheme`),
+  whoever rendered it: a `ppr` shell, and a page whose response opted in to
+  the document cache before `next()` (#978, see `/document-cache`). A
+  visitor with no stored theme sees the default, and one with a stored theme
+  sees it after hydration. Any other render, a 404 included, starts at the
+  visitor's own theme.
+- A live loader (no `ssr: false`). Loaders do not get `ctx.theme` or
+  `ctx.setTheme`; read the cookie directly. A live loader runs on every
+  request, HITs included, and on a `ppr` route needs `loading()` or an inline
+  `<Suspense>` above its reader. A bake-lane loader (`ssr: false`) runs at
+  capture, where this `cookies()` read refuses the capture, and so does a
+  loader a handler awaits with `ctx.use()`.
 
 ```typescript
 import { cookies, createLoader } from "@rangojs/router";
@@ -118,6 +157,19 @@ export const ThemedLoader = createLoader(async () => {
 });
 ```
 
+If you bind it with its own `cache()`, the entry is shared across users, so the
+miss fails unless it has a `key()`. Any `key()` switches that check off, so
+make it include the theme:
+
+```typescript
+loader(ThemedLoader, () => [
+  cache({
+    ttl: 300,
+    key: () => `themed:${cookies().get("theme")?.value ?? "system"}`,
+  }),
+]);
+```
+
 ## Client
 
 ```tsx

package/skills/typesafety/env-and-bindings.md

@@ -103,7 +103,8 @@ interface PaginationData {
 }
 export const Pagination = createVar<PaginationData>();
 
-// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+// Non-cacheable var — reading inside cache(), "use cache", or a PPR shell
+// capture throws at runtime
 interface SessionData {
   userId: string;
 }
@@ -115,7 +116,14 @@ export const Session = createVar<SessionData>({ cache: false });
 Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
 marks a specific write as non-cacheable even if the var itself is cacheable.
 "Least cacheable wins" — if either says `cache: false`, the value throws on
-read inside `cache()` or `"use cache"`.
+read inside `cache()` or `"use cache"`. On a `ppr` route the read also throws
+anywhere the shell capture waits for it (a handler, a promise it passes or
+pushes, an async server component, an `ssr: false` loader, a loader a handler
+awaits) and refuses the capture: the route keeps rendering without a shell,
+and a warning fires once per key. A loader without `ssr: false` that no
+handler awaits may read it, unless it is bound with its own `cache()` and no
+`key()`: that miss fails, since the entry is shared (`/loader` → "Cache
+Key").
 
 ### Producer (handler, layout, or middleware)
 
@@ -331,3 +339,11 @@ the value at click time; `ctx.setLocationState(entry)` attaches state from a
 handler; `redirect(url, { state })` carries it through a redirect; and
 `ProductPreview.read()` / `.write(value)` / `.delete()` access the current
 history entry outside React (client-only, non-reactive).
+`ProductPreview.read(location)` reads the slot from any `{ state }` snapshot,
+such as a `transition({ when })` context's `from` / `to`, and works without
+`window`.
+
+The `state` option on `<Link>`, `router.push()` and `router.replace()` is typed
+`HistoryState`: an array of called entries (`[ProductPreview({ ... })]`) or
+plain structured-clone data. A bare entry (`state: ProductPreview({ ... })`) or
+an uncalled definition (`state: [ProductPreview]`) is a compile error.

package/skills/use-cache/SKILL.md

@@ -142,6 +142,11 @@ Different functions always produce different cache keys, even for the same route
 This is important for intercepted routes -- the path handler and intercept handler
 each have their own `functionId` and therefore their own cache entries.
 
+The key is only what the function declares: its id and arguments. A call made
+inside a route `cache()` with a `key()` does not inherit that key, so a value
+the route partitions by (a tier header, a session) must be passed in as an
+argument. The same holds for a loader's own `cache()` (`/loader` → "Cache Key").
+
 ### Route context is folded into the key
 
 The tainted `ctx` object is excluded from arg serialization (see below), but
@@ -224,13 +229,32 @@ export const ProductLoader = createLoader(async (ctx) => getProduct(ctx));
 per-request values (cookies, headers) are not reflected in the cache key. Without
 this guard, one user's data would be served to another.
 
+The raw reads throw the same way: `ctx.request.headers` on any `ctx` passed in
+(handler, loader, middleware; it is one `Request` object, also
+`getRequestContext().request`), and `getRequestContext().cookie()` /
+`.cookies()`. A `ctx` or a `Request` argument keys the entry by its route and
+URL only, never by its headers.
+
 Extract the value before the cached function and pass it as an argument:
 
 ```typescript
 const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
+
+// the same for a header
+const language = ctx.request.headers.get("accept-language") ?? "en";
+const greeting = await getGreeting(language);
 ```
 
+Building the key from a `Request` argument reads only its URL.
+`ctx.request.clone()` is guarded like `ctx.request.headers`. One gap remains:
+`fetch(ctx.request)` and `new Request(ctx.request)` don't throw, and the guard
+can't see through them. The fetch forwards the visitor's `Cookie` and
+`Authorization`, so its response is per visitor, and the copy's headers are
+the visitor's; either one stored in the entry serves one visitor's data to
+the next. Don't make them in a cached body: fetch outside and pass the
+result in, or pass in the values the fetch depends on.
+
 `ctx.get()` of a **non-cacheable variable** (`createVar({ cache: false })`, or
 a value written with `ctx.set(key, value, { cache: false })`) throws the same
 way, whether it goes through `getRequestContext().get()` or a `ctx` passed in
@@ -254,14 +278,20 @@ Ordinary (cacheable) variables stay readable. Calling the cached function from
 a loader does not exempt it: the loader re-runs on every request, but the
 cached body does not.
 
-The non-cacheable variable guard does not reach into LOADER bodies consumed
-inside the cached function (`await ctx.use(loader)`): loaders always run
-fresh, so their variable reads are exempt — but the CONSUMED VALUE is captured
-into the shared cache entry like any other computed data. (`cookies()` and
-`headers()` still throw there: that guard follows the cached body's whole
-async chain, loaders included.) Same rule across `cache()` and the PPR shell:
-handler/cached-scope consumption = baked copy, client-side `useLoader` = live
-(the consumption-lane rule, `/rango` → Invariants).
+A LOADER body consumed inside the cached function (`await ctx.use(loader)`)
+is part of that body: its value is captured into the shared cache entry like
+any other computed data, so a `{ cache: false }` variable read there throws,
+exactly as `cookies()`, `headers()`, `ctx.request.headers` and a theme read do
+(one guard follows the
+cached body's whole async chain, loaders included). The check runs only when
+the loader body starts inside the cached function: a loader something else in
+the request already started (a handler's `ctx.use()`, a route `loader()`)
+returns its memoized value without it, and that value is still stored in the
+entry. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
+client-side `useLoader` = live (the consumption-lane rule, `/rango` →
+Invariants). Under a route `cache()` a loader body's reads stay allowed (the
+route entry never stores a loader's value); during a PPR capture they refuse
+the capture, a handler-consumed loader's included.
 
 ### Side-Effect Guards
 
@@ -504,20 +534,55 @@ built into the server bundle, see `/prerender`.)
 Entries are tagged by the profile's `tags` plus any runtime `cacheTag(...tags)`
 calls in the function body. `cacheTag` has two forms: inside a `"use cache"`
 function it tags that entry; called during a request render outside
-`"use cache"` it tags the request's `ppr` shell / document-cache entry instead
-(see `/caching` → "Tag-Based Invalidation"). All built-in stores
-(`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`) index by tag.
-Invalidate on demand with `updateTag(...tags)` (awaitable,
-read-your-own-writes; for server actions) or `revalidateTag(...tags)`
-(background, non-blocking; for route handlers/webhooks). Both hard-purge; the
-difference is awaitability, not stale-serving. For `CFCacheStore`, cross-colo
-invalidation needs a `kv` namespace (markers live in that same namespace) or
-`tagPurge`. The separate `revalidate()` export is the client-update axis (which
-segments re-render on a navigation or action), not a cache bust.
-
-A `"use cache"` entry's tags do not propagate to an enclosing `cache()` segment
-entry: invalidating them re-runs the function on the next miss of the outer
-boundary, not before (see `/cache-guide` → "Nesting rule").
+`"use cache"` it tags what the render stores: the enclosing route `cache()`
+entry, a cached loader's own entry when called in its body, and the `ppr`
+shell or document-cache entry built from them (on a `ppr` route, only when
+shell material calls it). See `/caching` → "Tag-Based Invalidation". All
+built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`,
+`VercelCacheStore`) index by tag. Invalidate on demand with
+`updateTag(...tags)` (awaitable; for server actions) or
+`revalidateTag(...tags)` (background, non-blocking; for route
+handlers/webhooks). Both evict rather than mark stale, and the request that
+calls either reads its own writes; `updateTag()` also waits for the durable
+write. PPR shell reads on `CFCacheStore`/`VercelCacheStore` go through
+per-isolate memos, which the invalidating user skips via the fresh-reads
+cookie. For `CFCacheStore`, cross-colo invalidation needs a `kv` namespace
+(markers live in that same namespace) or `tagPurge`. The separate
+`revalidate()` export is the client-update control (which segments re-render
+on a navigation or action), not a cache bust.
+
+A route `cache()` entry stores the tags of the `"use cache"` reads inside it,
+so `updateTag()` of one evicts the enclosing entry and any `ppr` shell or
+document built from it. A loader's own `cache()` entry does the same for the
+reads in its body, and a `"use cache"` function for the `"use cache"`
+functions it calls: the outer entry bakes the inner value, so it carries the
+inner tags, whether the inner call ran, was a hit, or joined another call's execution. That includes calls made
+by the server components a cached component returns, which render when the
+value is stored.
+
+```typescript
+async function getStock(sku: string) {
+  "use cache";
+  cacheTag("stock");
+  return db.stock(sku);
+}
+
+async function getProductCard(sku: string) {
+  "use cache";
+  return { sku, stock: await getStock(sku) };
+}
+
+// getProductCard's entry is tagged "stock": updateTag("stock") evicts both.
+```
+
+A call that started before `updateTag()`/`revalidateTag()` of one of its tags
+returns what it read but does not store it, in any request: written after the
+invalidation, the old value would be served as newer than it. The next call
+runs the function again. The same holds for a stale entry's background
+refresh, a loader's own `cache()`, route `cache()` entries and the document
+cache. Another isolate's invalidation is caught through the store's markers:
+`CFCacheStore` with KV, `VercelCacheStore`. On a KV-less `CFCacheStore` only
+this isolate's invalidations are caught; ttl+swr bounds the rest.
 
 ## Interaction with Other Caching
 
@@ -531,7 +596,10 @@ boundary, not before (see `/cache-guide` → "Nesting rule").
 | `Prerender()`    | Route segment tree | Build-time | Pre-render known params, optional live fallback       |
 
 Inside a `ppr` shell, a `"use cache"` value that renders as shell material is
-pinned at capture time for the life of that shell (see `/ppr` → Pitfalls).
+pinned at capture time for the life of that shell (see `/ppr` → Pitfalls). A
+hole's own read (in a loader without `ssr: false` under `loading()` or an
+inline `<Suspense>`) always returns the store's current entry, never the
+shell's copy, even when a loader the capture ran read the same entry.
 
 ## Dev Mode and tests
 

package/skills/vercel/SKILL.md

@@ -89,12 +89,24 @@ import { getCache, waitUntil } from "@vercel/functions";
 
 const defaults = { ttl: 60, swr: 300 };
 const memoryStore = new MemorySegmentCacheStore({ defaults });
+// One handle per process: getCache() resolves the platform cache on every
+// call, and VercelCacheStore keeps its PPR shell and tag-marker memos per
+// handle. After updateTag(), the same process misses at once, the rest of the
+// region once its marker memo refreshes (memo.markerMaxStaleMs, default 2000),
+// and the mutating user at once (the fresh-reads cookie skips the memos).
+// Another region serves a memoized shell until memo.shellMs (default 2000)
+// passes, since the tag markers are regional and only expireTag is global. A
+// platform expireTag issued outside rango writes no marker, so every memo
+// serves the shell until its window passes.
+const runtimeCache = process.env.VERCEL
+  ? getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })
+  : undefined;
 
 function resolveCache() {
-  if (process.env.VERCEL) {
+  if (runtimeCache) {
     return {
       store: new VercelCacheStore({
-        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        cache: runtimeCache,
         waitUntil,
         defaults,
       }),

package/skills/view-transitions/SKILL.md

@@ -227,8 +227,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 server-side gate. PPR routes run it before route handlers and
-  // on every replay; other routes run it after handlers on fresh resolution.
+  // Browser predicate, once per navigation: false commits it urgently with no
+  // view transition. See "Conditional transitions".
   when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
@@ -240,47 +240,162 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`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 hold is navigation-wide: the navigation streams its `loading()` fallback instead of holding only when no other matched segment still has a transition (the common case is a single `transition()` on the route).
+`transition({ when })` decides, per navigation, whether the navigation holds.
+It is a **browser** predicate: it runs once per navigation, at the first
+commit that presents the destination, and never on the server, on the
+document load, or on progressive-enhancement paths. Return `false` and the
+navigation commits urgently: the `loading()` skeleton streams and no view
+transition runs.
+
+Write it inline in `urls()`. The Vite plugin hoists the literal into a
+`"use client"` module, and the route carries it to the browser as a client
+reference. The hoist applies to the router's `transition`: the `urls()`
+helper (renamed or not) or `transition` imported from `@rangojs/router`,
+with the function written directly as the `when` value (an arrow, a
+`function`, or a `when() {}` method; `as` / `satisfies` wrappers are
+fine). A config built elsewhere, such as `transition(cfg)`, is not hoisted:
+export that predicate from a `"use client"` module instead.
 
-Timing follows the route's rendering contract:
+```ts
+// Hold unless the navigation leaves the "b" tab (the navigation SOURCE):
+transition({ when: ({ from }) => from.params.tab !== "b" });
+
+// Hold only for forward navigations inside /list:
+transition({
+  when: ({ kind, to }) => kind !== "pop" && to.url.pathname.startsWith("/list"),
+});
 
-- 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.
+// Hold only after a specific action revalidated the route:
+transition({ when: ({ isAction }) => isAction(addToCart) });
+```
 
-Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
+For a predicate you share between routes or unit-test, export it from a
+`"use client"` module and import it into the urls file:
 
 ```ts
+// src/transitions.ts
+"use client";
 import type { TransitionWhenContext } from "@rangojs/router";
+import { Slide } from "./location-states.js";
 
-// Ordinary route: hold only when the handler marked this request:
-transition({ when: (ctx) => ctx.get(KeepScroll) === true });
+export function slideWhen({ to }: TransitionWhenContext): boolean {
+  return Slide.read(to)?.animate !== false;
+}
 
-// Hold only when arriving from a specific page (the navigation SOURCE):
-transition({
-  when: ({ currentUrl }) => currentUrl?.pathname.startsWith("/list") === true,
-});
-transition({ when: ({ fromRouteName }) => fromRouteName === "products.list" });
+// src/urls.tsx
+import { slideWhen } from "./transitions.js";
+path("/photos/:id", PhotoPage, { name: "photo" }, () => [
+  transition({ default: "slide", when: slideWhen }),
+]);
 
-// Hold only after a specific action revalidated the route:
-transition({
-  when: ({ actionId }) => actionId === "src/actions/cart.ts#addToCart",
-});
+// A Link that opts this navigation out through location state:
+<Link to="/photos/2" state={[Slide({ animate: false })]}>Next</Link>;
 ```
 
-| field                                                  | meaning                                      | populated                                                                             |
-| ------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `currentUrl` / `currentParams` / `fromRouteName`       | navigation **source**                        | soft nav + action-success; `undefined` on initial full load and action/PE error paths |
-| `nextUrl` / `nextParams`                               | navigation **target**                        | always                                                                                |
-| `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 request vars + app env                  | always; PPR timing exposes middleware vars, not handler writes                        |
+Predicate modules (a `"use client"` export, or a hoisted inline literal) load
+with the client entry chunk, because the router must be able to call them at
+the first navigation. Keep them small: type imports and location-state
+definitions only, and nothing that touches `window` at module scope (the
+module is also evaluated during SSR).
+
+The rule is "a predicate runs where its effect lands": the hold is a browser
+commit decision, so the predicate runs in the browser. An inline literal may
+reference module-level imports only when they are client-safe (they are
+re-emitted into the hoisted module); a free server binding (a `const` in the
+urls file, a handler variable, a component used as JSX) or a server-only
+import is a build error that names it, and so are `import()`, `import.meta`
+other than `import.meta.env`, `this` / `arguments` of the enclosing
+function, and a `get when()` accessor. A server function passed by name, or a non-function, fails dev
+startup, the build and HMR re-discovery with the route name and pattern.
 
-A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
+### Context
 
-**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).
+```ts
+interface RouteLocation {
+  url: URL;
+  params: Record<string, string>;
+  routeName: string | undefined;
+  state: unknown; // the entry's history.state; read slots with Def.read(location)
+}
 
-**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">`).
+interface TransitionWhenContext {
+  kind: "push" | "replace" | "pop" | "action" | "revalidate";
+  from: RouteLocation; // the committed location being left
+  to: RouteLocation; // the destination; === from for "action" and "revalidate"
+  isAction: IsActionFn; // the revalidate() matcher; false off-action
+  action?: { id; formData; result; error }; // kind "action" only
+}
+```
+
+| `kind`         | started by                                           | `to.state`                                                                                                                         |
+| -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `"push"`       | `Link`, `router.push()`                              | the pushed state plus server `ctx.setLocationState()` (handler, middleware, action)                                                |
+| `"replace"`    | `Link replace`, `router.replace()`                   | same as push                                                                                                                       |
+| `"pop"`        | back/forward                                         | the target entry's stored state                                                                                                    |
+| `"action"`     | a server action's revalidation, error boundary incl. | the current entry's state plus action-set state (none on the error lane: an error response sets no location state); `action.*` set |
+| `"revalidate"` | `router.refresh()`, a stale entry's revalidation     | the current entry's state                                                                                                          |
+
+- `Def.read(location)` reads a location-state slot from `from` or `to`
+  without clearing flash state.
+- Middleware-set location state reaches `to.state` on a PPR replay HIT too
+  (middleware runs on every HIT); a route handler's does not, because a HIT
+  runs no handler. Set it from middleware when a `ppr` route decides on it.
+- A `clientUrls()` cross-route navigation decides at its optimistic swap,
+  before the server responds, so its `to.state` holds only the pushed
+  state.
+- On `"pop"`, `from.state` and `from.routeName` come from the router's
+  per-history-entry memory; after a reload they are `undefined`.
+- `get()`, `env` and handler state do not exist in the browser.
+
+### Combination and `false`
+
+- The navigation holds only when **every** committed segment's `when`
+  returns true, kept or re-sent: a layout the navigation keeps still gates
+  it ([#989](https://github.com/rangojs/rango/issues/989)). The same function
+  on several segments is called once.
+- `false` makes the whole navigation urgent, so no segment animates. Every
+  `<ViewTransition>` stays in the tree with its classes set to `"none"`, so a
+  same-route navigation that flips `true -> false -> true` never remounts
+  the route or loses its state
+  ([#995](https://github.com/rangojs/rango/issues/995)).
+- That holds for every kind, actions and revalidations included: a gated-off
+  action or revalidation commit is urgent too, so a segment it re-renders
+  streams its `loading()`. The router commits an action's result after the
+  response arrives, outside the transition React opens for a form action or
+  `useActionState` call, so React does not hold it either.
+- A predicate that throws counts as `false` and is logged with
+  `console.error` (the conservative default: no hold).
+- Intercept (modal) commits skip the evaluation, including a back/forward
+  that opens or closes a modal.
+- A stale revalidation the user navigated away from before it landed is
+  discarded without calling the predicate.
+- Intercept `from` differs: while a modal is open, an intercept selector's
+  `from` is the page under the modal (see the intercept skill); here it is
+  always the location on screen.
+- In a `clientUrls()` group, `false` also opts a same-route navigation out of
+  the group's default hold.
+
+`kind` lines up with the class keys in "Direction-aware transitions": a
+`"pop"` restored from the history cache animates with `"navigation-back"`
+(a pop that refetches uses `"navigation"`); `"push"`, `"replace"` and a
+`router.refresh()` (`"revalidate"`) use `"navigation"`; a stale entry's
+revalidation (`"revalidate"`) and an action's refetch (`"action"`) use
+`"action"`. An action's own commit (`useActionState`, a form action) carries
+no transition type (see the note under "Direction-aware transitions").
+
+### Opting out per navigation
+
+`router.push(url, { transition: false })`, `router.replace(url, {
+transition: false })` and `<Link transition={false}>` present one
+navigation the way `when` returning `false` does, without calling any
+predicate. Back/forward, actions and revalidation have no per-navigation
+options and are unaffected.
+
+```tsx
+<Link to="/photos/2" transition={false}>
+  Jump without the slide
+</Link>
+```
 
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 
@@ -361,6 +476,12 @@ await expect(page$).toBeVisible();
 Waiting for `toHaveCount(1)` first is not enough: the count passes through 1
 before the second host is inserted.
 
+Unit-test a `when` with `runTransitionWhen(when, { kind, from, to, action })`
+from `@rangojs/router/testing`, and a route's hold with `renderRoute`:
+`router.navigate()` decides with `kind: "push"`, `router.refresh()` with
+`kind: "revalidate"`. Pop, action and `clientUrls()` optimistic-swap
+decisions are e2e territory. See the testing skill, `predicates.md`.
+
 ## Recommendations
 
 **Put `<ParallelOutlet />` in layouts, not routes.** A route-level `transition` wraps the route component itself, so a `<ParallelOutlet />` rendered directly inside that route component remains inside the route VT subtree — modal opens on a route with a parallel outlet _will_ trigger the route's VT walker. The narrowing fix only applies at layout boundaries. If you combine intercept modals with route-level transitions, mount the slot one level up in a layout.

package/src/__augment-tests__/augmented.check.ts

@@ -10,10 +10,14 @@ import type {
   Handler,
   MiddlewareContext,
   ResponseHandlerContext,
+  RouteLocation,
   RouteParams,
   RouteSearchParams,
+  ServerRouteLocation,
+  TransitionWhenFn,
 } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { InterceptWhenFn } from "../server/context.js";
 import { href } from "../href-client.js";
 import type { Money, TestBindings } from "./augment.js";
 
@@ -69,6 +73,23 @@ type _routeName = Expect<
   Equal<DefaultRouteName, "home" | "blog.post" | "search">
 >;
 
+// transition({ when }) / intercept({ when }) locations carry the public route
+// name (internal names never reach them), typed like every routeName.
+type _locationRouteName = Expect<
+  Equal<RouteLocation["routeName"], DefaultRouteName | undefined>
+>;
+type _serverLocationRouteName = Expect<
+  Equal<ServerRouteLocation["routeName"], DefaultRouteName | undefined>
+>;
+const transitionWhenTypo: TransitionWhenFn = ({ to }) =>
+  // @ts-expect-error - "blog.pots" is not a generated route name
+  to.routeName === "blog.pots";
+const interceptWhenTypo: InterceptWhenFn = ({ from }) =>
+  // @ts-expect-error - "hom" is not a generated route name
+  from.routeName === "hom";
+void transitionWhenTypo;
+void interceptWhenTypo;
+
 // RouteParams / RouteSearchParams resolve from the generated map with no
 // explicit route map argument.
 type _params = Expect<Equal<RouteParams<"blog.post">, { slug: string }>>;
@@ -131,6 +152,8 @@ type _flightOverride = Expect<Equal<Rango.FlightSerialize<Money>, number>>;
 // Reference the top-level assertion aliases so they are unambiguously evaluated.
 export type _Assertions = [
   _routeName,
+  _locationRouteName,
+  _serverLocationRouteName,
   _params,
   _search,
   _orderWireByPattern,