@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/vite/debug.ts

@@ -0,0 +1,185 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+
+import debugFactory from "debug";
+
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+  chunks: "rango:chunks",
+} as const;
+
+// Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
+// console.logs in this plugin. Map it to `rango:*` so those call sites can
+// be migrated to the `debug` pipeline without breaking existing setups.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): Debugger | undefined {
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
+  return undefined;
+}
+
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
 import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -71,12 +72,12 @@ export function postprocessBundle(state: DiscoveryState): void {
           writeFileSync(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
-            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+            `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
           );
         }
       } catch (replaceErr: any) {
         console.warn(
-          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
+          `[rango] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
     }
@@ -104,7 +105,7 @@ export function postprocessBundle(state: DiscoveryState): void {
         }
 
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           "",
@@ -121,11 +122,11 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
+          `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write prerender assets: ${err.message}`,
+          `[rango] Failed to write prerender assets: ${err.message}`,
         );
       }
     }
@@ -169,11 +170,11 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
+          `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
-          `[rsc-router] Failed to write static assets: ${err.message}`,
+          `[rango] Failed to write static assets: ${err.message}`,
         );
       }
     }

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,
@@ -20,6 +30,15 @@ import {
   expandPrerenderRoutes,
   renderStaticHandlers,
 } from "./prerender-collection.js";
+import {
+  resolveHostRouterHandlers,
+  DiscoveryError,
+  type CaughtDiscoveryError,
+} from "./discovery-errors.js";
+import { createRangoDebugger, timed, NS } from "../debug.js";
+import { computeProductionHash } from "../plugins/client-ref-hashing.js";
+
+const debug = createRangoDebugger(NS.discovery);
 
 /**
  * Import the user's entry via RSC runner, generate manifests for each
@@ -38,41 +57,40 @@ export async function discoverRouters(
   // Import the entry file via RSC environment.
   // For node preset: this is the router file (createRouter() registers in RouterRegistry).
   // For cloudflare preset: this is the worker entry (which imports the router).
-  await rscEnv.runner.import(state.resolvedEntryPath);
+  await timed(debug, "inner: import entry", () =>
+    rscEnv.runner.import(state.resolvedEntryPath),
+  );
 
   // Import the router package to access the registry
-  const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
   let registry: Map<string, any> = serverMod.RouterRegistry;
 
   if (!registry || registry.size === 0) {
     // No RSC routers found directly. Check for host routers with lazy handlers
     // that need to be resolved to trigger sub-app createRouter() calls.
+    //
+    // Handler failures are collected rather than swallowed: when the registry
+    // is still empty afterwards, these errors (typically a sub-app whose router
+    // module failed to import) are the most likely cause and are surfaced in
+    // the terminal "No routers found" error below.
+    const discoveryErrors: CaughtDiscoveryError[] = [];
     try {
       const hostRegistry: Map<string, any> | undefined =
         serverMod.HostRouterRegistry;
 
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
-          `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`,
+          `[rango] 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 {
-                // Lazy handler may fail in temp server context, that's OK
-              }
-            }
-          }
-          if (entry.fallback && typeof entry.fallback.handler === "function") {
-            try {
-              await entry.fallback.handler();
-            } catch {
-              // Fallback handler may fail in temp server context
-            }
-          }
+        const handlerErrors = await resolveHostRouterHandlers(hostRegistry);
+        discoveryErrors.push(...handlerErrors);
+        for (const { context, error } of handlerErrors) {
+          debug?.("caught error while resolving %s: %O", context, error);
         }
 
         // Re-read RouterRegistry - sub-app createRouter() calls should have populated it
@@ -87,22 +105,31 @@ export async function discoverRouters(
           registry = freshRegistry;
         }
       }
-    } catch {
-      // Host-router discovery is best-effort; skip if unavailable
+    } catch (error) {
+      // Host-router discovery is best-effort; record the failure so it can be
+      // surfaced if no routers are found.
+      discoveryErrors.push({ context: "host-router discovery", error });
     }
 
     // If still no routers after host router resolution, fail
     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);
     }
   }
 
-  // Import build utilities for manifest generation
-  const buildMod = await rscEnv.runner.import("@rangojs/router/build");
+  // 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",
+    () => rscEnv.runner.import("@rangojs/router/build"),
+  );
   const generateManifestFull = buildMod.generateManifestFull;
 
+  debug?.("inner: found %d router(s) in registry", registry.size);
+
   const nestedRouterConflict = findNestedRouterConflict(
     [...registry.values()]
       .map((router) => router.__sourceFile)
@@ -130,6 +157,30 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  // Built-in clientChunks context (present only when the built-in strategy is
+  // active). Collect the production hashes of "use client" error/notFound
+  // fallback modules so the strategy can route them into app-fallback.
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx
+    ? (refKey: string) =>
+        clientChunkCtx.fallbackRefs.add(
+          computeProductionHash(state.projectRoot, refKey),
+        )
+    : undefined;
+  // Router-level boundary defaults (`createRouter({ defaultErrorBoundary, ... })`)
+  // 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. 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) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
+
+  const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
       continue;
@@ -138,10 +189,23 @@ export async function discoverRouters(
     const manifest = generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : undefined,
+      {
+        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+      },
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+
+    // Router-level "use client" boundary defaults -> app-fallback (the
+    // route-tree errorBoundary()/notFoundBoundary() helpers are already
+    // collected inside generateManifestFull via collectClientFallbackRef).
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
+
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p: any) => !p.includes(":") && !p.includes("*"),
@@ -193,24 +257,23 @@ 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(
-      `[rsc-router] Router "${id}" -> ${routeCount} routes ` +
+      `[rango] Router "${id}" -> ${routeCount} routes ` +
         `(${staticRoutes} static, ${dynamicRoutes} dynamic)`,
     );
   }
@@ -226,7 +289,7 @@ export async function discoverRouters(
     );
     if (autoIds.length > 1) {
       console.warn(
-        `[rsc-router] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). ` +
+        `[rango] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). ` +
           `In multi-router setups, each createRouter() must have an explicit \`id\` option ` +
           `to ensure per-router manifest data is matched correctly at runtime. ` +
           `Example: createRouter({ id: "site", ... })`,
@@ -234,11 +297,17 @@ export async function discoverRouters(
     }
   }
 
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
+
   // Build route trie from merged manifest + ancestry
   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) {
@@ -271,64 +340,36 @@ export async function discoverRouters(
         }
       }
 
+      // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
+      // identical to undefined, so no empty->undefined coercion is needed.
       newMergedRouteTrie = buildRouteTrie(
         newMergedRouteManifest,
         mergedRouteAncestry,
         routeToStaticPrefix,
-        Object.keys(mergedRouteTrailingSlash).length > 0
-          ? mergedRouteTrailingSlash
-          : undefined,
-        prerenderRouteNames.size > 0 ? prerenderRouteNames : undefined,
-        passthroughRouteNames.size > 0 ? passthroughRouteNames : undefined,
-        Object.keys(mergedResponseTypeRoutes).length > 0
-          ? mergedResponseTypeRoutes
-          : undefined,
+        mergedRouteTrailingSlash,
+        prerenderRouteNames,
+        passthroughRouteNames,
+        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 &&
-            Object.keys(manifest.routeTrailingSlash).length > 0
-            ? manifest.routeTrailingSlash
-            : undefined,
-          perRouterPrerenderNames && perRouterPrerenderNames.size > 0
-            ? perRouterPrerenderNames
-            : undefined,
-          perRouterPassthroughNames && perRouterPassthroughNames.size > 0
-            ? perRouterPassthroughNames
-            : undefined,
-          manifest.responseTypeRoutes &&
-            Object.keys(manifest.responseTypeRoutes).length > 0
-            ? manifest.responseTypeRoutes
-            : undefined,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
 
+  debug?.(
+    "inner: trie build done (%sms)",
+    (performance.now() - trieStart).toFixed(1),
+  );
+
   // Commit all local state to the shared discovery state atomically.
   // This ensures a failed re-discovery (e.g. from a transient module
   // evaluation error) preserves the last known-good state.