@rangojs/router 0.0.0-experimental.115 → 0.0.0-experimental.117

package/src/vite/rango.ts

@@ -23,7 +23,10 @@ import {
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
-import { resolveClientChunks } from "./utils/client-chunks.js";
+import {
+  resolveClientChunks,
+  type ClientChunkContext,
+} from "./utils/client-chunks.js";
 import type { RangoOptions } from "./plugin-types.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
@@ -69,9 +72,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   // @vitejs/plugin-rsc in both presets. The built-in strategy only splits where it
   // recognizes a route structure, so this default is a no-op for flat / host-split
   // apps and never duplicates the shared runtime.
-  const clientChunks = resolveClientChunks(
-    resolvedOptions.clientChunks ?? true,
-  );
+  const clientChunksOption = resolvedOptions.clientChunks ?? true;
+  // Shared context the built-in strategy reads at build time: the production
+  // hashes of registered error/notFound fallback modules (-> app-fallback).
+  // Populated by the discovery plugin in buildStart, before the client build
+  // invokes the strategy. Only wired when the built-in strategy is active; a
+  // custom function owns its own grouping.
+  const useBuiltInClientChunks = clientChunksOption === true;
+  const clientChunkCtx: ClientChunkContext | undefined = useBuiltInClientChunks
+    ? { fallbackRefs: new Set<string>() }
+    : undefined;
+  const clientChunks = resolveClientChunks(clientChunksOption, clientChunkCtx);
   debugConfig?.("rango(%s) setup start", preset);
 
   const plugins: PluginOption[] = [];
@@ -157,6 +168,14 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
@@ -317,6 +336,14 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
@@ -508,6 +535,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
       preset,
+      clientChunkCtx,
     }),
   );
 

package/src/vite/utils/client-chunks.ts

@@ -6,10 +6,28 @@
 
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
 import { createRangoDebugger, NS } from "../debug.js";
+import { hashRefKey } from "../plugins/client-ref-hashing.js";
 
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
 export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
 
+/**
+ * Build-time context the discovery pass populates and the built-in strategy
+ * reads. It refines how the catch-all (no route-root marker) modules are grouped
+ * without touching marker splits or the shared runtime:
+ *
+ * - `fallbackRefs`: production hashes of the `"use client"` modules a consumer
+ *   registered as `errorBoundary`/`notFoundBoundary` fallbacks. Pulled into a
+ *   dedicated `app-fallback` chunk so the error UI is not co-bundled with the
+ *   very route code it exists to catch failures for (resilience), and so the
+ *   chunk it would otherwise sit in gets named after a real module rather than
+ *   the boundary. Populated by reading each fallback element's client-reference
+ *   `$$id` during discovery (see discover-routers).
+ */
+export interface ClientChunkContext {
+  fallbackRefs: Set<string>;
+}
+
 /**
  * Opt-in observability for the built-in strategy. The route-root marker list is
  * intentionally finite (see {@link ROUTE_ROOT_DIRS}); a consumer whose layout
@@ -101,18 +119,31 @@ const ROUTE_ROOT_DIRS = new Set([
  *   `app-components`), re-introducing cross-app leakage.
  *
  * Resolution order:
- * 1. If the path passes through a {@link ROUTE_ROOT_DIRS} marker that has a
- *    directory after it, key on that next segment (the route id) — robust to any
- *    nesting depth below it (`routes/foo/components/ui/X.tsx` -> `app-foo`).
- * 2. Otherwise return `undefined` (inherit the default `serverChunk` grouping).
+ * 1. Shared runtime (React / router / node_modules) -> `undefined` (never split).
+ * 2. A registered error/notFound fallback (`ctx.fallbackRefs`) -> `app-fallback`,
+ *    regardless of location, so the error UI is decoupled from the happy path.
+ * 3. A {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on that
+ *    next segment (the route id), robust to any nesting depth.
+ * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export function directoryClientChunks(
   meta: ClientChunkMeta,
+  ctx?: ClientChunkContext,
 ): string | undefined {
   if (isSharedRuntime(meta)) {
     // React / router runtime / node_modules: always shared, expected, uninteresting.
     return undefined;
   }
+  // Registered error/notFound fallbacks -> a dedicated chunk. The error UI must
+  // not co-bundle with the code it catches failures for, and removing it lets the
+  // chunk it would otherwise anchor be named after a real module, not the boundary.
+  if (
+    ctx?.fallbackRefs.size &&
+    ctx.fallbackRefs.has(hashRefKey(meta.normalizedId))
+  ) {
+    debugChunks?.("fallback %s -> app-fallback", meta.normalizedId);
+    return "app-fallback";
+  }
   const segments = meta.normalizedId.split("/").filter(Boolean);
   const dirCount = segments.length - 1; // exclude the filename
   if (dirCount >= 1) {
@@ -144,13 +175,16 @@ export function directoryClientChunks(
  * grouping.
  *
  * - `false` / `undefined` -> `undefined` (no override).
- * - `true`               -> the built-in {@link directoryClientChunks} strategy.
- * - function             -> the user's function, used verbatim.
+ * - `true`               -> the built-in {@link directoryClientChunks} strategy,
+ *   bound to the discovery-populated {@link ClientChunkContext} (fallback chunk).
+ * - function             -> the user's function, used verbatim (full control; the
+ *   fallback refinement does not apply — the consumer owns the grouping).
  */
 export function resolveClientChunks(
   option: ClientChunks | undefined,
+  ctx?: ClientChunkContext,
 ): RscClientChunksFn | undefined {
   if (!option) return undefined;
-  if (option === true) return directoryClientChunks;
+  if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }

package/src/vite/utils/manifest-utils.ts

@@ -1,78 +1,11 @@
-/**
- * Flatten prefix tree leaf nodes into precomputed route entries.
- * Leaf nodes have no children (no nested includes), so their routes can be
- * used directly by evaluateLazyEntry() without running the handler.
- * Non-leaf nodes are skipped because they have nested lazy includes that
- * require the handler to run for discovery.
- *
- * A leaf is also skipped when its staticPrefix collides with an ancestor
- * include node's staticPrefix. That happens when a dynamic param collapses the
- * staticPrefix of nested includes onto the parent's (e.g. `/m/:id/edit` -> sp
- * `/m`): precomputing such a leaf under the collapsed prefix would let the
- * ancestor's lazy entry claim a route it cannot register (the route is behind
- * further nested lazy includes), producing a RouteNotFoundError at request time
- * (issue #506). Those routes are resolved via the handler chain instead.
- */
-export function flattenLeafEntries(
-  prefixTree: Record<string, any>,
-  routeManifest: Record<string, string>,
-  result: Array<{ staticPrefix: string; routes: Record<string, string> }>,
-): void {
-  function visit(node: any, ancestorStaticPrefixes: Set<string>): void {
-    const children = node.children || {};
-    if (
-      Object.keys(children).length === 0 &&
-      node.routes &&
-      node.routes.length > 0
-    ) {
-      // Leaf node. Skip if its staticPrefix collides with an ancestor include
-      // node's staticPrefix (dynamic-param collapse) — see doc comment above.
-      if (ancestorStaticPrefixes.has(node.staticPrefix)) {
-        return;
-      }
-      // Collect its routes from the manifest
-      const routes: Record<string, string> = {};
-      for (const name of node.routes) {
-        if (name in routeManifest) {
-          routes[name] = routeManifest[name];
-        }
-      }
-      result.push({ staticPrefix: node.staticPrefix, routes });
-    } else {
-      // Non-leaf: recurse into children, tracking this node's staticPrefix as
-      // an ancestor so a collapsed nested leaf below it is not over-claimed.
-      const nextAncestors = new Set(ancestorStaticPrefixes);
-      nextAncestors.add(node.staticPrefix);
-      for (const child of Object.values(children)) {
-        visit(child, nextAncestors);
-      }
-    }
-  }
-  for (const node of Object.values(prefixTree)) {
-    visit(node, new Set());
-  }
-}
-
-/**
- * Walk prefix tree to map each route name to its scope's staticPrefix.
- */
-export function buildRouteToStaticPrefix(
-  prefixTree: Record<string, any>,
-  result: Record<string, string>,
-): void {
-  function visit(node: any): void {
-    const sp = node.staticPrefix || "";
-    for (const name of node.routes || []) {
-      result[name] = sp;
-    }
-    for (const child of Object.values(node.children || {})) {
-      visit(child);
-    }
-  }
-  for (const node of Object.values(prefixTree)) {
-    visit(node);
-  }
-}
+// Pure prefix-tree walks live in the build layer so runtime code can consume
+// them without importing from vite/. Re-exported here for the vite-side
+// callers (discover-routers, virtual-module-codegen) that already import them
+// from this module.
+export {
+  flattenLeafEntries,
+  buildRouteToStaticPrefix,
+} from "../../build/prefix-tree-utils.js";
 
 /**
  * Wrap a value as `JSON.parse('...')` instead of a JS object literal.

package/src/vite/utils/shared-utils.ts

@@ -116,6 +116,50 @@ export function createVirtualEntriesPlugin(
   };
 }
 
+// Matches rollup's FILE_NAME_CONFLICT message and reports whether the colliding
+// file is a content-hashed asset, e.g.
+//   The emitted file "assets/index-DlGNrvnU.css" overwrites a previously ...
+//   The emitted file "assets/inter-latin-Dx4kXJAl.woff2" overwrites a ...
+// The match is UNANCHORED on purpose: by the time the warning reaches this user
+// onwarn handler, Vite's logger has wrapped rollup's raw message with an ANSI
+// color sequence and a "[CODE] " label, e.g.
+//   "[FILE_NAME_CONFLICT] The emitted file \"...\" overwrites ..."
+// A "^The emitted file" anchor sits behind that prefix and never matches; and
+// Vite also strips the JSON.stringify quotes rollup puts around the filename, so
+// the match is UNANCHORED and quote-OPTIONAL ("?...?"?). The non-whitespace
+// capture stops at the space before "overwrites" (Vite's unquoted display form)
+// or the closing quote (raw rollup form); either way it carries no ANSI.
+// A content-hashed name ends with a "-" separator + a Vite content hash. The
+// hash is a FIXED-LENGTH base64url run ([A-Za-z0-9_-], default 8), so it can
+// itself contain "-"/"_": it CANNOT be located by splitting on the last "-"
+// (that lands inside the hash whenever it carries a dash, e.g. "...-Cabi7G8-" ->
+// "" or "...-CkhJZR-_" -> "_", which let those conflicts leak). Instead take the
+// trailing HASH_LEN chars and require the "-" separator right before them. The
+// hash must hold an uppercase letter or digit (a real hash is never an
+// all-lowercase word), so stable names like "assets/manifest.json" or
+// "assets/loading-skeleton.css" still surface as potential genuine overwrites.
+function isContentHashedAssetConflict(message: string | undefined): boolean {
+  if (!message) return false;
+  const match =
+    /The emitted file "?([^"\s]+)"? overwrites a previously emitted file/.exec(
+      message,
+    );
+  if (!match) return false;
+  const fileName = match[1];
+  const base = fileName.slice(fileName.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const stem = base.slice(0, dot);
+  // HASH_LEN tracks Vite's default [hash] width; bump it if an app sets a custom
+  // assetFileNames hash length.
+  const HASH_LEN = 8;
+  if (stem.length < HASH_LEN + 1 || stem[stem.length - HASH_LEN - 1] !== "-") {
+    return false;
+  }
+  const hash = stem.slice(-HASH_LEN);
+  return /^[A-Za-z0-9_-]+$/.test(hash) && /[A-Z0-9]/.test(hash);
+}
+
 /**
  * Rollup onwarn handler that suppresses known harmless warnings:
  * - "use client" directives: handled by the RSC plugin, not relevant to Rollup
@@ -126,6 +170,14 @@ export function createVirtualEntriesPlugin(
  *   by the bundler, rather than the vite:reporter message handled below (Rollup/Vite 7 shape).
  * - empty bundle: @vitejs/plugin-rsc scan build (step 1/5) produces an empty "index" chunk
  *   because the RSC entry is fully externalized during client-reference analysis
+ * - file name conflicts on content-hashed assets: @vitejs/plugin-rsc copies the rsc
+ *   environment's imported CSS/assets into the client bundle (its assets-manifest
+ *   generateBundle re-emits each via emitFile with an explicit content-hashed
+ *   fileName). When the client bundle already produced that identical asset,
+ *   rollup raises FILE_NAME_CONFLICT even though the bytes are identical (a
+ *   content hash collision IS a content match). Only these are suppressed; a
+ *   collision on a stable name still surfaces. No upstream fix as of
+ *   @vitejs/plugin-rsc@0.5.27; remove when it skips the redundant emit.
  */
 export function onwarn(
   warning: Vite.Rollup.RollupLog,
@@ -139,6 +191,12 @@ export function onwarn(
   ) {
     return;
   }
+  if (
+    warning.code === "FILE_NAME_CONFLICT" &&
+    isContentHashedAssetConflict(warning.message)
+  ) {
+    return;
+  }
   // @vitejs/plugin-rsc@0.5.14: rsc:virtual:vite-rsc/assets-manifest renderChunk
   // returns { code } without map, causing Rollup to warn about incorrect sourcemaps.
   // This is harmless (simple string replacement). Remove this suppression if a