@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

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

@@ -1,62 +1,7 @@
-/**
- * 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.
- */
-export function flattenLeafEntries(
-  prefixTree: Record<string, any>,
-  routeManifest: Record<string, string>,
-  result: Array<{ staticPrefix: string; routes: Record<string, string> }>,
-): void {
-  function visit(node: any): void {
-    const children = node.children || {};
-    if (
-      Object.keys(children).length === 0 &&
-      node.routes &&
-      node.routes.length > 0
-    ) {
-      // Leaf node: 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
-      for (const child of Object.values(children)) {
-        visit(child);
-      }
-    }
-  }
-  for (const node of Object.values(prefixTree)) {
-    visit(node);
-  }
-}
-
-/**
- * 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);
-  }
-}
+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/package-resolution.ts

@@ -1,57 +1,29 @@
-/**
- * Package Resolution Utilities
- *
- * Handles detection of workspace vs npm install context and generates
- * appropriate aliases and exclude lists for Vite configuration.
- */
-
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { resolve } from "node:path";
-import packageJson from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json";
+
+const require = createRequire(import.meta.url);
 
 /**
  * The canonical name used in virtual entries (without scope)
  */
 const VIRTUAL_PACKAGE_NAME = "@rangojs/router";
 
-/**
- * Get the published package name (e.g., "@rangojs/router")
- */
 export function getPublishedPackageName(): string {
   return packageJson.name;
 }
 
-/**
- * Check if the package is installed from npm (scoped) vs workspace (unscoped)
- *
- * In workspace development:
- * - Package is installed as "@rangojs/router" via pnpm workspace alias
- * - The scoped name (@rangojs/router) doesn't exist in node_modules
- *
- * When installed from npm:
- * - Package is installed as "@rangojs/router"
- * - We need aliases to map "@rangojs/router/*" to "@rangojs/router/*"
- */
 export function isInstalledFromNpm(): boolean {
   const packageName = getPublishedPackageName();
   // Check if the scoped package exists in node_modules
   return existsSync(resolve(process.cwd(), "node_modules", packageName));
 }
 
-/**
- * Check if we're in a monorepo/workspace development context
- */
 export function isWorkspaceDevelopment(): boolean {
   return !isInstalledFromNpm();
 }
 
-/**
- * Subpaths derived from package.json exports that use TypeScript source.
- * These must be excluded from Vite's dependency optimization (they ship
- * as .ts/.tsx, not compiled JS) and aliased when installed from npm.
- *
- * Derived automatically from the exports field to prevent drift.
- */
 const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
   .filter((key) => {
     const entry = (
@@ -67,12 +39,6 @@ const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
   })
   .map((key) => key.replace(/^\./, ""));
 
-/**
- * Generate the list of modules to exclude from Vite's dependency optimization.
- *
- * We include both the published name and the virtual name because
- * Vite's optimizer runs before alias resolution.
- */
 export function getExcludeDeps(): string[] {
   const packageName = getPublishedPackageName();
   const excludes: string[] = [];
@@ -89,24 +55,10 @@ export function getExcludeDeps(): string[] {
   return excludes;
 }
 
-/**
- * Subpaths that need aliasing — same as SOURCE_EXPORT_SUBPATHS.
- * When installed from npm, virtual entries may use a different package name
- * than the published one; aliases bridge them.
- */
 const ALIAS_SUBPATHS = SOURCE_EXPORT_SUBPATHS;
 
-/**
- * Generate aliases to map virtual package paths to the actual published package.
- *
- * Only needed when installed from npm, where the package is under @rangojs/router
- * but virtual entries import from rsc-router/*.
- *
- * Returns empty object in workspace development where rsc-router resolves directly.
- */
 export function getPackageAliases(): Record<string, string> {
   if (isWorkspaceDevelopment()) {
-    // No aliases needed - rsc-router resolves directly
     return {};
   }
 
@@ -119,3 +71,19 @@ export function getPackageAliases(): Record<string, string> {
 
   return aliases;
 }
+
+export function getVendorAliases(): Record<string, string> {
+  const specs = [
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+  ];
+  const aliases: Record<string, string> = {};
+  for (const spec of specs) {
+    try {
+      aliases[spec] = require.resolve(spec);
+    } catch {
+      // Non-fatal; Vite will warn if it cannot resolve the spec
+    }
+  }
+  return aliases;
+}

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

@@ -9,18 +9,8 @@ import {
 } from "node:fs";
 import { resolve } from "node:path";
 
-/**
- * Escape special RegExp characters in a string for safe interpolation
- * into new RegExp() patterns.
- */
-export function escapeRegExp(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+import { escapeRegExp } from "../../regex-escape.js";
 
-/**
- * Encode route param values for path interpolation while preserving path
- * separators for wildcard params (splat-style values can include `/`).
- */
 export function encodePathParam(value: unknown): string {
   return String(value)
     .split("/")
@@ -28,31 +18,45 @@ export function encodePathParam(value: unknown): string {
     .join("/");
 }
 
-/**
- * Substitute route params into a pattern, stripping constraint and optional
- * syntax (:param(a|b)? -> value). Also handles wildcard params (*key).
- */
 export function substituteRouteParams(
   pattern: string,
   params: Record<string, string>,
   encode: (value: string) => string = encodeURIComponent,
 ): string {
   let result = pattern;
+  let hadOmittedOptional = false;
+
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
-    result = result.replace(
-      new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
-      encode(value),
-    );
-    result = result.replace(`*${key}`, encode(value));
+    if (value === "") {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
+        "",
+      );
+      result = result.replace(`*${key}`, "");
+    } else {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+        encode(value),
+      );
+      result = result.replace(`*${key}`, encode(value));
+    }
+  }
+
+  result = result.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\?/g, () => {
+    hadOmittedOptional = true;
+    return "";
+  });
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
   }
+
   return result;
 }
 
-/**
- * Run an async function over items with bounded concurrency.
- * Errors propagate immediately and abort remaining work.
- */
 export async function runWithConcurrency<T>(
   items: T[],
   concurrency: number,
@@ -64,19 +68,30 @@ export async function runWithConcurrency<T>(
     return;
   }
   let nextIndex = 0;
+  // On first failure (the default prerender.onError: "fail" re-throws), stop
+  // scheduling new work so the remaining workers don't keep running full RSC
+  // renders before the build aborts. The first error is surfaced after all
+  // in-flight workers settle, preserving the throw-to-fail-build behavior.
+  let firstError: unknown;
+  let failed = false;
   async function worker() {
-    while (nextIndex < items.length) {
+    while (nextIndex < items.length && !failed) {
       const idx = nextIndex++;
-      await fn(items[idx]);
+      try {
+        await fn(items[idx]);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
     }
   }
   await Promise.all(Array.from({ length: limit }, () => worker()));
+  if (failed) throw firstError;
 }
 
-/**
- * Group prerender entries by their concurrency setting so each group
- * can be rendered with the appropriate parallelism.
- */
 export function groupByConcurrency<T extends { concurrency: number }>(
   entries: T[],
 ): { concurrency: number; entries: T[] }[] {
@@ -96,10 +111,6 @@ export function groupByConcurrency<T extends { concurrency: number }>(
   }));
 }
 
-/**
- * Notify all routers' onError callbacks about a build-time error.
- * Uses a synthetic request since there is no real request during build.
- */
 export function notifyOnError(
   registry: Map<string, any>,
   error: unknown,
@@ -139,6 +150,42 @@ export function notifyOnError(
   }
 }
 
+/**
+ * Resolve a thrown build-time render error into the prerender build's policy and
+ * log a per-entry line. A `Skip` (or any render error under `prerender.onError:
+ * "warn"`) logs and returns so the caller skips the entry; a render error under
+ * the default "fail" logs FAIL, notifies `onError`, and re-throws to fail the
+ * build. Shared by `expandPrerenderRoutes` (prerender) and `renderStaticHandlers`
+ * (static) so the Skip/warn/fail policy lives in one place. `label` is the padded
+ * URL / handler name for the log line; `elapsed` is the per-entry duration string.
+ */
+export function resolvePrerenderError(
+  registry: Map<string, any>,
+  error: any,
+  onError: "fail" | "warn",
+  label: string,
+  elapsed: string,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+): void {
+  const isSkip = error?.name === "Skip";
+  if (isSkip || onError === "warn") {
+    if (isSkip) {
+      console.log(`[rango]   SKIP ${label} (${elapsed}ms) - ${error.message}`);
+    } else {
+      console.warn(
+        `[rango]   WARN ${label} (${elapsed}ms) - render error, not pre-rendered (prerender.onError: "warn"): ${error.message}`,
+      );
+    }
+    notifyOnError(registry, error, phase, routeKey, pathname, true);
+    return;
+  }
+  console.error(`[rango]   FAIL ${label} (${elapsed}ms) - ${error.message}`);
+  notifyOnError(registry, error, phase, routeKey, pathname);
+  throw error;
+}
+
 function getStagedAssetDir(projectRoot: string): string {
   return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
 }

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

@@ -1,43 +1,57 @@
-import type { Plugin } from "vite";
+import type { Plugin, ResolvedConfig } from "vite";
 import * as Vite from "vite";
 import { getPublishedPackageName } from "./package-resolution.js";
+import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
   VIRTUAL_ENTRY_BROWSER,
   VIRTUAL_ENTRY_SSR,
   getVirtualEntryRSC,
+  getVirtualVersionContent,
   VIRTUAL_IDS,
 } from "../plugins/virtual-entries.js";
 
+// Cloudflare preset: @cloudflare/vite-plugin sets optimizeDeps.entries (string
+// or array) on the rsc environment. Single source for both the discovery plugin
+// and the version injector so they target the same entry.
+export function resolveRscEntryFromConfig(
+  config: ResolvedConfig,
+): string | undefined {
+  const entries = (config.environments as any)?.["rsc"]?.optimizeDeps?.entries;
+  if (typeof entries === "string") return entries;
+  if (Array.isArray(entries) && entries.length > 0) return entries[0];
+  return undefined;
+}
+
 /**
- * esbuild plugin to provide rsc-router:version virtual module during optimization.
- * This is needed because esbuild runs during Vite's dependency optimization phase,
- * before Vite's plugin system can handle virtual modules.
+ * Rolldown plugin to provide the version virtual module during dependency
+ * optimization. Vite 8 optimizes deps with Rolldown (a Rollup-style plugin
+ * pipeline that is separate from the main plugin set), so this is a
+ * resolveId/load plugin under optimizeDeps.rolldownOptions. Any dep pulled into
+ * optimization that imports the version virtual module gets a "dev" stub here;
+ * the real VERSION is injected into runtime modules by the version plugin.
  */
-const versionEsbuildPlugin = {
+const versionRolldownPlugin = {
   name: "@rangojs/router-version",
-  setup(build: any): void {
-    build.onResolve({ filter: /^rsc-router:version$/ }, (args: any) => ({
-      path: args.path,
-      namespace: "@rangojs/router-virtual",
-    }));
-    build.onLoad(
-      { filter: /.*/, namespace: "@rangojs/router-virtual" },
-      () => ({
-        contents: `export const VERSION = "dev";`,
-        loader: "js",
-      }),
-    );
+  resolveId(id: string): string | undefined {
+    if (id === VIRTUAL_IDS.version) return "\0" + VIRTUAL_IDS.version;
+    return undefined;
+  },
+  load(id: string): string | undefined {
+    if (id === "\0" + VIRTUAL_IDS.version) {
+      return getVirtualVersionContent("dev");
+    }
+    return undefined;
   },
 };
 
 /**
- * Shared esbuild options for dependency optimization.
- * Includes the version stub plugin for all environments.
+ * Shared Rolldown options for dependency optimization (Vite 8).
+ * Includes the version stub plugin and the performance-tracks RSDW patch.
  */
-export const sharedEsbuildOptions: {
-  plugins: (typeof versionEsbuildPlugin)[];
+export const sharedRolldownOptions: {
+  plugins: any[];
 } = {
-  plugins: [versionEsbuildPlugin],
+  plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()],
 };
 
 /**
@@ -102,14 +116,54 @@ 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
- * - sourcemap errors: caused by "use client" directive at line 1:0 confusing sourcemap resolution
- * - sourcemap incomplete: plugins that transform without generating sourcemaps (router + RSC plugin)
- * - dynamic/static mixed imports: expected for router internals (e.g. request-context, cache-scope)
- * - 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
+ * Suppress known harmless warnings: "use client" directives, sourcemap errors,
+ * mixed imports (expected for router internals), empty bundles, and content-hashed
+ * asset collisions from @vitejs/plugin-rsc copying RSC-env assets to the client bundle.
  */
 export function onwarn(
   warning: Vite.Rollup.RollupLog,
@@ -118,14 +172,17 @@ export function onwarn(
   if (
     warning.code === "MODULE_LEVEL_DIRECTIVE" ||
     warning.code === "SOURCEMAP_ERROR" ||
-    warning.code === "EMPTY_BUNDLE"
+    warning.code === "EMPTY_BUNDLE" ||
+    warning.code === "INEFFECTIVE_DYNAMIC_IMPORT"
+  ) {
+    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
-  // future version of @vitejs/plugin-rsc fixes the missing sourcemap.
   if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
     return;
   }
@@ -140,10 +197,6 @@ export function onwarn(
   defaultHandler(warning);
 }
 
-/**
- * Manual chunks configuration for client build.
- * Splits React and router packages into separate chunks for better caching.
- */
 export function getManualChunks(id: string): string | undefined {
   const normalized = Vite.normalizePath(id);
 
@@ -155,13 +208,10 @@ export function getManualChunks(id: string): string | undefined {
   ) {
     return "react";
   }
-  // Use dynamic package name from package.json
-  // Check both npm install path and workspace symlink resolved path
   const packageName = getPublishedPackageName();
   if (
     normalized.includes(`node_modules/${packageName}/`) ||
-    normalized.includes("packages/rsc-router/") ||
-    normalized.includes("packages/rangojs-router/")
+    /\/packages\/(rsc-router|rangojs-router)\/(src|dist)\//.test(normalized)
   ) {
     return "router";
   }

package/src/browser/action-response-classifier.ts

@@ -1,99 +0,0 @@
-/**
- * Discriminated union of post-reconciliation action response scenarios.
- *
- * Error and full-update-unsupported are handled inline in the bridge
- * before reconciliation. This classifier only runs for partial responses
- * that have been successfully reconciled.
- */
-export type ActionScenario =
-  | {
-      type: "navigated-away";
-      historyKeyChanged: boolean;
-      onInterceptRoute: boolean;
-    }
-  | { type: "hmr-missing" }
-  | { type: "consolidation-needed"; segmentIds: string[] }
-  | { type: "concurrent-skip"; otherFetchingCount: number }
-  | { type: "normal" };
-
-/**
- * Pure data inputs for classifying a partial action response.
- * All values come from the bridge but no browser APIs or side effects.
- */
-export interface ClassifierInput {
-  /** window.location.pathname captured at action start */
-  actionStartPathname: string;
-  /** window.location.pathname at classification time */
-  currentPathname: string;
-  /** window.history.state?.key captured at action start */
-  actionStartLocationKey: string | undefined;
-  /** window.history.state?.key at classification time */
-  currentLocationKey: string | undefined;
-  /** Number of segments after reconciliation */
-  reconciledSegmentCount: number;
-  /** Number of matched segment IDs from server */
-  matchedCount: number;
-  /** Segment IDs needing consolidation (from concurrent action tracking) */
-  consolidationSegments: string[] | null;
-  /** Number of other actions still in "fetching" phase */
-  otherFetchingActionCount: number;
-  /** Current intercept source URL (null when not on intercept route) */
-  currentInterceptSource: string | null;
-}
-
-/**
- * Classify a partial action response into one of 5 post-reconciliation
- * scenarios.
- *
- * Called after error and full-update cases are handled inline by the bridge.
- * The classification order matches the priority chain:
- * 1. User navigated away during action
- * 2. HMR missing segments (fewer reconciled than matched)
- * 3. Consolidation needed (concurrent actions finished)
- * 4. Concurrent skip (other actions still fetching)
- * 5. Normal (single action, no issues)
- *
- * This is a pure function with no side effects - the bridge handles
- * all UI updates, store mutations, and network requests based on the
- * returned scenario.
- */
-export function classifyActionResponse(input: ClassifierInput): ActionScenario {
-  // Check if user navigated away during the action
-  const userNavigatedAway =
-    input.currentPathname !== input.actionStartPathname ||
-    input.currentLocationKey !== input.actionStartLocationKey;
-
-  if (userNavigatedAway) {
-    const historyKeyChanged =
-      input.currentLocationKey !== input.actionStartLocationKey;
-    return {
-      type: "navigated-away",
-      historyKeyChanged,
-      onInterceptRoute: input.currentInterceptSource !== null,
-    };
-  }
-
-  // HMR resilience: segments missing after reconciliation
-  if (input.reconciledSegmentCount < input.matchedCount) {
-    return { type: "hmr-missing" };
-  }
-
-  // Consolidation needed for concurrent actions
-  if (input.consolidationSegments && input.consolidationSegments.length > 0) {
-    return {
-      type: "consolidation-needed",
-      segmentIds: input.consolidationSegments,
-    };
-  }
-
-  // Other actions still fetching - skip UI update
-  if (input.otherFetchingActionCount > 0) {
-    return {
-      type: "concurrent-skip",
-      otherFetchingCount: input.otherFetchingActionCount,
-    };
-  }
-
-  // Normal single-action completion
-  return { type: "normal" };
-}