@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/vite/discovery/discover-routers.ts

@@ -11,6 +11,16 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
 } from "../../build/generate-route-types.js";
+// Pure data transforms over generateManifestFull's output. Imported directly
+// from source (not the public ./build barrel, and not the runner) because they
+// are realm-independent: buildRouteTrie/buildPerRouterTrie operate on plain
+// manifest data, and collectFallbackClientRefs keys on the global-registry
+// Symbol.for("react.client.reference"), so it detects client references in a
+// boundary tree regardless of which realm imported the walker. Only
+// generateManifestFull must stay on the runner (it invokes user handlers via
+// RangoContext from the runner realm) — see the runner.import below.
+import { buildRouteTrie, buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
 import {
   flattenLeafEntries,
   buildRouteToStaticPrefix,
@@ -107,7 +117,10 @@ export async function discoverRouters(
     }
   }
 
-  // Import build utilities for manifest generation
+  // generateManifestFull must run in the RSC runner realm: it invokes the
+  // user's urlpatterns.handler() via RangoContext, consuming router instances
+  // from the runner. The trie/fallback-ref builders are pure transforms over
+  // its output and are imported directly from source above.
   const buildMod = await timed(
     debug,
     "inner: import @rangojs/router/build",
@@ -158,11 +171,12 @@ export async function discoverRouters(
   // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
   // "use client" default boundary directly off the router instance. The value is
   // commonly a handler function wrapping the client boundary in server providers,
-  // so collectFallbackClientRefs invokes + walks the tree. Routed through buildMod
-  // so it runs in the same RSC runner realm the boundary value came from.
+  // so collectFallbackClientRefs invokes + walks the tree. The walker keys on the
+  // global-registry Symbol.for("react.client.reference"), so it detects client
+  // references in a runner-realm boundary tree even when imported here directly.
   const collectFromBoundaryNode = (node: unknown): void => {
-    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
-      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
     }
   };
 
@@ -172,7 +186,7 @@ export async function discoverRouters(
       continue;
     }
 
-    const manifest = generateManifestFull(
+    const manifest = await generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
       {
@@ -243,20 +257,19 @@ export async function discoverRouters(
     // Flatten prefix tree leaf nodes into precomputed entries.
     // Leaf nodes (no children) can have their routes used directly by
     // evaluateLazyEntry() without running the handler at runtime.
+    // Walk once into a per-router array, then fold it into the merged array;
+    // the merged and per-router entries are identical, so a second walk is
+    // redundant. Append order is preserved within and across routers.
+    const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      newMergedPrecomputedEntries,
+      routerPrecomputed,
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
     newPerRouterManifestDataMap.set(id, manifest.routeManifest);
-    const routerPrecomputed: PrecomputedEntry[] = [];
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      routerPrecomputed,
-    );
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
@@ -294,8 +307,7 @@ export async function discoverRouters(
   let newMergedRouteTrie: any = null;
   const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
+    if (mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
       const routeToStaticPrefix: Record<string, string> = {};
       for (const { manifest } of allManifests) {
@@ -340,36 +352,15 @@ export async function discoverRouters(
         mergedResponseTypeRoutes,
       );
 
-      // Build per-router tries for multi-router isolation.
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      // Returns null for route-less manifests (route-trie.ts).
       for (const { id, manifest } of allManifests) {
-        if (
-          !manifest._routeAncestry ||
-          Object.keys(manifest._routeAncestry).length === 0
-        )
-          continue;
-        const perRouterStaticPrefix: Record<string, string> = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie(manifest);
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-
-        const perRouterPrerenderNames = manifest.prerenderRoutes
-          ? new Set<string>(manifest.prerenderRoutes)
-          : undefined;
-        const perRouterPassthroughNames = manifest.passthroughRoutes
-          ? new Set<string>(manifest.passthroughRoutes)
-          : undefined;
-
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash,
-          perRouterPrerenderNames,
-          perRouterPassthroughNames,
-          manifest.responseTypeRoutes,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }

package/src/vite/discovery/discovery-errors.ts

@@ -192,3 +192,64 @@ export class DiscoveryError extends Error {
     Object.setPrototypeOf(this, DiscoveryError.prototype);
   }
 }
+
+/** How the dev caller should surface a discovery failure. */
+export interface DiscoveryFailureReport {
+  level: "error" | "warn";
+  message: string;
+}
+
+/**
+ * Decide how to surface a dev-boot discovery failure in the terminal.
+ *
+ * The bare "no routers found" case (a DiscoveryError with no caught host-handler
+ * failures) is ambiguous. It is either:
+ *   - a genuine misconfiguration — the entry never calls createRouter(), or the
+ *     configured entry path is wrong; or
+ *   - a transient artifact of a Vite dependency re-optimization racing with boot
+ *     discovery (a module read before the entry import resolves to the
+ *     pre-optimize copy of the runner graph while createRouter() populated the
+ *     post-optimize copy — see router-discovery.ts).
+ *
+ * We can only tell them apart when the caller observed the dep optimizer's
+ * `browserHash` change across the discovery attempt (`reoptimizeObserved`): a
+ * reload-causing re-optimization landed mid-flight, so the empty read was
+ * transient and the app self-heals per-request (handler.ts builds the trie from
+ * the router's live urlpatterns) with discovery re-running on the next boot.
+ *
+ * A DiscoveryError that DOES carry caught host-handler failures already embeds
+ * the real cause in its message, and any non-DiscoveryError is a hard failure;
+ * both stay loud with full detail.
+ */
+export function describeDiscoveryFailure(
+  err: unknown,
+  opts: { reoptimizeObserved?: boolean } = {},
+): DiscoveryFailureReport {
+  if (err instanceof DiscoveryError && err.caught.length === 0) {
+    const entry = err.entryPath ?? "the router entry";
+    if (opts.reoptimizeObserved) {
+      return {
+        level: "warn",
+        message:
+          `[rango] No routers found while Vite was re-optimizing dependencies on ` +
+          `dev boot. This is transient: routes are served per-request and ` +
+          `discovery re-runs automatically, so it clears on the next boot. If ` +
+          `routes still 404, confirm ${entry} calls createRouter().`,
+      };
+    }
+    return {
+      level: "error",
+      message:
+        `${err.message}\n` +
+        `  Ensure ${entry} calls createRouter() at module top level and that the ` +
+        `configured router entry path is correct.`,
+    };
+  }
+
+  const e = err as { stack?: string; message?: string };
+  const detail = e?.stack ?? e?.message ?? String(err);
+  return {
+    level: "error",
+    message: `[rango] Router discovery failed: ${detail}`,
+  };
+}

package/src/vite/discovery/prerender-collection.ts

@@ -6,13 +6,14 @@
  * generation.
  */
 
-import { contextSet } from "../../context-var.js";
+import { contextSet, hasContextVars } from "../../context-var.js";
 import {
   encodePathParam,
   substituteRouteParams,
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
+  resolvePrerenderError,
   stageBuildAssetModule,
 } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
@@ -135,9 +136,7 @@ export async function expandPrerenderRoutes(
                 (performance.now() - getParamsStart).toFixed(1),
               );
               const concurrency = def.options?.concurrency ?? 1;
-              const hasBuildVars =
-                Object.keys(buildVars).length > 0 ||
-                Object.getOwnPropertySymbols(buildVars).length > 0;
+              const hasBuildVars = hasContextVars(buildVars);
               for (const params of paramsList) {
                 let url = substituteRouteParams(
                   pattern,
@@ -233,6 +232,10 @@ export async function expandPrerenderRoutes(
   const manifestEntries: Record<string, string> = {};
   let doneCount = 0;
   let skipCount = 0;
+  // #587: a render error reaches here (matchForPrerender now re-throws it rather
+  // than baking the error boundary). Default "fail" fails the build; "warn" logs
+  // and skips baking the URL.
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   const startTotal = performance.now();
 
   // Group entries by concurrency for batched rendering.
@@ -282,10 +285,9 @@ export async function expandPrerenderRoutes(
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // interceptHandles is the pre-encoded MERGED (main + intercept)
+                // handle string (the producer merged before encoding).
+                handles: result.interceptHandles ?? "",
               });
               manifestEntries[interceptKey] = stageBuildAssetModule(
                 state.projectRoot,
@@ -300,35 +302,22 @@ export async function expandPrerenderRoutes(
             doneCount++;
             break;
           } catch (err: any) {
-            if (err.name === "Skip") {
-              const elapsed = (performance.now() - startUrl).toFixed(0);
-              console.log(
-                `[rango]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-              );
-              skipCount++;
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                entry.routeName,
-                entry.urlPath,
-                true,
-              );
-              break;
-            }
-            // Regular error: log, notify, and fail the build
+            // Skip, or a render error under prerender.onError "warn": skip the
+            // URL (never bake the error page, #587). A render error under the
+            // default "fail" re-throws below to fail the build.
             const elapsed = (performance.now() - startUrl).toFixed(0);
-            console.error(
-              `[rango]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            notifyOnError(
+            resolvePrerenderError(
               registry,
               err,
+              prerenderOnError,
+              entry.urlPath.padEnd(40),
+              elapsed,
               "prerender",
               entry.routeName,
               entry.urlPath,
             );
-            throw err;
+            skipCount++;
+            break;
           }
         }
       },
@@ -381,6 +370,7 @@ export async function renderStaticHandlers(
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
 
   // Count handlers for the log header
   for (const [, exportNames] of state.resolvedStaticModules) {
@@ -420,7 +410,8 @@ export async function renderStaticHandlers(
             !state.isBuildMode,
           );
           if (result) {
-            const hasHandles = Object.keys(result.handles).length > 0;
+            // result.handles is the pre-encoded handle string ("" when none).
+            const hasHandles = result.handles !== "";
             const exportValue = hasHandles
               ? JSON.stringify(result)
               : JSON.stringify(result.encoded);
@@ -436,23 +427,19 @@ export async function renderStaticHandlers(
             break;
           }
         } catch (err: any) {
-          if (err.name === "Skip") {
-            const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rango]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            staticSkip++;
-            notifyOnError(registry, err, "static", undefined, undefined, true);
-            handled = true;
-            break;
-          }
-          // Regular error: log, notify, and fail the build
+          // Same Skip/warn/fail policy as the prerender loop (shared helper).
           const elapsed = (performance.now() - startHandler).toFixed(0);
-          console.error(
-            `[rango]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          resolvePrerenderError(
+            registry,
+            err,
+            prerenderOnError,
+            name.padEnd(40),
+            elapsed,
+            "static",
           );
-          notifyOnError(registry, err, "static");
-          throw err;
+          staticSkip++;
+          handled = true;
+          break;
         }
       }
       if (!handled) {

package/src/vite/discovery/state.ts

@@ -19,7 +19,18 @@ export interface PluginOptions {
   /** Build-time env option from rango() config. */
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
-  preset?: "node" | "cloudflare";
+  preset?: "node" | "cloudflare" | "vercel";
+  /**
+   * Route-discovery scan filter (glob include/exclude) from rango() config.
+   * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
+   */
+  discovery?: { include?: string[]; exclude?: string[] };
+  /**
+   * What to do when a Prerender/Static render throws at build time, from
+   * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+   * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+   */
+  prerenderOnError?: "fail" | "warn";
   /**
    * Shared context the built-in clientChunks strategy reads. Discovery populates
    * it (registered fallback hashes + single-router name) before the client build

package/src/vite/discovery/virtual-module-codegen.ts

@@ -49,7 +49,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         );
         genFileVars.push(varName);
       } else {
-        // Routers without sourceFile: inline their manifest data directly
         routersWithoutGenFile.push({
           id: entry.id,
           manifest: entry.routeManifest,
@@ -68,14 +67,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
-    // Flatten NamedRoutes entries: search schema objects -> plain string paths
     if (genFileVars.length > 0) {
       lines.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
       );
     }
 
-    // Build the merged manifest from gen file imports + inlined data
     if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
       lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
     } else {
@@ -86,7 +83,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
     }
 
-    // Set per-router manifests
     let genVarIdx = 0;
     for (const entry of state.perRouterManifests) {
       if (entry.sourceFile) {
@@ -114,8 +110,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     // against live router.urlpatterns, which is always correct after a
     // program reload.
 
-    // Register lazy loaders for per-router manifest modules.
-    // Each import() uses a static string literal so Rollup creates separate chunks.
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
@@ -129,9 +123,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     return lines.join("\n");
   }
 
-  // No manifest: either discovery hasn't completed or no runner (Cloudflare dev).
-  // Still inject __PRERENDER_DEV_URL so the prerender store can fetch on-demand.
-  // Re-resolve origin now since the server is listening by module load time.
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||
@@ -160,7 +151,6 @@ export function generatePerRouterModule(
   const lines: string[] = [];
 
   if (routerEntry?.sourceFile) {
-    // Import manifest from the gen file so HMR auto-propagates
     const routerDir = dirname(routerEntry.sourceFile);
     const routerBasename = basename(routerEntry.sourceFile).replace(
       /\.(tsx?|jsx?)$/,
@@ -189,5 +179,5 @@ export function generatePerRouterModule(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`,
     );
   }
-  return lines.join("\n") || "// empty router manifest";
+  return lines.join("\n") || "";
 }

package/src/vite/index.ts

@@ -8,10 +8,19 @@
 
 export { rango } from "./rango.js";
 export { poke } from "./plugins/refresh-cmd.js";
+// The built-in clientChunks strategy, exported so a custom `clientChunks`
+// function can OVERLAY it (route a few modules to a dedicated chunk, delegate
+// the rest) instead of replacing the whole route/marker grouping. Without this
+// a consumer override silently loses app-fallback/route splitting for the
+// entire app. Note: called without a ClientChunkContext the fallbackRefs-based
+// `app-fallback` split is inactive — discovery wires it only for the built-in.
+export { directoryClientChunks } from "./utils/client-chunks.js";
 
 export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
+  RangoVercelOptions,
+  VercelPresetOptions,
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,

package/src/vite/inject-client-debug.ts

@@ -0,0 +1,88 @@
+import type { Connect } from "vite";
+
+/**
+ * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
+ * module so the flag reaches the CLIENT debug logs by just setting the env var.
+ *
+ * internal-debug.ts normally reads the flag via `typeof __RANGO_DEBUG__`, a Vite
+ * define. That delivery is unreliable on the client: in dev Vite ships the define
+ * only as an injected global whose presence varies across consumer setups, so the
+ * module can fall through to `process.env` (undefined in the browser) and the FE
+ * debug flag silently stays false while the server logs work. A Vite `transform`
+ * runs on the module regardless of how (or whether) the define is delivered, in
+ * both dev and build and for every environment, so the discovery plugin uses this
+ * to replace the module with the resolved literal.
+ */
+
+/**
+ * Scope to the router's own internal-debug module: the published package
+ * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+ * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+ * consumer file that merely sits under a directory named `rangojs-router`.
+ * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ */
+export function isRouterInternalDebugId(id: string): boolean {
+  if (!id.includes("internal-debug")) return false;
+  const norm = id.replace(/\\/g, "/");
+  return (
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"))
+  );
+}
+
+/**
+ * Transform: replace the module with the resolved literal.
+ * Returns null for any module that is not the router's internal-debug module.
+ */
+export function injectClientDebugFlag(
+  id: string,
+): { code: string; map: null } | null {
+  // Cheap early-out: this hook runs on every module in every environment.
+  if (!isRouterInternalDebugId(id)) return null;
+  // Emit the whole module: internal-debug.ts has a single export, kept in sync.
+  return {
+    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
+    map: null,
+  };
+}
+
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * immune -- workspace source is outside node_modules and served no-cache --
+ * which is why this bit only npm consumers.
+ *
+ * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
+ * are byte-identical across flag states), so forcing revalidation for this one
+ * tiny module is sufficient and costs one conditional request per session. The
+ * middleware is unconditional (not gated on the flag) so an already-poisoned
+ * cache heals in both directions. Alternatives that do not work: a plugin
+ * `resolveId` appending a flag query never fires in Vite 8 dev for
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value,
+        );
+      };
+    }
+    next();
+  };
+}