@rangojs/router 0.30.1 → 0.32.0

package/dist/vite/index.js

@@ -4841,6 +4841,11 @@ function getAppVersion() {
 }
 
 // src/router/basename.ts
+function normalizeBasename(basename2) {
+  if (!basename2) return void 0;
+  const trimmed = basename2.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : void 0;
+}
 function prefixBasename(path6, basename2) {
   if (!basename2 || !path6.startsWith("/") || path6 === basename2 || path6.startsWith(basename2 + "/") || path6.startsWith(basename2 + "?") || path6.startsWith(basename2 + "#")) {
     return path6;
@@ -5988,7 +5993,7 @@ function serializeSearchSchema(route2, value) {
     throw projectionError(route2, 'path option "search" must be an object');
   }
   const entries = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = value[key];
     if (typeof schemaValue !== "string" || !SEARCH_SCHEMA_VALUES.has(schemaValue)) {
       throw projectionError(
@@ -7141,7 +7146,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.30.1",
+  version: "0.32.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -7334,7 +7339,7 @@ var package_default = {
     tag: "latest"
   },
   scripts: {
-    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     prepublishOnly: "pnpm build",
     typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
@@ -9325,14 +9330,7 @@ function collectCreateRouterCallChain(endpoint) {
     current = receiver;
   }
 }
-function extractAllUrlsFromRouter(code) {
-  const sourceFile = ts5.createSourceFile(
-    "router.tsx",
-    code,
-    ts5.ScriptTarget.Latest,
-    true,
-    ts5.ScriptKind.TSX
-  );
+function findRouterUrls(sourceFile) {
   let result = null;
   function visit(node) {
     if (result) return;
@@ -9360,7 +9358,7 @@ function extractAllUrlsFromRouter(code) {
           if (urls2) extracted.push(urls2);
         }
         if (extracted.length > 0) {
-          result = extracted;
+          result = { createRouterCall, extractions: extracted };
           return;
         }
       }
@@ -9368,13 +9366,9 @@ function extractAllUrlsFromRouter(code) {
     ts5.forEachChild(node, visit);
   }
   visit(sourceFile);
-  return result ?? [];
-}
-function extractUrlsFromRouter(code) {
-  const extractions = extractAllUrlsFromRouter(code);
-  return extractions[extractions.length - 1] ?? null;
+  return result;
 }
-function extractBasenameFromRouter(code) {
+function extractAllUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -9382,25 +9376,112 @@ function extractBasenameFromRouter(code) {
     true,
     ts5.ScriptKind.TSX
   );
-  let result;
-  function visit(node) {
-    if (result !== void 0) return;
-    if (ts5.isCallExpression(node) && ts5.isIdentifier(node.expression) && node.expression.text === "createRouter") {
-      for (const arg of node.arguments) {
-        if (ts5.isObjectLiteralExpression(arg)) {
-          for (const prop of arg.properties) {
-            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "basename" && ts5.isStringLiteral(prop.initializer)) {
-              result = prop.initializer.text;
-              return;
-            }
-          }
+  return findRouterUrls(sourceFile)?.extractions ?? [];
+}
+function extractUrlsFromRouter(code) {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
+}
+function unwrapTypeOperators(expr) {
+  while (ts5.isAsExpression(expr) || ts5.isSatisfiesExpression(expr)) {
+    expr = expr.expression;
+  }
+  return expr;
+}
+function hasModifier(statement, kind) {
+  return ts5.canHaveModifiers(statement) && (ts5.getModifiers(statement)?.some((m) => m.kind === kind) ?? false);
+}
+function findTopLevelConst(sourceFile, name, exported) {
+  for (const statement of sourceFile.statements) {
+    if (ts5.isVariableStatement(statement) && statement.declarationList.flags & ts5.NodeFlags.Const && !hasModifier(statement, ts5.SyntaxKind.DeclareKeyword) && (!exported || hasModifier(statement, ts5.SyntaxKind.ExportKeyword))) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts5.isIdentifier(decl.name) && decl.name.text === name) {
+          return decl.initializer && unwrapTypeOperators(decl.initializer);
         }
       }
     }
-    ts5.forEachChild(node, visit);
   }
-  visit(sourceFile);
-  return result;
+  return void 0;
+}
+function findNamedImport(sourceFile, name) {
+  for (const statement of sourceFile.statements) {
+    if (!ts5.isImportDeclaration(statement) || !ts5.isStringLiteral(statement.moduleSpecifier) || statement.importClause?.isTypeOnly) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts5.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (!el.isTypeOnly && el.name.text === name) {
+        return {
+          specifier: statement.moduleSpecifier.text,
+          exportedName: el.propertyName?.text ?? name
+        };
+      }
+    }
+  }
+  return void 0;
+}
+function resolveTopLevelConst(name, sourceFile, routerFilePath) {
+  const local = findTopLevelConst(sourceFile, name, false);
+  if (local) return local;
+  const imported = findNamedImport(sourceFile, name);
+  if (!imported) return void 0;
+  const target = resolveImportPath(imported.specifier, routerFilePath);
+  if (!target) return void 0;
+  const targetSource = readFileSync4(target, "utf-8");
+  return findTopLevelConst(
+    ts5.createSourceFile(target, targetSource, ts5.ScriptTarget.Latest, true),
+    imported.exportedName,
+    true
+  );
+}
+function isTopLevelScope(node) {
+  for (let p = node.parent; !ts5.isSourceFile(p); p = p.parent) {
+    if (ts5.isFunctionLike(p) || ts5.isClassLike(p) || ts5.isBlock(p) || ts5.isCaseBlock(p) || ts5.isModuleBlock(p) || ts5.isIterationStatement(p, false)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveRouterBasename(routerSource, routerFilePath) {
+  const sourceFile = ts5.createSourceFile(
+    routerFilePath,
+    routerSource,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  const options = findRouterUrls(sourceFile)?.createRouterCall.arguments[0];
+  const prop = options && ts5.isObjectLiteralExpression(options) ? options.properties.find(
+    (p) => (ts5.isPropertyAssignment(p) || ts5.isShorthandPropertyAssignment(p)) && ts5.isIdentifier(p.name) && p.name.text === "basename"
+  ) : void 0;
+  if (!prop) return {};
+  const valueExpr = ts5.isPropertyAssignment(prop) ? prop.initializer : prop.name;
+  const expr = unwrapTypeOperators(valueExpr);
+  let value = getStringValue(expr);
+  if (value === null && isTopLevelScope(prop)) {
+    if (ts5.isIdentifier(expr)) {
+      const init = resolveTopLevelConst(expr.text, sourceFile, routerFilePath);
+      value = init ? getStringValue(init) : null;
+    } else if (ts5.isPropertyAccessExpression(expr) && ts5.isIdentifier(expr.expression)) {
+      const owner = resolveTopLevelConst(
+        expr.expression.text,
+        sourceFile,
+        routerFilePath
+      );
+      value = owner ? resolveConstMember(owner, expr.name.text) : null;
+    }
+  }
+  return value === null ? { unresolved: valueExpr.getText(sourceFile).replace(/\s+/g, " ") } : { value };
+}
+function resolveConstMember(owner, name) {
+  if (!ts5.isObjectLiteralExpression(owner) || owner.properties.some(ts5.isSpreadAssignment)) {
+    return null;
+  }
+  const member = owner.properties.find(
+    (p) => ts5.isPropertyAssignment(p) && ts5.isIdentifier(p.name) && p.name.text === name
+  );
+  return member ? getStringValue(unwrapTypeOperators(member.initializer)) : null;
 }
 function applyBasenameToRoutes(result, basename2) {
   const prefixed = {};
@@ -9498,8 +9579,9 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
-  const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  const basename2 = normalizeBasename(
+    resolveRouterBasename(routerSource, routerFilePath).value
+  );
   const result = { routes: {}, searchSchemas: {} };
   const memo = createScanMemo();
   for (const extraction of extractions) {
@@ -12693,7 +12775,8 @@ async function createTempRscServer(state, options = {}) {
       // to resolveId/load (plus transform for import rewriters, see
       // IMPORT_REWRITE_PLUGINS) and placed last so framework resolution runs first;
       // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
-      ...state.userResolvePlugins
+      ...state.userResolvePlugins,
+      ...options.plugins ?? []
     ]
   });
 }
@@ -14583,7 +14666,7 @@ function bundleScanPhase(s, context, bundle) {
 }
 
 // src/vite/utils/forward-user-plugins.ts
-function isDenied(name) {
+function isFrameworkPlugin(name) {
   return name.startsWith("vite:") || name === "rsc" || name.startsWith("rsc:") || name.startsWith("@rangojs/router") || name.startsWith("@cloudflare/vite-plugin") || name.startsWith("vite-plugin-cloudflare");
 }
 var IMPORT_REWRITE_PLUGINS = /* @__PURE__ */ new Set([
@@ -14610,7 +14693,7 @@ function selectForwardableResolvePlugins(plugins) {
   const forwarded = [];
   for (const p of plugins) {
     const name = p?.name;
-    if (!name || isDenied(name)) continue;
+    if (!name || isFrameworkPlugin(name)) continue;
     if (!isForwardable(p)) continue;
     forwarded.push(stripToResolutionHooks(p));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -259,7 +259,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",

package/skills/comparison/references/framework-comparison.md

@@ -558,8 +558,9 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 `<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
 `defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
-`prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
-whose response branches on `currentUrl`). Intercepted plain `<a href>` elements
+`prefetchKey` (`":source"` scopes a prefetch to the originating page; the
+router does so itself for an intercept target and for a `revalidate()` that
+read the source page and kept a segment). Intercepted plain `<a href>` elements
 inside the router basename follow the same default; common static-resource
 extensions are excluded unless `data-prefetch="true"` identifies an application
 route, and `data-prefetch="false"` or `"none"` opts out unsafe GET links. A

package/skills/document-cache/SKILL.md

@@ -228,6 +228,11 @@ suffixes are still appended.
   (`rango-state-fresh` by default), so it is not stored. A stale entry's
   background re-run sets no fresh-reads cookie (no visitor made that
   invalidation), so its invalidation does not keep the refreshed page out.
+- A document that carries location state (`ctx.setLocationState()`, or the
+  one-shot cookie a document redirect left for it): it is the visitor's, so it
+  is not stored, leaves `private, no-store`, and a request that arrives with
+  that cookie, or whose earlier middleware set state, is not answered from a
+  stored entry (see `/hooks` `state.md`, "State on a document response")
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch

package/skills/hooks/state.md

@@ -101,6 +101,7 @@ Back/forward and state the server sets on a navigation
 | `<Link state>`, `router.push()` / `router.replace()`         | in the commit that shows the destination                         |
 | back/forward                                                 | in the commit that restores the entry (cached or refetched)      |
 | the server, on a navigation (`setLocationState`, a redirect) | in the commit that shows the destination                         |
+| the server, on a document load (a page load, a no-JS post)   | once the page has hydrated, as stored state                      |
 | a navigation the server answers with nothing to re-render    | with the new location: the page on screen is the entry's         |
 | `router.push(url, { revalidate: false })` (no server fetch)  | with the new location: the page does not change                  |
 | a server action's `setLocationState` (no navigation)         | when the action's response arrives, added to what readers show   |
@@ -279,8 +280,8 @@ import { FlashMessage } from "../location-states";
 ```
 
 Or via `ctx.setLocationState()` from a handler or middleware. It is delivered
-with a client navigation's or an action's response; a document response
-carries no location state (there is no history entry to write it to yet):
+with a client navigation's or an action's response, and with a document
+response too (see "State on a document response" below):
 
 ```tsx
 (ctx) => {
@@ -289,6 +290,109 @@ carries no location state (there is no history entry to write it to yet):
 };
 ```
 
+### Several writes to one definition
+
+Entries accumulate across definitions, but one definition is one slot in
+`history.state`: for the same definition the last write wins. Two
+`ctx.setLocationState(Toasts(...))` calls in one response, or
+`redirect(url, { state: [Toasts(a), Toasts(b)] })`, deliver only the later
+value, without a warning. A server action, a handler and the middleware
+around them all write to the same response, so a shared helper that writes a
+definition replaces what an earlier call wrote.
+
+To combine several messages, make the state an array and write it once, for
+example by collecting them in a request variable and writing the definition
+at the end of the action:
+
+```ts
+export const Toasts = createLocationState<ToastMessage[]>({ flash: true });
+
+// One write per response, with every toast in it.
+getRequestContext().setLocationState(Toasts([...savedToasts, loginToast]));
+```
+
+### State on a document response
+
+A document request has no history entry yet, so the router carries what the
+server set to the client and writes it there when the client starts. This
+covers the mutations that most need a flash message: a `<form action={fn}>`
+posted before hydration or without JS, a payment provider redirecting the
+shopper back, a link from an email.
+
+| The document request                                                         | Where the state travels                                          |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| renders a page (`setLocationState` in a handler, middleware or no-JS action) | the document's bootstrap payload                                 |
+| redirects (`redirect(url, { state })`, or `setLocationState` and a redirect) | a one-shot cookie the target's document request reads and clears |
+| redirects with `{ external: true }` or off-origin                            | nowhere: the cookie would not reach the target                   |
+
+```tsx
+// A payment provider sends the shopper back to /checkout/callback.
+path("/checkout/callback", async (ctx) => {
+  const ok = await completeOrder(ctx.searchParams.get("token"));
+  return ok
+    ? redirect("/orders/confirmed", { state: [Flash({ text: "Paid" })] })
+    : redirect("/checkout", { state: [Flash({ text: "Payment declined" })] });
+});
+```
+
+- **When a reader gets it.** `useLocationState` returns `undefined` while the
+  document streams and hydrates, then the value, at the moment it would get
+  state stored in the entry. A flash message shows just after hydration.
+- **Without JS, no flash.** The state rides to the client, and only the
+  client writes it into the entry and hands it to readers. A visitor with JS
+  disabled gets the page as the server rendered it, where every reader of the
+  state shows `undefined`: the post and its redirect work, but the message
+  never shows. If such visitors must see it, render it from the server, for
+  example from a search param or a cookie your handler reads.
+- **Flash and refresh.** Flash state is cleared once read, as always. The
+  cookie is cleared by the response that read it, so a refresh of the target
+  renders without it. A page whose handler sets state on every request
+  delivers it again on a refresh, because the handler ran again. A no-JS post
+  answered with a page (no redirect) is re-posted by the browser on refresh;
+  redirect after the post (`redirect(url, { status: 303, state })`) to avoid
+  that.
+- **Caching.** A document that carries state, and the redirect carrying it
+  on, are sent `Cache-Control: private, no-store`, after every middleware.
+  The document cache neither stores such a document nor answers a request
+  that arrives with the cookie from a stored one. A shared PPR shell never
+  holds state: on a `ppr` route, state set before the render (by middleware,
+  or the cookie) rides the live payload of a shell HIT or MISS, and the shell
+  is still served and captured; state a handler sets keeps that route from
+  being captured, so it renders in full. `no-store` also keeps the
+  page out of the browser's back/forward cache (Chrome's bfcache), so Back to
+  it loads it again. That costs little for a one-off flash; a handler that
+  sets state on every request pays it on every page view.
+- **`ppr` and cached routes.** A shell HIT and a `cache()` hit run no
+  handler, so a handler there cannot set state on that request. Set it from
+  middleware, which runs on every request; the HIT still serves, with the
+  state in its live payload.
+- **The cookie.** It is named after the router's state cookie
+  (`<stateCookieName>-ls`, `__Host-` prefixed on https), `HttpOnly`,
+  `SameSite=Lax`, `Path=/`, and lives 60 seconds. Only the next GET document
+  request of the redirect's target pathname that navigates reads it: where
+  the browser sends `Sec-Fetch-Dest`, it must be `document`, `iframe` or
+  `frame`, so a `<link rel=prefetch>` or a `fetch()` of that path leaves it
+  to the navigation. A form POST to it, a client navigation and a Flight
+  fetch leave it too, as does a request of another path. A
+  target that redirects again carries the state on to the next target. There
+  is one such cookie per router: two document redirects within a moment (two
+  tabs) keep only the later one's state. Without https there is no `__Host-`
+  prefix, so a sibling subdomain could set the cookie: treat state that
+  arrives this way as a message to show, not as a fact to act on.
+- **Known limit: a redirect from one router to another.** The cookie is
+  named after the redirecting router's state cookie, which holds its router
+  id (`<stateCookiePrefix>_<routerId>`), and a router reads only its own. On
+  one origin served by several routers (a host router, or several
+  `createRouter()` apps behind one worker), a document redirect from one
+  router to a path another serves loses its state, without a warning. Carry
+  such a message another way, such as a search param.
+- **JSON only across a redirect.** The cookie holds JSON: a `Date` arrives as
+  a string, a `Map` or `Set` as `{}`, `undefined` is dropped. Development
+  warns, naming the slot. A value JSON cannot encode (a `bigint`), or state
+  over the cookie's 4000-byte limit, is dropped from the redirect with a
+  `console.warn`. Carry an id and load the rest on the target page.
+  Navigation and action payloads are not limited this way.
+
 ### State from another deploy
 
 History entries survive reloads and back/forward, so a tab left open across a
@@ -419,10 +523,10 @@ as the server rendered it:
   where it sits (a `<Suspense>` boundary that hydrates late included), or
   whether the definition's module is loaded at all. Other slots on the entry
   are left alone.
-- State the server sets is never dropped by this: a document response carries
-  no location state, and `ctx.setLocationState()` / `redirect(url, { state })`
-  reach `history.state` only through navigations and actions in the running
-  app, after start-up.
+- State the server sets is never dropped by this: the state a document
+  response carries is written after the `~r` keys are removed, so a
+  `clearOnReload` slot the server set for this load is applied on this load
+  (and removed by the next one). Navigations and actions write after start-up.
 - `.write()` stores under the same key, so it does not survive a refresh
   either.
 - Adding the option to an existing definition moves it to the `~r` key: state

package/skills/intercept/SKILL.md

@@ -316,7 +316,8 @@ or not the intercept applies from that page (`rsc-rendering.ts`
 `x-rsc-prefetch-scope: source`, set from `MatchResult.interceptTargeted`). A
 full page prefetched from a page where `when` is false never serves a click
 from a page where it is true. Routes no intercept targets keep one shared
-prefetch entry.
+prefetch entry, unless a `revalidate()` that read the source page kept a
+segment (`MatchResult.sourceHeld`, same header).
 
 ```typescript
 // Intercept only when opened from the shop index

package/skills/ppr/SKILL.md

@@ -500,6 +500,18 @@ Rango warns with the shell key and backs capture off instead of rendering the
 same doomed generation on every request. Move a deterministic self-invalidation
 out of render code if you want the shell to persist.
 
+### Location state on a ppr route
+
+A shared shell never holds location state: the capture builds its own
+payload, without it. State set before the render (from middleware, or the
+one-shot cookie a document redirect left for this request) rides the live
+payload: a HIT serves the shell with the state in its tail's payload, a MISS
+carries it and still captures. Either response leaves `private, no-store`.
+State a handler sets skips the capture of that MISS, so that route renders in
+full: a HIT runs no handler, so a handler's `ctx.setLocationState()` does not
+happen on a HIT. Set it from middleware (see `/hooks` `state.md`, "State on a
+document response").
+
 ### Opting out per request with `ctx.dynamic()`
 
 Middleware and handlers can call `ctx.dynamic()` to force this request onto a

package/skills/rango/SKILL.md

@@ -445,11 +445,11 @@ npx rango generate src/urls.tsx src/api/
 
 Three modes:
 
-| Flag        | Behavior                                                                                                                                    |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic).                   |
-| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                                  |
-| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config. |
+| Flag        | Behavior                                                                                                                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic), or an explicit `createRouter` `basename` isn't a string literal or top-level const. |
+| `--static`  | Static parser, but writes partial output (an unreadable basename leaves patterns unprefixed) and prints the diagnostics as warnings.                                                                          |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config.                                                                   |
 
 ### Auto-detection
 

package/skills/server-actions/SKILL.md

@@ -645,6 +645,14 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+The same holds for a form posted without JS (or before hydration): an action
+that redirects with `state` carries it to the target in a one-shot cookie,
+and one that sets it with `getRequestContext().setLocationState()` and does
+not redirect carries it in the re-rendered page. Either way the target reads
+it with `useLocationState` once it has hydrated. Prefer a `303` redirect, so a
+refresh does not post the form again. State that crosses a no-JS redirect
+travels as JSON (see `/hooks` `state.md`, "State on a document response").
+
 Build the target by name rather than a literal path:
 `throw redirect(getRequestContext().reverse("account.settings"))`. It fills
 mount params (`:accountId`, `:locale`) from the page URL the action was called

package/skills/testing/client-components.md

@@ -8,25 +8,26 @@
 
 ### Options — `RenderRouteOptions`
 
-| Field             | Type                                                                   | Meaning                                                                                                                                                                                                                                       |
-| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
-| `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
-| `outletPending`   | `boolean`                                                              | Seed `useOutlet().pending` through each synthetic segment's production `OutletProvider`. Defaults to `false`; this is context seeding, not a simulated navigation/Suspense/action lifecycle.                                                  |
-| `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
-| `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
-| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; keys an unkeyed `def` (like `withLocationStateKey(def)`) and writes `value` to `history.state` under `def.__rsc_ls_key`. See [Location state](#location-state).              |
-| `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
-| `lateHandles`     | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Handle values that arrive AFTER hydration, as a late loader push does: `[handle, valuesAfterTheUpdate[]]` replaces that handle's `handles` seed once the root has hydrated (or mounted). See [Hydration](#hydration).                         |
-| `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
-| `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
-| `basename`        | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                          |
-| `mount`           | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                   |
-| `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
-| `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
-| `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
-| `hydrate`         | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml`, `recoverableErrors` and `shellError`. See [Hydration](#hydration).            |
-| `rewrite`         | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                 |
+| Field                   | Type                                                                   | Meaning                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`               | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                                                                                         |
+| `loaderData`            | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                                                                               |
+| `outletPending`         | `boolean`                                                              | Seed `useOutlet().pending` through each synthetic segment's production `OutletProvider`. Defaults to `false`; this is context seeding, not a simulated navigation/Suspense/action lifecycle.                                                                                                                 |
+| `loaders`               | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                                                                                          |
+| `params`                | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                                                                                       |
+| `locationState`         | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; keys an unkeyed `def` (like `withLocationStateKey(def)`) and writes `value` to `history.state` under `def.__rsc_ls_key`. See [Location state](#location-state).                                                                             |
+| `documentLocationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | The location state the document response carried (a handler, middleware or no-JS form action set it, or a document redirect's cookie brought it), as `[def, value]` pairs. Merged at start-up after `locationState` and the `clearOnReload` pass. See [State a document carried](#state-a-document-carried). |
+| `handles`               | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                                                                                |
+| `lateHandles`           | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Handle values that arrive AFTER hydration, as a late loader push does: `[handle, valuesAfterTheUpdate[]]` replaces that handle's `handles` seed once the root has hydrated (or mounted). See [Hydration](#hydration).                                                                                        |
+| `handle`                | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                                                                               |
+| `routeMap`              | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                                                                                              |
+| `basename`              | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                                                                                         |
+| `mount`                 | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                                                                                  |
+| `theme`                 | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                                                                                |
+| `nonce`                 | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                                                                                        |
+| `defaultPrefetch`       | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere.                                                                |
+| `hydrate`               | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml`, `recoverableErrors` and `shellError`. See [Hydration](#hydration).                                                                           |
+| `rewrite`               | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                                                                                |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
 
@@ -265,6 +266,30 @@ it("drops them on a refresh and carries again on the next navigation", async ()
 });
 ```
 
+### State a document carried
+
+A page load, a no-JS form post that renders a page, and the target of a document redirect carry the location state the server set for them (see `/hooks`, state.md, "State on a document response"). Start-up merges it into the entry after the `clearOnReload` pass, so a reader gets it once the root has hydrated, `clearOnReload` slots included. Seed it with `documentLocationState`, not `locationState`: `locationState` is the entry's stored state, which `hydrate: true` passes through the `clearOnReload` pass first.
+
+| To test                                                    | Do                                                                                                                |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| a flash a document carried, as the page hydrates           | `renderRoute(routes, { hydrate: true, documentLocationState })`                                                   |
+| a document's `clearOnReload` state replacing a stale entry | `hydrate: true` with the stale value in `locationState`, the new one in `documentLocationState`                   |
+| what the server put in the document                        | `serveShellRequest(router, url).readLocationState()` (see [`./serve-shell-request.md`](./serve-shell-request.md)) |
+
+```tsx
+it("shows the flash the declined-payment redirect carried", async () => {
+  const { serverHtml, getByRole } = await renderRoute(
+    [{ path: "/checkout", Component: FlashBanner }],
+    {
+      hydrate: true,
+      documentLocationState: [[FlashMessage, { text: "Payment declined" }]],
+    },
+  );
+  expect(serverHtml).not.toContain("Payment declined"); // useLocationState is undefined until hydration
+  expect(getByRole("alert")).toHaveTextContent("Payment declined");
+});
+```
+
 ## Hydration
 
 A plain `renderRoute` mounts with `createRoot`, so a component never runs its hydration render: `useSyncExternalStore` skips `getServerSnapshot`, and nothing compares the first client render with server HTML. `hydrate: true` runs the document-load sequence instead. renderRoute renders the same element (same providers, seeds, and RTL `reactStrictMode`) to HTML with `react-dom/server`'s `renderToString`, puts that HTML in the container, and hydrates it through RTL (`render(ui, { hydrate: true, onRecoverableError })`), so `cleanup()` unmounts it like any other render. `serverHtml` is what the server pass produced; `recoverableErrors` holds the message of every error React recovered from, which is where a hydration mismatch arrives.