@rangojs/router 0.24.4 → 0.26.0

package/skills/middleware/SKILL.md

@@ -59,7 +59,9 @@ only between a route handler and its child/orphan layouts and parallels (so
 their latency overlaps rendering rather than blocking it. See `/loader` →
 "Parallel and streaming".
 
-The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
+The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation. When the action throws, the `errorBoundary()` render is wrapped too, in both transports: the boundary reads the middleware's `ctx.set()` values and the response carries its headers.
+
+Around the render after an action, route middleware's `ctx.request` is the page's GET: `method` is `"GET"`, with no body, and the headers are the POST's without `content-type` and `content-length`. It decides as it would for a GET of the page. Global middleware, which wraps the action, sees the POST, and so does `getRequestContext().request`. So a method check in route middleware never sees the mutation: it cannot block or answer one, since the action already ran. A header its GET branch sets also lands on the action's response. If a header must stay off mutation responses (a public `Cache-Control`), set it from global middleware.
 
 Revalidation is still partial. Route middleware wraps the render pass that
 does happen, but it does not force unrelated outer segments to recompute.
@@ -256,7 +258,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.header("X-Frame-Options", "DENY"); // set one response header
   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.reverse("home"); // URL for a global route name (no ".name", no param auto-fill; a missing required param throws)
   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)
 
@@ -442,8 +444,10 @@ 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") {
+  // A rewrite moves a server action or form post to its target, where the
+  // action runs. A lock answers mutations itself, so none runs under
+  // maintenance. HEAD rewrites like GET, as under .disallowMutations().
+  if (ctx.request.method !== "GET" && ctx.request.method !== "HEAD") {
     return new Response("Maintenance", {
       status: 503,
       headers: { "Retry-After": "600" },
@@ -463,6 +467,16 @@ path("/maintenance", MaintenancePage, { name: "maintenance" }, () => [
 ]);
 ```
 
+Without the `Response` branch, `.disallowMutations()` keeps a lock from
+running mutations: a server action or form post under it is an error before
+the action runs (a 500 the client shows as an error, reported through
+`onError` with phase `"routing"`), and GET and HEAD rewrite as usual. The
+`Response` above gives the caller a proper 503 instead.
+
+```typescript
+throw rewrite("maintenance").disallowMutations();
+```
+
 Targets, like `ctx.reverse` with a path form:
 
 ```typescript
@@ -519,7 +533,9 @@ carries `x-rango-rewrite: <target pathname>`.
 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.
+direct visit does. A shell keyed by the visitor's URL
+(`rewrite(...).shell("visitor")`, see Caches) reads it, since its key covers
+that URL.
 
 **Middleware only, by design.** `rewrite()` is a middleware tool. A route
 handler or a loader (any loader, `ssr: false` included) cannot rewrite: its
@@ -540,12 +556,59 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+**Mutations: where the middleware sits decides.** A server action or a no-JS
+form post from a rewritten page is posted to the visitor's URL, so the same
+middleware sees it:
+
+- **Global middleware** on the visitor's URL runs before the action. A
+  rewrite there moves the mutation to the target first, with its body: the
+  target's global middleware, then the action, once, then the target's
+  route middleware and render, as a direct post to the target. So a
+  routing rewrite (a multi-tenant host, an A/B split, a visitor URL with no
+  route) keeps its page's forms working, in JS and no-JS. Rewrite every
+  method: a rewrite written for GETs only leaves the mutation on the
+  visitor's URL, so the action runs on the visitor's route and its render
+  replaces the page. A lock must not run the mutation: return a `Response`
+  for mutations, or throw `rewrite(...).disallowMutations()`, which refuses
+  it with an error before the action runs. It chains with `.shell()` in
+  either order.
+- **Route middleware** runs after the action, around the re-render, and
+  sees it as the page's GET. A routing rewrite there (A/B, URL override,
+  the `discontinued` example above) fires as on a GET, including one
+  written for GETs only (`if (ctx.request.method !== "GET") return next()`).
+  The action runs once, then the re-render runs as the target (its global
+  and route middleware, its render, or its error boundary when the action
+  threw), and the page keeps its layout and state. Route middleware cannot
+  refuse the action, so `.disallowMutations()` has no effect there: the
+  render moves to the target, dev logs a warning on each throw, and
+  production logs one `console.error`. Put a lock in global middleware.
+- Global middleware on the target's pass sees the POST, with its headers.
+  A no-JS form post keeps its body, so a form-field check (a CSRF token
+  read from `ctx.request.clone().formData()`) passes on every pass, and so
+  does a mutation a global rewrite moved before its action, whose action
+  runs on the target's pass: do not skip a body check when
+  `ctx.rewrittenFrom` is set. Always read a clone; a rewrite after middleware
+  read the body itself is an error, since the action would get no
+  arguments. After a route-middleware rewrite, a JS action's body is gone
+  (the action read it), and that pass drops the `content-type` too, so a
+  body check gated on the content-type passes over it; that pass never runs
+  the action. Global middleware runs once per pass, as for any rewrite, so a
+  one-time token belongs in the action. An action's target must be a page
+  route: a rewrite that sends a server action or form post that already ran,
+  or a JS action before it runs, to a response route (`path.json()`) or a
+  path that redirects is an error. A plain POST a global rewrite moves
+  reaches a response route with its body, as a direct post would, and so
+  does a no-JS form post, whose action the router finds only on a page
+  route.
+
 **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`).
+a loader fetch (`useFetchLoader`, `load()`: it
+rejects with the rule) or its middleware. A `.disallowMutations()` rewrite
+from global middleware handling a non-GET, non-HEAD request (a JS action or
+a no-JS form post) is an error too, by your choice: it reads
+`rewrite("…") refused a mutation: .disallowMutations() was set`.
 
 **try/catch around next().** A thrown rewrite passes through your
 middleware's `catch`. Rethrow it:
@@ -570,12 +633,26 @@ the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
 - 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.
+  be served before your middleware runs. A page the document cache stores
+  is rendered as a direct visit to the target: it carries 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.
+- A PPR shell (`ppr` target) is read and written only by requests on its
+  URL. A rewritten request renders live at the visitor's URL, and a direct
+  visit captures the target's shell, so values you set before the throw
+  never reach it. Pick a shell for the rewritten request with `.shell()` on
+  the thrown value: `"visitor"` keys a shell by the visitor's URL, captured
+  with the visitor's location and `ctx.rewrittenFrom` (one shell per public
+  URL, the right choice for a routing catch-all); `"target"` reads and
+  captures the target's shared shell, which shows the target's URL to the
+  visitor on a HIT and bakes in what the rewriting middleware set, so keep it
+  for a lock or promo page that renders neither:
+
+  ```typescript
+  throw rewrite("item", { id }).shell("visitor");
+  ```
+
 - 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
@@ -600,10 +677,29 @@ the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
   };
   ```
 
+**Navigating from a rewritten page.** A navigation, prefetch or action from
+the page diffs against the route that rendered it, as one from a direct
+visit does: the payload carries the target (`metadata.rewriteTarget`), and
+the browser sends it back with the next request from that page. A
+`revalidate()` sees the target's params and URL (`currentParams.id` against
+`nextParams.id` holds a loader on a sort change), and a navigation to the
+page already shown re-renders nothing. A move to another visitor URL with
+the same target (`/promo/a` to `/promo/b`, both rewritten to
+`/promo/landing`) re-runs the route and its loaders, which may read
+`ctx.rewrittenFrom`. The browser only names the page being left: what
+renders still comes from the request's URL and your middleware.
+
 **Testing.** `runMiddleware` reports a thrown rewrite as `result.rewrite`
-(`{ pathname, search, routeName? }`). `serveShellRequest` takes a rewritten
+(`{ pathname, search, routeName?, mutationsDisallowed? }`, the last `true`
+only for `.disallowMutations()`). `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`.
+Pass the page's `metadata.rewriteTarget` as `partial.rewriteTarget` (or
+`action.rewriteTarget`) to send a request from it as the browser does.
+With `action` or `form` (from `createActionForm`) it posts a mutation to the
+visitor's URL, so a global rewrite's move, a `.disallowMutations()` refusal
+(it rejects with the refusal) and a route-middleware rewrite's re-render are
+testable too.
 `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

package/skills/observability/SKILL.md

@@ -302,6 +302,17 @@ Then inspect:
   first paint.
 - the `Server-Timing` header to compare local logs with browser-network timing.
 
+## Telling a page is a Rango app
+
+Every page sets `window.__rango = { version }` (frozen, one key) from the
+bundled client entry before hydration. `version` is the exact npm semver of
+`@rangojs/router`, nothing else: no build hash, router id or config. It is for
+devtools and support; the router never reads it and no option turns it off.
+
+```js
+window.__rango; // { version: "0.24.2" }
+```
+
 ## Zero-overhead defaults
 
 `debugPerformance` is off by default, `telemetry` emits nothing unless a sink

package/skills/parallel/SKILL.md

@@ -206,9 +206,9 @@ parallel(
   () => [
     // The loader keeps its own revalidation: by default it re-runs after
     // every action. Scope it here to stop that.
-    loader(CategoriesLoader, () => [revalidate(() => false)]),
+    loader(CategoriesLoader, () => [revalidate(false)]),
     loading(<SidebarSkeleton />),
-    revalidate(() => false), // the slot component renders once, then is kept
+    revalidate(false), // the slot component renders once, then is kept
   ]
 )
 ```
@@ -430,7 +430,7 @@ boundary above it: the route's `loading()`, replacing the entire route content
 with the route skeleton while one slot refetches. Either scope the slot's
 `revalidate()` (share the route's named contract, as above) or give the slot
 its own `loading()` so the fallback stays local. Don't reach for a bare
-`revalidate(() => false)`: the slot then never refreshes on param changes
+`revalidate(false)`: the slot then never refreshes on param changes
 either, and keeps the previous param's content on e.g. a product-to-product
 navigation.
 
@@ -438,7 +438,7 @@ navigation.
 it the first time. A slot the browser has not rendered yet has nothing to keep
 showing, so on that first render the decision is clamped to `true` and your
 callback's `false` is ignored; from then on it is honored and the browser keeps
-the copy it already has. So `revalidate(() => false)` means "render once, then
+the copy it already has. So `revalidate(false)` means "render once, then
 never re-render", never "don't appear".
 
 Revalidate callbacks must be synchronous. A callback that returns a Promise is
@@ -565,7 +565,7 @@ export const shopPatterns = urls(({
       { "@sidebar": () => <CategorySidebar /> },
       () => [
         loader(CategoriesLoader),
-        revalidate(() => false),
+        revalidate(false),
       ]
     ),
 

package/skills/ppr/SKILL.md

@@ -151,12 +151,42 @@ 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).
+A URL's shared shell is read and written only by requests on that URL. A
+request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr` route
+neither reads the target's shell nor captures it: it renders live, at the
+visitor's location (`usePathname()`, `ctx.rewrittenFrom`), on every request.
+The target's shell is captured by a direct visit or a `router.prerender()` warm
+of the target's URL, so nothing a rewriting middleware set (a variable, the
+visitor's URL) ends up in the shell every direct visitor gets.
+
+The rewrite chooses a shell for the rewritten request with `.shell()`:
+
+```ts
+// A routing catch-all: each public URL gets a shell of its own.
+throw rewrite("item", { id }).shell("visitor");
+
+// A lock or promo page that renders nothing of the visitor's URL. A lock
+// also refuses mutations, which a rewrite otherwise moves to the target.
+throw rewrite("maintenance").shell("target").disallowMutations();
+```
+
+- `.shell("visitor")` keys the shell by the visitor's URL and the target
+  (`visitorShellCacheKey(router, "/summer", "/item/1")` in a test; the target
+  route's `cache.searchParams` filter and its own partition apply). The
+  capture renders the visitor's location and `ctx.rewrittenFrom`, and a
+  variable set before the throw may be baked in, since the key covers the URL
+  it came from. Navigation replay uses the same key. A build shell of the
+  target is never served to it. Store growth is one shell per public URL;
+  `updateTag()` reaches every one of them through the shell's tags.
+- `.shell("target")` reads and captures the target's shared shell from the
+  rewritten request. The shell then shows the target's URL to a rewritten
+  visitor on a HIT (`usePathname()` hydrates against the address bar, so a
+  component that renders it mismatches), and a variable set before the throw
+  is baked into the shell direct visitors get. Use it only for a page that
+  renders neither.
+
+A rewritten navigation without `.shell()` reports
+`x-rango-ppr-replay: BYPASS; reason=rewritten`.
 
 ### Request-partitioned shells
 
@@ -806,14 +836,17 @@ that settled inside the capture window pinned its capture-time value into the
 shared shell; found live as a storefront basket — with the capturing session's
 identifiers — served to anonymous visitors.)
 
-### Handles: handler pushes bake; loader pushes keep "nesting = liveness"
+### Handles: handler and bake-lane pushes bake; loader pushes keep "nesting = liveness"
 
 - `ctx.use(H)(promise)` from a handler — a TOP-LEVEL pushed promise is awaited
   at capture and BAKED into the shell (bounded by `ppr.captureTimeout`, 15s by
   default).
-- A promise pushed from a LOADER is never in the shell and the capture does not
-  wait for it: however slow it is (or if it never settles), the shell is still
-  stored, and the HIT's own loader run delivers the value after hydration.
+- `ctx.use(H)(promise)` (or `.defer()`) from an `ssr: false` LOADER, or a
+  loader it awaits — awaited at capture and BAKED the same way, judged by the
+  value it settles to, as `push(await promise)` would be (#1182). One that
+  rejects, or does not settle within `ppr.captureTimeout`, refuses the
+  capture, as a handler's does. A loader without `ssr: false` never runs at
+  capture, so its pushes are never in the shell.
 - `ctx.use(H)({ x: promise })` from a HANDLER — also baked. The capture waits
   for every promise nested in a handler's push, at any depth of plain objects,
   arrays and JSX props, before it records the handles every HIT replays. Keep
@@ -967,60 +1000,73 @@ pushes stay as the prelude rendered them, even where a live loader also
 awaits it, while its data is fresh. (They follow the run instead once the
 entry has lost a pin, because the loader that awaits it then runs.) To keep
 its pushes live, declare it as its own `loader()` on the route. A push the
-capture cannot record (a deferred push, or one holding a promise) marks every
-loader record of the page to run: those bodies then still run on each replay,
-in the background, and that push reaches the page (from the loader's own
-`cache()` entry when it hits) with the run's value, on a document HIT and on
-a client navigation alike. On a document HIT it arrives after hydration.
-
-**Handles on a shell HIT.** A promise pushed from a loader is live and is
-never in a shell. To have a value in the shell's HTML, push it settled
-(await it) from the `ssr: false` loader, or push it from the handler.
-
-Three things follow, in this order of scope:
-
-1. **What is in a shell's HTML** changes only for promise pushes of
-   `ssr: false` loaders and of the loaders they await: `push(promise)`, or a
-   pushed value that holds a promise. Those run at capture, and the shell
-   renders no element for such a push. A loader without `ssr: false` never
-   ran at capture, so nothing of it was ever in the shell.
-2. **On a shell HIT every loader push made during the request arrives after
+capture cannot record (one whose value, once settled, holds a promise) marks
+every loader record of the page to run: those bodies then still run on each
+replay, in the background, and that push reaches the page (from the loader's
+own `cache()` entry when it hits) with the run's value, on a document HIT and
+on a client navigation alike. On a document HIT it arrives after hydration.
+
+**Handles on a shell HIT.** The shell holds what its capture's document
+rendered: the handlers' pushes and the `ssr: false` loaders' pushes, a
+promise (`push(promise)`, `.defer()`) resolved. A pushed promise is judged by
+the value it settles to, as `push(await promise)` would be (#1182). A
+live-lane loader's push is never in a shell.
+
+Four things follow, in this order of scope:
+
+1. **What is in a shell's HTML.** The capture awaits a promise an
+   `ssr: false` loader (or a loader it awaits) pushes, under
+   `ppr.captureTimeout`, and bakes the value. One that settles to a value
+   holding a promise is live: the shell renders no element for it. A loader
+   without `ssr: false` never runs at capture, so nothing of it is ever in
+   the shell.
+2. **A pushed promise that fails refuses the capture.** One that rejects, or
+   does not settle within `ppr.captureTimeout`, keeps the route on MISS, as
+   a handler's does, and the warning names the loader and the handle. Catch
+   it and push a fallback, or push it from a live-lane loader.
+3. **On a shell HIT every loader push made during the request arrives after
    hydration**, a live-lane loader's included. The document hydrates with
    exactly the handle data the shell's HTML was rendered from (the handlers'
-   pushes and the settled pushes of the loaders that ran at capture), and
-   the request's own pushes follow as a normal `useHandle` update.
-3. **`useHandle` on every document, `ppr` or not:** a reader that React is
+   pushes and the pushes of the loaders that ran at capture), and the
+   request's own pushes follow as a normal `useHandle` update.
+4. **`useHandle` on every document, `ppr` or not:** a reader that React is
    hydrating reads the handle data its HTML was rendered from, wherever its
    boundary hydrates, and takes the newer data right after. So a reader
    inside the `loading()` or `<Suspense>` of a loader that pushes after an
    `await` hydrates clean.
 
-| On the HIT's request                                                        | In the HIT's HTML      | The client                                        |
-| --------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- |
-| a handler's push, a pinned `ssr: false` loader's settled push               | yes (the shell has it) | hydrates with it                                  |
-| a deferred push (`push(promise)`), or a push holding a promise, by a loader | no                     | gets it right after hydration                     |
-| a live-lane loader's push                                                   | no                     | gets it right after hydration                     |
-| the run of an `ssr: false` loader the shell has no pin for                  | the capture's push     | hydrates with the capture's, then shows the run's |
+| On the HIT's request                                                                       | In the HIT's HTML      | The client                                        |
+| ------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------- |
+| a handler's push, a pinned `ssr: false` loader's push (`push(promise)` and `.defer()` too) | yes (the shell has it) | hydrates with it                                  |
+| a push by an `ssr: false` loader whose value holds a promise                               | no                     | gets it right after hydration                     |
+| a live-lane loader's push                                                                  | no                     | gets it right after hydration                     |
+| the run of an `ssr: false` loader the shell has no pin for                                 | the capture's push     | hydrates with the capture's, then shows the run's |
 
-A value a loader pushes as a promise is therefore in the HTML of a document
-MISS (the render awaits it) and of a route without `ppr`, and not in the
-HTML of a shell HIT. When a crawler or the first paint needs it, change one
-line:
+So a title an `ssr: false` loader pushes to `Meta`, promise or not, is in
+every HIT's `<head>`: a crawler and a link preview see it. It bakes with the
+shell and is invalidated with it (its TTL, its tags, `updateTag()`). A value
+that must stay per request comes from a loader without `ssr: false`, which
+nothing has to read:
 
 ```ts
-ctx.use(Notes)(db.stockNote(id)); // a promise: live, after hydration on a HIT
-ctx.use(Notes)(await db.stockNote(id)); // settled: baked into the shell
+const StockNote = createLoader(async (ctx) => {
+  ctx.use(Notes)(db.stockNote(ctx.params.id)); // live: after hydration on a HIT
+  return null;
+});
+path("/product/:id", ProductPage, { name: "product", ppr: true }, () => [
+  loader(Product, { ssr: false }), // bakes: its data and its pushes
+  loader(StockNote), // live lane: runs on every request
+]);
 ```
 
-The settled push bakes with the shell and is invalidated with it (its TTL,
-its tags). A promise is not baked, whenever it settles: it is the shape that
-says "per request", the same as a promise in the loader's data.
+Or nest the value in a settled push (`{ label, count: promise }`): the whole
+push then stays live, and every pinned body of the page runs on each HIT.
 
 A pinned loader's pushes are exactly the ones its capture made. If its body
-pushes a settled value only on some runs (behind a condition), a replay that
-runs it shows the capture's answer, a push or none, never a later run's next
-to the pinned data. A deferred push is the exception by design: it is
-delivered on every replay.
+pushes a value only on some runs (behind a condition), a replay that runs it
+shows the capture's answer, a push or none, never a later run's next to the
+pinned data. A push whose value holds a promise is the exception by design:
+it is delivered on every replay.
 
 One arrangement mixes sources by design. A loader that reads a
 `cache()`-bound loader with `ctx.use()` before that binding starts (a loader
@@ -1299,7 +1345,10 @@ shell-cache only public/shared pages, keep per-user content in live-lane
 loaders (no `ssr: false`) or nested promises in bake-lane loader data — NOT in
 handler output or plain bake-lane container data — mark the variable
 `{ cache: false }` so a stray shell read refuses the capture, or key per
-variant at the CDN tier.
+variant at the CDN tier. A variable a middleware sets before `throw rewrite()`
+never reaches the target's shared shell: a rewritten request captures none
+unless its rewrite opts in with `.shell("target")` (see "A request middleware
+rewrote"); with `.shell("visitor")` it lands only in that URL's own shell.
 
 ## What always renders without a shell
 
@@ -1307,7 +1356,9 @@ Non-GET, non-partial RSC/action/loader fetches, partial requests without an
 eligible captured segment snapshot, per-request CSP nonce, `streamMode:
 "allReady"`, redirects, 404s, error renders, routes without `ppr`, a document
 request the route's own `cache()` scope refuses (`cache(false)`, or a
-`condition()` returning false for it), and any store without the shell family.
+`condition()` returning false for it), a request middleware rewrote whose
+rewrite chose no shell (`rewrite(...).shell()`), and any store without the
+shell family.
 A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled) or when the router's
 document version changes, so a deploy that changes the router self-heals via

package/skills/prerender/SKILL.md

@@ -1020,8 +1020,7 @@ in dev. A removed page is the exception: its marker answers 404 in dev too.
   that only a refresh produced.
 - **Connected clients can lag.** A refresh has no response to reach open tabs:
   a client that prefetched the page keeps its copy for `prefetchCacheTTL`
-  (default 300s) and the browser HTTP cache (`prefetchCacheControl`). Lower
-  them if the window matters.
+  (default 300s, in memory only). Lower it if the window matters.
 - **Entries are per deploy.** Keys carry the router's data version, so a deploy
   that changes server code starts from the build entries again; a client-only
   deploy keeps refreshed pages.
@@ -1330,9 +1329,9 @@ write that started before an invalidation of one of its tags is refused.
 ### Limits worth knowing
 
 - **Only the router's own handler.** A warm goes through `router.fetch`, the
-  handler `createRouter`'s `cache`, `nonce` and `version` configure. An app
-  entry that builds its own `createRSCHandler({ cache, version })` is not what
-  a warm runs: put those options on `createRouter`.
+  handler `createRouter`'s `cache` and `nonce` configure. An app
+  entry that builds its own `createRSCHandler({ cache })` is not what a warm
+  runs: put the option on `createRouter`.
 - **Document records only.** Navigation (`partial:`) and intercept records
   fill on the first navigation.
 - **One location at a time.** A warm does not reach a copy another location

package/skills/rango/SKILL.md

@@ -111,6 +111,7 @@ stated, greppable contract.
 | debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
 | share config across routes              | factory returning a helper array   | /composability          |
 | compose a sub-app / module              | `include()`                        | /route                  |
+| lay out a whole app                     | section modules, guards, groups    | /app-structure          |
 | modal / soft navigation                 | `intercept()`                      | /intercept              |
 | route group of client components        | `clientUrls()` in `"use client"`   | /client-urls            |
 | set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader    | /loader                 |
@@ -306,8 +307,10 @@ Grouped by concern — read when you need to…
 | Skill                     | Description                                                                |
 | ------------------------- | -------------------------------------------------------------------------- |
 | `/router-setup`           | Create and configure the RSC router                                        |
+| `/app-structure`          | Whole-app recipes: large app with admin, multi-app, content site, shop     |
 | `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
 | `/client-urls`            | Client-component route groups with `clientUrls()` — no handlers            |
+| `/ux-architecture`        | Recipes for fast, stable navigation with `urls()` and `clientUrls()`       |
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |

package/skills/response-routes/SKILL.md

@@ -617,7 +617,10 @@ path.json(
 
 A dot-local name (`ctx.reverse(".comments")`) is a type error here. The
 runtime reverse has no scope to resolve it against, so untyped (JS) code that
-calls it throws `Unknown route` and the route answers 500.
+calls it throws `Unknown route` and the route answers 500. Leaving out a
+required param (`ctx.reverse("blog.api.comments")`) throws
+`Missing param "slug" for route "blog.api.comments"`, with or without a params
+object; it never returns the `/:slug` pattern as a URL.
 
 ## Content Negotiation
 

package/skills/router-setup/SKILL.md

@@ -266,8 +266,6 @@ Notes:
   a cleared cache) on every build; the build prints one note when that applies.
   A router that renders no such action keeps its cache without one (`/use-cache`,
   `/cache-guide`).
-- `createRouter({ version })` takes effect on every preset, including `node`
-  and `vercel`. It replaces both computed cache versions with that exact value.
 - `@rangojs/router/vite` also exports `poke()`, a dev-server plugin: type `e`
   then Enter (or Ctrl+R where the terminal passes it through) to full-reload
   the browser.

package/skills/scripts/SKILL.md

@@ -133,6 +133,17 @@ re-pushed inline script. The GTM demo does exactly this: a root-layout `Script`
 bootstrap fires the first page_view on document load, and a `"use client"`
 `<GtmPageViews>` component fires a page_view on every subsequent soft navigation.
 
+**Key that component on a handle value that carries the page's path, not on the
+URL.** Handle values arrive on their own channel, by design: on a page React
+holds in a transition (`transition()`, a same-route search change, a prefetched
+click) the URL changes before the destination's `content_group` and title land,
+so an effect keyed on `usePathname()` sends the previous page's tagging. Push
+the navigation's `pathname + search` into your `Gtm` handle (collected as `page.path`) from a root
+`parallel()` slot with `revalidate(true)`, read the tagging with `useHandle(Gtm)`,
+and send the page_view when `page.path` differs from the last path sent (seed it
+with the landing path, which the bootstrap already sent). The pattern, its
+trade-offs and the code are in [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design).
+
 ## The inline-self-inject rule (GTM/GA4/Segment)
 
 If an inline bootstrap must run **before** an external loader, do NOT push the
@@ -202,6 +213,6 @@ warns once per key. See `/ppr` → "What always renders without a shell".
 - **Partytown / web-worker offloading** — push the worker config with
   `type: "text/partytown"` and wire Partytown's own nonce config manually.
 
-A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
+A full GTM + GA4-style integration (page_view on first render + soft nav keyed on a path-carrying handle value, nonce,
 ecommerce events) lives in the router repository's `tests/vite-rsc-demo` app
 (not shipped in this package).