@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

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

@@ -1,52 +1,116 @@
-import type { Plugin } from "vite";
+import type { Plugin, ResolvedConfig } from "vite";
 import * as Vite from "vite";
+import { isAbsolute, resolve } from "node:path";
 import { getPublishedPackageName } from "./package-resolution.js";
+import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
   VIRTUAL_ENTRY_BROWSER,
-  VIRTUAL_ENTRY_SSR,
+  getVirtualEntrySSR,
   getVirtualEntryRSC,
+  getVirtualEntryRSCHost,
+  getVirtualVersionContent,
   VIRTUAL_IDS,
 } from "../plugins/virtual-entries.js";
+import type { HeadScriptsOption } from "../plugin-types.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()],
 };
 
+/**
+ * Normalize an explicit `hostRouter` option into the specifier emitted as the
+ * host entry's `import ... from "<path>"`, and — for the forms that resolve
+ * unambiguously against the project root — verify the file exists (failing with
+ * a rango message instead of a downstream bundler "failed to resolve").
+ *
+ * Only a BARE specifier ("src/worker.rsc.tsx") that exists under the root is
+ * rewritten (to "./src/...") so it is not read as a package. A bare specifier
+ * that does NOT exist under the root is passed through VERBATIM: it may be a
+ * Vite alias ("@/worker.rsc.tsx"), an imports-map entry ("#app/worker"), or a
+ * workspace package the bundler resolves — rewriting or rejecting those was a
+ * regression (aliases worked before normalization existed). "./"/"../", a
+ * leading-slash (Vite root-relative), and a filesystem-absolute path are
+ * emitted unchanged — Vite resolves each. A leading-slash path and a
+ * filesystem-absolute path are indistinguishable on POSIX, so both are treated
+ * as "rooted": passed through WITHOUT an existence check (guessing between the
+ * two would wrongly reject a valid file — this was a regression the first time
+ * the check was added). Only the explicitly-relative forms, which resolve
+ * unambiguously against the root, fail fast with a rango message.
+ *
+ * `exists` is injected so the logic is unit-testable without a real filesystem.
+ */
+export function normalizeHostRouterEntry(
+  rawInput: string,
+  root: string,
+  exists: (absPath: string) => boolean,
+): string {
+  const raw = rawInput.replaceAll("\\", "/");
+  const isRelative = raw.startsWith("./") || raw.startsWith("../");
+  const isRooted = raw.startsWith("/") || isAbsolute(rawInput);
+  if (isRooted) return raw;
+  if (isRelative) {
+    if (!exists(resolve(root, raw))) {
+      throw new Error(
+        `[rango] hostRouter entry not found: "${rawInput}" (resolved under ` +
+          `${root}). Point it at your createHostRouter() module, e.g. ` +
+          `rango({ hostRouter: "./src/worker.rsc.tsx" }).`,
+      );
+    }
+    return raw;
+  }
+  // Bare specifier: an existing root-relative file gets the explicit "./";
+  // anything else (alias, imports-map, package) is the bundler's to resolve.
+  return exists(resolve(root, raw)) ? "./" + raw : raw;
+}
+
 /**
  * Create a virtual modules plugin for default entry files.
  * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).
  */
 export function createVirtualEntriesPlugin(
   entries: { client: string; ssr: string; rsc?: string },
-  routerPathRef?: { path?: string },
+  routerPathRef?: { path?: string; kind?: "router" | "host" },
+  options?: { headScripts?: HeadScriptsOption },
 ): Plugin {
   // Build virtual modules map based on which entries use virtual IDs
   const virtualModules: Record<string, string> = {};
@@ -55,7 +119,7 @@ export function createVirtualEntriesPlugin(
     virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
   }
   if (entries.ssr === VIRTUAL_IDS.ssr) {
-    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
   }
 
   // RSC entry is resolved lazily in load() because routerPath may be
@@ -94,7 +158,9 @@ export function createVirtualEntriesPlugin(
             : routerPathRef.path;
           // Normalize backslashes for Windows (path.join/slice preserve native separators)
           const absoluteRouterPath = raw.replaceAll("\\", "/");
-          return getVirtualEntryRSC(absoluteRouterPath);
+          return routerPathRef.kind === "host"
+            ? getVirtualEntryRSCHost(absoluteRouterPath)
+            : getVirtualEntryRSC(absoluteRouterPath);
         }
       }
       return null;
@@ -102,14 +168,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 +224,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;
   }
@@ -141,8 +250,16 @@ export function onwarn(
 }
 
 /**
- * Manual chunks configuration for client build.
- * Splits React and router packages into separate chunks for better caching.
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
  */
 export function getManualChunks(id: string): string | undefined {
   const normalized = Vite.normalizePath(id);
@@ -155,13 +272,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" };
-}

package/src/browser/react/use-client-cache.ts

@@ -1,58 +0,0 @@
-"use client";
-
-import { useContext, useCallback } from "react";
-import { NavigationStoreContext } from "./context.js";
-
-/**
- * Return type for useClientCache hook
- */
-export interface ClientCacheControls {
-  /**
-   * Clear the client-side navigation cache.
-   * Call this after data changes that happen outside of server actions
-   * (e.g., REST API calls, WebSocket updates, etc.)
-   *
-   * This will also broadcast to other tabs to clear their caches.
-   */
-  clear: () => void;
-}
-
-/**
- * Hook to access client-side cache controls
- *
- * Use this when you need to manually invalidate the navigation cache
- * after data changes that happen outside of server actions.
- *
- * Server actions automatically clear the cache, so you only need this for:
- * - REST API mutations
- * - WebSocket-driven updates
- * - Other non-RSC data changes
- *
- * @example
- * ```tsx
- * function DataEditor() {
- *   const { clear } = useClientCache();
- *
- *   async function handleSave() {
- *     await fetch('/api/data', { method: 'POST', body: JSON.stringify(data) });
- *     // Clear cache so back/forward navigation shows fresh data
- *     clear();
- *   }
- *
- *   return <button onClick={handleSave}>Save</button>;
- * }
- * ```
- */
-export function useClientCache(): ClientCacheControls {
-  const ctx = useContext(NavigationStoreContext);
-
-  if (!ctx) {
-    throw new Error("useClientCache must be used within NavigationProvider");
-  }
-
-  const clear = useCallback(() => {
-    ctx.store.clearHistoryCache();
-  }, [ctx]);
-
-  return { clear };
-}

package/src/browser/shallow.ts

@@ -1,40 +0,0 @@
-/**
- * Shallow comparison utility for selector optimization
- *
- * Used by useNavigation hook to prevent unnecessary re-renders
- * when the selected value hasn't changed.
- *
- * @param a - First value
- * @param b - Second value
- * @returns true if values are shallowly equal
- */
-export function shallow<T>(a: T, b: T): boolean {
-  // Same reference or primitive equality
-  if (Object.is(a, b)) return true;
-
-  // Different types or non-objects
-  if (typeof a !== "object" || typeof b !== "object") return false;
-
-  // Null checks
-  if (a === null || b === null) return false;
-
-  // Compare object keys
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-
-  if (keysA.length !== keysB.length) return false;
-
-  // Check each key's value with Object.is
-  for (const key of keysA) {
-    if (
-      !Object.is(
-        (a as Record<string, unknown>)[key],
-        (b as Record<string, unknown>)[key],
-      )
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}

package/src/handles/index.ts

@@ -1,7 +0,0 @@
-/**
- * Built-in handles for rsc-router.
- */
-
-export { Meta } from "./meta.ts";
-export { MetaTags } from "./MetaTags.tsx";
-export { Breadcrumbs, type BreadcrumbItem } from "./breadcrumbs.ts";

package/src/network-error-thrower.tsx

@@ -1,23 +0,0 @@
-"use client";
-
-import type { ReactNode } from "react";
-import type { NetworkError } from "./errors.js";
-
-interface NetworkErrorThrowerProps {
-  error: NetworkError;
-}
-
-/**
- * Client component that throws a NetworkError during render.
- * Used to trigger the root error boundary when a network error occurs
- * during navigation or server actions.
- *
- * This must be a separate component because:
- * 1. Errors must be thrown during React's render phase to be caught by error boundaries
- * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
- */
-export function NetworkErrorThrower({
-  error,
-}: NetworkErrorThrowerProps): ReactNode {
-  throw error;
-}

package/src/router/middleware-cookies.ts

@@ -1,55 +0,0 @@
-/**
- * Cookie Utilities
- *
- * Parsing and serialization for HTTP cookies used by middleware context.
- */
-
-import type { CookieOptions } from "./middleware-types.js";
-
-/**
- * Parse cookies from Cookie header
- */
-export function parseCookies(
-  cookieHeader: string | null,
-): Record<string, string> {
-  if (!cookieHeader) return {};
-
-  const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
-
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name) {
-      const raw = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(raw);
-      } catch {
-        // Malformed percent-encoded value (e.g. %zz) - fall back to raw value
-        cookies[name] = raw;
-      }
-    }
-  }
-
-  return cookies;
-}
-
-/**
- * Serialize a cookie for Set-Cookie header
- */
-export function serializeCookie(
-  name: string,
-  value: string,
-  options: CookieOptions = {},
-): string {
-  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
-
-  if (options.domain) cookie += `; Domain=${options.domain}`;
-  if (options.path) cookie += `; Path=${options.path}`;
-  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
-  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
-  if (options.httpOnly) cookie += "; HttpOnly";
-  if (options.secure) cookie += "; Secure";
-  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
-
-  return cookie;
-}