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

package/src/testing/run-middleware.ts

@@ -0,0 +1,231 @@
+/**
+ * runMiddleware — unit-test one or more middleware functions in isolation.
+ *
+ * Executes the middleware chain via the SAME executeLoaderMiddleware the router
+ * uses, so ordering, `next()`, short-circuit (return OR throw Response),
+ * double-next guards, and header/cookie merging behave identically to
+ * production. The chain runs inside runWithRequestContext, so cookie/header
+ * mutations and getRequestContext() resolve.
+ *
+ * The returned `ctx` is the underlying RequestContext (not the per-middleware
+ * MiddlewareContext), exposing `ctx.cookies()`, `ctx.get()`, and
+ * `ctx.res.headers` for assertions on what the chain produced.
+ *
+ * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
+ * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ */
+
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { executeLoaderMiddleware } from "../router/middleware.js";
+import { createReverseFunction } from "../router/handler-context.js";
+import type { MiddlewareFn } from "../router/middleware-types.js";
+import {
+  createTestRequestContext,
+  headersToObject,
+  snapshotRunEffects,
+  type CreateTestContextOptions,
+  type VarsInit,
+  type StateCookieSeed,
+} from "./internal/context.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+
+/**
+ * Options for runMiddleware.
+ */
+export interface RunMiddlewareOptions<TEnv = any> {
+  /**
+   * The request the chain runs under: a `Request`, or a URL string (absolute or
+   * path). Optional for parity with `runLoader`/`runInRequestContext` — when
+   * omitted it defaults to `http://localhost/`. Pass it for path-, header-, or
+   * cookie-driven middleware.
+   */
+  request?: Request | string;
+  /** Environment bindings surfaced as `ctx.env`. */
+  env?: TEnv;
+  /** Route params surfaced as `ctx.params`. */
+  params?: Record<string, string>;
+  /** Variables a prior middleware would have set (object or [key, value] list). */
+  vars?: VarsInit;
+  /** Route name -> pattern map enabling `ctx.reverse()`. */
+  routeMap?: Record<string, string>;
+  /**
+   * Matched route name surfaced as `ctx.routeName`. Does NOT scope `.name`
+   * reverse: the chain receives a map-only `reverse` (built from `routeMap`
+   * alone), matching production app/response middleware — see the reverse
+   * construction below.
+   */
+  routeName?: string;
+  /** Router basename surfaced on the context (drives redirect() prefixing). */
+  basename?: string;
+  /** Theme config in the `createRouter({ theme })` shape (enables ctx.theme). */
+  theme?: ThemeConfig | true;
+  /**
+   * Terminal handler invoked when the chain calls `next()` all the way through.
+   * Defaults to a 200 empty Response. Use this to model the downstream
+   * route/handler response.
+   */
+  next?: () => Promise<Response>;
+  /**
+   * Cache store backing any `use cache` function a middleware invokes. Without
+   * it, registerCachedFunction bypasses (it checks for a store first), so the
+   * cached function runs uncached and its taint/profile guards never fire.
+   */
+  cacheStore?: SegmentCacheStore;
+  /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
+  cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Customize the rango state cookie a middleware that calls
+   * `invalidateClientCache()` rotates (the name is always seeded — default
+   * `rango-state_router_0` — so it rotates like production). Assert via the
+   * `Set-Cookie` on `result.response` / `result.cookies`.
+   */
+  stateCookie?: StateCookieSeed;
+}
+
+/**
+ * Result of runMiddleware.
+ */
+export interface RunMiddlewareResult<TEnv = any> {
+  /** The final Response (downstream response, or a middleware short-circuit). */
+  response: Response;
+  /**
+   * The underlying RequestContext. Read `ctx.cookies()`, `ctx.get(...)`, and
+   * `ctx.res.headers` to assert on the chain's effects. (This is always the
+   * RequestContext the chain ran under — not a per-middleware MiddlewareContext —
+   * so `ctx.cookies()` and the other RequestContext accessors are available.)
+   */
+  ctx: RequestContext<TEnv>;
+  /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
+  nextCalled: number;
+  /**
+   * The effective cookie view after the chain ran: request cookies merged with
+   * anything the chain set or deleted (last-write-wins), as `{ name: value }`.
+   * The public way to assert a cookie a middleware set, without casting through
+   * the `@internal` `ctx.cookies()`. Set-Cookie headers are also on `response`.
+   */
+  cookies: Record<string, string>;
+  /**
+   * The final response's headers as a plain `{ name: value }` object (the same
+   * view as `response.headers`), EXCLUDING `set-cookie` (use `cookies`). The
+   * public way to assert a header a middleware set (e.g. a security header)
+   * without reading `ctx.res.headers`. Header names are lowercased.
+   */
+  headers: Record<string, string>;
+  /**
+   * Location state the chain set via `ctx.setLocationState()` / `redirect({ state })`,
+   * resolved to the flat `{ key: value }` shape the client reads off
+   * `history.state` (empty object when none) — parity with `runInRequestContext`
+   * and `renderHandler`.
+   */
+  locationState: Record<string, unknown>;
+  /**
+   * The resolved rango state cookie name seeded for the run (default
+   * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert a
+   * middleware's `invalidateClientCache()` rotation against it without
+   * recomputing — parity with `runInRequestContext` / `runLoaderResult` /
+   * `renderHandler`.
+   */
+  stateCookieName: string;
+}
+
+/**
+ * Run a middleware chain and return the response plus observable context.
+ *
+ * @example
+ * ```ts
+ * const { response, ctx, nextCalled } = await runMiddleware(
+ *   async (ctx, next) => {
+ *     if (!ctx.get("user")) return new Response(null, { status: 401 });
+ *     return next();
+ *   },
+ *   { request: "/dashboard", vars: [["user", { id: 1 }]] },
+ * );
+ * // nextCalled === 1, response.status === 200
+ * ```
+ */
+export async function runMiddleware<TEnv = any>(
+  mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[],
+  opts: RunMiddlewareOptions<TEnv>,
+): Promise<RunMiddlewareResult<TEnv>> {
+  const mwArray = Array.isArray(mw) ? mw : [mw];
+
+  const ctxOpts: CreateTestContextOptions<TEnv> = {
+    env: opts.env,
+    request: opts.request,
+    vars: opts.vars,
+    routeMap: opts.routeMap,
+    routeName: opts.routeName,
+    params: opts.params,
+    basename: opts.basename,
+    theme: opts.theme,
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
+    stateCookie: opts.stateCookie,
+  };
+
+  const {
+    ctx,
+    request: builtRequest,
+    variables,
+    stateCookieName,
+  } = createTestRequestContext<TEnv>(ctxOpts);
+
+  let nextCalled = 0;
+  const finalHandler = async (): Promise<Response> => {
+    nextCalled++;
+    return opts.next?.() ?? new Response(null, { status: 200 });
+  };
+
+  // Match production: app/response middleware receive ctx.reverse built from the
+  // route map ALONE (no matched route name or current params), so reversing a
+  // parameterized route without explicit params does NOT auto-fill from the
+  // current request. Passing routeName/params here would recreate the
+  // false-confidence class fixed in dispatch.
+  const reverse = opts.routeMap
+    ? (createReverseFunction(opts.routeMap) as (
+        name: string,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ) => string)
+    : undefined;
+
+  // Keep the RETURNED ctx.reverse consistent with the map-only reverse the
+  // chain receives. createTestRequestContext installs an auto-fill reverse
+  // (correct for the loader phase) when routeName/params are passed, but
+  // production app/response middleware see a map-only reverse. Without this,
+  // a middleware reading getRequestContext().reverse — or a consumer asserting
+  // on result.ctx.reverse — would observe auto-fill that production never does.
+  if (reverse) {
+    (ctx as RequestContext<TEnv>).reverse =
+      reverse as RequestContext<TEnv>["reverse"];
+  }
+
+  const response = await runWithRequestContext(ctx, () =>
+    executeLoaderMiddleware<TEnv>(
+      mwArray,
+      builtRequest,
+      (opts.env ?? {}) as TEnv,
+      opts.params ?? {},
+      variables,
+      finalHandler,
+      reverse,
+    ),
+  );
+
+  const { cookies, locationState } = snapshotRunEffects(ctx);
+  const headers = headersToObject(response.headers);
+  return {
+    response,
+    ctx,
+    nextCalled,
+    cookies,
+    headers,
+    locationState,
+    stateCookieName,
+  };
+}

package/src/testing/vitest-stubs/cloudflare-email.ts

@@ -0,0 +1,9 @@
+// Stub for the `cloudflare:email` runtime virtual, shipped for Cloudflare
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`).
+export class EmailMessage {
+  constructor(
+    public from: string,
+    public to: string,
+    public raw: unknown,
+  ) {}
+}

package/src/testing/vitest-stubs/cloudflare-workers.ts

@@ -0,0 +1,21 @@
+// Stub for the `cloudflare:workers` runtime virtual, shipped for Cloudflare
+// consumers (enable via `rangoTestAliases({ preset: "cloudflare" })`). A CF app's
+// route tree commonly imports `cloudflare:workers` (e.g. `import { env } from
+// "cloudflare:workers"`), which does not resolve in a bare Vitest process.
+export const env: Record<string, unknown> = {};
+
+export class DurableObject<Env = unknown> {
+  constructor(
+    public ctx: unknown,
+    public env: Env,
+  ) {}
+}
+
+export class WorkerEntrypoint<Env = unknown> {
+  constructor(
+    public ctx: unknown,
+    public env: Env,
+  ) {}
+}
+
+export class RpcTarget {}

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -0,0 +1,16 @@
+// Stub for `@vitejs/plugin-rsc/rsc`, shipped so consumers do not have to write a
+// per-file `vi.mock(...)`. Importing a router internal transitively pulls this
+// module, whose real top-level body imports Vite virtuals that do not resolve in
+// plain node. The unit/integration primitives (dispatch/runLoader/runMiddleware)
+// never render RSC, so empty fns suffice.
+export const createFromReadableStream = (): never => {
+  throw new Error("plugin-rsc stub: createFromReadableStream not available");
+};
+export const renderToReadableStream = (): never => {
+  throw new Error("plugin-rsc stub: renderToReadableStream not available");
+};
+export const loadServerAction = (): undefined => undefined;
+export const decodeReply = (): undefined => undefined;
+export const decodeAction = (): undefined => undefined;
+export const decodeFormState = (): undefined => undefined;
+export const createTemporaryReferenceSet = (): Record<string, never> => ({});

package/src/testing/vitest-stubs/version.ts

@@ -0,0 +1,5 @@
+// Stub for the build-only `@rangojs/router:version` virtual module, shipped so
+// consumers do not have to author it. The rango Vite plugin injects this at
+// build time; in a bare Vitest process it must be aliased to a stub. Empty
+// string keeps generated URLs free of a version path segment.
+export const VERSION = "";

package/src/testing/vitest.ts

@@ -0,0 +1,305 @@
+/**
+ * @rangojs/router/testing/vitest
+ *
+ * Vitest setup helper for the UNIT + INTEGRATION + DOM test project of a
+ * @rangojs/router consumer app. It returns the `resolve.alias` entries that make
+ * a real app's router / loaders / middleware importable in a bare Vitest process.
+ *
+ * Why this is needed (the documented "vi.mock(plugin-rsc) + import router"
+ * recipe is not sufficient for a real app):
+ *
+ * - `@rangojs/router` resolves to SERVER-ONLY STUBS outside the `react-server`
+ *   condition — `urls()`, `createRouter()`, `cookies()`, `getRequestContext()`
+ *   throw "only available in a react-server environment". Importing the app's own
+ *   router/loaders/middleware then fails immediately. Vitest does NOT apply the
+ *   `react-server` condition to bare-package exports resolution, and enabling it
+ *   globally flips React to its server build (no `createContext`), crashing the
+ *   router's client-boundary imports. The surgical fix is to alias ONLY the bare
+ *   `@rangojs/router` specifier to its react-server entry (real impls) while
+ *   leaving React as the client build — which is exactly what this helper does.
+ * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
+ *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ * - Cloudflare apps additionally import the `cloudflare:workers` /
+ *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
+ *
+ * Usage (recommended one-call form — see {@link rangoTestConfig}):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * 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",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ *
+ * `rangoTestConfig` bundles the resolve aliases ({@link rangoTestAliases}) with
+ * the `server.deps.inline` contract ({@link rangoInlineDeps}) an installed
+ * consumer needs — @rangojs/router ships as TS source, and without `deps.inline`
+ * Vitest hands those `.ts` files to Node, which on Node >= 23 throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. Use the lower-level
+ * `rangoTestAliases` directly only if you wire `deps.inline` yourself.
+ *
+ * Notes:
+ * - The Flight project (real RSC rendering via `@rangojs/router/testing/flight`)
+ *   uses the `react-server` condition AND needs this same alias whenever a
+ *   rendered handler/component imports a server API (`getRequestContext`,
+ *   `cookies`) from the bare `@rangojs/router` — without it that import resolves
+ *   to the throwing out-of-react-server stub (`resolve.conditions` alone is not
+ *   reliably applied to bare-package export resolution). The alias points at
+ *   `index.rsc.ts` (the real react-server build) and leaves React itself
+ *   untouched, so it does NOT crash the server React build. The router's OWN
+ *   Flight tests omit it only because they import via RELATIVE paths, not the
+ *   bare specifier; a consumer importing the bare specifier must include it. See
+ *   the testing skill (`skills/testing/setup.md`, shipped in the package) for
+ *   the complete Flight config.
+ * - `renderRoute` (`@rangojs/router/testing/dom`) tests run in this same project
+ *   under a DOM environment (`happy-dom`/`jsdom`); the alias does not affect them.
+ * - A router using `Prerender()` / `createLoader()` / `Static()` now CONSTRUCTS in
+ *   a bare test: each assigns a process-stable runtime fallback `$$id` ONLY under
+ *   a test runner (`process.env.VITEST`), so `createRouter().routes(...)` builds
+ *   without the "missing `$$id`" throw (for `dispatch` / `assertGeneratedRoutesMatch`).
+ *   Outside a test runner (a real build) a missing id still THROWS — so an
+ *   unsupported handler shape the plugin skipped (e.g. `export let`) fails loud
+ *   rather than getting a silent synthetic id. (The plugin always injects for
+ *   supported `export const` shapes, and the static manifest keys on that id.)
+ * - Importing your app's whole router *file* can still fail for app-specific
+ *   reasons (page modules pulling their own deps, or plugin `virtual:` modules
+ *   that need the rango plugin) — build whole-router `dispatch`/drift checks from
+ *   a focused include, or use e2e.
+ */
+
+import { fileURLToPath } from "node:url";
+
+/** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
+export interface TestAlias {
+  find: string | RegExp;
+  replacement: string;
+}
+
+/** Options for {@link rangoTestAliases}. */
+export interface RangoTestAliasOptions {
+  /**
+   * Deployment preset, matching `rango({ preset })` in the Vite plugin. With
+   * `"cloudflare"` the helper additionally stubs the Cloudflare Workers runtime
+   * virtuals (`cloudflare:workers` / `cloudflare:email`) a CF app's route tree
+   * imports. A string (not a boolean) so more presets can be added without an
+   * API change. Default: `"node"`.
+   */
+  preset?: "node" | "cloudflare";
+}
+
+/**
+ * Resolve a path relative to this module. Anchored at the PACKAGE ROOT
+ * (`../../` from both `src/testing/vitest.ts` and the shipped
+ * `dist/testing/vitest.js` — each is two levels below the root), so the alias
+ * targets always point at the `src/*.ts` files Vite transpiles at test time,
+ * regardless of whether this helper is loaded as source (in-repo) or as the
+ * compiled `dist` entry (an installed consumer).
+ */
+function here(relativeFromRoot: string): string {
+  return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
+}
+
+/**
+ * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
+ * import a real @rangojs/router app's router/loaders/middleware. Spread into a
+ * Vitest config: `resolve: { alias: rangoTestAliases(...) }` (concat your own
+ * aliases as needed).
+ */
+export function rangoTestAliases(
+  opts: RangoTestAliasOptions = {},
+): TestAlias[] {
+  const aliases: TestAlias[] = [
+    // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
+    // subpaths (/testing, /client, /cache, ...) are untouched. React stays the
+    // client build, so createContext and "use client" modules work.
+    { find: /^@rangojs\/router$/, replacement: here("src/index.rsc.ts") },
+    {
+      find: "@rangojs/router:version",
+      replacement: here("src/testing/vitest-stubs/version.ts"),
+    },
+    {
+      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
+    },
+  ];
+
+  if (opts.preset === "cloudflare") {
+    aliases.push(
+      {
+        find: "cloudflare:workers",
+        replacement: here("src/testing/vitest-stubs/cloudflare-workers.ts"),
+      },
+      {
+        find: "cloudflare:email",
+        replacement: here("src/testing/vitest-stubs/cloudflare-email.ts"),
+      },
+    );
+  }
+
+  return aliases;
+}
+
+/**
+ * Vitest `server.deps.inline` patterns that force Vite (not Node) to transpile
+ * @rangojs/router's TypeScript source under test.
+ *
+ * REQUIRED for an installed (node_modules) consumer: @rangojs/router ships as TS
+ * source, and Vitest externalizes node_modules by default — so without this Node
+ * loads the `.ts` files directly and, on Node >= 23, throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. In this monorepo it is a no-op
+ * (the workspace symlink resolves to a realpath outside node_modules, which Vite
+ * already transpiles), which is precisely why an in-repo dogfood never surfaces
+ * the need and the contract has to be shipped explicitly.
+ */
+export const rangoInlineDeps: RegExp[] = [/@rangojs[/\\]router/];
+
+/** The Vitest `test`-block fragment {@link rangoTestConfig} returns. */
+export interface RangoTestConfig {
+  alias: TestAlias[];
+  server: { deps: { inline: RegExp[] } };
+}
+
+/**
+ * The complete Vitest `test`-block fragment a consumer needs: the resolve
+ * aliases ({@link rangoTestAliases}) AND the `server.deps.inline` contract
+ * ({@link rangoInlineDeps}). Spread it into your `test` block so both land in
+ * one place and a consumer cannot forget the `deps.inline` half (omitting it
+ * loads rango's TS source through Node and breaks on Node >= 23):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * 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",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ */
+export function rangoTestConfig(
+  opts: RangoTestAliasOptions = {},
+): RangoTestConfig {
+  return {
+    alias: rangoTestAliases(opts),
+    // fresh copy so the shared rangoInlineDeps const is never aliased into (or
+    // mutated through) a consumer's resolved config
+    server: { deps: { inline: [...rangoInlineDeps] } },
+  };
+}
+
+/** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
+interface FlightTransformPlugin {
+  name: string;
+  transform(
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin for the FLIGHT (react-server) Vitest project that applies the
+ * `"use client"` transform to a consumer's client modules — the same transform a
+ * real build applies. With it, `renderServerTree` (`@rangojs/router/testing/flight`)
+ * resolves client islands AUTOMATICALLY from the server tree's own imports: no
+ * `clientComponents` to pass, no filename convention. Without it, a `"use client"`
+ * module is imported as a plain (unmarked) function and would render server-side,
+ * so you must list islands via `renderServerTree(..., { clientComponents })`.
+ *
+ * Add it to your react-server Vitest project. This is the COMPLETE config — the
+ * alias, `server.deps.inline`, and `NODE_ENV` are load-bearing, not optional (see
+ * the inline notes). The testing skill (`skills/testing/setup.md`, shipped in the
+ * package) has the annotated walkthrough.
+ *
+ * ```ts
+ * // vitest.rsc.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import {
+ *   rangoUseClientTransform,
+ *   rangoTestAliases,
+ *   rangoInlineDeps,
+ * } from "@rangojs/router/testing/vitest";
+ *
+ * // Flight serialization needs React's production build; the dev build's jsxDEV
+ * // crashes / yields unstable snapshots.
+ * process.env.NODE_ENV = "production";
+ *
+ * export default defineConfig({
+ *   plugins: [rangoUseClientTransform()],
+ *   resolve: {
+ *     conditions: ["react-server"],
+ *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
+ *     // reading getRequestContext()/cookies() resolves the real impl, not the
+ *     // throwing stub. Pass { preset: "cloudflare" } for a CF app.
+ *     alias: rangoTestAliases(),
+ *   },
+ *   test: {
+ *     include: ["test/**\/*.rsc-test.{ts,tsx}"],
+ *     pool: "forks",
+ *     execArgv: ["--conditions=react-server"],
+ *     // Required for an INSTALLED consumer on Node >= 23 (rango ships TS source).
+ *     server: { deps: { inline: rangoInlineDeps } },
+ *   },
+ * });
+ * ```
+ *
+ * Each `"use client"` module's exports are replaced with client references keyed
+ * by the module's absolute path (the boundary id), the export name becoming the
+ * boundary name. Modules without the directive (server components) are untouched,
+ * so `renderToFlightString` of pure leaf trees is unaffected.
+ */
+export function rangoUseClientTransform(): FlightTransformPlugin {
+  return {
+    name: "rango:testing-use-client",
+    async transform(code, id) {
+      if (id.includes("/node_modules/")) return undefined;
+      // Fast path: only parse modules that mention the directive.
+      if (!code.includes("use client")) return undefined;
+      const { parseAstAsync } = await import("vite");
+      const { hasDirective, transformDirectiveProxyExport } =
+        await import("@vitejs/plugin-rsc/transforms");
+      // vite's parser and the transforms ship structurally-compatible but
+      // distinctly-typed ASTs (oxc vs estree); cast through the transform's own
+      // parameter type, exactly as plugin-rsc does at runtime.
+      type TransformAst = Parameters<typeof transformDirectiveProxyExport>[0];
+      let ast: TransformAst;
+      try {
+        ast = (await parseAstAsync(code)) as unknown as TransformAst;
+      } catch {
+        return undefined;
+      }
+      if (!hasDirective(ast.body, "use client")) return undefined;
+      const result = transformDirectiveProxyExport(ast, {
+        directive: "use client",
+        code,
+        runtime: (name: string) =>
+          `$$RangoRSD.registerClientReference(` +
+          `() => { throw new Error("client reference " + ${JSON.stringify(name)} + " is not callable on the server"); }, ` +
+          `${JSON.stringify(id)}, ${JSON.stringify(name)})`,
+      });
+      if (!result) return undefined;
+      const { output } = result;
+      // The vendored server serializer is the one renderToFlightString uses;
+      // resolvable here under the react-server condition.
+      output.prepend(
+        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";\n`,
+      );
+      return {
+        code: output.toString(),
+        map: output.generateMap({ hires: true }),
+      };
+    },
+  };
+}

package/src/types/cache-types.ts

@@ -78,6 +78,14 @@ export interface CacheOptions<TEnv = unknown> {
    * - Loader-specific caching strategies
    * - Hot data in fast cache, cold data in larger/slower cache
    *
+   * Tag invalidation caveat: a per-boundary store becomes reachable by
+   * `updateTag()` / `revalidateTag()` once this boundary is resolved in the
+   * current process. If the store is *durable* (shared across processes) and the
+   * very first request to a fresh worker is an `updateTag`/`revalidateTag` for a
+   * tag held only in this store - before this boundary is matched - that
+   * invalidation can miss it. For data you invalidate by tag, prefer the
+   * app-level store (always reachable), or ensure the boundary is warmed.
+   *
    * @example
    * ```typescript
    * const kvStore = new CloudflareKVStore(env.CACHE_KV);
@@ -145,10 +153,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * Note: Tags are passed through to the store but built-in stores
-   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
-   * invalidate by tag. Effective tag-based invalidation requires a
-   * custom store implementation with secondary indices.
+   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
+   * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
+   * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed
+   * invalidation requires a `kv` namespace (markers live in that same namespace).
    *
    * @example
    * ```typescript

package/src/types/error-types.ts

@@ -155,7 +155,11 @@ export interface OnErrorContext<TEnv = any> {
   stack?: string;
 
   /**
-   * Additional metadata specific to the error phase
+   * Additional metadata specific to the error phase. For the `cache` phase,
+   * `metadata.category` is a `CacheErrorCategory` (exported from
+   * `@rangojs/router/cache`) identifying the failure kind, e.g. `cache-read`
+   * (transient outage, degraded to a miss) vs `cache-corrupt` (faulty entry
+   * self-healed) vs `cache-invalidate` (a failed background revalidateTag).
    */
   metadata?: Record<string, unknown>;
 }

package/src/types/global-namespace.ts

@@ -97,7 +97,17 @@ export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never
 export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
 
 /**
- * Default variables type - uses global augmentation if available, Record<string, any> otherwise
+ * Variables type backing the string-key `ctx.get` / `ctx.set` overloads.
+ *
+ * Uses `Rango.Vars` augmentation when present; otherwise falls back to
+ * `Record<string, any>` so an un-augmented app can use string-key vars with
+ * zero config -- at the cost of a typo'd key being silently `any`.
+ *
+ * This `any` fallback is deliberate (see #561) and is an intentional asymmetry
+ * with `DefaultEnv` above, which falls back to `unknown`: env bindings are
+ * platform-critical and should be registered, so a forgotten binding is made a
+ * compile error; vars are ad-hoc and middleware-set, so the zero-config path
+ * wins. Augment `Rango.Vars` for type-safe keys.
  */
 export type DefaultVars = keyof Rango.Vars extends never
   ? Record<string, any>