@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.124",
+  "version": "0.0.0-experimental.126",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -157,6 +157,17 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx 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 dlx esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm dlx 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",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
@@ -168,19 +179,19 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0",
-    "@shared/e2e": "0.0.1"
+    "vitest": "^4.0.0"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
@@ -208,15 +219,5 @@
     "vitest": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx 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 dlx esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm dlx 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",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/breadcrumbs/SKILL.md

@@ -81,6 +81,66 @@ path("/product/:id", async (ctx) => {
 Async content is a `Promise<ReactNode>`. Resolve it in your component
 with React's `use()` hook wrapped in `<Suspense>`.
 
+### Deferred content (decide now, resolve from a deep component)
+
+When the handler should DECIDE to push a crumb (it holds `ctx`, so the decision
+must land before the handles stream seals) but the value is produced far away — by
+a deep async component, not the handler — call `.defer()` on the push function.
+`ctx.use(Handle)` returns the push function; `.defer(options)` reserves the crumb's
+slot synchronously and returns a **resolver that is push-equal** — you call it
+later, anywhere in the render, with the same argument you'd have passed to the
+push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
+forgotten resolve can't hold the Flight stream (and the HTTP response) open forever.
+
+Reserve the slot in the handler, then resolve it from a nested async component
+that closes over the resolver — no extra wiring (the resolver is a plain closure,
+not outlet context):
+
+```tsx
+import { Breadcrumbs } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+import { Suspense } from "react";
+
+function DocsLayout(ctx) {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  // Decide now (the slot is reserved before the stream seals); resolve later.
+  const resolveCrumb = breadcrumb.defer({ timeoutMs: 5000, else: null });
+
+  // Deep, async, far from the handler — closes over the resolver, never touches ctx.
+  // Same call shape as breadcrumb({ ... }), just deferred:
+  async function LiveCrumb() {
+    const n = await countOpenIssues();
+    resolveCrumb({ label: "Docs", href: "/docs", content: <span>{n}</span> });
+    return null;
+  }
+
+  return (
+    <>
+      <Suspense>
+        <LiveCrumb />
+      </Suspense>
+      <Outlet />
+    </>
+  );
+}
+```
+
+If the resolver is never called, the slot auto-resolves to `else` after
+`timeoutMs` (default 10s) and warns in dev — graceful degradation instead of a
+hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; any
+other non-finite or negative value falls back to the default rather than silently
+disabling the safety net.
+
+**Consumer note:** because `.defer()` reserves the slot for the WHOLE item, a
+client reading the handle (`useHandle(Breadcrumbs)`) sees that entry as a
+`Promise` until it resolves. Type such reads with the exported
+`DeferredHandleEntry<BreadcrumbItem>` (from `@rangojs/router/client`); a
+deferred-aware consumer should `use()` thenable entries inside `<Suspense>`, while
+a simple one can skip them (`typeof entry.then === "function"`). Use `.defer()`
+only when even `label`/`href` are unknown at handler time — if you know them and
+only the `content` is async, push a concrete item with a `Promise` `content` field
+instead (no `.defer()` needed).
+
 ## Consuming Breadcrumbs (Client)
 
 Use `useHandle(Breadcrumbs)` in a client component to read the accumulated items:

package/skills/hooks/SKILL.md

@@ -89,8 +89,8 @@ import { useSegments } from "@rangojs/router/client";
 function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
 
-  // path: ["/shop", "products", "123"]
-  // segmentIds: ["shop-layout", "products-route"]
+  // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
   // location: URL object
 
   return <nav>{path.join(" > ")}</nav>;

package/skills/route/SKILL.md

@@ -296,6 +296,12 @@ path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
 path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
+> handler return instead. (Dev logs a warning if this is hit.)
+
 ### Redirect with location state
 
 Carry typed state through redirects (e.g. flash messages):

package/skills/server-actions/SKILL.md

@@ -465,7 +465,10 @@ See `/middleware` for the full cross-segment revalidation contract.
 
 `redirect()` works inside actions. Both `return redirect(...)` and
 `throw redirect(...)` are supported and behave the same way for the
-client. Throwing is clearer when the redirect is conditional.
+client. Throwing is clearer when the redirect is conditional, and it keeps
+the action's return type narrow (e.g. `Promise<void>`) — `redirect()` returns
+a `Response`, so the `return` form needs `Promise<Response>` in the signature.
+Prefer `throw redirect(...)`; never cast with `as any`.
 
 ```typescript
 "use server";
@@ -490,6 +493,27 @@ 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.
 
+### Same-origin by default (open-redirect protection)
+
+`redirect()` is same-origin by default on every path — JS, no-JS PE, and
+full-page. A cross-origin target (e.g. from unvalidated user input) is blocked
+and the user is sent to the app root instead, so `redirect(userInput)` can never
+become an open redirect. To intentionally redirect off-host (an OAuth provider,
+say), opt in explicitly:
+
+```typescript
+throw redirect("https://accounts.google.com/o/oauth2/v2/auth?...", {
+  external: true,
+});
+```
+
+`{ external: true }` is the audit point: passing user input with it re-opens the
+cross-origin risk and is your responsibility (the Rails `allow_other_host: true`
+model). Omit it and off-host targets stay blocked. `external` only waives the
+**same-origin** rule, not scheme safety: the target must be `http(s)` — a
+`javascript:` or `data:` URL is still neutralized, so a forged or mistaken
+`external` target can never become a scriptable navigation.
+
 ## Error Handling
 
 ### Validation errors — return them as state

package/skills/testing/SKILL.md

@@ -81,23 +81,23 @@ The single rule that drives everything:
 
 Each primitive links to its sub-file (API + recipe + caveats).
 
-| The behavior is…                                                                                          | Layer        | Primitive                                                                      | Import root                      |
-| --------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------ | -------------------------------- |
-| a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                             | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                         | `@rangojs/router/testing`        |
-| one loader's data logic                                                                                   | unit (node)  | [`runLoader`](./loader.md)                                                     | `@rangojs/router/testing`        |
-| a loader's cookie / header / redirect output (auth-loader pattern)                                        | unit (node)  | [`runLoaderResult`](./loader.md)                                               | `@rangojs/router/testing`        |
-| one middleware's ordering / short-circuit / cookie+header merge                                           | unit (node)  | [`runMiddleware`](./middleware.md)                                             | `@rangojs/router/testing`        |
-| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                     | unit (node)  | [`runInRequestContext`](./server-actions.md)                                   | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, or a seeded handle read                                                 | unit         | [`collectHandle` / seeded `handles`](./handles.md)                             | `@rangojs/router/testing[/dom]`  |
-| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`) | unit (DOM)   | [`renderRoute`](./client-components.md)                                        | `@rangojs/router/testing/dom`    |
-| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight           | integration  | [`dispatch`](./response-routes.md)                                             | `@rangojs/router/testing`        |
-| a real async **Server Component** / Flight serialization shape                                            | RSC unit     | [`renderToFlightString` + `toMatchFlight`](./flight.md)                        | `@rangojs/router/testing/flight` |
-| a client island's **typed props** / the **server-rendered** host content                                  | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md) | `@rangojs/router/testing/flight` |
-| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                   | RSC unit     | [`renderHandler`](./render-handler.md)                                         | `@rangojs/router/testing/flight` |
-| navigation, hydration, PE parity, view transitions, real SSR                                              | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)         | `@rangojs/router/testing/e2e`    |
-| cache hit/miss/stale, prerender (= a cache hit by design)                                                 | e2e + signal | [`assertCacheStatus` / telemetry sink](./cache-prerender.md)                   | `@rangojs/router/testing[/e2e]`  |
-| generated route map drift vs runtime                                                                      | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                         | `@rangojs/router/testing`        |
-| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                 | unit/integr. | [your own double via `env`](./bindings.md)                                     | (any primitive's `env` option)   |
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                     | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                                                      | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                    | `@rangojs/router/testing`        |
+| a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing[/dom]`  |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                               | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                        | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                        | `@rangojs/router/testing/e2e`    |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md) | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                    | (any primitive's `env` option)   |
 
 Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 `/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,

package/skills/testing/cache-prerender.md

@@ -1,9 +1,20 @@
 # Testing cache / SWR / prerender — assertCacheStatus
 
-**Layer:** e2e + signal · **Import:** the cache-status helpers (`assertCacheStatus`/`parseCacheHeader`/`createCacheSink`/`filterCacheDecisions`) are re-exported from BOTH entries — use `@rangojs/router/testing` from a Vitest unit/integration test, and `@rangojs/router/testing/e2e` from a plain Playwright runner (the e2e barrel avoids the Vite-only virtuals the main barrel pulls in). · **DSL it tests:** `cache()` / `"use cache"` / loader cache / `Prerender(...)` (see `/caching`, `/prerender`, `/use-cache`)
+**Layer:** e2e + signal · **Import:** the cache-status helpers (`assertCacheStatus`/`parseCacheHeader`/`createCacheSink`/`assertCacheDecision`/`filterCacheDecisions`) are re-exported from BOTH entries — use `@rangojs/router/testing` from a Vitest unit/integration test, and `@rangojs/router/testing/e2e` from a plain Playwright runner (the e2e barrel avoids the Vite-only virtuals the main barrel pulls in). · **DSL it tests:** `cache()` / `"use cache"` / loader cache / `Prerender(...)` (see `/caching`, `/prerender`, `/use-cache`)
 
 The router's REAL cache pipeline runs (runtime cache, SWR revalidation, prerender lookup); you SEED nothing — you drive a request through the real fetch path and read the resulting cache decision. The decision surfaces two ways: the `X-Rango-Cache` response header (a debug gate) or a captured `cache.decision` telemetry event.
 
+## Which path to use
+
+Both report the SAME coarse route-level signal (keyed by the route NAME). Pick by **transport**, not by meaning:
+
+| Path          | Helper                                                                     | Transport                                                                                       | Needs the debug gate?                             | Production surface                | Per-segment `shouldRevalidate`? |
+| ------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------- | ------------------------------- |
+| **Header**    | `assertCacheStatus(res, routeKey, expected)` / `parseCacheHeader`          | the `X-Rango-Cache` response header — the ONLY signal a black-box Playwright `Response` carries | Yes (`debugCacheSignal` / `RANGO_TEST_SIGNALS=1`) | the header (gated off by default) | no                              |
+| **Telemetry** | `assertCacheDecision(events, routeKey, expected)` / `filterCacheDecisions` | a captured `cache.decision` event off a `createCacheSink()` sink                                | No                                                | zero                              | yes (the only path exposing it) |
+
+Use the header path when all you have is a black-box `Response` (a Playwright `APIResponse`); use the telemetry path when you can wire `createRouter({ telemetry: sink })` and want zero production surface or per-segment `shouldRevalidate`. `assertCacheDecision` is the one-call counterpart of `assertCacheStatus` (parallel `(…, routeKey, expected)` shape — captured `events` in place of a `Response`); reach for raw `filterCacheDecisions` only when you need the per-segment event fields directly.
+
 ## API
 
 ### Options — `assertCacheStatus(target, segment, expected)`
@@ -38,7 +49,11 @@ parseCacheHeader(headerValue: string | null | undefined): Record<string, string>
 // createCacheSink -> a sink to wire via createRouter({ telemetry: sink }), plus the array it records into.
 createCacheSink(): { sink: TelemetrySink; events: TelemetryEvent[] }
 
-// filterCacheDecisions -> narrow captured events to cache.decision events.
+// assertCacheDecision -> the one-call telemetry assert (counterpart of assertCacheStatus).
+// Throws on mismatch / no matching segment / unknown routeKey; returns void.
+assertCacheDecision(events: readonly TelemetryEvent[], routeKey: string, expected: ExpectedCacheStatus): void
+
+// filterCacheDecisions -> narrow captured events to cache.decision events (raw form).
 filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[]
 ```
 
@@ -74,16 +89,27 @@ parityDescribe("product page caches", (f) => {
 Zero-prod-surface alternative — the telemetry sink. No header at all; you inspect captured `cache.decision` events:
 
 ```ts
-import { createCacheSink, filterCacheDecisions } from "@rangojs/router/testing";
+import {
+  createCacheSink,
+  assertCacheDecision,
+  filterCacheDecisions,
+} from "@rangojs/router/testing";
 
 const { sink, events } = createCacheSink();
 const router = createRouter({ telemetry: sink }).routes(urlpatterns);
 // ...drive a request through the router's RSC fetch path...
+
+// One-call assert (counterpart of assertCacheStatus), keyed by the route NAME:
+assertCacheDecision(events, "product.detail", "stale");
+
+// Or read the raw event when you need per-segment fields (shouldRevalidate):
 const decision = filterCacheDecisions(events)[0];
 expect(decision.segments?.[0].cacheStatus).toBe("stale");
 expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 ```
 
+`events` accumulates across requests, so the FIRST matching segment for a `routeKey` wins — slice or recreate the sink between requests for the same route.
+
 ## Caveats
 
 - The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.

package/skills/testing/flight.md

@@ -1,21 +1,24 @@
-# Testing an async Server Component — renderToFlightString
+# Pinning the Flight wire payload — renderToFlightString
 
 **Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` + `@rangojs/router/testing/flight-matchers` · **DSL it tests:** an async Server Component / Flight output (see `/route`)
 
+> **Prefer `renderServerTree` (see [`./server-tree.md`](./server-tree.md)) for assertions on a Flight render** — it deserializes to a traversable tree with TYPED boundary props (a `Date` is a `Date`, not the opaque `$D...` encoding). Reach for `renderToFlightString` + the wire matchers (`toMatchFlight`/`toMatchFlightSnapshot`) only to pin the raw wire payload SHAPE — a `toMatchFlightSnapshot` drift snapshot. That is the niche/escape-hatch case; for "testing an async Server Component (assert what it rendered)" start at `./server-tree.md`.
+
 `renderToFlightString` runs the REAL react-server-dom serializer the router uses at runtime — your async Server Component genuinely renders to its Flight wire string in plain node, with a request context active for the render. What you SEED is the request, headers, env, params, routeName, and vars that context exposes.
 
 ## API
 
 ### Options — `RenderToFlightStringOptions`
 
-| Field       | Type                     | Meaning                                                                                                                                                                                                                                                                    |
-| ----------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`   | `Request \| string`      | The request the render runs under: a `Request`, or a URL string (absolute or path). Defaults to `http://localhost/`. A component reading `getRequestContext()` sees this request's url/cookies. When a `Request` is passed, its headers are used and `headers` is ignored. |
-| `headers`   | `HeadersInit`            | Request headers (e.g. Cookie) visible to the server tree, used only when `request` is a string.                                                                                                                                                                            |
-| `env`       | `unknown`                | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                     |
-| `params`    | `Record<string, string>` | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                 |
-| `routeName` | `string`                 | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                            |
-| `vars`      | `VarsInit`               | Variables a prior middleware would have set, visible via `ctx.get(...)`. Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).                                                                                                                             |
+| Field       | Type                     | Meaning                                                                                                                                                                                                                                                                      |
+| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`   | `Request \| string`      | The request the render runs under: a `Request`, or a URL string (absolute or path). Defaults to `http://localhost/`. A component reading `getRequestContext()` sees this request's url/cookies. When a `Request` is passed, its headers are used and `headers` is ignored.   |
+| `headers`   | `HeadersInit`            | Request headers (e.g. Cookie) visible to the server tree, used only when `request` is a string.                                                                                                                                                                              |
+| `env`       | `unknown`                | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                       |
+| `params`    | `Record<string, string>` | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                   |
+| `routeName` | `string`                 | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                              |
+| `routeMap`  | `Record<string, string>` | Route name -> pattern map scoping `ctx.reverse()` (like `renderHandler`). Without it, a component that reverses resolves against the GLOBAL route map and is order-dependent on whatever router registered last. Pass the router-under-test's map for deterministic reverse. |
+| `vars`      | `VarsInit`               | Variables a prior middleware would have set, visible via `ctx.get(...)`. Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).                                                                                                                               |
 
 ### Context — `RequestContext` (what your component receives)
 
@@ -78,7 +81,7 @@ it("snapshots the normalized payload", async () => {
 
 - Leaf / server-only: a client island in the tree emits an un-hydratable `I[...]` import row against the empty client manifest. Keep Flight tests to leaf server components; test full pages at e2e.
 - Requires the react-server vitest project (see `./setup.md`): `resolve.conditions` includes `react-server`, the `@rangojs/router -> index.rsc.ts` alias, `NODE_ENV=production`, and the worker `execArgv`. Name files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`. The main vitest project must NOT set `react-server` (it would flip React to the no-hooks server build).
-- A component that imports a server API (`getRequestContext`, `cookies`) from the bare `@rangojs/router` barrel works ONLY with the `index.rsc.ts` alias wired (see `./setup.md`); without it the bare import resolves to the throwing out-of-react-server stub. Pure-leaf components that take all data as props need no barrel import and are the simplest case.
+- A component that imports a server API (`getRequestContext`, `cookies`) from the bare `@rangojs/router` barrel works ONLY with the `index.rsc.ts` alias wired (see `./setup.md`); without it the bare import resolves to the throwing out-of-react-server stub. `renderToFlightString` / `renderServerTree` self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error. Pure-leaf components that take all data as props need no barrel import and are the simplest case.
 - `toMatchFlight` is containment (substring), not equality — the row framing (prefixes/quoting) is an internal serializer detail, so pin the rendered text/shape, not the framing. `toMatchFlightSnapshot()` snapshots the normalized payload; run under `NODE_ENV=production` for the cleanest, most stable bytes.
 - No hydration / no interaction here — that is the e2e tier. For typed assertions on a client boundary's props (a `Date` back as a `Date`), or to confirm an island actually crossed the boundary, use `renderServerTree` (see `./server-tree.md`).
 

package/skills/testing/render-handler.md

@@ -20,6 +20,8 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 | `loaders`          | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                       |
 | `clientComponents` | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                   |
 | `stateCookie`      | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the value is `{version}:{timestamp}`, default `"0"`). |
+| `cacheStore`       | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                        |
+| `cacheProfiles`    | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                      |
 
 ### Context — `HandlerContext` (what your handler receives)
 
@@ -110,6 +112,7 @@ it("asserts the client-cache directives", async () => {
 - A `throw redirect()` is captured on `thrown` (with `tree` undefined, since it produced a `Response`) — assert on `thrown`/`response`, no try/catch needed.
 - No hydration and no interaction — for clicks, forms, and navigation use e2e.
 - `renderHandler` runs a handler FUNCTION `(ctx) => rsc`; for a plain ELEMENT `<Page/>` use `renderServerTree` (see [`./server-tree.md`](./server-tree.md)).
+- A handler that calls a `"use cache"` function runs UNCACHED unless you seed `cacheStore` (and `cacheProfiles` for a named profile). With nothing seeded the runtime bypasses to the live body and warns once under the test runner — assert real cache behavior by passing `{ cacheStore: new MemorySegmentCacheStore(), cacheProfiles: { default: { ttl: 60 } } }`.
 
 ## See also
 

package/skills/testing/server-tree.md

@@ -2,7 +2,7 @@
 
 **Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** client islands across the boundary + server-rendered host content (see `/route`)
 
-`renderServerTree` serializes the real Flight (identical bytes to `renderToFlightString`) and then deserializes it back to an inspectable React element tree you traverse — that serialize/deserialize round-trip is REAL; what you SEED is the element you render plus the request context (`request`/`headers`/`params`/`vars`/`env`). The win over the wire string: a client boundary's props come back as real JS values (a `Date` is a `Date`, not the opaque `$D...` encoding) and you can confirm a `"use client"` component actually crossed the boundary (an `I` row) instead of being inlined. There is NO hydration and NO interaction — boundaries are inert placeholders carrying props.
+`renderServerTree` is the DEFAULT way to assert on a Flight render; `renderToFlightString` (see [`./flight.md`](./flight.md)) is the escape hatch for pinning the raw wire bytes. It serializes the real Flight (identical bytes to `renderToFlightString`) and then deserializes it back to an inspectable React element tree you traverse — that serialize/deserialize round-trip is REAL; what you SEED is the element you render plus the request context (`request`/`headers`/`params`/`vars`/`env`). The win over the wire string: a client boundary's props come back as real JS values (a `Date` is a `Date`, not the opaque `$D...` encoding) and you can confirm a `"use client"` component actually crossed the boundary (an `I` row) instead of being inlined. There is NO hydration and NO interaction — boundaries are inert placeholders carrying props.
 
 ## API
 

package/skills/testing/setup.md

@@ -106,7 +106,7 @@ Scripts:
 
 - Node >= 23 requires `rangoTestConfig()`, not bare `rangoTestAliases()`. `@rangojs/router` is consumed as SOURCE (exports -> `./src/*.ts`), and Node >= 23 refuses to type-strip `.ts` under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). `rangoTestConfig` ships as compiled JS AND adds `server.deps.inline: [/@rangojs[/\\]router/]` so Vite (not Node) transpiles rango source. With bare `rangoTestAliases` you must wire `deps.inline` yourself.
 - Two separate projects. The node/DOM project keeps React on its CLIENT build; the Flight project uses the `react-server` condition in a separate `vitest.rsc.config.ts`. The main project must NOT set `react-server` — it flips React to the no-hooks server build and breaks every `renderRoute` / client test.
-- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`).
+- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
 - `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
 - The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.

package/src/__internal.ts

@@ -9,10 +9,6 @@
  * adding them to the public API.
  */
 
-// ============================================================================
-// Segment Resolution (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal representation of a resolved route segment.
@@ -26,10 +22,6 @@ export type { ResolvedSegment, SegmentMetadata } from "./types.js";
  */
 export type { MatchResult, SlotState } from "./types.js";
 
-// ============================================================================
-// Intercept System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Context for intercept route selection.
@@ -40,10 +32,6 @@ export type {
   InterceptWhenFn,
 } from "./server/context.js";
 
-// ============================================================================
-// Browser State (Internal)
-// ============================================================================
-
 /**
  * @internal
  * RSC protocol payload structure.
@@ -68,10 +56,6 @@ export type {
   NavigationUpdate,
 } from "./browser/types.js";
 
-// ============================================================================
-// Handle System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handle storage mechanism.
@@ -84,26 +68,17 @@ export type { HandleStore, HandleData } from "./server/handle-store.js";
  */
 export type { SegmentHandleData } from "./cache/types.js";
 
-// ============================================================================
-// Cache Internals
-// ============================================================================
-
 /**
  * @internal
  * Internal cache entry data structure.
  */
 export type {
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
   SerializedSegmentData,
   CacheDefaults,
 } from "./cache/types.js";
 
-// ============================================================================
-// Router Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Router context for AsyncLocalStorage.
@@ -114,10 +89,6 @@ export type {
   InterceptResult,
 } from "./router/router-context.js";
 
-// ============================================================================
-// Match Pipeline (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Route match context during pipeline processing.
@@ -133,10 +104,6 @@ export type {
  */
 export type { RouteMatchResult } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Server Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Entry data during route traversal.
@@ -153,10 +120,6 @@ export type {
   EntryPropSegments,
 } from "./server/context.js";
 
-// ============================================================================
-// Handler Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handler context with additional props for router internals.
@@ -164,30 +127,18 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
-// ============================================================================
-// Rendering (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Builds React element trees from route segments.
  */
 export { renderSegments } from "./segment-system.js";
 
-// ============================================================================
-// Error Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Error sanitization and network error utilities.
  */
 export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
 
-// ============================================================================
-// Type Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
@@ -217,10 +168,6 @@ export type {
   RevalidationDecisionEvent,
 } from "./router/telemetry.js";
 
-// ============================================================================
-// Pre-render / Static Handler Guards (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Type guard for prerender handler definitions.
@@ -233,20 +180,12 @@ export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
  */
 export { isStaticHandler } from "./static-handler.js";
 
-// ============================================================================
-// URL Pattern Internals
-// ============================================================================
-
 /**
  * @internal
  * Sentinel used to tag response-type route entries.
  */
 export { RESPONSE_TYPE } from "./urls.js";
 
-// ============================================================================
-// Route Match Debug (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for route matching performance analysis.
@@ -256,10 +195,6 @@ export {
   getMatchDebugStats,
 } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Debug Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for manifest inspection and comparison.

package/src/browser/action-coordinator.ts

@@ -5,7 +5,7 @@ import type { ActionEntry } from "./event-controller.js";
  * full-update-unsupported cases are handled inline in the bridge before
  * reconciliation; this only covers successfully-reconciled partial responses.
  */
-export type ActionScenario =
+type ActionScenario =
   | {
       type: "navigated-away";
       historyKeyChanged: boolean;

package/src/browser/action-fence.ts

@@ -15,6 +15,16 @@
  * keeps a sibling tab from seeing a pre-commit signal. Refcounted so concurrent
  * actions compose: each action raises and lowers its own reference, and the
  * fence is down only when the count reaches zero.
+ *
+ * The refcount is a single module-level counter, not keyed by routerId.
+ * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
+ * read it unscoped, so an action in one router would suppress another router's
+ * navigation/prefetch caches. This is correct only because two routers cannot
+ * coexist in one live document: an SPA navigation crossing a host-router
+ * boundary forces a full document reload (src/router/request-classification.ts
+ * app-switch terminal), so there is always exactly one live router per
+ * document. A future multi-router-in-one-document feature must not silently
+ * inherit this global, cross-router cache suppression.
  */
 
 let fenceCount = 0;