@rangojs/router 0.0.0-experimental.7a20d911 → 0.0.0-experimental.7cf4e116

package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.7a20d911",
+  "version": "0.0.0-experimental.7cf4e116",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -110,6 +110,11 @@
       "react-server": "./src/cache/cache-runtime.ts",
       "default": "./src/cache/cache-runtime.ts"
     },
+    "./cloudflare": {
+      "types": "./src/cloudflare/index.ts",
+      "react-server": "./src/cloudflare/index.ts",
+      "default": "./src/cloudflare/index.ts"
+    },
     "./theme": {
       "types": "./src/theme/index.ts",
       "default": "./src/theme/index.ts"
@@ -126,6 +131,31 @@
     "./host/testing": {
       "types": "./src/host/testing.ts",
       "default": "./src/host/testing.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    },
+    "./testing/vitest": {
+      "types": "./src/testing/vitest.ts",
+      "default": "./dist/testing/vitest.js"
+    },
+    "./testing/dom": {
+      "types": "./src/testing/dom.entry.ts",
+      "default": "./src/testing/dom.entry.ts"
+    },
+    "./testing/e2e": {
+      "types": "./src/testing/e2e/index.ts",
+      "default": "./src/testing/e2e/index.ts"
+    },
+    "./testing/flight": {
+      "types": "./src/testing/flight.entry.ts",
+      "react-server": "./src/testing/flight.entry.ts",
+      "default": "./src/testing/flight.entry.ts"
+    },
+    "./testing/flight-matchers": {
+      "types": "./src/testing/flight-matchers.ts",
+      "default": "./src/testing/flight-matchers.ts"
     }
   },
   "publishConfig": {
@@ -133,45 +163,69 @@
     "tag": "experimental"
   },
   "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
     "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",
     "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
     "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   },
   "dependencies": {
-    "@vitejs/plugin-rsc": "^0.5.19",
+    "@types/debug": "^4.1.12",
+    "@vitejs/plugin-rsc": "^0.5.26",
+    "debug": "^4.4.1",
     "magic-string": "^0.30.17",
-    "picomatch": "^4.0.3",
-    "rsc-html-stream": "^0.0.7"
+    "picomatch": "^4.0.4",
+    "rsc-html-stream": "^0.0.7",
+    "tinyexec": "^0.3.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
+    "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
-    "@cloudflare/vite-plugin": "^1.25.0",
-    "@vitejs/plugin-rsc": "^0.5.14",
-    "react": "^18.0.0 || ^19.0.0",
-    "vite": "^7.3.0"
+    "@cloudflare/vite-plugin": "^1.38.0",
+    "@playwright/test": "^1.49.1",
+    "@testing-library/react": ">=16",
+    "@vitejs/plugin-rsc": "^0.5.26",
+    "react": ">=19.2.6 <20",
+    "react-dom": ">=19.2.6 <20",
+    "vite": "^8.0.0",
+    "vitest": ">=3"
   },
   "peerDependenciesMeta": {
     "@cloudflare/vite-plugin": {
       "optional": true
     },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
   }
 }

package/skills/api-client/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: api-client
+description: Build a typed client for consuming your own response-route JSON APIs (no codegen)
+---
+
+# Typed API Client
+
+Response routes (`path.json()`) already ship typed responses — `RouteResponse<typeof patterns, "name">` resolves to the **bare payload**, inferred from your handler with no codegen. This skill wraps that inference in a small **typed client** so first-party TypeScript code calls your endpoints like functions instead of hand-writing `fetch` + URL building per call site.
+
+This is a **recipe, not a framework feature** — copy the helper below into your app. It depends only on **type-only** imports from `@rangojs/router` (`RouteResponse`, `ExtractParams`, `ProblemDetails`), which are erased at build time, so it runs anywhere a `fetch` does — **browser, worker, or server**. Nothing new to install or version.
+
+> **Scope:** the typed client is a **first-party TypeScript** convenience. External/third-party consumers use the plain wire directly — bare JSON on success, RFC 9457 `application/problem+json` on error — which needs no client. (Language-agnostic OpenAPI generation is a separate, future feature.)
+
+## What you get
+
+```ts
+const api = createApiClient(apiShopPatterns, routes, { baseUrl });
+
+await api.health.get(); // no params → callable bare
+await api.product.get({ params: { productId } }); // params typed + required
+await api.cart.post({ body: { productId, qty: 2 } }); // body sent as JSON
+//    ^ result is the bare payload type (RouteResponse), not `any`, no `.data`
+```
+
+- **Output typed** from the handler's return (`RouteResponse`), zero codegen.
+- **Params required + typed** from the route pattern (`/catalog/:productId` → `{ productId: string }`); a missing or misspelled param is a **compile error**, not a runtime 404.
+- **Autocomplete** over every route name; rename-safe.
+- **Errors throw a typed `ApiError`** carrying the `ProblemDetails` body.
+
+(`search` and `body` are _not_ route-typed — see Notes.)
+
+## The two inputs
+
+1. **The `urls()` patterns value** — the type source. `typeof apiShopPatterns` carries the per-route response payloads (`_responses`) and patterns (`_routes`).
+2. **The generated route map** — the name → pattern source. `rango generate` emits a per-module `<name>.gen.ts` exporting `routes`:
+
+```ts
+// api-shop.gen.ts (generated — do not edit)
+export const routes = {
+  catalog: "/catalog",
+  product: "/catalog/:productId",
+  cart: "/cart",
+  // ...
+} as const;
+```
+
+Routes that declare a **search schema** are generated as objects instead — `index: { path: "/", search: { q: "string" } }`. The helper accepts both the string and `{ path }` forms. If a `urls()` block is mounted under a name prefix, build a local-keyed map from your global `NamedRoutes` so the keys match the block's route names (e.g. `{ catalog: NamedRoutes["apiShop.catalog"], ... } as const`).
+
+## The helper (copy into your app)
+
+```ts
+// lib/api-client.ts
+import type {
+  RouteResponse,
+  ExtractParams,
+  ProblemDetails,
+} from "@rangojs/router";
+
+type SearchParams = Record<string, string | number | boolean>;
+
+// A generated route-map entry is a pattern string, or an object with `path`
+// (routes that declare a search schema generate the object form).
+type RouteMapEntry = string | { readonly path: string };
+type PatternOf<E> = E extends string
+  ? E
+  : E extends { readonly path: infer P extends string }
+    ? P
+    : never;
+
+// `params` is optional when the route has no *required* params (incl.
+// optional-only routes like `/:locale?`), required otherwise. Typed as
+// `ExtractParams` (not `undefined`) so optional params can still be passed.
+type Args<TPattern extends string> =
+  {} extends ExtractParams<TPattern>
+    ? {
+        params?: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      }
+    : {
+        params: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      };
+
+type Method<TPatterns, K extends string, TEntry> =
+  {} extends ExtractParams<PatternOf<TEntry>>
+    ? (args?: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>
+    : (args: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>;
+
+type ApiClient<TPatterns, TRouteMap extends Record<string, RouteMapEntry>> = {
+  [K in keyof TRouteMap & string]: {
+    get: Method<TPatterns, K, TRouteMap[K]>;
+    post: Method<TPatterns, K, TRouteMap[K]>;
+    put: Method<TPatterns, K, TRouteMap[K]>;
+    patch: Method<TPatterns, K, TRouteMap[K]>;
+    delete: Method<TPatterns, K, TRouteMap[K]>;
+  };
+};
+
+/** Thrown on a non-2xx response; carries the RFC 9457 problem body. */
+export class ApiError extends Error {
+  status: number;
+  problem: ProblemDetails;
+  constructor(status: number, problem: ProblemDetails) {
+    super(problem.detail || `HTTP ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.problem = problem;
+  }
+}
+
+// Client-safe path builder: substitutes :params (incl. optional/constrained
+// forms) into the pattern. No dependency on the server-only createReverse.
+function fillPath(pattern: string, params?: Record<string, string>): string {
+  return pattern
+    .replace(/:([A-Za-z0-9_]+)(?:\([^)]*\))?\??/g, (_m, name: string) => {
+      const v = params?.[name];
+      return v == null ? "" : encodeURIComponent(String(v));
+    })
+    .replace(/\/{2,}/g, "/");
+}
+
+export function createApiClient<
+  TPatterns,
+  const TRouteMap extends Record<string, RouteMapEntry>,
+>(
+  _patterns: TPatterns,
+  routeMap: TRouteMap,
+  opts: { baseUrl?: string; fetch?: typeof fetch } = {},
+): ApiClient<TPatterns, TRouteMap> {
+  const doFetch = opts.fetch ?? fetch;
+  const baseUrl = opts.baseUrl ?? "";
+  const call =
+    (name: string, method: string) =>
+    async (args?: {
+      params?: Record<string, string>;
+      search?: SearchParams;
+      body?: unknown;
+    }) => {
+      const entry = routeMap[name];
+      const pattern = typeof entry === "string" ? entry : entry.path;
+      let url = baseUrl + fillPath(pattern, args?.params);
+      if (args?.search) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(args.search)) {
+          if (v != null) qs.append(k, String(v));
+        }
+        const s = qs.toString();
+        if (s) url += (url.includes("?") ? "&" : "?") + s;
+      }
+      const res = await doFetch(url, {
+        method,
+        ...(args?.body !== undefined
+          ? {
+              body: JSON.stringify(args.body),
+              headers: { "content-type": "application/json" },
+            }
+          : {}),
+      });
+      if (!res.ok) {
+        const problem = (await res.json().catch(() => ({}))) as ProblemDetails;
+        throw new ApiError(res.status, problem);
+      }
+      return res.json();
+    };
+  return new Proxy({} as any, {
+    get: (_t, name: string) => ({
+      get: call(name, "GET"),
+      post: call(name, "POST"),
+      put: call(name, "PUT"),
+      patch: call(name, "PATCH"),
+      delete: call(name, "DELETE"),
+    }),
+  }) as ApiClient<TPatterns, TRouteMap>;
+}
+```
+
+## Using it
+
+```ts
+import { apiShopPatterns } from "./urls/api-shop";
+import { routes } from "./urls/api-shop.gen";
+import { createApiClient, ApiError } from "./lib/api-client";
+
+const api = createApiClient(apiShopPatterns, routes, {
+  baseUrl: import.meta.env.VITE_API_URL ?? "",
+});
+
+try {
+  const product = await api.product.get({ params: { productId: "42" } });
+  // `product` is the handler's bare return type — e.g. `product.name` is typed.
+} catch (err) {
+  if (err instanceof ApiError && err.status === 404) {
+    console.warn(err.problem.code, err.problem.detail); // typed ProblemDetails
+  } else {
+    throw err;
+  }
+}
+```
+
+## Notes
+
+- **Client-safe by construction.** The helper imports only **types** from `@rangojs/router` (erased at build) and builds URLs itself by substituting `:params` into the pattern — it does **not** use `createReverse`, which is a server/RSC-only export that throws in the browser. So `createApiClient` works in client components, workers, and on the server alike.
+- **Params are route-typed; search and body are not.** Path params come from the route pattern (`ExtractParams`), so they are precise and required. `search` is generically typed (`Record<string, string | number | boolean>`), and `body` is `unknown` (serialized to JSON). Typed request **input** needs a declared schema layer, which is intentionally out of scope here — thread per-route schemas in yourself if you want typed search/body.
+- **Verb-agnostic wire.** Rango response routes do not dispatch on HTTP method — `.get`/`.post`/etc. set the request method but hit the same handler. Use whichever verb reads best for the operation.
+- **Path building.** `fillPath` handles standard `:param`, optional `:param?`, and constrained `:param(a|b)` forms. For exotic patterns or strict trailing-slash policies, swap in your own builder (or the router's `reverse` on the server).
+- **Want a return-based style instead of throwing?** Branch on `res.ok` yourself: the wire is the bare value on 2xx and `ProblemDetails` on non-2xx (see `/response-routes`). Wrapping the calls in a `{ ok, data } | { ok: false, error }` result type is a small variation on the same helper.
+- **Third parties.** The typed client is TypeScript-only and needs your route types. External consumers in any language use the plain wire as-is (bare JSON + problem+json); no client required.
+
+See `/response-routes` for the endpoint side and `/typesafety` for how `RouteResponse` / `PathResponse` inference works.

package/skills/breadcrumbs/SKILL.md

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

package/skills/bundle-analysis/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: bundle-analysis
+description: Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.
+argument-hint: "<app-dir>"
+---
+
+# Bundle Analysis
+
+Use this when you want **proof** that your Rango app is shipping the bundles you expect: small client, no server leaks, no doubled React, reasonable RSC worker size.
+
+## What this checks
+
+Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — and each ships its own bundle. The most common bundle bugs in a Rango app are:
+
+1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
+2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare vite plugin folds NODE_ENV automatically; vanilla `vite build` does it for client but not always for SSR/RSC.
+3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
+4. **Inefficient client-reference grouping.** Each `"use client"` boundary becomes a chunk. Too many small client components = many tiny chunks; one giant client component = one giant chunk that defeats code-splitting.
+
+Tree-shaking does _not_ catch (1) generated data inlined as string literals or (2) data-dependent conditionals like React's. You need a visualizer.
+
+## Step 1: Install the visualizer
+
+In your app's directory:
+
+```bash
+pnpm add -D rollup-plugin-visualizer
+# or: npm install --save-dev rollup-plugin-visualizer
+# or: yarn add -D rollup-plugin-visualizer
+```
+
+## Step 2: Wire it into your `vite.config.ts`
+
+Add a small helper that registers one visualizer instance **per Vite environment** (not just one global). The plugin caches its options after the first call, so a single instance can't handle multi-environment builds — you'll get a report for one environment and silence for the others.
+
+```ts
+// vite.config.ts
+import { defineConfig, type PluginOption, type Plugin } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+import { join } from "node:path";
+// ... your other imports ...
+
+function analyze(): PluginOption[] {
+  if (!process.env.RANGO_ANALYZE) return [];
+  return (["client", "ssr", "rsc"] as const).map((envName) => {
+    const inner = visualizer({
+      filename: join("bundle-stats", `${envName}.html`),
+      template: "treemap",
+      gzipSize: true,
+      brotliSize: true,
+    }) as Plugin;
+    return {
+      ...inner,
+      name: `analyze-${envName}`,
+      applyToEnvironment(env) {
+        return env.name === envName;
+      },
+    } as Plugin;
+  });
+}
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    // your existing plugins...
+    ...analyze(),
+  ],
+  // For non-Cloudflare apps, fold NODE_ENV explicitly so React's CJS files
+  // emit only the .production.js variants in SSR/RSC. Skip if your build
+  // setup already does this (the Cloudflare vite plugin does).
+  define:
+    command === "build"
+      ? { "process.env.NODE_ENV": JSON.stringify("production") }
+      : undefined,
+}));
+```
+
+Add `bundle-stats/` to your `.gitignore`.
+
+## Step 3: Build with the analyzer enabled
+
+```bash
+RANGO_ANALYZE=1 pnpm exec vite build
+```
+
+You'll get three HTML reports in `bundle-stats/`:
+
+- `bundle-stats/client.html` — what runs in the browser
+- `bundle-stats/ssr.html` — what runs during HTML stream
+- `bundle-stats/rsc.html` — what runs in your RSC server (Worker / Node)
+
+Open them with a quick local server (file:// has CORS issues with the embedded scripts):
+
+```bash
+pnpm dlx serve -l 5050 .
+# then visit http://localhost:5050/bundle-stats/client.html
+```
+
+## Step 4: Triage the reports
+
+### Open `client.html` first
+
+The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/brotli numbers.
+
+**Look for:**
+
+- **Your server code.** Any of your own files that contain database queries, secret keys, server actions implementation (not the action _reference_), or `node:` imports. If they appear in the client treemap with non-zero bytes, they leaked. Common causes:
+  - A shared module that mixes client and server code without a `"use client"` or `"use server"` directive.
+  - A barrel file (`index.ts`) that re-exports both client and server symbols. Tree-shaking should help, but `JSON.parse('{...}')` data and side-effecting top-level statements survive.
+  - Client component imports a server-only utility through an indirect path (e.g., shared types file that pulls server modules).
+- **Multiple copies of the same package.** Look for two boxes with the same package name but different version paths. Usually means a transitive dep pinned a different version.
+- **The `@rangojs/router` chunk** should be roughly **50 KB gzip** (74 files). If significantly larger, you might be importing client-incompatible APIs from the wrong subpath.
+- **Per-route client-reference chunks** (named like `chunk-<hash>.js`). Each `"use client"` boundary can become its own chunk. If you have hundreds of tiny chunks, you may have over-split (every leaf component as a client component); if you have one massive 200 KB chunk, you've under-split (a wide client tree behind one boundary).
+
+### Now check `ssr.html`
+
+**Look for:**
+
+- **`react-dom-server.edge.development-*.js`** (or any `*.development*.js` chunk). This is the dev/prod React doubling. Fix: add `define: { "process.env.NODE_ENV": '"production"' }` to your vite config (see Step 2).
+- **Your client components** appearing in SSR. They're _expected_ here — SSR hydration needs to produce HTML for them. The same components show up in `client.html` too because the browser hydrates them. This is not a leak.
+- **Total SSR size**: a reasonable Rango SSR is ~140 KB gzip plus your app code. If it's >300 KB, almost always (1) dev/prod React duplication or (2) a giant data structure being inlined.
+
+### Now check `rsc.html`
+
+**Look for:**
+
+- **`virtual:rsc-router/routes-manifest`** should be **tiny** (< 1 KB). If it's > 100 KB, you're on an old version of `@rangojs/router` that inlined the trie eagerly — upgrade to a release that includes commit `d10a2470`.
+- **`virtual:rsc-router/routes-manifest/<hash>`** is the lazy per-router chunk. Its size is proportional to your route count. For a typical app: 5–50 KB gzip. For a stress-test app with thousands of routes: hundreds of KB. If yours is unexpectedly huge, check whether you're generating routes you don't need.
+- **`<your-router>.named-routes.gen.ts`** — generated route map. Should match your route count.
+- **Your action and loader implementations** — these run server-side. Expected to be here, not in client.
+- **Worker-incompatible code** (Node-only imports like `node:fs` that Cloudflare doesn't support). The build will usually fail before the analyzer runs, but if you're seeing runtime errors at the edge, the RSC treemap shows what made it in.
+
+## Step 5: Fix what you find
+
+| Finding                                                  | Fix                                                                                                                                                                         |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your server code in `client.html` (non-zero bytes)       | Audit the import chain. Add `"use server"` to server-only files. Move shared data out of barrel files. Use the `@rangojs/router/server` subpath for explicitly server APIs. |
+| Your server code in `client.html` listed but 0 bytes     | Tree-shaking already eliminated it. Cosmetic. Leave it.                                                                                                                     |
+| `react-dom-server.edge.development-*.js` in SSR or RSC   | Add the `define` block from Step 2 to your vite config.                                                                                                                     |
+| Routes-manifest > 100 KB gzip in RSC eager chunk         | Update `@rangojs/router` to a release that includes the lazy-only manifest fix.                                                                                             |
+| Same package version present twice                       | Run `pnpm dedupe` (or `npm dedupe`). If the duplication persists, a transitive dep pins an incompatible version — open a PR upstream or pin the resolution.                 |
+| Client chunk > 500 KB gzip with a single dominant module | That module is your largest client component. Consider lazy-loading via dynamic `import()` or moving non-interactive parts to server components.                            |
+| Hundreds of tiny client chunks                           | You've sprinkled `"use client"` too liberally. Hoist directives to higher boundaries so React groups them.                                                                  |
+
+## When to re-run
+
+- Before every production deploy, especially after adding new dependencies.
+- After upgrading `@rangojs/router`, React, or `@vitejs/plugin-rsc`.
+- After adding routes that scale with data (e.g., one route per item from a content directory) — the manifest may have grown.
+- When CI starts reporting larger artifact sizes.
+
+## Reporting Rango regressions
+
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+
+- The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
+- The `@rangojs/router` version (`pnpm why @rangojs/router`).
+- Your `vite.config.ts`.
+
+The framework maintainers run a similar audit internally — the methodology in this skill mirrors what they use to validate every release.