@rangojs/router 0.32.0 → 0.33.0

package/skills/testing/serve-shell-request.md

@@ -20,13 +20,13 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Options — `ServeShellRequestOptions`
 
-| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends it as a `<Link>` prefetch (`X-Rango-Prefetch`), so `prefetch: false` work is deferred. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
-| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which defers nothing. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ### Returns — `ServeShellRequestResult`
 

package/skills/testing/server-actions.md

@@ -53,6 +53,14 @@
 | `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing.                               |
 | `locationState`   | `Record<string, unknown>` | The flash set via `ctx.setLocationState()` / `redirect({ state })`, as the flat `{ key: value }` the client reads.                                                                                |
 
+`runInRequestContext` runs your function, not the router's action handling,
+so its `response` carries no write bump: the router sets that around every
+action it runs (the state cookie's `{version}:{timestamp}:{write}`, write part
+bumped unless the action called `keepClientCache()`). To assert it, send the
+action through the router with `serveShellRequest(router, url, { action })`
+(or `{ form }` with `createActionForm` for a post before hydration) and read
+the state `Set-Cookie` on `result.response`.
+
 Low-level building blocks (all from `@rangojs/router/testing`):
 
 - `createTestRequestContext(opts)` builds the context WITHOUT entering it and returns `{ ctx, request, url, variables, stateCookieName }`. Its `ctx.reverse` accepts any name from your `routeMap`.

package/skills/ux-architecture/SKILL.md

@@ -249,6 +249,13 @@ them right:
   server").
 - A prefetch runs the predicates too, so a loader that holds costs nothing in
   the prefetch of a tab switch.
+- A predicate that reads `currentParams` or `fromRouteName` and keeps its
+  segment shares that prefetch only between the pages with equal values of
+  what it read; one that reads `currentUrl` makes it page-only (2.6).
+  `bySlug` keeps only on an unchanged slug, so a product's tabs share their
+  prefetches; `bySearch` reads the URL, so the cost is the links between one
+  query's tabs. A layout rule comparing a param most pages share (a locale,
+  an account) groups by that param and keeps the sharing.
 - Unit-test them with `runRevalidate` (`/testing`).
 
 ### 2.5 loading() or an inline Suspense
@@ -279,8 +286,14 @@ A prefetch is a navigation sent early: the server renders the destination's
 handlers and loaders for it, from the page you are on (`/links`, "What a
 prefetch renders"). A click that adopts a complete prefetch commits with no
 request. Entries live 300 s by default (`prefetchCacheTTL`) in the router's
-memory only (prefetch responses carry no `Cache-Control`), and an action
-drops them unless it calls `keepClientCache()`. A prefetch whose page failed
+memory. An action marks them stale unless it calls `keepClientCache()`: a
+click on one shows it at once, then revalidates the page in the background
+(`/server-actions`, "Client Cache After an Action"). The browser HTTP cache
+keeps a prefetch for as long only when nothing in it is live: a document cache
+HIT, or an answer whose every sent segment came from a `cache()` record or a
+Prerender entry and that runs no loader
+(`Cache-Control: private, max-age=<prefetchCacheTTL>`). Any other prefetch
+carries no `Cache-Control` of the router's. A prefetch whose page failed
 is never used: a 500 or 404, and a 200 whose render reported an error (a
 loader that threw, a `loading()` handler that fell back to its
 `errorBoundary()`, an async component that threw). The click sends its own
@@ -301,11 +314,16 @@ The rule: **prefetch broadly, and flag what is expensive.**
   already on screen whose `revalidate()` re-runs it for the destination is
   prefetched with it, so the click does not wait on a fill for data the page
   is already showing.
-- The trade-off, measured on a `clientUrls()` tab in a consumer app (dev, a
-  loaded machine): with the tab's loader flagged, a hover then a click 150 ms
+- `prefetch: false` applies to speculative prefetches: viewport and render.
+  A hover, or `useRouter().prefetch()`, is intent to click and runs the
+  loader, so its click needs no fill. A hover over a link a viewport prefetch
+  already answered sends nothing, and that click still fills.
+- The trade-off of a deferring prefetch, measured on a `clientUrls()` tab in
+  a consumer app (dev, a loaded machine), before a hover's prefetch ran
+  flagged loaders: with the tab's loader flagged, a hover then a click 150 ms
   later showed the content in 843 to 918 ms; with the tab prefetched whole, in
   77 to 157 ms. The flagged click pays the fill request and then React's
-  300 ms on the tab's fallback.
+  300 ms on the tab's fallback. A viewport-prefetched link still pays it.
 - A click that adopts a prefetch with a flagged loader shows the page at once
   and sends one fill request for the flagged loaders. Read a flagged loader
   under its own `<Suspense>`: with no boundary, React keeps the page being
@@ -313,12 +331,33 @@ The rule: **prefetch broadly, and flag what is expensive.**
 - On a server route, `loading(fallback, { prefetch: false })` keeps the whole
   entry behind that fallback out of the prefetch (`/route`, "`loading()`
   options"). A group's `loading()` takes no options.
-- The default prefetch entry is shared by every source page. When the
-  target's `revalidate()` reads `currentParams`, `currentUrl` or
-  `fromRouteName` and keeps the segment, the router scopes that prefetch to
-  the page that sent it (`x-rsc-prefetch-scope: source`): another page
-  prefetches its own. `prefetchKey=":source"` on the Link scopes every
-  prefetch of it (`src/browser/react/Link.tsx`, `prefetchKey`).
+- One prefetch of a page serves every page that links to it, so a paginated list
+  or a grid does not prefetch each link again after every navigation. The server
+  makes an answer page-only (`x-rsc-prefetch-scope: source`) when sharing it
+  would be wrong: an intercept targets the route or the page sending it, the
+  answer defers a `prefetch: false` unit the page does not show yet, a
+  `revalidate()` on the target read `currentUrl` and kept its segment, a rule
+  on the route (or inside its `path()`) read the page being left and kept the
+  segment through the route's default, or a kept answer sends no segment at
+  all. Only a click from that exact URL, query
+  and hash included, uses a page-only answer, so every page prefetches it
+  again (`/links`, "Shared prefetches and `prefetchKey`").
+- A `revalidate()` that read `currentParams` or `fromRouteName` and kept its
+  segment, or a prerendered target reached from a page with the same route
+  params, groups the answer (`x-rsc-prefetch-scope: params; <label>`): the
+  pages with equal values of what was read share it. A layout rule comparing
+  `currentParams.locale` shares each prefetch between the pages of one locale.
+  Spreading `currentParams` reads every param; read the ones the rule needs by
+  name. A page's own block (a category hero) still goes in its route or in a
+  layout inside its `path()`, and links that follow a mount param come from
+  `useReverse`; neither needs a rule (`/app-structure`, "Prefetches are
+  shared").
+- `prefetchKey=":source"` on a Link, or
+  `router.prefetch(url, { key: ":source" })`, makes that link's prefetches
+  page-only. Use it when the target's answer depends on the page through
+  something the server does not track: `context` in a `revalidate()`, or a
+  `Referer` read. It costs the same requests, so set it per link, not
+  app-wide.
 
 ### 2.7 transition() and view transitions
 
@@ -375,16 +414,16 @@ The rule: **prefetch broadly, and flag what is expensive.**
   the error to the nearest error boundary, which replaces the page and its
   form (`/client-urls`, "A loader that fails on its rerun").
 - `keepClientCache()` in an action that changed nothing keeps the prefetches
-  and the history cache.
+  and the history cache fresh: no revalidation after a click or on Back.
 - `useOptimistic` gives feedback before the action answers.
 
 ### 2.10 Updates you did not make: three channels
 
-| The change                                         | The tool                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Your own mutation                                  | A server action plus `revalidate()` rules (`isAction(ref)`, `actionResult`). The server re-runs what the action touched in the same response; nothing else to call.                                                                                                                                                                                                                                                                                                                           |
-| Out of band: a push, polling, a REST call, a login | `useLoader(L).load()` (also `refetch`): a plain `load()` of a route-registered loader updates every reader of it. `refreshGroup` on reads plus `useRefreshLoaders()` refreshes several loaders at once. Both need a fetchable loader, `createLoader(fn, true)`; a plain one answers 403. `router.refresh()` re-renders the current route's server data and keeps client state. `invalidateClientCache()` marks the history cache stale and drops prefetches when the change makes them wrong. |
-| Shared server caches (other users' data)           | Tags: `cache({ tags })` or `cacheTag()`, then `updateTag()` in the action (awaitable, the action's response reads fresh) or `revalidateTag()` from a webhook. `revalidate()` is not cache invalidation (`/cache-guide`).                                                                                                                                                                                                                                                                      |
+| The change                                         | The tool                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your own mutation                                  | A server action plus `revalidate()` rules (`isAction(ref)`, `actionResult`). The server re-runs what the action touched in the same response; nothing else to call.                                                                                                                                                                                                                                                                                                                                              |
+| Out of band: a push, polling, a REST call, a login | `useLoader(L).load()` (also `refetch`): a plain `load()` of a route-registered loader updates every reader of it. `refreshGroup` on reads plus `useRefreshLoaders()` refreshes several loaders at once. Both need a fetchable loader, `createLoader(fn, true)`; a plain one answers 403. `router.refresh()` re-renders the current route's server data and keeps client state. `invalidateClientCache()` marks the history cache stale, drops prefetches and rotates the state when the change makes them wrong. |
+| Shared server caches (other users' data)           | Tags: `cache({ tags })` or `cacheTag()`, then `updateTag()` in the action (awaitable, the action's response reads fresh) or `revalidateTag()` from a webhook. `revalidate()` is not cache invalidation (`/cache-guide`).                                                                                                                                                                                                                                                                                         |
 
 ### 2.11 Handles: titles and breadcrumbs
 
@@ -448,7 +487,7 @@ ctx.reverse(".product", { slug: "b", locale: "de" }); // switch language
   take unchecked path strings: prefer the typed `useReverse` map.
 - `useReverse` with another module's map, or `useReverse(NamedRoutes)` under
   a mount, gives a wrong URL with no error. Build cross-module links on the
-  server and pass them as props or loader data (dc-t57).
+  server and pass them as props or loader data.
 - A server layout stays held across navigations, its own `:projectId`
   changing included: partial rendering by design. Links it rendered keep the
   old params. Put param-dependent nav links in a client component with
@@ -929,6 +968,16 @@ Each entry: what the user sees, why, the fix.
 15. **An effect keyed on a location-state object.** In a group the object is
     the one the navigation passed until the commit, then the history entry's
     copy: the effect runs twice. Fix: key it on a primitive field.
+16. **A page's own block in a shared layout, kept by a rule that reads the
+    page being left** (a category hero in a template over the product pages,
+    re-rendered when `currentParams.category` changes). Nothing looks wrong,
+    but every prefetch under that layout is shared only between the pages of
+    one category (or with the same params, off the category routes): the
+    other pages prefetch their links again and the server renders them
+    again. Fix: put
+    the block in its route, or in a layout inside its `path()`; it
+    re-renders on its own params with no rule (`/app-structure`, "Prefetches
+    are shared").
 
 ## 5. Known gaps
 

package/src/bin/rango.ts

@@ -1,4 +1,5 @@
-import { resolve, dirname } from "node:path";
+#!/usr/bin/env node
+import { resolve, dirname, basename } from "node:path";
 import { readFileSync, statSync, existsSync } from "node:fs";
 import {
   findTsFiles,
@@ -8,6 +9,7 @@ import {
   detectUnresolvableIncludesForUrlsFile,
   findNestedRouterConflict,
   formatNestedRouterConflictError,
+  isRoutableSourceFile,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -93,6 +95,19 @@ Examples:
   );
 }
 
+/**
+ * A createRouter() file that is not a test: a test builds its own router (a
+ * Flight test's `*.rsc-test.tsx` usually mounts an inline urls() tree), and a
+ * named-routes.gen.ts beside it would merge its routes into the app's global
+ * GeneratedRouteMap. The same rule findRouterFiles() applies in Vite.
+ */
+function isRouterFile(filePath: string, source: string): boolean {
+  return (
+    isRoutableSourceFile(basename(filePath)) &&
+    /\bcreateRouter\s*[<(]/.test(source)
+  );
+}
+
 /**
  * Walk up from a file path to find the project root (directory containing
  * package.json or vite.config.ts).
@@ -141,7 +156,7 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
+      if (isRouterFile(filePath, source)) {
         routerFiles.push(filePath);
       }
       // Both spellings, matching the writer's own gate: "clientUrls(" does
@@ -181,7 +196,8 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
   // Deduplicate diagnostics (router and urls detection may find the same issue)
   const seen = new Set<string>();
   const uniqueDiagnostics = allDiagnostics.filter((d) => {
-    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    // Every unreadable routes mount has pathPrefix "/": its detail names it.
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}${d.reason === "unresolvable-routes" ? `:${d.detail}` : ""}`;
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -192,10 +208,11 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     console.error("\n[rango] Unresolvable routes detected:\n");
     formatDiagnostics(uniqueDiagnostics);
     console.error(
-      "\nThe static parser cannot resolve these includes or basename because " +
-        "they use factory functions or dynamic expressions. A basename must be " +
-        "a string literal or a top-level const (in the router file or imported " +
-        "from a relative module).\n\n" +
+      "\nThe static parser cannot resolve these includes, routes or basename " +
+        "because they use factory functions or dynamic expressions. A router's " +
+        "routes must be a urls() call, a builder function or a variable holding " +
+        "urls(); a basename must be a string literal or a top-level const (in " +
+        "the router file or imported from a relative module).\n\n" +
         "Options:\n" +
         "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
         "  rango generate <path> --static    Accept partial output (missing routes or basename prefix above)\n",
@@ -255,7 +272,7 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
+      if (isRouterFile(filePath, source)) {
         routerEntries.push(filePath);
       }
       // Also generate per-module types for urls files. Both spellings — a
@@ -281,6 +298,10 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
+  // Loads from its own chunk only because the bin is built with esbuild
+  // --splitting (package.json "build"). A single-file bundle folds this module
+  // in and hoists its Vite imports to the top, so every command, --help
+  // included, failed without vite installed.
   let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
   try {
     const mod = await import("../build/runtime-discovery.ts");
@@ -290,9 +311,12 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
       err.code === "ERR_MODULE_NOT_FOUND" ||
       err.code === "MODULE_NOT_FOUND"
     ) {
+      // runtime-discovery checks vite and @vitejs/plugin-rsc itself and names
+      // what to install, so reaching here means a bundled chunk file is
+      // missing: the installed package is incomplete.
       console.error(
-        "[rango] Runtime discovery requires 'vite' and '@vitejs/plugin-rsc'.\n" +
-          "Install them with: pnpm add -D vite @vitejs/plugin-rsc",
+        `[rango] Failed to load runtime discovery: ${err.message}\n` +
+          "The installed @rangojs/router looks broken (a CLI chunk is missing). Reinstall it.",
       );
     } else {
       console.error(`[rango] Failed to load runtime discovery: ${err.message}`);
@@ -320,9 +344,11 @@ function formatDiagnostics(
     const prefix =
       d.reason === "unresolvable-basename"
         ? "createRouter basename"
-        : d.namePrefix
-          ? `${d.namePrefix}.*`
-          : `${d.pathPrefix}*`;
+        : d.reason === "unresolvable-routes"
+          ? "createRouter routes"
+          : d.namePrefix
+            ? `${d.namePrefix}.*`
+            : `${d.pathPrefix}*`;
     console.error(`  ${prefix}`);
     console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
     console.error(`    Source:  ${d.sourceFile}`);

package/src/browser/action-fence.ts

@@ -38,12 +38,82 @@
 
 let fenceCount = 0;
 
+/**
+ * Whether a cookie read saw the state rotate externally while the fence was
+ * up and no action's landing took it yet (navigation-store-handle.ts reports
+ * it). Almost always an action's own server-seat `invalidateClientCache()`
+ * `Set-Cookie`; a sibling tab's rotation in that window reads the same and
+ * costs one full flush, today's behavior. navigation-store.ts takes it when
+ * an action lands, so one rotation makes one landing flush, not every later
+ * landing of the batch.
+ */
+let rotatedInFence = false;
+
+/**
+ * Whether a cookie read saw a write-only change of the state (a server
+ * action's response, this tab's or another's) while the fence was up and no
+ * action's landing took it yet. A landing marks every cache stale, so it
+ * takes this; when the fence drops with it still set (the actions that
+ * landed called keepClientCache(), failed before they were sent, or reloaded
+ * on a version mismatch), the drop hands it to `unlandedWriteHandler`.
+ */
+let wroteInFence = false;
+
+let unlandedWriteHandler: (() => void) | null = null;
+
+/**
+ * Register what runs when the fence drops holding a write no landing took:
+ * the navigation store's markCachesStaleAfterWrite (navigation-store-handle.ts).
+ */
+export function setUnlandedWriteHandler(handler: (() => void) | null): void {
+  unlandedWriteHandler = handler;
+}
+
 export function enterActionFence(): void {
+  if (fenceCount === 0) {
+    rotatedInFence = false;
+    wroteInFence = false;
+  }
   fenceCount++;
 }
 
 export function exitActionFence(): void {
   if (fenceCount > 0) fenceCount--;
+  if (fenceCount === 0 && wroteInFence) {
+    wroteInFence = false;
+    unlandedWriteHandler?.();
+  }
+}
+
+/** A cookie read saw an external state rotation (rango-state.ts observer). */
+export function noteStateRotation(): void {
+  if (fenceCount > 0) rotatedInFence = true;
+}
+
+/**
+ * A cookie read saw a write-only change (rango-state.ts write observer).
+ * Returns whether the fence is up and took it; with the fence down the
+ * caller marks the caches stale itself.
+ */
+export function noteStateWrite(): boolean {
+  if (fenceCount === 0) return false;
+  wroteInFence = true;
+  return true;
+}
+
+/** A landing marked every cache stale: a write seen so far is covered. */
+export function takeStateWriteInActionFence(): void {
+  wroteInFence = false;
+}
+
+/**
+ * Whether the state rotated externally since the fence went up or the last
+ * landing took it, and clear it. False with the fence down.
+ */
+export function takeStateRotationInActionFence(): boolean {
+  const rotated = fenceCount > 0 && rotatedInFence;
+  rotatedInFence = false;
+  return rotated;
 }
 
 export function isActionFenceActive(): boolean {
@@ -53,4 +123,6 @@ export function isActionFenceActive(): boolean {
 /** Test-only: reset the refcount between cases. */
 export function __resetActionFence(): void {
   fenceCount = 0;
+  rotatedInFence = false;
+  wroteInFence = false;
 }

package/src/browser/cookie-name.ts

@@ -91,31 +91,48 @@ export function getRawCookieValue(
 }
 
 /**
- * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
- * Only the build-derived version is encoded (it is arbitrary); the `:`
- * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
- * shape survives and `:` is a legal cookie-value octet.
+ * Encode a state value for the wire: `encodeURIComponent(version):timestamp`,
+ * plus `:write` when the write part is not 0. Only the build-derived version
+ * is encoded (it is arbitrary); the `:` separators and the numeric parts stay
+ * raw, so the shape survives and `:` is a legal cookie-value octet. A value no
+ * server action has bumped keeps the two-part shape it had before the write
+ * part existed.
  */
-export function encodeStateValue(version: string, timestamp: number): string {
-  return `${encodeURIComponent(version)}:${timestamp}`;
+export function encodeStateValue(
+  version: string,
+  timestamp: number,
+  write = 0,
+): string {
+  const base = `${encodeURIComponent(version)}:${timestamp}`;
+  return write === 0 ? base : `${base}:${write}`;
 }
 
-/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
+/**
+ * Parsed state value. `version` is decoded; `timestamp` (the invalidation
+ * part) and `write` are the raw integers. `write` is 0 for a two-part value.
+ */
 export interface StateValue {
   version: string;
   timestamp: number;
+  write: number;
 }
 
 /**
- * Decode a wire value back into `{version, timestamp}`. Returns null for a
- * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
- * mint fresh instead of trusting garbage.
+ * Decode a wire value back into `{version, timestamp, write}`. Accepts the
+ * two-part `{version}:{timestamp}` (a value no action bumped, or one an open
+ * tab wrote before the write part existed) and the three-part
+ * `{version}:{timestamp}:{write}`. Returns null for a malformed value (no `:`,
+ * empty version, a non-numeric part, or more parts) so callers mint fresh
+ * instead of trusting garbage.
  */
 export function decodeStateValue(raw: string): StateValue | null {
   const colon = raw.indexOf(":");
   if (colon <= 0) return null;
-  const timestamp = Number(raw.slice(colon + 1));
-  if (!Number.isFinite(timestamp)) return null;
+  const parts = raw.slice(colon + 1).split(":");
+  if (parts.length > 2) return null;
+  const timestamp = parseStatePart(parts[0]!);
+  const write = parts.length === 2 ? parseStatePart(parts[1]!) : 0;
+  if (timestamp === null || write === null) return null;
   let version: string;
   try {
     version = decodeURIComponent(raw.slice(0, colon));
@@ -124,7 +141,31 @@ export function decodeStateValue(raw: string): StateValue | null {
     // a thrown URIError here would 500 the server seat or fail client boot.
     return null;
   }
-  return { version, timestamp };
+  return { version, timestamp, write };
+}
+
+function parseStatePart(part: string): number | null {
+  if (part === "") return null;
+  const value = Number(part);
+  return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * The `{version}:{timestamp}` part of a wire value: what every in-memory
+ * comparison on the client reads (the prefetch cache keys, the action
+ * fence's rotation check, the external-rotation observer). A change to it is
+ * a hard invalidation (a deploy, or invalidateClientCache() on either seat);
+ * a change to the write part alone is a server action's write, which marks
+ * caches stale and flushes nothing. The full value, write part included, is
+ * what requests send as `X-Rango-State`, so the browser HTTP cache (Vary)
+ * misses after every write. A raw cut, no decode: the version is
+ * percent-encoded, so the second `:` is always the write separator.
+ */
+export function stateEpoch(raw: string): string {
+  const first = raw.indexOf(":");
+  if (first < 0) return raw;
+  const second = raw.indexOf(":", first + 1);
+  return second < 0 ? raw : raw.slice(0, second);
 }
 
 /**
@@ -132,7 +173,9 @@ export function decodeStateValue(raw: string): StateValue | null {
  * one, so a re-mint inside the same millisecond (or a backward clock step) still
  * differs from the current value. `prevRaw` is the current wire value (the
  * client's in-memory mirror, or the server's inbound header/cookie) or null; its
- * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
+ * timestamp is the floor. The write part starts over (left out): the new
+ * timestamp alone makes the value one no response was cached under. Shared by
+ * both seats so the monotonic guard lives once.
  */
 export function mintStateValue(
   version: string,
@@ -143,6 +186,31 @@ export function mintStateValue(
   return encodeStateValue(version, ts);
 }
 
+/**
+ * Bump the write part of `prevRaw`, keeping its version and timestamp: what
+ * the response of a server action without a directive sets. Keeping the
+ * version keeps the bump soft for a client still on another build (a form
+ * posted from a document served before a deploy); its own boot handles the
+ * deploy. Returns null when `prevRaw` is absent or malformed: a client with
+ * no state value sends no `X-Rango-State` and has nothing in the HTTP cache
+ * keyed by one.
+ *
+ * The new write part must be one no response was cached under. It is
+ * strictly greater than the previous one, and it is the current time in
+ * microseconds with random low digits: two actions that start from the same
+ * value (two tabs, or two in flight in one tab) can run in the same server
+ * millisecond (a Worker's clock does not move between I/O), and the second
+ * response must not set the value the first one set, under which a prefetch
+ * between them may have been cached with the second write missing.
+ */
+export function bumpStateWrite(prevRaw: string | null): string | null {
+  const prev = prevRaw ? decodeStateValue(prevRaw) : null;
+  if (!prev) return null;
+  const fresh = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  const write = Math.max(fresh, prev.write + 1);
+  return encodeStateValue(prev.version, prev.timestamp, write);
+}
+
 /**
  * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
  * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure

package/src/browser/invalidate-client-cache.ts

@@ -1,12 +1,14 @@
 /**
  * Client seat of `invalidateClientCache()` (the `default` export condition).
  *
- * Makes the current client behave as if a server action had just completed:
- * the history cache is marked stale (SWR), the prefetch map is flushed, the
- * state rotates, and sibling tabs are broadcast to — the same
- * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
- * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
- * entry instantly and revalidates.
+ * The full client invalidation, more than a server action without a
+ * directive does: the history cache is marked stale (SWR), the prefetch map
+ * is flushed (in-flight prefetches aborted, visible links prefetch again), the
+ * state rotates, and sibling tabs are broadcast to, which adopt the new state
+ * and flush too (`invalidateCacheAndBroadcast()`). A directive-free action
+ * only marks history and prefetches stale and rotates nothing
+ * (`markCacheAsStaleAndBroadcast()`). History is marked stale, not cleared, so
+ * Back renders the cached entry instantly and revalidates.
  */
 
 import { getRegisteredStore } from "./navigation-store-handle.js";
@@ -27,7 +29,7 @@ export function invalidateClientCache(): void {
 
   const store = getRegisteredStore();
   if (store) {
-    store.markCacheAsStaleAndBroadcast();
+    store.invalidateCacheAndBroadcast();
     return;
   }