@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/skills/debug-manifest/SKILL.md

@@ -13,10 +13,10 @@ Inspect the route manifest to verify parent relationships, shortCodes, and route
 In development, visit:
 
 ```
-http://localhost:PORT/__debug_manifest
+http://localhost:PORT/?__debug_manifest
 ```
 
-Returns formatted JSON with all routes and layouts.
+Returns formatted JSON. The HTTP endpoint shape is `{ routerId, routeManifest, routeAncestry, routeTrie, precomputedEntries }` (see below for the programmatic API shape).
 
 ## Programmatic Access
 
@@ -32,6 +32,8 @@ if (process.env.NODE_ENV !== "production") {
 
 ## Manifest Structure
 
+The programmatic `router.debugManifest()` call returns `{ routes, layouts, totalRoutes, totalLayouts }`:
+
 ```json
 {
   "routes": {

package/skills/document-cache/SKILL.md

@@ -28,7 +28,7 @@ const router = createRouter<AppBindings>({
   urls: urlpatterns,
   // App-level cache store. The document cache middleware uses this store's
   // getResponse/putResponse methods.
-  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
 });
 
 router.use(
@@ -150,7 +150,7 @@ import { urlpatterns } from "./urls";
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  cache: (_env, ctx) => new CFCacheStore({ ctx: ctx! }),
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
 });
 
 router.use(

package/skills/handler-use/SKILL.md

@@ -40,7 +40,7 @@ ProductPage.use = () => [
   loading(<ProductSkeleton />),
   middleware(async (ctx, next) => {
     await next();
-    ctx.header("Cache-Control", "private, max-age=60");
+    ctx.headers.set("Cache-Control", "private, max-age=60");
   }),
 ];
 ```

package/skills/hooks/SKILL.md

@@ -915,8 +915,8 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 | `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                    |
 | `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                         |
 | `useLinkStatus()`         | Link pending state                                             | { pending }                                                        |
-| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error                                             |
-| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading                                              |
+| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error, load, refetch                              |
+| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading, error, refetch                              |
 | `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`              |
 | `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                    |
 | `useAction()`             | Server action state                                            | state, error, result                                               |

package/skills/host-router/SKILL.md

@@ -66,7 +66,7 @@ Why two methods instead of one overloaded `.map()`:
 | `.` or `*`        | Any apex domain (`example.com`)                |
 | `**`              | Any domain (apex + all subdomains)             |
 | `*.`              | Any single-level subdomain (`www.example.com`) |
-| `**. `            | Any multi-level subdomain (`a.b.example.com`)  |
+| `**.`             | Any multi-level subdomain (`a.b.example.com`)  |
 | `example.com`     | Exact domain                                   |
 | `*.com`           | Any apex `.com` domain                         |
 | `*.example.com`   | Single subdomain of `example.com`              |

package/skills/intercept/SKILL.md

@@ -23,7 +23,7 @@ function ShopLayout() {
   );
 }
 
-export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
+export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) => [
   layout(<ShopLayout />, () => [
     // Intercept product detail - shows modal during soft navigation
     intercept(

package/skills/loader/SKILL.md

@@ -561,6 +561,8 @@ entirely (no read, no write).
 ### Per-Loader Store Override
 
 ```typescript
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+
 const hotStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
 
 loader(PricingLoader, () => [

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

@@ -597,11 +597,13 @@ function ErrorBoundary() {
 }
 
 // Rango: errorBoundary() wrapping a group of routes
+// Server-side error boundaries only receive `error` (no `reset` — server render
+// cannot be retried; users can navigate away or refresh).
 layout(<DashboardLayout />, () => [
-  errorBoundary(({ error, reset }) => (
+  errorBoundary(({ error }) => (
     <div>
       <h2>Something went wrong</h2>
-      <button onClick={reset}>Try again</button>
+      <p>{error.message}</p>
     </div>
   )),
   path("/dashboard", DashboardIndex, { name: "dashboard" }),

package/skills/mime-routes/SKILL.md

@@ -81,7 +81,7 @@ export const urlpatterns = urls(({ path }) => [
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — first variant (JSON, since it was registered first)
+- `Accept: */*` — RSC page (the primary, since it was registered first)
 
 ## Wildcard Routes
 

package/skills/prerender/SKILL.md

@@ -119,6 +119,8 @@ interface BuildContext<TParams> {
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
+  searchParams: URLSearchParams; // URLSearchParams from the synthetic URL (always empty for prerender)
+  search: {}; // Typed search params -- always {} for prerender (no real query string)
   set(key: string, value: any): void; // Set context variable (string key)
   set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
   get(key: string): any; // Read context variable (string key)

package/skills/rango/SKILL.md

@@ -218,17 +218,18 @@ Grouped by concern — read when you need to…
 
 **Client & presentation** — build the client-side UX:
 
-| Skill               | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `/hooks`            | Client-side React hooks                                                   |
-| `/theme`            | Light/dark mode with FOUC prevention                                      |
-| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration |
-| `/fonts`            | Load web fonts with preload hints                                         |
-| `/css`              | Import CSS in the Document `<head>` (`?url` + managed `precedence` links) |
-| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                |
-| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots             |
-| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                     |
-| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope        |
+| Skill               | Description                                                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `/hooks`            | Client-side React hooks                                                                                                            |
+| `/theme`            | Light/dark mode with FOUC prevention                                                                                               |
+| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration                                                          |
+| `/fonts`            | Load web fonts with preload hints                                                                                                  |
+| `/css`              | Import CSS in the Document `<head>` (`?url` + managed `precedence` links)                                                          |
+| `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
+| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
+| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
+| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
 
 **Observability & production health**:
 

package/skills/response-routes/SKILL.md

@@ -316,7 +316,7 @@ the response payload straight from the `urls()` patterns and needs no
 ### ParamsFor with Response Routes
 
 ```typescript
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Works for both RSC and response routes
 type ProductParams = ParamsFor<"api.productDetail">;
@@ -422,7 +422,7 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;

package/skills/route/SKILL.md

@@ -346,6 +346,10 @@ state persists on back/forward. See `/hooks` for details.
 Attach location state to any server response (not just redirects):
 
 ```typescript
+import { createLocationState } from "@rangojs/router";
+
+const ServerInfo = createLocationState<{ data: string }>();
+
 path("/dashboard", (ctx) => {
   ctx.setLocationState(ServerInfo({ data: "welcome" }));
   return <Dashboard />;

package/skills/router-setup/SKILL.md

@@ -62,6 +62,9 @@ urls(
     revalidate, // Control revalidation
     intercept, // Intercept routes for modals
     when, // Conditional rendering
+    errorBoundary, // Add an error boundary
+    notFoundBoundary, // Add a not-found boundary
+    transition, // Configure view transitions
   }) => [
     // Route definitions here
   ],

package/skills/scripts/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: scripts
+description: Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle
+argument-hint: "[vendor]"
+---
+
+# Scripts
+
+Inject `<script>` tags into the document the idiomatic Rango way: push a config
+from a **server** route/layout handler with `ctx.use(Script)(config)`, and render
+them with the built-in **`<Scripts />`** component (the `Meta` / `<MetaTags>`
+pair, but for scripts). The request CSP **nonce is applied automatically to
+document-rendered scripts** — you never read or pass it. (The one exception is an
+async script first encountered on a soft navigation; see the nonce caveat under
+"Execution contract".)
+
+## Setup
+
+`<Scripts />` is a client component; place it in your Document (which is
+`"use client"`). The default Document already includes both sites; a custom one
+adds them next to `<MetaTags />`:
+
+```tsx
+// document.tsx ("use client")
+import { MetaTags, Scripts } from "@rangojs/router/client";
+
+export function Document({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <MetaTags />
+        <Scripts /> {/* renders position: "head" scripts (the default) */}
+      </head>
+      <body>
+        <Scripts position="body" /> {/* renders position: "body" scripts */}
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Push from a handler
+
+`ScriptConfig` is a discriminated union — exactly one of three shapes, so invalid
+combinations are compile errors:
+
+```ts
+import { Script } from "@rangojs/router";
+
+// 1. External ASYNC — a React resource. Loads once when first encountered,
+//    including after a soft navigation, deduped by src. The fire-and-forget case.
+ctx.use(Script)({ id: "stripe", src: "https://js.stripe.com/v3", async: true });
+
+// 2. External ORDERED — in-place, optional `defer`. Document-load (see below).
+ctx.use(Script)({
+  id: "plausible",
+  src: "https://plausible.io/js/script.js",
+  defer: true,
+  attributes: { "data-domain": "example.com" },
+});
+
+// 3. INLINE — `id` REQUIRED, raw JS body (escaped against </script> by <Scripts>).
+//    For GTM/GA4/Segment let the body self-inject its loader (see below).
+ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+```
+
+| Shape            | Required             | Optional                                        | Forbidden               |
+| ---------------- | -------------------- | ----------------------------------------------- | ----------------------- |
+| Inline           | `id`, `children`     | `position`, `type`, `attributes`                | `src`, `async`, `defer` |
+| External async   | `src`, `async: true` | `id`, `position`, `type`, `attributes`          | `children`, `defer`     |
+| External ordered | `src`                | `defer`, `id`, `position`, `type`, `attributes` | `children`, `async`     |
+
+- `id` — dedup key (last-push-wins), and rendered as the script's DOM `id` (for
+  vendors that target `<script id="…">`). Required for inline (React never dedups
+  inline scripts); for ordered external it falls back to `src`. Async externals
+  dedup by `src` (matching React), so there `id` is the DOM id only.
+- `position` — `"head"` (default) or `"body"`. An async script is hoisted to
+  `<head>` by React regardless.
+- `type` — free string: `"module"`, `"application/ld+json"`, `"text/partytown"`, …
+- `attributes` — React-cased (`crossOrigin`, not `crossorigin`) and React-typed
+  (`data-*`, `integrity`, `referrerPolicy`, …). Excluded: the fields the handle
+  manages (`id`/`src`/`async`/`defer`/`type`/`children`/`nonce`) and all `on*`
+  handlers (`onLoad`/`onError`/… — a config is serialized to the client, so a
+  function can't survive; use a `"use client"` component for callbacks).
+
+## Execution contract (read this)
+
+React makes a `<script>` it mounts on the client INERT (it creates the element via
+innerHTML, which the HTML spec never executes). So:
+
+| Script                           | Runs on hard load              | Runs on soft (`<Link>`) navigation                    |
+| -------------------------------- | ------------------------------ | ----------------------------------------------------- |
+| Inline (`children`)              | Yes (it's in the initial HTML) | **No** — it is document-load only                     |
+| External ordered (`defer`/plain) | Yes                            | **No** — document-load only                           |
+| External `async`                 | Yes                            | **Yes** — React loads the resource on first encounter |
+
+`<Scripts>` enforces this honestly: after hydration it **freezes** the inline +
+ordered set to what was in the initial HTML, so a navigation never inserts an
+inert (silently dead) `<script>`. Async configs stay reactive. Reusing an `id`
+shapes the INITIAL document output (last-push-wins) — it does not re-run a script
+during navigation.
+
+**Nonce caveat for soft-nav async.** The "nonce is applied automatically" claim
+holds for DOCUMENT-RENDERED scripts (they carry the nonce in the SSR HTML). An
+async script first encountered on a soft navigation is injected by React on the
+client, where `useNonce()` is `undefined` by design (the router does not serialize
+the nonce to the client — that would weaken CSP), so it has no nonce attribute. It
+still loads under `'strict-dynamic'` (React's nonced runtime injects it, so the
+trust propagates) — which is the recommended policy — or if your `script-src`
+allows the host. A nonce-only policy without `'strict-dynamic'` would block it.
+
+**Per-navigation behavior belongs in a client component or hook**, not in a
+re-pushed inline script. The GTM demo does exactly this: a root-layout `Script`
+bootstrap fires the first page_view on document load, and a `"use client"`
+`<GtmPageViews>` component fires a page_view on every subsequent soft navigation.
+
+## The inline-self-inject rule (GTM/GA4/Segment)
+
+If an inline bootstrap must run **before** an external loader, do NOT push the
+loader as a separate `{ src, async }` config: React 19 hoists a declarative
+`<script async src>` to the **top** of `<head>`, above your inline bootstrap, so
+the loader could run before the bootstrap. Instead let the bootstrap inject its
+own loader (Google's snippet does exactly this):
+
+```ts
+function gtmBootstrap(id: string): string {
+  return [
+    "window.dataLayer=window.dataLayer||[];",
+    'window.dataLayer.push({"gtm.start":new Date().getTime(),event:"gtm.js"});',
+    `(function(d,s,i){var j=d.createElement(s);j.async=true;j.src="https://www.googletagmanager.com/gtm.js?id="+encodeURIComponent(i);var f=d.getElementsByTagName(s)[0];f.parentNode.insertBefore(j,f);})(document,"script",${JSON.stringify(id)});`,
+  ].join("");
+}
+```
+
+Under a `'strict-dynamic'` CSP the nonced inline script vouches for the loader it
+creates, so the injected loader needs no nonce of its own.
+
+### Per-route tagging on the first render
+
+A route can **override** a layout's bootstrap by reusing the `id`, baking
+per-route data into the FIRST (hard-load) page_view server-side — the Script
+handle is collected after handlers run (parent → child, last-wins):
+
+```ts
+// root layout: generic bootstrap
+ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+// a route: same id, with content_group baked in
+ctx.use(Script)({
+  id: "gtm",
+  children: gtmBootstrapWith({ content_group: "blog" }),
+});
+```
+
+## CSP
+
+The nonce is automatic for document-rendered scripts. Include `'strict-dynamic'`
+in `script-src` (recommended): besides letting a nonced loader vouch for the
+scripts it injects, it also covers the one nonce-less case — an async script first
+loaded on a soft navigation is injected client-side without a nonce (see the
+caveat above), and `'strict-dynamic'` trusts it via React's nonced runtime.
+Otherwise allow the vendor hosts. For GTM/GA4 (Google's wildcards): `script-src
+'self' 'nonce-…' 'strict-dynamic' https://*.googletagmanager.com`, plus `img-src`
+/ `connect-src` for `*.google-analytics.com` / `*.analytics.google.com`, and
+`frame-src https://*.googletagmanager.com` for the GTM `<noscript>` iframe. See
+[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp).
+
+## Not covered (do it yourself)
+
+- **`onLoad` / `onReady` / `onError`** — callbacks can't cross the server handle
+  boundary. Render your own `"use client"` component with a load listener keyed
+  off the script id.
+- **`<noscript>` fallbacks** (e.g. the GTM body iframe) — not a `<script>`;
+  render it directly in your Document `<body>`.
+- **Partytown / web-worker offloading** — push the worker config with
+  `type: "text/partytown"` and wire Partytown's own nonce config manually.
+
+A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
+ecommerce events) lives in `tests/vite-rsc-demo`.

package/skills/testing/SKILL.md

@@ -88,7 +88,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | 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 handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
 | 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` |

package/skills/testing/bindings.md

@@ -39,12 +39,26 @@ import { requireMembership } from "../app/middleware";
 import { authorizeAction } from "../app/actions";
 
 // A D1Database double satisfying drizzle-orm/d1's driver contract.
-const fakeD1 = makeFakeD1({
-  // .raw() serves positional rows in schema-column order, driver-encoded.
-  raw: () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
-  // .run() returns { success, meta }, no rows.
-  run: () => ({ success: true, meta: { changes: 1 } }),
-});
+// rango ships no double for D1 — build your own to match the driver.
+const fakeD1 = {
+  prepare: () => ({
+    // .raw() serves positional rows in schema-column order, driver-encoded.
+    raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+    // .run() returns { success, meta }, no rows.
+    run: async () => ({ success: true, meta: { changes: 1 } }),
+    all: async () => ({ results: [], success: true, meta: {} }),
+    first: async () => null,
+    bind: (..._args: unknown[]) => ({
+      raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+      run: async () => ({ success: true, meta: { changes: 1 } }),
+      all: async () => ({ results: [], success: true, meta: {} }),
+      first: async () => null,
+    }),
+  }),
+  batch: async (stmts: unknown[]) =>
+    stmts.map(() => ({ results: [], success: true, meta: {} })),
+  exec: async (_sql: string) => ({ count: 0, duration: 0 }),
+};
 
 describe("bindings seam", () => {
   it("loader reads through env.DB", async () => {

package/skills/testing/cache-prerender.md

@@ -60,10 +60,13 @@ filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[]
 ## Recipe
 
 ```ts
-// In a Playwright e2e, import the cache-status helpers from the e2e entry —
+// In a Playwright e2e, import from the e2e entry —
 // the @rangojs/router/testing barrel pulls a build-only virtual that does not
 // resolve in a plain Playwright runner.
-import { assertCacheStatus } from "@rangojs/router/testing/e2e";
+import { expect, test } from "@playwright/test";
+import { assertCacheStatus, createRangoE2E } from "@rangojs/router/testing/e2e";
+
+const { parityDescribe } = createRangoE2E({ test, expect });
 
 parityDescribe("product page caches", (f) => {
   test("second request is a hit", async ({ page }) => {

package/skills/testing/client-components.md

@@ -21,6 +21,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `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).                                |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — 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.
 
@@ -36,6 +37,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `useRouter`                    | The router handle, including `.basename`.                                                     |
 | `usePathname`                  | Current committed pathname.                                                                   |
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
+| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
 | `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path).                                                 |
 | `useLocationState`             | SEEDED `history.state` value.                                                                 |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |

package/skills/testing/e2e-parity.md

@@ -49,7 +49,7 @@ This is full-stack: the harness builds and serves your real app (`pnpm dev` or `
 
 `createRangoE2E(...)` -> `RangoE2E`:
 
-- `useFixture(options)` -> `Fixture` (`{ mode, root, url(path?), proc() }`). `url(path)` resolves against the running server.
+- `useFixture(options)` -> `Fixture` (`{ mode, root, url(url?), proc() }`). `url(path)` resolves against the running server.
 - `parityDescribe(name, (f) => { ... }, options?)` -> registers a dev describe `name` AND a production describe `` `${name} (production)` ``. Body runs once per describe with that describe's `Fixture`.
 - `expectParity(page, intent, opts) => Promise<void>` — runs `intent` over the JS page and a fresh no-JS context, asserts observed testids' text + pathname/search/hash + `document.cookie` are equal. `opts` is the required `observe` plus optional `baseURL`, `waitFor`, and `ignoreCookies` (the rango state cookie is excluded automatically).
 - `rangoMatchers` — `{ toHaveRangoPathname }` only (pass to `expect.extend`).

package/skills/testing/flight.md

@@ -24,15 +24,14 @@
 
 A request context is active for the whole render, so an async Server Component can read it via `getRequestContext()` / the router's server APIs. The notable surfaces seeded from the options above:
 
-| Field       | Type                                      | Meaning                                                               |
-| ----------- | ----------------------------------------- | --------------------------------------------------------------------- |
-| `request`   | `Request`                                 | The backing request (from `request`/`headers`).                       |
-| `url`       | `URL`                                     | The request URL.                                                      |
-| `env`       | `unknown`                                 | Env / bindings (from `env`).                                          |
-| `params`    | `Record<string, string>`                  | Route params (from `params`).                                         |
-| `routeName` | `string \| undefined`                     | Matched route name (from `routeName`).                                |
-| `get`       | `<T>(v: ContextVar<T>) => T \| undefined` | Read a var seeded via `vars` (by `createVar()` handle or string key). |
-| `cookies`   | reader                                    | Cookies parsed from the request's Cookie header.                      |
+| Field       | Type                                                                       | Meaning                                                               |
+| ----------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `request`   | `Request`                                                                  | The backing request (from `request`/`headers`).                       |
+| `url`       | `URL`                                                                      | The request URL.                                                      |
+| `env`       | `unknown`                                                                  | Env / bindings (from `env`).                                          |
+| `params`    | `Record<string, string>`                                                   | Route params (from `params`).                                         |
+| `routeName` | `string \| undefined`                                                      | Matched route name (from `routeName`).                                |
+| `get`       | `<T>(v: ContextVar<T>) => T \| undefined; <K extends string>(key: K): any` | Read a var seeded via `vars` (by `createVar()` handle or string key). |
 
 ### Returns — `Promise<string>`
 

package/skills/testing/render-handler.md

@@ -39,7 +39,7 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 | `get`              | `(Var) => value`                     | Read a seeded `vars` variable.                                                                 |
 | `headers`          | `Headers`                            | Response headers; set via `ctx.headers.set(...)` (merged into `result.response`).              |
 | `setLocationState` | `(entries) => void`                  | Set location state (surfaced on `result.locationState`).                                       |
-| `waitUntil`        | `(promise) => void`                  | Register background work.                                                                      |
+| `waitUntil`        | `(fn: () => Promise<void>) => void`  | Register background work.                                                                      |
 
 ### Returns — `RenderHandlerResult`
 

package/skills/testing/response-routes.md

@@ -82,7 +82,7 @@ describe("api routes via dispatch", () => {
 
 - Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
-- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning a `Response` (e.g. `Response.json(x)`) passes through unchanged. A thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or the effective `ctx.setStatus()` override); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
+- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning a `Response` (e.g. `Response.json(x)`) passes through unchanged. A thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or a non-200 `ctx.res.status` already set upstream in the request pipeline); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
 - A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
 - A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.

package/skills/testing/server-actions.md

@@ -28,17 +28,17 @@
 
 `fn` receives `ctx`, the full entered `RequestContext`; the same object resolves via `getRequestContext()` inside `fn`. Notable fields:
 
-| Field                          | Type                           | Meaning                                                                                                                                                                                                           |
-| ------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`                          | `TEnv`                         | The seeded platform bindings.                                                                                                                                                                                     |
-| `request`                      | `Request`                      | The concrete request the run is bound to.                                                                                                                                                                         |
-| `cookies()`                    | `() => Record<string, string>` | @internal effective cookie view. To read or queue cookies inside the action, use the standalone `cookies()` from `@rangojs/router` (`cookies().get(name)` / `cookies().set(...)`), which returns a `CookieStore`. |
-| `get(token)` / `set(token, v)` | accessor                       | Read/write request-scoped vars (seeded from `vars` / `variables`).                                                                                                                                                |
-| `params`                       | `Record<string, string>`       | Seeded route params.                                                                                                                                                                                              |
-| `reverse(name, params?)`       | function                       | Build a URL from `routeMap` (when seeded).                                                                                                                                                                        |
-| `header(name, value)`          | function                       | Queue a response header.                                                                                                                                                                                          |
-| `setLocationState(...)`        | function                       | Set the flash / location state the client reads.                                                                                                                                                                  |
-| `theme`/`setTheme`             | —                              | Theme accessors, inert unless `theme` is seeded.                                                                                                                                                                  |
+| Field                          | Type                     | Meaning                                                                                                                                                                                                           |
+| ------------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`                          | `TEnv`                   | The seeded platform bindings.                                                                                                                                                                                     |
+| `request`                      | `Request`                | The concrete request the run is bound to.                                                                                                                                                                         |
+| `cookies()`                    | `Record<string, string>` | @internal effective cookie view. To read or queue cookies inside the action, use the standalone `cookies()` from `@rangojs/router` (`cookies().get(name)` / `cookies().set(...)`), which returns a `CookieStore`. |
+| `get(token)` / `set(token, v)` | accessor                 | Read/write request-scoped vars (seeded from `vars` / `variables`).                                                                                                                                                |
+| `params`                       | `Record<string, string>` | Seeded route params.                                                                                                                                                                                              |
+| `reverse(name, params?)`       | function                 | Build a URL from `routeMap` (when seeded).                                                                                                                                                                        |
+| `header(name, value)`          | function                 | Queue a response header.                                                                                                                                                                                          |
+| `setLocationState(...)`        | function                 | Set the flash / location state the client reads.                                                                                                                                                                  |
+| `theme`/`setTheme`             | —                        | Theme accessors, inert unless `theme` is seeded.                                                                                                                                                                  |
 
 ### Returns — `RunInRequestContextResult<T>`
 

package/skills/testing/setup.md

@@ -53,6 +53,7 @@ import { defineConfig } from "vitest/config";
 import {
   rangoTestAliases,
   rangoUseClientTransform,
+  rangoInlineDeps,
 } from "@rangojs/router/testing/vitest";
 
 // Production React in this process AND any forked worker (forks inherit env).
@@ -69,6 +70,8 @@ export default defineConfig({
     include: ["**/*.rsc-test.{ts,tsx}"],
     pool: "forks",
     execArgv: ["--conditions=react-server"], // or React throws "react-server condition must be enabled"
+    // Required for an installed consumer on Node >= 23 (rango ships TS source).
+    server: { deps: { inline: rangoInlineDeps } },
   },
 });
 ```

package/skills/typesafety/SKILL.md

@@ -32,8 +32,9 @@ is only needed when you want the richer `typeof router.routeMap` shape
 available globally.
 
 - `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
-  Use for `Handler<"name">`, `Prerender<"name">`, server `ctx.reverse()`,
-  and named-route param/search inference.
+  Use for `Handler<"name">` (type annotation), `Prerender<"name">(...)` (function
+  call with type arg for param inference), server `ctx.reverse()`, and
+  named-route param/search inference.
 - `typeof router.routeMap` — the real merged route map from your router
   instance, including response-route metadata such as `{ path, response }`.
 - `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`