@rangojs/router 0.22.1 → 0.24.0

package/skills/loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loader
-description: Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, or must be settled in the SSR'd document (ssr:false).
+description: Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:false), or must stay out of link prefetches (prefetch:false).
 argument-hint: "[loader]"
 ---
 
@@ -285,7 +285,9 @@ See `/route` for the full handler-context contract (shared with loaders) and
 
 - `ctx.params` — merged route params + explicit loader params. For fetchable
   loaders called with `load(Loader, { params: { ... } })`, explicit params
-  override route-matched params.
+  override route-matched params. Explicit params are string values; a request
+  with another value or a `__proto__`, `constructor` or `prototype` key is
+  rejected (400, `load()` fails with `Invalid loader params`).
 - `ctx.routeParams` — server-trusted route params from URL pattern matching.
   Cannot be overridden by client-provided params.
 
@@ -333,6 +335,10 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+In a `clientUrls()` group the same `loader(Def, () => [revalidate(fn)])` form
+runs on the server with these arguments; the build moves the predicate out of
+the `"use client"` module (`/client-urls` → "Revalidation runs on the server").
+
 ### `revalidate()` return shapes
 
 > **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
@@ -936,6 +942,8 @@ function ProductPage() {
 }
 ```
 
+A skeleton that has appeared stays on screen for at least about 300 ms before React replaces it with what it was waiting for: React does not replace a fallback sooner than 300 ms after the last fallback committed ([#1078](https://github.com/rangojs/rango/issues/1078)). On a cold click that mounts the `loading()` boundary, a loader that finishes sooner than that still shows its skeleton for about 300 ms, while a slower loader is not delayed. The router leaves this to React: an early skeleton is preferred to holding the click, and a fully prefetched click commits complete and shows none. A nested `loading()` whose data lands after the outer one has been revealed shows its own fallback, and the 300 ms starts again. The loaders feature page on the docs site has the measured figures. Under `transition()` a related cost applies; see [view-transitions](../view-transitions/SKILL.md).
+
 ## Loader Authority: notFound() and redirect()
 
 A loader may **throw** `notFound()` and `redirect()` — data-dependent
@@ -1094,6 +1102,195 @@ The costs and constraints:
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful.
 
+## `prefetch: false` — Keep a Loader Out of Prefetches
+
+A `<Link>` prefetch is a navigation sent early: the server renders every
+handler and every loader for it. With the default `"viewport"` strategy that
+means a grid of forty product links runs forty copies of your slowest loader
+for pages most visitors never open. Pass `prefetch: false` to keep one loader
+out:
+
+```tsx
+import { Suspense } from "react";
+
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(PriceLoader), // cheap: still runs in the prefetch
+  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in a prefetch
+  loading(<ProductSkeleton />),
+]),
+```
+
+(`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
+`{ ssr: false, prefetch: false }` if you need both.)
+
+What happens:
+
+- A **prefetch** of the route does not run the loader and does not read its
+  `cache()`; the payload marks it deferred. The rest of the page prefetches as
+  usual.
+- Only on a route the browser does not show yet. A loader the page already
+  holds, on a same-route navigation such as `/product/a` to `/product/b`, runs
+  in the prefetch when it revalidates, exactly as without the flag, and the
+  click sends no second request. The rule: a click that adopts a prefetch is
+  never worse than the same click with no prefetch at all (one exception: a
+  click before its prefetch has answered, under "The limits"), and content on
+  screen is never swapped for a fallback because of the flag. For the same
+  reason a prefetch that deferred something is used only on the page that
+  made it: a page that already shows the segment makes its own prefetch.
+- A **click** that adopts that prefetch is never blocked by the loader. A
+  deferred loader behaves like a loader that is still streaming, and where
+  the page reads it (`useLoader(ReviewsLoader)`) React does what it does for
+  one:
+  - the read has its own `<Suspense>`: the page shows at once with that
+    fallback in it. This can be a finer fallback than the same click shows
+    with no prefetch, where the whole route is still streaming behind its
+    `loading()`;
+  - the nearest boundary is the route's `loading()`: that fallback shows;
+  - no boundary at all: React holds the page being left until the value
+    arrives.
+
+  Meanwhile the browser sends one second request, the fill, that runs only
+  the deferred loader. Its value arrives in the page that is already on
+  screen, as a streamed loader's does; nothing remounts.
+
+- A **document request** (hard load), a **navigation with no prefetch to
+  adopt**, an action, back/forward and a no-JS form post run the loader as
+  they always did. Leaving the option out is the old behavior.
+
+Read the loader behind a boundary, as you would any streamed loader:
+
+```tsx
+"use client";
+function Reviews() {
+  const { data } = useLoader(ReviewsLoader);
+  return <ReviewList items={data} />;
+}
+
+// in the server component:
+<Suspense fallback={<ReviewsSkeleton />}>
+  <Reviews />
+</Suspense>;
+```
+
+The limits:
+
+- **A click before its prefetch has answered waits for it, then fetches the
+  deferred part.** The flag is there to keep expensive or slow work out of
+  every prefetch, so that an API that is costly to call is not called for
+  every link a visitor might click. A click that comes while the link's
+  prefetch is still in flight reuses that prefetch, as it does without the
+  flag, and sends the fill when the prefetch answers. The page shows no later
+  than with no prefetch; the deferred part shows its fallback until the fill
+  lands, and can complete later than a click with no prefetch, by up to what
+  was left of the prefetch. That is the price of keeping the work out of the
+  prefetch.
+- **A navigation started before the fill answers cancels it.** It is
+  cancelled when the newer navigation starts, not when that one commits. If
+  the newer navigation then ends without replacing the page (a redirect the
+  client refuses, an action refetch that drops its response), the deferred
+  part keeps its fallback until the next navigation. Every other ending
+  replaces the page anyway.
+- **`navigate()` resolves after the fill has answered.** The click's
+  navigation fills the deferred part itself, so `await navigate(url)` (and a
+  `router.push()` you await) settles a round trip after the page committed.
+  `useNavigation()` reads `idle` from the commit, with `isStreaming` true
+  until the fill has streamed in.
+- **A boundary is required for a fallback.** With no `loading()` on the entry
+  and no `<Suspense>` around the read, nothing can show a fallback, so React
+  holds the page being left on screen until the fill returns.
+  `useNavigation()` reads `state: "loading"` for that time, as on any
+  navigation that is still streaming, so a progress bar shows, and the URL
+  hooks (`useNavigation().location`) change with the page. The address bar
+  has already changed: it moves with the click, where a click with no
+  prefetch moves it when its response starts. There is no definition-time
+  error.
+- **`ctx.rendered()` is refused.** A loader that can be deferred throws on
+  every request kind (a document load included, so you see it the first time
+  you open the page in development) if it calls `await ctx.rendered()`. The
+  fill does not re-run the entry's handler, so there is no render to wait for
+  and no handle data to read. Remove `{ prefetch: false }` from the loader, or
+  stop calling `ctx.rendered()`. Pushing a handle from the loader is fine.
+- **`ctx.set()` values from held handlers are not visible.** The fill runs the
+  deferred work and middleware only. A handler or layout the client already
+  holds does not run again, so a variable it set with `ctx.set()` is missing
+  when the loader reads it with `ctx.get()`. Variables set by middleware are
+  there, as middleware runs on every request; so are `ctx.params` and
+  `ctx.request`.
+- **`redirect()`, `notFound()` and handle pushes arrive late.** They behave as
+  for a loader that streams behind `loading()`, but they come with the fill,
+  after the page is already on screen: a redirect becomes a replace
+  navigation, `notFound()` renders the nearest not-found boundary, an error
+  reaches the error boundary.
+- **The fill reads through the loader's own caching; a prefetch reads none
+  of it, by intent.** A loader with `cache()` that nothing in the prefetch
+  reads is skipped even when its entry is warm, and so is a `"use cache"`
+  function it calls: a prefetch that looked would have to run the loader on
+  a miss, which is the work the flag keeps out. The fill is where the loader
+  runs. It serves a warm `cache()` entry without running the loader, runs
+  the loader and stores on a cold one, and a `"use cache"` function inside
+  the loader hits or stores as on any request.
+- **A loader something else reads with `ctx.use()` runs in the prefetch.**
+  The reader needs the value, so the flag cannot keep the loader out. When
+  the read is in time, the loader is an ordinary loader for that prefetch,
+  its own `cache()` included: one run (none on a warm entry), the reader and
+  the loader's data agree, nothing deferred, no fill for it. In time means:
+  inside a handler that has no `loading()` (the router waits for it), or
+  before the reader's first `await`.
+- **Two late readers make it run twice.** The loader runs in the prefetch for
+  its reader and again in the fill, because by the time the read happens the
+  loader's own segment has already been sent as deferred:
+
+  ```tsx
+  // 1. A handler under loading() is streamed: the router does not wait for
+  //    it, so a read after its first await comes late.
+  path(
+    "/product/:id",
+    async (ctx) => {
+      const product = await getProduct(ctx.params.id);
+      const reviews = await ctx.use(ReviewsLoader); // late: runs it here
+      return <Product product={product} reviews={reviews} />;
+    },
+    { name: "product" },
+    () => [
+      loader(ReviewsLoader, { prefetch: false }), // and the fill runs it again
+      loading(<ProductSkeleton />),
+    ],
+  );
+
+  // 2. A loader that is not deferred itself and reads it after an await.
+  const SummaryLoader = createLoader(async (ctx) => {
+    const product = await getProduct(ctx.params.id);
+    const reviews = await ctx.use(ReviewsLoader); // late: two runs
+    return summarize(product, reviews);
+  });
+  ```
+
+  Data is never missing, only fetched twice, and the page shows the fill's
+  value. To get one run, start the read before the first `await`
+  (`const reviews = ctx.use(ReviewsLoader)` at the top, awaited where you
+  need it), or drop the flag from a loader the page cannot render without.
+
+- **`clientUrls()` routes take it on `loader()`.** In a `clientUrls()`
+  definition `loader(Def, { prefetch: false })` works as here: a click
+  inside the group shows the destination at once, commits the prefetched
+  data with the URL, and one fill runs the flagged loaders (see
+  `/client-urls` → "`prefetch: false`"). A flagged `loading()` defers nothing
+  on a group route, from the group or from a server layout above it.
+- **No effect inside `intercept()`.** Its loaders accept the flag and ignore
+  it, in `urls()` and in `clientUrls()`: a prefetch that resolves an
+  intercept defers nothing.
+- **`ppr` and `ssr: false`.** On a `ppr` route an `ssr: false` loader is the
+  bake lane and is served from the shell, so `prefetch: false` is ignored for
+  it and development logs a warning. Under `cache()` and `Prerender` the flag
+  works as above (see `/caching`, `/prerender`, `/ppr`).
+
+To skip a handler along with its loaders, flag the `loading()` instead (see
+`/route` → "`loading()` options"). `loader(Def, { prefetch: false })` accepts
+only a boolean; anything else throws `loader() prefetch must be a boolean`.
+
+Test it with `serveShellRequest(router, url, { partial: { prefetch: true } })`
+and `result.readDeferred()` (see `/testing`).
+
 ## Fetchable Loaders
 
 By default, loaders only run as part of a render (document, navigation, or

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.
+description: Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects, rewrites (throw rewrite() renders another route at the same URL). Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, showing a maintenance page at the visitor's URL, or deciding whether middleware wraps server actions.
 argument-hint: [middleware-name]
 ---
 
@@ -19,7 +19,7 @@ There are two levels of middleware with different execution scopes:
 
 ### Global middleware (`router.use()`)
 
-Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders. A request a middleware rewrites (`throw rewrite()`, below) runs the chain again for the target: once per pass.
 
 ```typescript
 const router = createRouter<AppEnv>({})
@@ -257,6 +257,8 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.headers; // response Headers (stub before next(), the real response after)
   ctx.setLocationState(FlashMessage({ text: "Saved" })); // history state for the client
   ctx.reverse("home"); // URL for a global route name (no ".name", no param auto-fill)
+  ctx.rewrittenFrom; // the visitor's URL when this request was rewritten, else undefined
+  ctx.isRewrite(error); // true for a thrown rewrite() (rethrow it from a try/catch)
 
   // Opt the current request out of PPR shell lookup/capture.
   ctx.dynamic();
@@ -428,6 +430,185 @@ Read the flash on the target page with `useLocationState(FlashMessage)`. The `{
 
 A redirect is followed on a link click, `router.push()`, and Back/Forward to an entry the client has to fetch. On Back/Forward the redirect replaces the history entry it was triggered from: Back from the target lands on the entry before the redirecting one, not on the redirecting one again. The client follows at most 20 redirects in one navigation; a loop (two pages redirecting to each other) stops there with the error boundary and a `[rango] Server redirect loop` console error.
 
+## Rewrite: another route at the same URL
+
+`throw rewrite(target)` renders another route while the address bar keeps the
+visitor's URL: a maintenance or lock page, a deploy migration, a URL override,
+an A/B or geo split. A redirect changes the URL; a rewrite does not.
+
+```typescript
+import { getRequestContext, rewrite } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+
+export const maintenance: Middleware = async (ctx, next) => {
+  if (!locked || ctx.pathname === "/maintenance") return next();
+  // Mutations get a Response: a rewrite cannot answer a server action or a form post.
+  if (ctx.request.method !== "GET") {
+    return new Response("Maintenance", {
+      status: 503,
+      headers: { "Retry-After": "600" },
+    });
+  }
+  ctx.set(Lock, { until });
+  throw rewrite("maintenance");
+};
+
+// urls.tsx — the target sets its own status
+path("/maintenance", MaintenancePage, { name: "maintenance" }, () => [
+  middleware(async (ctx, next) => {
+    getRequestContext().setStatus(503);
+    ctx.header("Retry-After", "600");
+    await next();
+  }),
+]);
+```
+
+Targets, like `ctx.reverse` with a path form:
+
+```typescript
+throw rewrite("/maintenance"); // a path (basename-prefixed like redirect())
+throw rewrite("/maintenance?from=shop"); // a path with search
+throw rewrite("maintenance"); // a global route name without params
+throw rewrite("product", { slug }); // with params
+throw rewrite("product", { slug }, { tab: "reviews" }); // and search
+```
+
+**How it runs.** The throw unwinds the request to the router, which runs it
+again as the target, from the top, as a direct visit would: global middleware
+matched on the target's path (a `.use("/admin/*", guard)` or an inline
+`ctx.pathname` check decides on the rendered route), the target's route
+middleware, its render. Code after `await next()` in the pass that rewrote
+never runs, and global middleware runs once per pass.
+
+**Never skip a guard on a rewritten pass.** Authorization, auth and
+rate-limit checks run on every pass, as written: the target's guards
+deciding on the rendered route is what keeps a rewrite from becoming a way
+around them. `if (!ctx.rewrittenFrom)` is only for side effects you want
+once per request, such as a counter or a log line:
+
+```typescript
+export const countVisit: Middleware = async (ctx, next) => {
+  if (!ctx.rewrittenFrom) visits.increment(); // once per request
+  return next();
+};
+```
+
+**Throw it before `await next()`.** Once your `next()` ran the route, the
+page has rendered: a `throw rewrite()` after it (a "rewrite on 404" after
+`const res = await next()`) is an error, "throw rewrite() before await
+next()". Decide before calling `next()`. A rewrite thrown further down
+passes through your `await next()` as usual, and in a `catch` around it you
+may throw another rewrite in its place; after any other failure of `next()`
+(the route may have rendered before it failed) a rewrite is an error too.
+
+**Same request context.** Values you `ctx.set()` before the throw are
+readable in the target's middleware, handlers and loaders; cookies, headers
+and the status you set stay on the response; location state, theme and
+`ctx.dynamic()` carry over. The request, URLs, params and route name are the
+target's.
+
+**Old and new URL.** `ctx.url`, `ctx.pathname` and `ctx.searchParams` are
+the target's; `ctx.rewrittenFrom` is the visitor's URL (search included; the
+first URL after several rewrites; `undefined` when nothing rewrote).
+`usePathname()` and `useSearchParams()` show the visitor's URL in the server
+HTML and after hydration, except in a render other visitors are served (see
+Caches); `useParams()` and the route name are the target's. The response
+carries `x-rango-rewrite: <target pathname>`.
+
+**`ctx.rewrittenFrom` is request identity**, like `cookies()`: reading it
+inside a `cache()` boundary or a `"use cache"` function throws (pass what
+you need in from middleware), and a render other visitors may be served (a
+PPR shell capture, a page the document cache stores) reads `undefined`, as a
+direct visit does.
+
+**Middleware only, by design.** `rewrite()` is a middleware tool. A route
+handler or a loader (any loader, `ssr: false` included) cannot rewrite: its
+throw is an error whose message points you to route middleware. A rewrite
+that depends on data goes in the route's middleware, reading the data
+through a cached function the loader shares, so the lookup runs once:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  middleware(async (ctx, next) => {
+    const product = await getProduct(ctx.params.slug); // cached, shared with the loader
+    if (product.discontinued) {
+      throw rewrite("discontinued", { slug: ctx.params.slug });
+    }
+    await next();
+  }),
+  loader(productLoader), // calls getProduct(slug): a cache hit
+]);
+```
+
+**Throw it, don't return it.** A returned rewrite is an error. Where a
+rewrite cannot be honored it is an error that names the rule: a route
+handler or a loader (see above), a server action (use `redirect()`),
+intercept middleware, a loader fetch (`useFetchLoader`, `load()`: it
+rejects with the rule) or its middleware, and middleware handling a non-GET
+request (a JS action or a no-JS form post: return a `Response`).
+
+**try/catch around next().** A thrown rewrite passes through your
+middleware's `catch`. Rethrow it:
+
+```typescript
+export const errorPage: Middleware = async (ctx, next) => {
+  try {
+    return await next();
+  } catch (error) {
+    if (ctx.isRewrite(error)) throw error;
+    return new Response("Something went wrong", { status: 500 });
+  }
+};
+```
+
+**Loops.** More than 5 rewrites in one request, or a rewrite to the URL the
+request is on, answers 508 and reports a `RewriteLoopError` (its message has
+the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
+
+**Caches.**
+
+- The document cache keys a rewritten request by the target's URL, as a
+  direct visit. Register the rewriting middleware **before**
+  `createDocumentCacheMiddleware()`: a cache hit for the visitor's URL would
+  be served before your middleware runs. A page the document cache stores,
+  and a PPR shell of the target, are rendered as a direct visit to the
+  target: they carry the target's pathname and `ctx.rewrittenFrom` is
+  `undefined` there, so a component that renders `usePathname()` can
+  mismatch on hydration at the visitor's URL when such a page is served to
+  a rewritten request.
+- The client's prefetch and history caches keep a rewritten page under the
+  visitor's URL, and nothing tells them about the rewrite: a page prefetched
+  during a lock shows the lock page for up to `prefetchCacheTTL` after the
+  lock lifts. `invalidateClientCache()` drops a client's caches, for the
+  client that receives the response; mark the clients that saw the lock and
+  call it on their first response after it lifts:
+
+  ```typescript
+  import { cookies, invalidateClientCache, rewrite } from "@rangojs/router";
+
+  export const maintenance: Middleware = async (ctx, next) => {
+    if (!locked) {
+      if (cookies().get("saw-lock")) {
+        cookies().delete("saw-lock");
+        invalidateClientCache();
+      }
+      return next();
+    }
+    cookies().set("saw-lock", "1", { path: "/" });
+    // ...the lock as above
+    throw rewrite("maintenance");
+  };
+  ```
+
+**Testing.** `runMiddleware` reports a thrown rewrite as `result.rewrite`
+(`{ pathname, search, routeName? }`). `serveShellRequest` takes a rewritten
+page request through the full production pipeline (document or `partial`
+navigation): the target's middleware, render, status and `x-rango-rewrite`.
+`dispatch` re-dispatches too, for response routes only: it matches the
+visitor's URL first and throws on a component (RSC) route.
+`renderRoute(..., { request: "/shop", rewrite: "/maintenance" })` renders
+the target's route at the visitor's URL. See `/testing`.
+
 ## Authentication Middleware
 
 ```typescript

package/skills/migrate-nextjs/SKILL.md

@@ -850,8 +850,8 @@ For **dashboard / admin / settings-shaped sections** — high navigation
 frequency inside one layout, mostly tab/param/filter switches — also consider
 porting that route group to `clientUrls()` (`/client-urls`): the definition
 matches in the browser (instant optimistic pending, no server round-trip to
-start a transition) and browser-run `revalidate()` predicates hold data across
-switches that don't invalidate it, which is the fastest transition shape Rango
+start a transition) and per-loader `revalidate()` predicates (run on the
+server) hold data across switches that don't invalidate it, which is the fastest transition shape Rango
 has. Server-component routes and `clientUrls()` groups compose in one tree.
 
 ## 7. Server Actions

package/skills/migrate-react-router/SKILL.md

@@ -84,21 +84,24 @@ per app (both compose in one `urls()` tree via `include()`):
   | component (client, hooks)        | stays a client component — no conversion                 |
   | `loader` (throws `redirect`/404) | `createLoader()` — thrown `redirect()`/`notFound()` kept |
   | `useLoaderData()`                | `useLoader(Loader)` at the read site, under `<Suspense>` |
-  | `shouldRevalidate` (runs client) | `revalidate()` predicate — ALSO runs in the browser      |
+  | `shouldRevalidate` (runs client) | `revalidate()` predicate — runs on the server            |
   | `meta({ data })`                 | `ctx.use(Meta)` push from the loader body                |
   | `defer` / `Await`                | loaders stream; `<Suspense>` above each read             |
 
-  Note the `shouldRevalidate` row: a server-tree `revalidate()` runs on the
-  server, but a `clientUrls()` predicate runs in the browser with
-  client-computable args — the exact RR semantics. A group ported this way can
-  still be re-migrated to server handlers later, route by route.
+  Note the `shouldRevalidate` row: RR runs it in the browser, but a
+  `clientUrls()` loader's predicate runs on the server like a server-tree
+  `revalidate()`, with the same arguments (`actionResult` and `formData`
+  included). The build moves it out of the `"use client"` module, so it may
+  reference imports and globals only: move a predicate that captures
+  module-local values into its own module and import it. A group ported this
+  way can still be re-migrated to server handlers later, route by route.
 
 Start with server handlers; reach for `clientUrls()` when a route group's
 conversion cost is dominated by rewriting interactive components rather than
 by moving data fetching — or when the group is a **high-navigation-speed
 surface** (dashboard, admin panel, settings): browser-local matching gives
-instant optimistic pending, and browser-run predicates hold data across
-tab/param switches, so transitions are the fastest Rango offers. See
+instant optimistic pending, and per-loader `revalidate()` predicates (run on
+the server) hold data across tab/param switches, so transitions are the fastest Rango offers. See
 `/client-urls`.
 
 ## Migration Strategy

package/skills/migrate-react-router/data-and-actions.md

@@ -55,7 +55,7 @@ Use it only when you need capabilities beyond what the handler provides:
 If the React Router loader just fetches data for its page component AND the
 component can become a server component, merge it into the handler. If the
 component stays a client component, port the whole group with `clientUrls()`
-instead — loader, `useLoader` read, and browser-run `revalidate()` keep the RR
+instead — loader, `useLoader` read, and per-loader `revalidate()` keep the RR
 route-module shape (see the "Two target shapes" section in the main skill and
 `/client-urls`). See `/loader` for when the live data layer is useful.
 

package/skills/ppr/SKILL.md

@@ -149,6 +149,15 @@ material is shared per host+URL and request partition. `cache(false)`, or a
 `condition()` that returns false, on a ppr route now renders the request like a
 cache miss (no shell).
 
+### A request middleware rewrote
+
+A request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr`
+route is served the target's shell under the target's key. The capture
+renders the target as a direct visit: `ctx.rewrittenFrom` reads `undefined`
+there and the payload carries the target's pathname, so the shell is the
+same for direct and rewritten visitors (a component that renders
+`usePathname()` shows the target's URL to a rewritten visitor on a HIT).
+
 ### Request-partitioned shells
 
 A route whose `cache()` record is partitioned by the request partitions its
@@ -1069,6 +1078,19 @@ Four hard edges (each e2e/unit-pinned):
   must be fresh on every serve, it belongs on the live lane (no `ssr: false`) or
   in a nested promise.
 
+### `prefetch: false` on a `ppr` route
+
+A `ppr` route's handler output is stored, so a `loading()` flagged with
+`prefetch: false` does not skip the handler in a `<Link>` prefetch: the shell
+and its partial replay are served as usual and only the live loaders behind
+the fallback are deferred. A live loader registered with `{ prefetch: false }` is
+skipped the same way, and the click that adopts the prefetch sends one fill
+request for it. An `ssr: false` loader is the bake lane and is served from the
+shell, so on a `ppr` route `prefetch: false` is ignored for it, and
+development logs a warning that the loader "is registered with ssr: false
+and prefetch: false on a ppr route"; drop one of the two options. See
+`/loader` → "`prefetch: false`".
+
 ### The layout-with-loaders playbook (the storefront case)
 
 The most common real-app shape: an app-wide layout registers per-user loaders

package/skills/prerender/SKILL.md

@@ -666,6 +666,16 @@ build-time shell capture runs it and bakes its settled data into the shell,
 and a shell HIT runs it only when its return carries promises (`/ppr` → "The
 bake lane"). The Flight payload collection itself still skips loaders.
 
+### `prefetch: false` skips only the loaders
+
+A `Prerender` handler's output is stored, so a `loading()` flagged with
+`prefetch: false` on the route does not skip the handler in a `<Link>` prefetch: the
+stored output is served as usual, and only the loaders behind the fallback are
+deferred (a loader registered with `{ prefetch: false }` likewise). The click
+that adopts the prefetch shows the fallback and sends one fill request for
+them. This holds in development, where there is no build artifact, as in
+production. See `/loader` → "`prefetch: false`".
+
 ### Build-time handle data is frozen
 
 Handle values pushed via `ctx.use()` DURING pre-rendering (handler pushes at
@@ -1283,8 +1293,8 @@ fresh.
 A warm replaces the entry where it runs, and on a shared store that is the
 entry other locations read on their next miss. It does not reach a copy
 another location already holds: on `CFCacheStore`, each colo keeps serving its
-own Cache API copy until it expires, and an entry whose `ttl + swr` is under
-60 seconds never reaches KV at all.
+own Cache API copy until it expires or a tag invalidation rejects it, and an
+entry whose `ttl + swr` is under 60 seconds never reaches KV at all.
 
 So after a deploy (new keys: no location holds a copy) a warm alone makes
 the route ready everywhere. For a content change, invalidate first, then
@@ -1306,12 +1316,16 @@ path.json("/hooks/product-changed", async (ctx) => {
 
 The invalidation makes every location's copy unservable, so no visitor is
 served the old content, and the warm writes the new entry where it runs and
-to the shared store. A location with no copy of its own reads that entry on
-its next request and renders nothing. On `CFCacheStore`, a colo that was
-still holding its own (now invalidated) copy renders once for itself instead
-of reading the warmed entry, unless the store uses `tagPurge`, which evicts
-those copies. Await `updateTag()` before the warm: a write that started
-before an invalidation of one of its tags is refused.
+to the shared store. Every other location reads that entry on its next
+request and renders nothing: a location with no copy of its own, and, on
+`CFCacheStore` with `kvFallThrough: true` (default false), a colo that was
+still holding its own (now invalidated) copy, which reads KV as if it held
+none. Without the option such a colo renders once for itself, unless the store
+uses `tagPurge`, which evicts those copies. With the option, a colo renders
+for itself only while KV still hands it the entry from before the invalidation,
+which it refuses: Cloudflare documents up to 60
+seconds for a KV write to spread. Await `updateTag()` before the warm: a
+write that started before an invalidation of one of its tags is refused.
 
 ### Limits worth knowing
 

package/skills/rango/SKILL.md

@@ -168,13 +168,16 @@ stated, greppable contract.
   only applies when the enclosing cache recomputes; put a value in a loader if it
   must be fresher. See `/cache-guide` → "Combining Both".
 - **A predicate runs where its effect lands.** A server-tree `revalidate()`
-  decides what the server re-sends, so it runs on the server; an `intercept({
+  and a `clientUrls()` loader's `revalidate()` decide what the server re-sends,
+  so they run on the server (the build hoists a group's predicate out of its
+  `"use client"` module and passes it the `urls()` arguments: `/client-urls`);
+  an `intercept({
 when })` selector decides what the server renders, so it runs on the server;
-  a `clientUrls()` `revalidate()` and `transition({ when })` decide a browser
-  commit, so they run in the browser. A browser predicate sees URLs, params,
-  route names, history state and action data, never `get()`, `env` or handler
-  state; in a server `urls()` it is written inline (the build hoists it into a
-  client module) or imported from a `"use client"` module (`/view-transitions`).
+  `transition({ when })` decides a browser commit, so it runs in the browser.
+  A `transition({ when })` predicate sees URLs, params, route names, history
+  state and action data, never `get()`, `env` or handler state; in a server
+  `urls()` it is written inline (the build hoists it into a client module) or
+  imported from a `"use client"` module (`/view-transitions`).
 - **Vocabulary.** `revalidate()` keeps React Router's `shouldRevalidate`
   dialect (`currentUrl`/`nextUrl`, `currentParams`/`nextParams`). Navigation
   selectors (`intercept({ when })`, `transition({ when })`) use `from`/`to`
@@ -270,6 +273,9 @@ the `path()` re-run; layouts and parallels above the route are skipped.
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
 ```
 
+The same `actionResult` idiom works in a `clientUrls()` group's loader
+`revalidate()`, which runs on the server with these arguments.
+
 **The source is the source of truth.** Structure, types, and update policy are
 visible and local in the tree — read top-down, no hidden global model to hold in
 your head. A snippet earns its place only if, from the code alone, you can answer:
@@ -305,7 +311,7 @@ Grouped by concern — read when you need to…
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |
-| `/middleware`             | Request processing and authentication                                      |
+| `/middleware`             | Request processing, authentication, `throw rewrite()` (same-URL rewrites)  |
 | `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
 | `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
 | `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |