@rangojs/router 0.0.0-experimental.103 → 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.103",
+  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(
@@ -5162,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);
@@ -5184,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({
@@ -5209,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
     ]
   });
 }
@@ -5292,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;
       }
@@ -5987,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;
@@ -6213,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 }
@@ -6240,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: {
@@ -6339,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.103",
+  "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/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"));
 ```

package/src/host/index.ts

@@ -11,8 +11,8 @@
  *
  * const router = createHostRouter();
  *
- * router.host(['.']).map(() => import('./apps/main'));
- * router.host(['admin.*']).map(() => import('./apps/admin'));
+ * router.host(['.']).lazy(() => import('./apps/main'));
+ * router.host(['admin.*']).lazy(() => import('./apps/admin'));
  *
  * export default {
  *   fetch(request) {