@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/skills/streams-and-websockets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: streams-and-websockets
-description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats.
+description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.
 argument-hint: "[sse | websocket | agents]"
 ---
 

package/skills/tailwind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind
-description: Set up Tailwind CSS v4 with the Document component and CSS imports
+description: Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.
 argument-hint: [setup]
 ---
 

package/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader or middleware, or asking how to test a route end-to-end in dev and production.
 argument-hint: [layer]
 ---
 
@@ -88,6 +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 `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
 | 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`        |

package/skills/testing/handles.md

@@ -13,7 +13,7 @@ A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps
 | `handle`   | `Handle<TData, TAccumulated>`         | The handle whose registered collect to run.                                                                                                                                                                                                          |
 | `segments` | `ReadonlyArray<ReadonlyArray<TData>>` | Per-segment pushed values, one inner array per route segment, in **parent -> child** order. Empty inner arrays are filtered before the collect runs (matching production `collectHandleData` — a segment that pushed nothing is not passed through). |
 
-**Returns** `TAccumulated` — exactly what the handle's collect produces (a default-flatten array, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it warns and falls back to `segments.flat()`.
+**Returns** `TAccumulated` — exactly what the handle's collect produces (the default identity collect's per-segment `TData[][]`, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it falls back to that same identity default and **warns** — a handle with a custom collect that failed to register would otherwise return the wrong shape silently.
 
 ### runLoader option — `handles` — `src/testing/run-loader.ts`
 
@@ -40,7 +40,9 @@ import { describe, it, expect } from "vitest";
 import { collectHandle } from "@rangojs/router/testing";
 import { createHandle } from "@rangojs/router";
 
-const Breadcrumbs = createHandle<{ label: string; href: string }>(); // default flatten
+// Opt into a flat list; the default collect groups per segment (TData[][]).
+type Crumb = { label: string; href: string };
+const Breadcrumbs = createHandle<Crumb, Crumb[]>((segments) => segments.flat());
 
 it("flattens per-segment crumbs in parent->child order", () => {
   const home = { label: "Home", href: "/" };

package/skills/testing/render-handler.md

@@ -8,20 +8,21 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 
 ### Options — `RenderHandlerOptions`
 
-| Field              | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
-| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `params`           | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
-| `env`              | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
-| `request`          | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
-| `headers`          | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
-| `vars`             | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
-| `routeName`        | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
-| `routeMap`         | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
-| `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.                                                                                                                                                                                                                                      |
+| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
+| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
+| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
+| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
+| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
+| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
+| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
+| `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.                                                                                                                                                                                                                                      |
+| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                             |
 
 ### Context — `HandlerContext` (what your handler receives)
 

package/skills/testing/reverse-and-types.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
 
-The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed.
+The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed. It (and `diffGeneratedRoutes`) are **async — `await` them** — because expanding an async `include(prefix, () => import("./routes"))` group means importing that module first.
 
 ## API
 
@@ -13,7 +13,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 | `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.           |
 | `generatedMap` | `Record<string, unknown>` (optional) | The imported `*.named-routes.gen.ts` map (name→pattern, or `{ path }` objects). Omit to diff against the global route map (`getGlobalRouteMap()`) instead. |
 
-### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` returns)
+### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` resolves to)
 
 | Field      | Type                           | Meaning                                                                                                                                     |
 | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -24,7 +24,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 
 ### Returns — `assertGeneratedRoutesMatch`
 
-`void` on match. On drift, throws an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` returns the `GeneratedRoutesDiff` above without throwing.)
+`Promise<void>` — **await it**. Resolves on match; on drift the promise REJECTS with an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` resolves to the `GeneratedRoutesDiff` above and never rejects.) Both are async so an async `include(() => import())` group is imported and spliced into `routeMap` before the diff — call them without `await` and every route in that group reads as a false `missing`.
 
 ## Recipe
 
@@ -57,14 +57,15 @@ expectTypeOf<
 
 ```ts
 // 3. assertGeneratedRoutesMatch — a one-liner whole-app drift test. Real
-//    matching expands lazy include()d routes before the diff.
+//    matching expands lazy include()d routes before the diff. It is async
+//    (it awaits findMatch to import async include groups), so await it.
 import { it } from "vitest";
 import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
 import { router } from "../src/router";
 import generated from "../src/router.named-routes.gen";
 
-it("generated named-routes map is in sync with the router", () => {
-  assertGeneratedRoutesMatch(router, generated);
+it("generated named-routes map is in sync with the router", async () => {
+  await assertGeneratedRoutesMatch(router, generated);
 });
 ```
 
@@ -74,7 +75,7 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 
 - Type tests run at TYPECHECK time (`tsc --noEmit`), NOT in the vitest runner. They are their own layer — wire them into CI as a real step (`pnpm run typecheck`). A type test nobody runs is just a comment.
 - `@ts-expect-error` ERRORS if the line below it ever starts compiling, so a regressed guard fails the typecheck. A runtime test cannot assert "this should not type-check".
-- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (calls `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
+- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (awaits `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. It is **async** so it can await the module import behind an async `include(() => import())` group; `await` the call (or the async group's routes read as `missing`). This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
 - MULTI-APP route-map isolation. `href()`/`reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
 
 ## See also

package/skills/theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theme
-description: Opt-in theme system with FOUC prevention for light/dark mode
+description: Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).
 argument-hint: [setup]
 ---