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

package/dist/bin/rango.js

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/dist/vite/index.js

@@ -2224,7 +2224,14 @@ export const renderHTML = createSSRHandler({
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+var RSC_ENTRY_BOOTSTRAP_IMPORTS = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest"
+];
 function getVirtualEntryRSC(routerPath) {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`
+  ).join("\n");
   return `
 import {
   renderToReadableStream,
@@ -2238,15 +2245,9 @@ import { router } from "${routerPath}";
 import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
 import { VERSION } from "@rangojs/router:version";
 
-// Import loader manifest to ensure all fetchable loaders are registered at startup
-// This is critical for serverless/multi-process deployments where the loader module
-// might not be imported before a GET request arrives
-import "virtual:rsc-router/loader-manifest";
-
-// Import pre-generated route manifest so href() works immediately on cold start.
-// In build mode, this contains the full route map generated at build time.
-// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
-import "virtual:rsc-router/routes-manifest";
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS \u2014 the same list the custom-entry injector uses.
+${bootstrapImports}
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
@@ -2296,7 +2297,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.133",
+  version: "0.0.0-experimental.135",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2471,7 +2472,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -2486,22 +2487,22 @@ var package_default = {
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    esbuild: "^0.27.0",
+    esbuild: "^0.28.1",
     "happy-dom": "^20.10.1",
     jiti: "^2.6.1",
     react: "catalog:",
     "react-dom": "catalog:",
     typescript: "^5.3.0",
-    vitest: "^4.0.0"
+    vitest: "^4.1.9"
   },
   peerDependencies: {
-    "@cloudflare/vite-plugin": "^1.38.0",
+    "@cloudflare/vite-plugin": "^1.42.1",
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     react: ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    vite: "^8.0.0",
+    vite: "^8.0.16",
     vitest: ">=3"
   },
   peerDependenciesMeta: {
@@ -3927,9 +3928,9 @@ function createVersionInjectorPlugin(rscEntryPath) {
       if (normalizedId !== normalizedEntry) {
         return null;
       }
-      const prepend = [
-        `import "virtual:rsc-router/routes-manifest";`
-      ];
+      const prepend = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+        (id2) => `import "${id2}";`
+      );
       let newCode = code;
       const needsVersion = code.includes("createRSCHandler") && !code.includes("@rangojs/router:version") && /createRSCHandler\s*\(\s*\{/.test(code);
       if (needsVersion) {
@@ -4031,6 +4032,19 @@ import { readFileSync as readFileSync6 } from "node:fs";
 import { createRequire as createRequire2, register } from "node:module";
 import { pathToFileURL } from "node:url";
 
+// src/vite/inject-client-debug.ts
+function injectClientDebugFlag(id) {
+  if (!id.includes("internal-debug")) return null;
+  const norm = id.replace(/\\/g, "/");
+  const isInternalDebug = /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) && (norm.includes("/@rangojs/router/") || norm.includes("/packages/rangojs-router/"));
+  if (!isInternalDebug) return null;
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};
+`,
+    map: null
+  };
+}
+
 // src/vite/plugins/virtual-stub-plugin.ts
 function createVirtualStubPlugin() {
   const STUB_PREFIXES = [
@@ -4318,7 +4332,7 @@ function checkSelfGenWrite(state, filePath, consume) {
 import { AsyncLocalStorage } from "node:async_hooks";
 
 // src/internal-debug.ts
-var INTERNAL_RANGO_DEBUG = typeof __RANGO_DEBUG__ !== "undefined" ? __RANGO_DEBUG__ : typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
+var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
 
 // src/router/logging.ts
 var routerLogContext = new AsyncLocalStorage();
@@ -6102,13 +6116,13 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
   let viteMode = "production";
   return {
     name: "@rangojs/router:discovery",
-    config() {
-      const config = {
-        define: {
-          __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG)
-        }
-      };
-      return config;
+    // Make INTERNAL_RANGO_DEBUG reach the CLIENT debug logs by just setting the
+    // env var. See injectClientDebugFlag: bakes the resolved flag into the
+    // internal-debug module so FE debug no longer depends on Vite delivering the
+    // `__RANGO_DEBUG__` define to the client (which it does only as an injected
+    // global whose presence varies across consumer setups). Runs in dev and build.
+    transform(_code, id) {
+      return injectClientDebugFlag(id);
     },
     configResolved(config) {
       s.projectRoot = config.root;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.133",
+  "version": "0.0.0-experimental.135",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -162,20 +162,9 @@
     "access": "public",
     "tag": "experimental"
   },
-  "scripts": {
-    "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 && 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:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -184,28 +173,28 @@
   },
   "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",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
-    "@cloudflare/vite-plugin": "^1.38.0",
+    "@cloudflare/vite-plugin": "^1.42.1",
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     "react": ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    "vite": "^8.0.0",
+    "vite": "^8.0.16",
     "vitest": ">=3"
   },
   "peerDependenciesMeta": {
@@ -227,5 +216,15 @@
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "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",
+    "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:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/composability/SKILL.md

@@ -22,7 +22,6 @@ import {
   loading,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
 } from "@rangojs/router";

package/skills/handler-use/SKILL.md

@@ -51,13 +51,13 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 
 `handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
 
-| Mount site                                        | Allowed item types                                                                                                                             |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition` |
-| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                      |
-| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                           |
-| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
-| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+| Mount site                                        | Allowed item types                                                                                                                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                            |
+| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                                                                 |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                      |
+| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `transition` (conditional activation is config-only: `intercept(..., { when })`) |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                     |
 
 For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
 

package/skills/intercept/SKILL.md

@@ -142,18 +142,41 @@ layout(ProductLayout, () => [
 ]);
 ```
 
-## Conditional Intercept with when()
+## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context:
+Only intercept based on navigation context. `when` is the 4th argument
+(an `InterceptConfig` object); the other use-items go in the 5th-argument
+callback.
 
 ```typescript
 intercept(
   "@modal",
   "product",
   <ProductModal />,
+  // Only intercept when coming from a different section
+  { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+  () => [
+    loader(ProductLoader),
+  ]
+)
+```
+
+`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+Pass an array of predicates for AND logic (all must return true). Omit `when`
+entirely and the intercept always activates.
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  {
+    when: [
+      ({ from }) => from.pathname.startsWith("/shop"),
+      ({ params }) => params.slug !== "featured",
+    ],
+  },
   () => [
-    // Only intercept when coming from a different section
-    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
     loader(ProductLoader),
   ]
 )
@@ -242,10 +265,13 @@ layout(ShopLayout, () => [
   ]),
 
   // This intercept is also pre-rendered at build time
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname.startsWith("/shop") },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 
@@ -253,8 +279,8 @@ Build-time behavior:
 
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
-- `when()` conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when()` is still evaluated at runtime by the intercept-resolution middleware
+- `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
+- `when` is still evaluated at runtime by the intercept-resolution middleware
 
 Runtime behavior:
 
@@ -305,7 +331,6 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
-  when,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -317,8 +342,8 @@ export const shopPatterns = urls(({
       "@modal",
       "product",  // Route name (without prefix)
       <ProductModalContent />,
+      { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
-        when(({ from }) => !from.pathname.startsWith("/shop/product/")),
         layout(<ModalWrapper />),
         loading(<ProductModalSkeleton />),
         loader(ProductLoader, () => [cache()]),
@@ -338,7 +363,7 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {

package/skills/loader/SKILL.md

@@ -671,6 +671,16 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+> **No registration needed — and no worker-entry import.** A fetchable loader
+> does not have to be registered with `loader()` in the route DSL, and it does
+> not have to be imported by any server module. Importing it into the client
+> component that calls `useFetchLoader()` / `load()` is enough. Rango discovers
+> every `createLoader(fn, true)` at build time and registers it for the
+> `_rsc_loader` endpoint, so a loader reachable only through a client component
+> still resolves in production — on both the generated entry and a hand-written
+> worker entry (e.g. a Cloudflare `worker.rsc.tsx`). You do **not** need to
+> force-import the loader in your worker entry to make it resolve.
+
 ### Fetchable Loader with Middleware
 
 Pass an options object instead of `true` to attach per-loader middleware.

package/skills/migrate-nextjs/SKILL.md

@@ -193,9 +193,9 @@ The main content always goes through `<Outlet />` via the `path()` handler.
 // Rango: explicit intercept in layout
 layout(<ShopLayout />, () => [
   path("/product/:id", ProductPage, { name: "product" }),
-  intercept("@modal", ".product", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-  ]),
+  intercept("@modal", ".product", <ProductModal />, {
+    when: ({ from }) => from.pathname.startsWith("/shop"),
+  }),
 ])
 ```
 

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

@@ -740,7 +740,135 @@ function ThemeToggle() {
 
 See `/theme` for full API including system detection and cookie persistence.
 
-## 10. Key Conceptual Differences
+## 10. Cloudflare Workers: streaming, dev tooling, and deploy
+
+This is the part of an RR7-on-Cloudflare migration that the API tables above do
+**not** cover, and it produces symptoms that look like router bugs but aren't.
+RR7 serves a fully-rendered HTML/Turbo-Stream response; Rango serves a **streamed**
+RSC/SSR response. Anything in the request path that was harmless for RR7 but
+**buffers the response** silently kills that stream — the `loading()` /
+`<Suspense>` fallback never shows and the page appears "awaited" (old content
+held until everything resolves).
+
+### 10a. Never buffer the Rango response in a custom worker entry
+
+RR7 Cloudflare entries commonly **rewrite the response body** — `await
+response.text()` / `await response.arrayBuffer()`, `HTMLRewriter`, cookie/URL
+rewriting, hybrid-proxy bridging. That is fine for RR7's complete HTML, but if it
+runs on the **Rango** path it consumes the stream and you lose streaming
+entirely.
+
+Rule: in the worker entry, the Rango response must pass through as a **stream**.
+Buffer only on non-Rango branches (a legacy/SFRA proxy, an error page).
+
+```typescript
+// BAD — buffers the whole RSC stream before returning (no streaming, no fallback)
+const response = await router.fetch(request, { env, ctx });
+const body = await response.text(); // <- drains the stream
+return new Response(rewrite(body), response);
+
+// GOOD — pass the body through as a stream (re-wrap headers only)
+const response = await router.fetch(request, { env, ctx });
+return new Response(response.body, response); // <- streams; safe to add headers
+```
+
+If you keep a legacy proxy (e.g. an SFRA/host fallback) that legitimately buffers
+to rewrite HTML, gate it so it only runs for proxied paths — never for the
+`router.fetch()` result.
+
+Keep the custom entry itself (host/site resolution, sessions, proxy fallback) —
+that's real product logic, not a deviation. Just don't let it touch the stream.
+
+### 10b. Use `vite dev` / `vite preview`, not `wrangler dev`, for local work
+
+The `@cloudflare/vite-plugin` runs **your worker entry** inside miniflare for both
+`vite dev` and `vite preview`, with bindings + `.dev.vars`, and it **streams**.
+`wrangler dev` does **not** stream RSC locally: it gzip-compresses the response by
+buffering the entire body before sending. Measured on a bare streaming Worker
+under `wrangler dev`: `Accept-Encoding: gzip` → first byte at the full delay
+(buffered); `Accept-Encoding: identity` → first byte at ~3ms (streams). The
+deployed Cloudflare edge does **streaming** compression, so this is a
+**local-`wrangler dev`-only artifact** — do not mistake it for a production
+streaming bug (verify the deployed edge with `curl` and watch chunk timing /
+`transfer-encoding: chunked`).
+
+```jsonc
+// package.json — the standard rango-on-Workers shape
+"dev":     "vite",          // streams, bindings, .dev.vars live
+"build":   "vite build",
+"preview": "vite preview",  // runs the built worker in workerd; also streams
+// wrangler is only for: wrangler deploy / wrangler secret
+```
+
+If a workflow truly requires `wrangler dev`, declare `Content-Encoding: identity`
+on streamed responses, gated to local hostnames (so the edge still compresses):
+
+```typescript
+if (
+  isLocalHostname(url.hostname) &&
+  response.body &&
+  !response.headers.has("content-encoding")
+) {
+  const ct = (response.headers.get("content-type") ?? "").toLowerCase();
+  if (ct.includes("text/html") || ct.includes("text/x-component")) {
+    const headers = new Headers(response.headers);
+    headers.set("content-encoding", "identity"); // wrangler skips gzip -> streams
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+}
+```
+
+### 10c. `.dev.vars` loads differently per tool
+
+A frequent "my env vars vanished after migration" symptom — it's the tool, not
+the file:
+
+| Command        | How `.dev.vars` is loaded                                                            |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `wrangler dev` | Loaded natively at runtime (RR7's path — why it "worked before")                     |
+| `vite dev`     | Loaded **live** by the plugin (+ `.dev.vars.<CLOUDFLARE_ENV>` if a named env is set) |
+| `vite preview` | Read from the **build output** `dist/<env>/.dev.vars`, written at `vite build` time  |
+
+So `vite preview` only sees vars that were present when you built — re-run
+`vite build` after editing `.dev.vars`. (`vite dev` is the simplest: live vars +
+streaming, no rebuild.)
+
+### 10d. Build output moves from `build/` to `dist/`
+
+RR7's `react-router build` writes to `build/`; Rango's `vite build` writes to
+`dist/` (`dist/client`, `dist/rsc`, …). The leftover `build/` paths in
+`wrangler.toml` and cleanup scripts must move, or you deploy stale/empty assets:
+
+```toml
+# wrangler.toml — was RR7's react-router build output
+- assets = { directory = "./build/client/", binding = "ASSETS" }
++ assets = { directory = "./dist/client/",  binding = "ASSETS" }
+```
+
+```jsonc
+// package.json — clean the real output dir
+- "cleanup": "rimraf ./build ./public/build"
++ "cleanup": "rimraf ./dist ./build ./public/build"
+```
+
+### 10e. Deploy the built worker, not the source entry
+
+`vite build` emits the **deployable** Worker config at `dist/<env>/wrangler.json`
+with `main: "index.js"` (the bundled worker), `no_bundle: true`, and
+`assets: "../client"`. A plain `wrangler deploy` run from the repo root uses the
+**root** `wrangler.toml`, where `main` points at your **source** entry
+(`app/.../worker.ts`) — and wrangler's bundler cannot resolve Rango's
+`virtual:rsc-router/*` modules, so deploying the source entry fails or ships a
+broken worker. Deploy the build output instead (e.g.
+`wrangler deploy -c dist/<env>/wrangler.json`) or use the plugin's deploy flow.
+RR7's `wrangler deploy` from root worked only because its worker was already
+fully bundled by `react-router build`.
+
+## 11. Key Conceptual Differences
 
 | Concept             | React Router                        | Rango                                  |
 | ------------------- | ----------------------------------- | -------------------------------------- |
@@ -769,3 +897,18 @@ See `/theme` for full API including system detection and cookie persistence.
 11. [ ] Update metadata to use `Meta` handle + `<MetaTags />`
 12. [ ] Replace custom theme provider with `theme: true` in createRouter (see `/theme`)
 13. [ ] Run `npx rango generate src/` to generate route types
+
+**Cloudflare Workers (if migrating an RR7-on-Workers app):**
+
+14. [ ] Audit the custom worker entry — the `router.fetch()` response must pass
+        through as a **stream** (`new Response(response.body, response)`); remove
+        any `.text()`/`.arrayBuffer()`/`HTMLRewriter` buffering from the Rango
+        path (keep it only on legacy/proxy branches). See §10a.
+15. [ ] Switch local dev to `vite dev` / `vite preview` (they stream + load
+        `.dev.vars` + provide bindings); stop using `wrangler dev` for local
+        verification — it gzip-buffers and kills streaming. See §10b.
+16. [ ] Move build output paths from RR7's `build/` to vite's `dist/` in
+        `wrangler.toml` (`assets` → `./dist/client/`) and cleanup scripts. See §10d.
+17. [ ] Fix deploy to use the built config `dist/<env>/wrangler.json`
+        (`no_bundle: true`), not a root `wrangler deploy` against the source
+        worker entry (which can't bundle Rango's virtual modules). See §10e.

package/skills/prerender/SKILL.md

@@ -243,16 +243,16 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 
 ## Interaction with DSL Items
 
-| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                       |
-| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                          |
-| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                    |
-| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                |
-| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                        |
-| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                           |
-| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                              |
-| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
+| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                            |
+| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                               |
+| `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                         |
+| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                     |
+| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                             |
+| `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                                |
+| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                   |
+| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
 When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
@@ -609,12 +609,12 @@ At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
   (filtered by `namespace?.startsWith("intercept:")`) and sets up slots.
 - **Direct navigation**: looks up `paramHash` (no suffix). Standard prerender path.
 - **Intercept miss (no `/i` entry)**: falls through to the normal pipeline so
-  intercept-resolution middleware runs live. This handles `when()` conditions
+  intercept-resolution middleware runs live. This handles `when` config conditions
   that prevented pre-rendering.
 
-The `when()` callback receives an `InterceptSelectorContext` with `from.pathname`
+The `when` config selector receives an `InterceptSelectorContext` with `from.pathname`
 which is unknown at build time. All intercepts are pre-rendered unconditionally;
-`when()` is evaluated at runtime by the intercept-resolution middleware.
+`when` is evaluated at runtime by the intercept-resolution middleware.
 
 ### Example: Pre-rendered route with intercept
 
@@ -633,10 +633,13 @@ layout(ShopLayout, () => [
 
   // Intercept detail from shop index into a modal.
   // At build time, this is resolved and stored under the /i key.
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname === "/shop"),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname === "/shop" },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 

package/skills/router-setup/SKILL.md

@@ -60,8 +60,7 @@ urls(
     cache, // Configure caching
     middleware, // Add middleware
     revalidate, // Control revalidation
-    intercept, // Intercept routes for modals
-    when, // Conditional rendering
+    intercept, // Intercept routes for modals (conditional via intercept(..., { when }))
     errorBoundary, // Add an error boundary
     notFoundBoundary, // Add a not-found boundary
     transition, // Configure view transitions