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

package/skills/testing/server-actions.md

@@ -0,0 +1,107 @@
+# Testing a server action — runInRequestContext
+
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `"use server"` action (see `/server-actions`)
+
+`runInRequestContext(fn, opts)` builds a real `RequestContext` (the same `createRequestContext` the RSC handler uses) AND enters it around `fn`, so an action that calls `getRequestContext()` / `cookies()` / `ctx.get(var)` runs with production fidelity. You SEED the request, env, and vars; the REAL machinery is cookie/header accumulation, location-state, and redirect/notFound throwing.
+
+## API
+
+### Options — `CreateTestContextOptions<TEnv>`
+
+| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                               |
+| --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                             |
+| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                 |
+| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                            |
+| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                              |
+| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                             |
+| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                              |
+| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                          |
+| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                         |
+| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                            |
+| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                             |
+| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                         |
+| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                            |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (value is `{version}:{timestamp}`, default `"0"`). |
+
+### Context — `RequestContext<TEnv>` (what your code receives)
+
+`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.                                                                                                                                                                  |
+
+### Returns — `RunInRequestContextResult<T>`
+
+| Field             | Type                      | Meaning                                                                                                                                                                                           |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `result`          | `T \| undefined`          | `fn`'s awaited return, or `undefined` if it threw.                                                                                                                                                |
+| `thrown`          | `unknown`                 | What `fn` threw (a redirect / `notFound` `Response` on the success path), or `undefined`. Captured, NOT re-thrown — assert on it.                                                                 |
+| `response`        | `Response`                | The merged `Response` (status + headers + Set-Cookie). On a thrown redirect, that redirect's `Location` merged with the accumulated cookies/headers.                                              |
+| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies + run mutations, last-write-wins.                                                                                                                          |
+| `headers`         | `Record<string, string>`  | Response headers the run set (plus a thrown redirect's `Location`), EXCLUDING `set-cookie` (use `cookies`). Names lowercased. A `keepClientCache()` call shows here as `x-rango-keep-cache: "1"`. |
+| `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing.                               |
+| `locationState`   | `Record<string, unknown>` | The flash set via `ctx.setLocationState()` / `redirect({ state })`, as the flat `{ key: value }` the client reads.                                                                                |
+
+Low-level variant: when you already hold a context from `createTestRequestContext(opts)`, call `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`) to enter it directly. `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+
+## Recipe
+
+```ts
+import { it, expect } from "vitest";
+import { runInRequestContext } from "@rangojs/router/testing";
+import { loginAction } from "../src/actions/login"; // sets a session cookie + flash, then throw redirect("/app")
+
+it("sets the session cookie + flash and redirects", async () => {
+  const { thrown, cookies, locationState } = await runInRequestContext(
+    () => loginAction(input),
+    {
+      env,
+      request: new Request("https://app.test/admin", {
+        headers: { Cookie: "sid=abc" },
+      }),
+    },
+  );
+  expect((thrown as Response).headers.get("Location")).toBe("/app"); // redirected
+  expect(cookies.session).toBeDefined(); // cookie set before the throw, no @internal cast
+  expect(locationState).toEqual({ flash: { text: "Welcome back" } });
+});
+
+it("asserts the client-cache directives an action issued", async () => {
+  // invalidateClientCache() rotates the state cookie -> a Set-Cookie on response.
+  const { response, stateCookieName } = await runInRequestContext(() =>
+    logoutAction(),
+  );
+  expect(
+    response.headers
+      .getSetCookie()
+      .some((c) => c.startsWith(stateCookieName + "=")),
+  ).toBe(true);
+
+  // keepClientCache() sets the suppression directive header (no cookie).
+  const { headers } = await runInRequestContext(() => dismissBannerAction());
+  expect(headers["x-rango-keep-cache"]).toBe("1");
+});
+```
+
+## Caveats
+
+- The snapshot fires whether `fn` RETURNS or THROWS. A `throw redirect("/app")` on the success path is captured on `thrown` (NOT re-thrown), so no try/catch is needed; assert on `thrown` for a throwing action.
+- There is no cookies / headers option. Seed a request cookie by passing a full `Request` with the `Cookie` header (as in the recipe).
+- `runWithRequestContext(ctx, fn)` is the low-level entry when you already hold a context; `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+- Platform bindings are yours to double via `env` (see `./bindings.md`).
+
+## See also
+
+- `/server-actions` — the DSL this tests
+- Siblings: `./render-handler.md`, `./middleware.md`, `./loader.md`, `./bindings.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "runInRequestContext — the handler / server-action test primitive"

package/skills/testing/server-tree.md

@@ -0,0 +1,128 @@
+# Inspecting the rendered tree — renderServerTree, findClientBoundaries, findElements
+
+**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` 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
+
+### Options — `RenderServerTreeOptions` (extends `RenderToFlightStringOptions`)
+
+| Field              | Type                      | Meaning                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`          | `Request \| string`       | The request the render runs under (absolute URL, path, or a `Request`). Defaults to `http://localhost/`. A server component reading `getRequestContext()` sees this url/cookies. A passed `Request`'s headers win; `headers` is then ignored.                                                                                          |
+| `headers`          | `HeadersInit`             | Request headers (e.g. `Cookie`) visible to the server tree, 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`                | Context variables visible via `ctx.get(...)`, as a prior middleware would have set them. Object form (`{ user }`) or `[key, value]` tuples.                                                                                                                                                                                            |
+| `clientComponents` | `Record<string, unknown>` | The `"use client"` components reachable from the tree, keyed by the boundary name to register each as a client reference (in place) so it serializes as an `I` row. Omit when `rangoUseClientTransform()` auto-discovers them, or for pure server-only trees. First-wins per worker; already-registered references are left untouched. |
+
+### Context — what your code receives
+
+A server component rendered here runs under a real request context: `getRequestContext()` resolves, `ctx.params`/`ctx.routeName`/`ctx.env` reflect the options, `ctx.get(MyVar)` reads a seeded `var`, and cookies come off the request. Same seeding as the handler-test primitives — you render an **element** you build (`<Page />`); to run a route **handler** `(ctx) => rsc` use `renderHandler` (see `./render-handler.md`).
+
+### Returns — `RenderServerTreeResult`
+
+```ts
+renderServerTree(element, opts?): Promise<{ flight: string; tree: unknown }>
+```
+
+| Field    | Type      | Meaning                                                                                                                                                                                                  |
+| -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flight` | `string`  | The raw Flight wire string (so `toMatchFlight` assertions still apply).                                                                                                                                  |
+| `tree`   | `unknown` | The deserialized React element tree. Server elements are plain React elements; each client boundary is an inert placeholder whose `props` are the real deserialized JS values that crossed the boundary. |
+
+#### `findClientBoundaries(tree, selector?) -> ClientBoundary[]`
+
+Every client boundary in document order; always an array (no throw on zero/many — destructure `const [tag] = ...` and assert `.length` when the count matters; no match yields `[]`). `selector` is a STRING (match by export name) or a `BoundarySelector` object, criteria AND-ed.
+
+| `BoundarySelector` | Type                                    | Meaning                                                                                    |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `name`             | `string`                                | Match the boundary's export name (same as a bare string).                                  |
+| `testId`           | `string`                                | Match `props["data-testid"]` exactly (a `data-testid` you passed AS A PROP to the island). |
+| `props`            | `Record<string, unknown>`               | Subset deep-equal match (Date/Map/Set/array/nested-object aware); unlisted props ignored.  |
+| `where`            | `(boundary: ClientBoundary) => boolean` | Arbitrary predicate.                                                                       |
+
+`ClientBoundary` = `{ id, name, props (excludes children), children, element }`.
+
+#### `findElements(tree, selector?) -> FoundElement[]`
+
+Every SERVER/HOST element a server component produced (`<article>`, `<h2>`), in document order; always an array. `selector` is a host TAG string (`"h2"`) or an `ElementSelector` object, criteria AND-ed.
+
+| `ElementSelector` | Type                                 | Meaning                                                                            |
+| ----------------- | ------------------------------------ | ---------------------------------------------------------------------------------- |
+| `tag`             | `string`                             | Match the host tag name (`"article"`, `"h2"`).                                     |
+| `testId`          | `string`                             | Match `props["data-testid"]` exactly (on a host element).                          |
+| `props`           | `Record<string, unknown>`            | Subset deep-equal match (Date/Map/Set/array/nested aware).                         |
+| `text`            | `string \| RegExp`                   | Match the element's text content (substring for a string, `.test()` for a RegExp). |
+| `where`           | `(element: FoundElement) => boolean` | Arbitrary predicate.                                                               |
+
+`FoundElement` = `{ tag, props (excludes children), children, text, element }`.
+
+#### `textContent(node) -> string`
+
+Concatenates every string/number leaf of a node's subtree in document order — the clean way to assert rendered text, instead of `JSON.stringify(tree).toContain(...)`.
+
+## Recipe
+
+```tsx
+import { it, expect } from "vitest";
+import {
+  renderServerTree,
+  findClientBoundaries,
+  findElements,
+  textContent,
+} from "@rangojs/router/testing/flight";
+import { PriceTag } from "./PriceTag.js"; // a "use client" component (any filename)
+
+async function ProductPanel({ amount, asOf }: { amount: number; asOf: Date }) {
+  await Promise.resolve();
+  return (
+    <article>
+      <h2>Wine</h2>
+      <PriceTag amount={amount} currency="USD" asOf={asOf} />
+    </article>
+  );
+}
+
+it("client props survive the serialize -> deserialize round trip", async () => {
+  const { flight, tree } = await renderServerTree(
+    <ProductPanel amount={19.5} asOf={new Date("2026-01-02T00:00:00Z")} />,
+    // Omit clientComponents when rangoUseClientTransform() is wired (see ./setup.md);
+    // otherwise register islands explicitly:
+    { clientComponents: { PriceTag } },
+  );
+  expect(flight).toMatchFlight("PriceTag"); // wire assertions still work
+
+  const [tag] = findClientBoundaries(tree, "PriceTag");
+  expect(tag.props.amount).toBe(19.5); // a real number
+  expect(tag.props.asOf).toBeInstanceOf(Date); // a real Date, not "$D..."
+});
+
+it("asserts the server-rendered host content", async () => {
+  const { tree } = await renderServerTree(
+    <ProductPanel amount={19.5} asOf={new Date("2026-01-02T00:00:00Z")} />,
+    { clientComponents: { PriceTag } },
+  );
+  const [h2] = findElements(tree, "h2");
+  expect(h2.text).toBe("Wine");
+  expect(textContent(tree)).toContain("Wine"); // instead of JSON.stringify(tree)
+});
+```
+
+## Caveats
+
+- This renders an ELEMENT you build (`<Page />`). To test a route HANDLER (a `(ctx) => rsc` function registered via `path(...)`), use `renderHandler` (see [`./render-handler.md`](./render-handler.md)) — handlers have their own util. Do NOT wrap a handler in `createElement` and render it here: a handler is not a component, so React would invoke it with `props` as its argument instead of the real `HandlerContext`, and the seeded `params`/`vars` plus `ctx.use`/`ctx.reverse`/`ctx.get`/`cookies()` would all be absent.
+- Island auto-discovery from the server tree's imports needs `rangoUseClientTransform()` in the rsc project (see `./setup.md`). Without it a plainly-imported island is just a function the serializer renders server-side — register islands explicitly via `{ clientComponents: { PriceTag } }`.
+- Same alias requirement as `./flight.md`: a rendered component (or handler) that reads `getRequestContext()`/`cookies()` from the `@rangojs/router` barrel needs the `index.rsc.ts` alias (see `./setup.md`), or it hits the throwing out-of-react-server stub.
+- A client boundary's props come back as REAL JS values after deserialization (a `Date` is a `Date`, not a `$D...` encoding) — but there is NO hydration and NO interaction; boundaries are inert placeholders carrying props.
+- Server COMPONENTS do not survive Flight as identities (they are executed during serialization), so `findElements` matches the host elements they PRODUCED, not the component function. Client islands keep identity — use `findClientBoundaries` for those.
+- `findClientBoundaries` finds islands (`I` rows); `findElements` finds host elements. A `testId` on an island matches with `findClientBoundaries`; a `testId` on a host element matches with `findElements`. Use `textContent(node)` in place of `JSON.stringify(tree).toContain`.
+- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration re-tests React more than your app and misses server/client divergence (the only hydration bug worth a dedicated test, which needs a real browser). Test interaction at e2e.
+
+## See also
+
+- `/route` — the DSL this tests
+- Siblings: `./flight.md`, `./render-handler.md`, `./setup.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)

package/skills/testing/setup.md

@@ -0,0 +1,123 @@
+# Testing setup — the two vitest projects
+
+**Layer:** cross-cutting (vitest config) · **Import:** `@rangojs/router/testing/vitest`
+
+Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolves the bare specifier to its react-server impls so your app's router / loaders / middleware import in a bare Vitest process. You SEED nothing here — this file only wires the two projects every other recipe builds on. The node/DOM project keeps React on its CLIENT build; the Flight project flips to the `react-server` condition.
+
+## API
+
+### Options — `RangoTestAliasOptions`
+
+| Field    | Type                     | Meaning                                                                                                                                                                                                                                                                                      |
+| -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preset` | `"node" \| "cloudflare"` | Deployment preset, matching `rango({ preset })` in the Vite plugin. `"cloudflare"` additionally stubs the `cloudflare:workers` / `cloudflare:email` runtime virtuals a CF route tree imports. A string (not a boolean) so more presets can be added without an API change. Default `"node"`. |
+
+### Functions
+
+| Function                    | Returns                                   | Use                                                                                                                                                                                                         |
+| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                         |
+| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                  |
+
+### Returns — `RangoTestConfig` (from `rangoTestConfig`)
+
+```ts
+interface RangoTestConfig {
+  alias: TestAlias[]; // -> test.alias
+  server: { deps: { inline: RegExp[] } }; // [/@rangojs[/\\]router/] -> test.server.deps.inline
+}
+```
+
+## Recipe
+
+```ts
+// vitest.config.ts — the node + DOM project (keeps React on its CLIENT build)
+import { defineConfig } from "vitest/config";
+import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["test/**/*.test.{ts,tsx}"],
+    environment: "node", // renderRoute tests add a `// @vitest-environment happy-dom` pragma
+    // `preset: "cloudflare"` also stubs cloudflare:workers / cloudflare:email (default "node").
+    ...rangoTestConfig({ preset: "cloudflare" }),
+  },
+});
+```
+
+```ts
+// vitest.rsc.config.ts — the Flight project (react-server condition)
+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).
+process.env.NODE_ENV = "production";
+
+export default defineConfig({
+  plugins: [rangoUseClientTransform()],
+  resolve: {
+    conditions: ["react-server"],
+    alias: rangoTestAliases({ preset: "cloudflare" }), // or { preset: "node" }
+  },
+  test: {
+    globals: true,
+    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 } },
+  },
+});
+```
+
+```ts
+// example.test.ts — one test in the node/DOM project, importing real app code
+import { describe, it, expect } from "vitest";
+import { dispatch } from "@rangojs/router/testing";
+import { createRouter } from "@rangojs/router";
+import { apiPatterns } from "../src/api/urls"; // path.json(...) routes only, no Prerender()
+
+const router = createRouter().routes(apiPatterns);
+
+describe("api", () => {
+  it("serializes a JSON response route", async () => {
+    const res = await dispatch(router, { request: "/health" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+});
+```
+
+Scripts:
+
+```jsonc
+{
+  "scripts": {
+    "test:unit": "vitest run",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts",
+  },
+}
+```
+
+## Caveats
+
+- 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`). `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.
+- The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
+- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
+
+## See also
+
+- (cross-cutting)
+- Siblings: `./flight.md`, `./server-tree.md`, `./render-handler.md`, `./response-routes.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")

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`
@@ -57,7 +58,7 @@ the auto-generated `GeneratedRouteMap`, so **`rango generate` alone gives you
 path-checked `href()`** with no manual augmentation. Response and MIME payload
 inference is the exception: it comes only from `typeof router.routeMap` (via
 `RegisteredRoutes`), because `GeneratedRouteMap` carries paths + search but no
-payloads — so `Rango.PathResponse` resolves to `ResponseEnvelope<never>` until you wire
+payloads — so `Rango.PathResponse` resolves to `never` until you wire
 `RegisteredRoutes`.
 
 Recommended setup:
@@ -237,7 +238,7 @@ async function get<T extends Rango.Path>(
 ): Promise<Rango.PathResponse<T>> {
   return fetch(href(path)).then((r) => r.json());
 }
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -245,7 +246,7 @@ route can match several patterns and union their responses.
 
 `Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
 return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
-`ResponseEnvelope<{ createdAt: string }>`, matching what `r.json()` yields. This
+`{ createdAt: string }` (bare value), matching what `r.json()` yields. This
 is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
 honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
 `Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary

package/skills/use-cache/SKILL.md

@@ -52,8 +52,9 @@ export async function ProductCard({ id }: { id: string }) {
 
 ## Named Cache Profiles
 
-Define profiles in createRouter. Profile names map to `"use cache: <name>"` and
-`cache('<name>')` in the DSL.
+Define profiles in createRouter. Profile names map to `"use cache: <name>"` in
+the directive. The DSL `cache()` does not accept a string profile name; use an
+options object (`cache({ ttl: 60 })`) or the `"use cache: <name>"` directive.
 
 ```typescript
 createRouter({
@@ -340,13 +341,13 @@ that same namespace). The separate `revalidate()` export is the client-update ax
 
 ## Interaction with Other Caching
 
-| Mechanism          | Granularity        | When       | Use case                                        |
-| ------------------ | ------------------ | ---------- | ----------------------------------------------- |
-| `"use cache"`      | Function/component | Runtime    | Cache individual data fetches or components     |
-| `cache()` DSL      | Route segment      | Runtime    | Cache entire route subtrees with children       |
-| `cache('profile')` | Route segment      | Runtime    | Same as cache() with a named profile            |
-| `Static()`         | Route segment      | Build-time | Render once, never re-render                    |
-| `Prerender()`      | Route segment      | Build-time | Pre-render known params, optional live fallback |
+| Mechanism            | Granularity        | When       | Use case                                        |
+| -------------------- | ------------------ | ---------- | ----------------------------------------------- |
+| `"use cache"`        | Function/component | Runtime    | Cache individual data fetches or components     |
+| `cache()` DSL        | Route segment      | Runtime    | Cache entire route subtrees with children       |
+| `cache({ ttl })` DSL | Route segment      | Runtime    | Cache a route subtree with explicit options     |
+| `Static()`           | Route segment      | Build-time | Render once, never re-render                    |
+| `Prerender()`        | Route segment      | Build-time | Pre-render known params, optional live fallback |
 
 ## Dev Mode
 

package/skills/vercel/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: vercel
+description: Deploy a Rango app to Vercel Functions (Build Output API v3)
+argument-hint:
+---
+
+# Vercel deployment
+
+The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
+
+## Setup
+
+```bash
+npm install @vercel/functions
+```
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [react(), rango({ preset: "vercel" })],
+});
+```
+
+`@vercel/functions` is required: it backs the generated function launcher (`waitUntil`) and `VercelCacheStore`. The build fails with a clear error if it is missing.
+
+`vite build` produces `.vercel/output`; deploy with the Vercel CLI (`vercel deploy --prebuilt`) or via Git integration.
+
+## Function configuration
+
+Per-function knobs go under `vercel` and are written into `.vc-config.json`:
+
+```typescript
+rango({
+  preset: "vercel",
+  vercel: {
+    runtime: "nodejs22.x", // default
+    maxDuration: 30, // seconds, default
+    memory: 1024, // MB (platform default when omitted)
+    regions: ["fra1"], // pin regions (platform default when omitted)
+    functionName: "index", // the <name>.func dir + config.json route
+  },
+});
+```
+
+## Runtime Cache
+
+`VercelCacheStore` wraps the Vercel Runtime Cache. Locally (no `process.env.VERCEL`) fall back to an in-memory store so dev/preview work without the platform:
+
+```typescript
+import {
+  MemorySegmentCacheStore,
+  VercelCacheStore,
+} from "@rangojs/router/cache";
+import { getCache, waitUntil } from "@vercel/functions";
+
+const defaults = { ttl: 60, swr: 300 };
+const memoryStore = new MemorySegmentCacheStore({ defaults });
+
+function resolveCache() {
+  if (process.env.VERCEL) {
+    return {
+      store: new VercelCacheStore({
+        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        waitUntil,
+        defaults,
+      }),
+    };
+  }
+  return { store: memoryStore };
+}
+
+export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
+```
+
+The cache factory receives `(env, ctx)`; on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`.
+
+## Host routers (multi-app)
+
+A multi-app host router deploys as a **single function** running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model). Two requirements:
+
+1. The host module exports the `HostRouter` **instance** (default export, or a named `hostRouter`/`router` export) — not a Cloudflare-style `{ fetch }` object, because rango owns the entry and calls `match()` for you.
+2. Point at the host entry (a host app has several `createRouter()` sub-apps, so auto-discovery can't pick one). rango auto-detects a lone `createHostRouter()` file; set `hostRouter` to be explicit:
+
+```typescript
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+```typescript
+// src/worker.rsc.tsx
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+export default hostRouter; // the instance
+```
+
+`{ env, ctx }` is threaded unchanged from the function to each matched sub-app's handler and its `cache(env, ctx)` factory. See the `host-router` skill for sub-app structure and routing patterns.
+
+## Tracing (custom spans)
+
+Vercel exposes tracing through OpenTelemetry. `createVercelTracing()` (from `@rangojs/router/vercel`) emits the router's `rango.*` phase spans onto the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs:
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config so
+// importing this module is what runs registerOTel(). A Rango/Vite app does NOT
+// auto-load `instrumentation.ts` like Next.js does, so a standalone
+// registerOTel() that nothing imports is a silent no-op.
+import { registerOTel } from "@vercel/otel";
+import { createVercelTracing } from "@rangojs/router/vercel";
+registerOTel({ serviceName: "my-app" });
+export const tracing = createVercelTracing();
+
+// router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+import { tracing } from "./instrumentation.js";
+export const router = createRouter({ tracing }).routes(/* ... */);
+```
+
+`createVercelTracing(opts?)` takes `{ enabled, spans, tracerName, tracer }` — same phase set as `createCloudflareTracing` (`rango.request/middleware/action/loader/render/ssr`). Caveats: Node-runtime only (Vercel custom spans are unsupported on Edge); `registerOTel()` must run before the first request; `@vercel/otel` is what unlocks Vercel Session Tracing + Trace Drains. The deploy bundles `@vercel/otel` and its `@opentelemetry/*` peers into the function (no `node_modules` at runtime), so they must be installed. See `examples/vercel-basic` for a worked hybrid setup and the `observability` skill for the cross-platform tracing model.
+
+## Local validation without deploying
+
+`vite preview` serves the static client assets only. To preview the RSC **function**, serve the assembled `.vercel/output` behind filesystem-then-function routing — `examples/vercel-basic/scripts/preview.mjs` does this (and `pnpm preview:vercel` runs it). For a faithful deploy test (isolated filesystem, ESM, self-contained bundle), `examples/vercel-basic/scripts/smoke.mjs` serves it from a temp dir outside the repo. Both share `scripts/serve-vercel-output.mjs`.

package/src/__augment-tests__/augmented.check.ts

@@ -9,7 +9,6 @@ import "./augment.js";
 import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import { href } from "../href-client.js";
-import type { ResponseEnvelope } from "../urls.js";
 import type { Money, TestBindings } from "./augment.js";
 
 type Expect<T extends true> = T;
@@ -79,13 +78,13 @@ wrappedHref("/not-a-route");
 type _orderWireByPattern = Expect<
   Equal<
     Rango.PathResponse<"/orders/:id">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;
 type _orderWireByPath = Expect<
   Equal<
     Rango.PathResponse<"/orders/42">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;