@rangojs/router 0.0.0-experimental.102 → 0.0.0-experimental.104

package/README.md

@@ -943,9 +943,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const hostRouter = createHostRouter();
 
-hostRouter.host(["*.localhost"]).map(() => import("./apps/admin/handler.js"));
-hostRouter.host(["localhost"]).map(() => import("./apps/site/handler.js"));
-hostRouter.fallback().map(() => import("./apps/site/handler.js"));
+hostRouter.host(["*.localhost"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["localhost"]).lazy(() => import("./apps/site/handler.js"));
+hostRouter.fallback().lazy(() => import("./apps/site/handler.js"));
 
 export default {
   async fetch(request, env, ctx) {
@@ -954,7 +954,7 @@ export default {
 };
 ```
 
-Each sub-app has its own `createRouter()` and `urls()`. The host router lazily imports the matched app's handler. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
+Use `.lazy(() => import("./sub-app"))` to mount a lazily-imported sub-app (a module whose `default` export is a handler or nested host router), and `.map((request) => Response)` for an inline request handler. Only `.lazy()` mounts are imported during build-time discovery; `.map(() => import(...))` is a type error. Each sub-app has its own `createRouter()` and `urls()`. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
 
 ## Meta Tags
 

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.102",
+  version: "0.0.0-experimental.104",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2205,7 +2205,8 @@ var package_default = {
   peerDependencies: {
     "@cloudflare/vite-plugin": "^1.25.0",
     "@vitejs/plugin-rsc": "^0.5.23",
-    react: "^18.0.0 || ^19.0.0",
+    react: ">=19.2.6 <20",
+    "react-dom": ">=19.2.6 <20",
     vite: "^7.3.0"
   },
   peerDependenciesMeta: {
@@ -3777,6 +3778,8 @@ function createDiscoveryState(entryPath, opts) {
     projectRoot: "",
     isBuildMode: false,
     userResolveAlias: void 0,
+    userRunnerConfig: void 0,
+    userResolvePlugins: [],
     scanFilter: void 0,
     cachedRouterFiles: void 0,
     opts,
@@ -4433,6 +4436,80 @@ async function renderStaticHandlers(state, rscEnv, registry) {
   );
 }
 
+// src/vite/discovery/discovery-errors.ts
+function indent(text, pad) {
+  return text.split("\n").map((line) => line.length > 0 ? pad + line : line).join("\n");
+}
+async function invokeLazyMount(loader, context, errors) {
+  try {
+    await loader();
+  } catch (error) {
+    errors.push({ context, error });
+  }
+}
+function isLazyMount(route) {
+  return !!route && route.kind === "lazy" && typeof route.handler === "function";
+}
+async function resolveHostRouterHandlers(hostRegistry) {
+  const errors = [];
+  for (const [hostId, entry] of hostRegistry) {
+    for (const route of entry.routes) {
+      if (isLazyMount(route)) {
+        await invokeLazyMount(
+          route.handler,
+          `host "${hostId}" route handler`,
+          errors
+        );
+      }
+    }
+    if (isLazyMount(entry.fallback)) {
+      await invokeLazyMount(
+        entry.fallback.handler,
+        `host "${hostId}" fallback handler`,
+        errors
+      );
+    }
+  }
+  return errors;
+}
+function formatNoRoutersError(entryPath, errors) {
+  const base = `[rsc-router] No routers found in registry after importing ${entryPath}`;
+  if (errors.length === 0) {
+    return base;
+  }
+  const formatted = errors.map(({ context, error }) => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const detail = err.stack ?? err.message;
+    return `  - while resolving ${context}:
+${indent(detail, "      ")}`;
+  }).join("\n");
+  return `${base}
+
+${errors.length} error(s) were caught during host-router discovery and likely explain why no routers were registered:
+${formatted}`;
+}
+function toCause(errors) {
+  if (errors.length === 0) return void 0;
+  if (errors.length === 1) return errors[0].error;
+  return new AggregateError(
+    errors.map((e) => e.error),
+    "Multiple host-router handlers failed during discovery"
+  );
+}
+var DiscoveryError = class _DiscoveryError extends Error {
+  constructor(entryPath, caught) {
+    super(formatNoRoutersError(entryPath, caught));
+    const cause = toCause(caught);
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+    this.name = "DiscoveryError";
+    this.entryPath = entryPath;
+    this.caught = caught;
+    Object.setPrototypeOf(this, _DiscoveryError.prototype);
+  }
+};
+
 // src/vite/discovery/discover-routers.ts
 var debug10 = createRangoDebugger(NS.discovery);
 async function discoverRouters(state, rscEnv) {
@@ -4449,27 +4526,17 @@ async function discoverRouters(state, rscEnv) {
   );
   let registry = serverMod.RouterRegistry;
   if (!registry || registry.size === 0) {
+    const discoveryErrors = [];
     try {
       const hostRegistry = serverMod.HostRouterRegistry;
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
           `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`
         );
-        for (const [, entry] of hostRegistry) {
-          for (const route of entry.routes) {
-            if (typeof route.handler === "function") {
-              try {
-                await route.handler();
-              } catch {
-              }
-            }
-          }
-          if (entry.fallback && typeof entry.fallback.handler === "function") {
-            try {
-              await entry.fallback.handler();
-            } catch {
-            }
-          }
+        const handlerErrors = await resolveHostRouterHandlers(hostRegistry);
+        discoveryErrors.push(...handlerErrors);
+        for (const { context, error } of handlerErrors) {
+          debug10?.("caught error while resolving %s: %O", context, error);
         }
         const freshServerMod = await rscEnv.runner.import(
           "@rangojs/router/server"
@@ -4480,12 +4547,11 @@ async function discoverRouters(state, rscEnv) {
           registry = freshRegistry;
         }
       }
-    } catch {
+    } catch (error) {
+      discoveryErrors.push({ context: "host-router discovery", error });
     }
     if (!registry || registry.size === 0) {
-      throw new Error(
-        `[rsc-router] No routers found in registry after importing ${state.resolvedEntryPath}`
-      );
+      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
     }
   }
   const buildMod = await timed(
@@ -4861,7 +4927,7 @@ function generateRoutesManifestModule(state) {
       }
     }
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -4897,18 +4963,6 @@ function generateRoutesManifestModule(state) {
         );
       }
     }
-    if (state.isBuildMode) {
-      if (state.mergedPrecomputedEntries && state.mergedPrecomputedEntries.length > 0) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`
-        );
-      }
-    }
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`
@@ -5174,6 +5228,52 @@ function createDiscoveryGate(s, debug11) {
   };
 }
 
+// src/vite/utils/forward-user-plugins.ts
+function isDenied(name) {
+  return name.startsWith("vite:") || name === "rsc" || name.startsWith("rsc:") || name.startsWith("@rangojs/router") || name.startsWith("@cloudflare/vite-plugin") || name.startsWith("vite-plugin-cloudflare");
+}
+function hasResolutionHooks(p) {
+  return Boolean(p.resolveId || p.load);
+}
+function stripToResolutionHooks(p) {
+  const stripped = { name: p.name };
+  if (p.enforce) stripped.enforce = p.enforce;
+  if (p.applyToEnvironment)
+    stripped.applyToEnvironment = p.applyToEnvironment;
+  if (p.resolveId) stripped.resolveId = p.resolveId;
+  if (p.load) stripped.load = p.load;
+  return stripped;
+}
+function selectForwardableResolvePlugins(plugins) {
+  if (!plugins) return [];
+  const forwarded = [];
+  for (const p of plugins) {
+    const name = p?.name;
+    if (!name || isDenied(name)) continue;
+    if (!hasResolutionHooks(p)) continue;
+    forwarded.push(stripToResolutionHooks(p));
+  }
+  return forwarded;
+}
+function pickForwardedRunnerConfig(config) {
+  const r = config.resolve ?? {};
+  const resolve10 = {};
+  if (r.alias !== void 0) resolve10.alias = r.alias;
+  if (r.dedupe !== void 0) resolve10.dedupe = r.dedupe;
+  if (r.conditions !== void 0) resolve10.conditions = r.conditions;
+  if (r.mainFields !== void 0) resolve10.mainFields = r.mainFields;
+  if (r.extensions !== void 0) resolve10.extensions = r.extensions;
+  if (r.preserveSymlinks !== void 0)
+    resolve10.preserveSymlinks = r.preserveSymlinks;
+  const userEsbuild = config.esbuild;
+  const esbuild = userEsbuild && typeof userEsbuild === "object" ? { ...userEsbuild, jsx: "automatic", jsxImportSource: "react" } : { jsx: "automatic", jsxImportSource: "react" };
+  return {
+    resolve: resolve10,
+    define: config.define,
+    esbuild
+  };
+}
+
 // src/vite/router-discovery.ts
 var debugDiscovery = createRangoDebugger(NS.discovery);
 var debugRoutes = createRangoDebugger(NS.routes);
@@ -5196,14 +5296,23 @@ function ensureCloudflareProtocolLoaderRegistered() {
 async function createTempRscServer(state, options = {}) {
   ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
+  const runnerConfig = state.userRunnerConfig;
+  const resolveConfig = runnerConfig?.resolve ?? {
+    alias: state.userResolveAlias
+  };
+  const esbuildConfig = runnerConfig?.esbuild ?? {
+    jsx: "automatic",
+    jsxImportSource: "react"
+  };
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
     server: { middlewareMode: true },
     appType: "custom",
     logLevel: "silent",
-    resolve: { alias: state.userResolveAlias },
-    esbuild: { jsx: "automatic", jsxImportSource: "react" },
+    resolve: resolveConfig,
+    ...runnerConfig?.define ? { define: runnerConfig.define } : {},
+    esbuild: esbuildConfig,
     ...options.cacheDir && { cacheDir: options.cacheDir },
     plugins: [
       rsc({
@@ -5221,7 +5330,11 @@ async function createTempRscServer(state, options = {}) {
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : void 0),
-      exposeRouterId()
+      exposeRouterId(),
+      // Forwarded user resolution plugins (e.g. vite-tsconfig-paths). Stripped
+      // to resolveId/load and placed last so framework resolution runs first;
+      // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
+      ...state.userResolvePlugins
     ]
   });
 }
@@ -5304,6 +5417,10 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       viteCommand = config.command;
       viteMode = config.mode;
       s.userResolveAlias = config.resolve.alias;
+      s.userRunnerConfig = pickForwardedRunnerConfig(config);
+      s.userResolvePlugins = selectForwardableResolvePlugins(
+        config.plugins
+      );
       if (!s.resolvedEntryPath && opts?.routerPathRef?.path) {
         s.resolvedEntryPath = opts.routerPathRef.path;
       }
@@ -5999,7 +6116,8 @@ ${err.stack}` : null
         ].filter(Boolean).join("\n");
         throw new Error(
           `[rsc-router] Build-time router discovery failed:
-${details}`
+${details}`,
+          { cause: err }
         );
       } finally {
         delete globalThis.__rscRouterDiscoveryActive;
@@ -6225,7 +6343,15 @@ async function rango(options) {
             esbuildOptions: sharedEsbuildOptions
           },
           resolve: {
-            alias: rangoAliases
+            alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"]
           },
           build: {
             rollupOptions: { onwarn }
@@ -6252,10 +6378,6 @@ async function rango(options) {
               build: {
                 outDir: "./dist/rsc/ssr"
               },
-              resolve: {
-                // Ensure single React instance in SSR child environment
-                dedupe: ["react", "react-dom"]
-              },
               // Pre-bundle SSR entry and React for proper module linking with childEnvironments
               // All deps must be listed to avoid late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
               optimizeDeps: {
@@ -6351,7 +6473,15 @@ ${list}`);
             rollupOptions: { onwarn }
           },
           resolve: {
-            alias: rangoAliases
+            alias: rangoAliases,
+            // Force a single React/React-DOM copy across all three RSC
+            // environments. RSC requires exactly one react/react-dom instance
+            // per environment runtime; consumer install topologies (pnpm
+            // strict layout, experimental React pins, third-party "use client"
+            // packages) can otherwise resolve duplicate copies, causing
+            // "Invalid hook call" / lost context. Child environments inherit
+            // this root dedupe, and Vite merges it with any consumer dedupe.
+            dedupe: ["react", "react-dom"]
           },
           environments: {
             client: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.102",
+  "version": "0.0.0-experimental.104",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -165,7 +165,8 @@
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.25.0",
     "@vitejs/plugin-rsc": "^0.5.23",
-    "react": "^18.0.0 || ^19.0.0",
+    "react": ">=19.2.6 <20",
+    "react-dom": ">=19.2.6 <20",
     "vite": "^7.3.0"
   },
   "peerDependenciesMeta": {

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.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
+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.

package/skills/host-router/SKILL.md

@@ -22,9 +22,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const router = createHostRouter();
 
-router.host(["."]).map(() => import("./apps/main"));
-router.host(["admin.*"]).map(() => import("./apps/admin"));
-router.host(["api.*"]).map(() => import("./apps/api"));
+router.host(["."]).lazy(() => import("./apps/main"));
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+router.host(["api.*"]).lazy(() => import("./apps/api"));
 
 export default {
   fetch(request: Request, env: Env, ctx: ExecutionContext) {
@@ -33,7 +33,31 @@ export default {
 };
 ```
 
-Each `.map()` receives either a direct handler `(request, input) => Response` or a lazy import `() => import(...)`. Lazy imports resolve a module with a `default` export that is either a handler function or another `HostRouter` (for nesting).
+## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
+
+A host pattern maps to one of two things, and you pick the method by intent:
+
+| Method  | Argument                       | Use for                                                      |
+| ------- | ------------------------------ | ------------------------------------------------------------ |
+| `.map`  | `(request, input) => Response` | An inline request handler that produces a response directly. |
+| `.lazy` | `() => import("./sub-app")`    | A lazily-imported handler or nested host router (a sub-app). |
+
+```typescript
+// Lazy mount: the module's default export is a handler or a HostRouter.
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+
+// Inline handler: returns a Response itself (sync or async).
+router.host(["health.*"]).map(() => new Response("ok"));
+router
+  .host(["echo.*"])
+  .map((request) => new Response(new URL(request.url).pathname));
+```
+
+Why two methods instead of one overloaded `.map()`:
+
+- **Build-time discovery** invokes only `.lazy()` mounts (to trigger each sub-app's `createRouter()` registration). Inline `.map()` handlers are never invoked during discovery, so they can't crash it or pollute its errors.
+- `.map(() => import("./sub-app"))` is a **type error** — a lazy import resolves to a module, not a `Response`. Use `.lazy()` for imports. (If the types are bypassed, e.g. from JS, a `.map()` handler that resolves to a module throws a clear `HostRouterError` at request time instead of returning the module.)
+- A lazy loader may declare an ignored parameter (`.lazy((_request?) => import("./x"))`); `.lazy()` accepts it because intent is explicit, not inferred from the signature.
 
 ## Pattern Syntax
 
@@ -65,8 +89,8 @@ const hosts = defineHosts({
   app: [".", "www.*"],
 });
 
-router.host(hosts.admin).map(() => import("./apps/admin"));
-router.host(hosts.app).map(() => import("./apps/main"));
+router.host(hosts.admin).lazy(() => import("./apps/admin"));
+router.host(hosts.app).lazy(() => import("./apps/main"));
 ```
 
 Returns a frozen object — keys are autocompleted by TypeScript.
@@ -88,7 +112,7 @@ router.use(async (request, input, next) => {
 router
   .host(["admin.*"])
   .use(requireAuth)
-  .map(() => import("./apps/admin"));
+  .lazy(() => import("./apps/admin"));
 ```
 
 Middleware signature: `(request: Request, input: RouterRequestInput, next: () => Promise<Response>) => Promise<Response>`
@@ -179,40 +203,41 @@ const request = createTestRequest({
 });
 
 // Test which route would match (without executing)
-router.test("admin.example.com"); // { pattern, handler } | null
+router.test("admin.example.com"); // { pattern, handler, kind } | null
 ```
 
 ## Error Types
 
 All errors extend `HostRouterError`:
 
-| Error                         | When                                        |
-| ----------------------------- | ------------------------------------------- |
-| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces |
-| `HostOverrideNotAllowedError` | Cookie override from disallowed host        |
-| `InvalidHostnameError`        | Cookie value isn't a valid hostname         |
-| `HostValidationError`         | Custom `validate` function threw            |
-| `NoRouteMatchError`           | No host pattern matched the request         |
-| `InvalidHandlerError`         | Handler is not a function                   |
+| Error                         | When                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces                                                       |
+| `HostOverrideNotAllowedError` | Cookie override from disallowed host                                                              |
+| `InvalidHostnameError`        | Cookie value isn't a valid hostname                                                               |
+| `HostValidationError`         | Custom `validate` function threw                                                                  |
+| `NoRouteMatchError`           | No host pattern matched the request                                                               |
+| `InvalidHandlerError`         | Handler is not a function, or a lazy mount resolved to a module without a usable `default` export |
+| `HostRouterError`             | A `.map()` inline handler resolved to a module namespace (a misused lazy import — use `.lazy()`)  |
 
 See the fallback section above for a `NoRouteMatchError` catch example.
 
 ## Nesting Host Routers
 
-A lazy handler can resolve to another `HostRouter`:
+A lazy mount can resolve to another `HostRouter`:
 
 ```typescript
 // apps/regional.ts
 import { createHostRouter } from "@rangojs/router/host";
 
 const regional = createHostRouter();
-regional.host(["us.*"]).map(() => import("./regions/us"));
-regional.host(["eu.*"]).map(() => import("./regions/eu"));
+regional.host(["us.*"]).lazy(() => import("./regions/us"));
+regional.host(["eu.*"]).lazy(() => import("./regions/eu"));
 
 export default regional;
 ```
 
 ```typescript
 // host-router.ts
-router.host(["**.regional.example.com"]).map(() => import("./apps/regional"));
+router.host(["**.regional.example.com"]).lazy(() => import("./apps/regional"));
 ```