@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1fa245e2

package/src/vite/plugin-types.ts

@@ -1,38 +1,53 @@
+// -- Build-time environment types -------------------------------------------
+
 /**
- * RSC plugin entry points configuration.
- * All entries use virtual modules by default. Specify a path to use a custom entry file.
+ * Context passed to a buildEnv factory function.
+ * Provides Vite config details for conditional env setup.
  */
-export interface RscEntries {
-  /**
-   * Path to a custom browser/client entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  client?: string;
+export interface BuildEnvFactoryContext {
+  /** Vite project root directory. */
+  root: string;
+  /** Vite mode (e.g. "development", "production"). */
+  mode: string;
+  /** Vite command ("serve" for dev, "build" for production). */
+  command: "serve" | "build";
+  /** Router deployment preset. */
+  preset: "node" | "cloudflare";
+}
 
-  /**
-   * Path to a custom SSR entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  ssr?: string;
+/**
+ * Factory function that creates build-time environment bindings.
+ * Called once at plugin startup. Return `dispose` to clean up resources.
+ */
+export type BuildEnvFactory = (
+  ctx: BuildEnvFactoryContext,
+) => Promise<BuildEnvResult> | BuildEnvResult;
 
-  /**
-   * Path to a custom RSC entry file.
-   * If not specified, a default virtual entry is used that imports the router from the `entry` option.
-   */
-  rsc?: string;
+/**
+ * Result of resolving build-time environment bindings.
+ */
+export interface BuildEnvResult {
+  /** Environment bindings available to Prerender/Static handlers via ctx.env. */
+  env: Record<string, unknown>;
+  /** Called after build completes to clean up resources (e.g., miniflare). */
+  dispose?: () => Promise<void> | void;
 }
 
 /**
- * Options for @vitejs/plugin-rsc integration
+ * Build-time environment configuration for Prerender and Static handlers.
+ *
+ * - `false` (default): no build-time env, `ctx.env` throws.
+ * - `"auto"`: calls `wrangler.getPlatformProxy()` (cloudflare preset only).
+ * - Object: used directly as `ctx.env` during build.
+ * - Factory: called once at startup, must return `{ env, dispose? }`.
  */
-export interface RscPluginOptions {
-  /**
-   * Entry points for client, ssr, and rsc environments.
-   * All entries use virtual modules by default.
-   * Specify paths only when you need custom entry files.
-   */
-  entries?: RscEntries;
-}
+export type BuildEnvOption =
+  | false
+  | "auto"
+  | Record<string, unknown>
+  | BuildEnvFactory;
+
+// -- Plugin options ---------------------------------------------------------
 
 /**
  * Base options shared by all presets
@@ -45,27 +60,16 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * Generate named-routes.gen.ts by parsing url modules at startup.
-   * Provides type-safe Handler<"name"> and href() without executing router code.
-   * Set to `false` to disable (run `npx rango extract-names` manually instead).
-   * @default true
-   */
-  staticRouteTypesGeneration?: boolean;
-
-  /**
-   * Glob patterns for files to include in route type scanning.
-   * Only files matching at least one pattern will be scanned.
-   * Patterns are relative to the project root.
-   * When unset, all .ts/.tsx files are scanned.
-   */
-  include?: string[];
-
-  /**
-   * Glob patterns for files to exclude from route type scanning.
-   * Takes precedence over `include`. Patterns are relative to the project root.
-   * Defaults to common test/build directories.
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Applies to both production build and dev on-demand
+   * prerender (`/__rsc_prerender`).
+   *
+   * This is the build-time env supplied by the Vite plugin, not the live
+   * request env. It is shared across all prerender invocations for the build.
+   *
+   * @default false
    */
-  exclude?: string[];
+  buildEnv?: BuildEnvOption;
 }
 
 /**
@@ -76,38 +80,6 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
-
-  /**
-   * Path to your router configuration file that exports the route tree.
-   * This file must export a `router` object created with `createRouter()`.
-   *
-   * When omitted, auto-discovers the router by scanning for files containing
-   * `createRouter`. If exactly one is found, it is used automatically.
-   * If multiple are found, an error is thrown with the list of candidates.
-   *
-   * @example
-   * ```ts
-   * rango({ router: './src/router.tsx' })
-   * // or simply:
-   * rango()
-   * ```
-   */
-  router?: string;
-
-  /**
-   * RSC plugin configuration. By default, rsc-router includes @vitejs/plugin-rsc
-   * with sensible defaults.
-   *
-   * Entry files (browser, ssr, rsc) are optional - if they don't exist,
-   * virtual defaults are used.
-   *
-   * - Omit or pass `true`/`{}` to use defaults (recommended)
-   * - Pass `{ entries: {...} }` to customize entry paths
-   * - Pass `false` to disable (for manual @vitejs/plugin-rsc configuration)
-   *
-   * @default true
-   */
-  rsc?: boolean | RscPluginOptions;
 }
 
 /**

package/src/vite/plugins/client-ref-dedup.ts

@@ -0,0 +1,115 @@
+import type { Plugin, ResolvedConfig } from "vite";
+
+const CLIENT_IN_SERVER_PROXY_PREFIX =
+  "virtual:vite-rsc/client-in-server-package-proxy/";
+
+/**
+ * Extract the bare package name from an absolute node_modules path.
+ * Handles scoped packages (@org/name) and nested node_modules.
+ * Returns null if the path doesn't contain a valid package reference.
+ *
+ * NOTE: This is a lossy transformation. It maps a specific submodule path
+ * (e.g., pkg/internal/context.js) to the package root (pkg). The load()
+ * hook then re-exports via the bare specifier, which resolves to the
+ * package entry point. This works for packages that barrel-export their
+ * "use client" symbols from the root, which covers the common case
+ * (component libraries like @mantine/core, @chakra-ui/react, etc.).
+ * Packages whose client symbols are only available from deep subpaths
+ * (not re-exported from the root) would lose those symbols after the
+ * rewrite. A more precise approach would resolve through the package's
+ * exports map to find the correct entry point, but that adds significant
+ * complexity for a rare edge case.
+ * See: https://github.com/cloudflare/vinext/pull/413
+ */
+export function extractPackageName(absolutePath: string): string | null {
+  // Find the last /node_modules/ segment (handles nested node_modules)
+  const marker = "/node_modules/";
+  const idx = absolutePath.lastIndexOf(marker);
+  if (idx === -1) return null;
+
+  const afterModules = absolutePath.slice(idx + marker.length);
+
+  if (afterModules.startsWith("@")) {
+    // Scoped package: @org/name
+    const parts = afterModules.split("/");
+    if (parts.length < 2 || !parts[1]) return null;
+    return `${parts[0]}/${parts[1]}`;
+  }
+
+  // Unscoped package: name
+  const name = afterModules.split("/")[0];
+  return name || null;
+}
+
+/**
+ * Vite plugin that deduplicates client references from third-party packages
+ * in dev mode.
+ *
+ * When @vitejs/plugin-rsc encounters a "use client" submodule inside a
+ * package imported from a server component, it creates a
+ * client-in-server-package-proxy virtual module that re-exports from the
+ * absolute file path. In the client environment, this absolute path bypasses
+ * Vite's pre-bundling, while direct client imports of the same package go
+ * through .vite/deps/. Two separate module instances are created, breaking
+ * React contexts (createContext runs twice, provider/consumer mismatch).
+ *
+ * This plugin intercepts absolute node_modules imports from proxy modules
+ * in the client environment and rewrites them to bare specifier imports
+ * that go through pre-bundling, ensuring a single module instance.
+ *
+ * Dev-only: production builds use the SSR manifest which handles module
+ * identity correctly.
+ */
+export function clientRefDedup(): Plugin {
+  let clientExclude: string[] = [];
+
+  return {
+    name: "@rangojs/router:client-ref-dedup",
+    enforce: "pre",
+    apply: "serve",
+
+    configResolved(config: ResolvedConfig) {
+      // Respect user's optimizeDeps.exclude — if a package is explicitly
+      // excluded from pre-bundling, we shouldn't redirect it there.
+      const clientEnv = config.environments?.["client"];
+      clientExclude =
+        clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
+    },
+
+    resolveId(source, importer, options) {
+      // Only intercept in the client environment
+      if (this.environment?.name !== "client") return;
+
+      // Only handle imports from client-in-server-package-proxy virtual modules
+      if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
+
+      // Only handle absolute node_modules paths
+      if (!source.includes("/node_modules/")) return;
+
+      // Must have an importer
+      if (!importer) return;
+
+      const packageName = extractPackageName(source);
+      if (!packageName) return;
+
+      // Don't redirect packages that are excluded from optimization
+      if (clientExclude.includes(packageName)) return;
+
+      // Return a virtual module that re-exports via bare specifier
+      return `\0rango:dedup/${packageName}`;
+    },
+
+    load(id) {
+      if (!id.startsWith("\0rango:dedup/")) return;
+
+      const packageName = id.slice("\0rango:dedup/".length);
+
+      // Re-export via bare specifier so Vite routes through pre-bundling
+      return [
+        `export * from ${JSON.stringify(packageName)};`,
+        `import * as __all__ from ${JSON.stringify(packageName)};`,
+        `export default __all__.default;`,
+      ].join("\n");
+    },
+  };
+}

package/src/vite/plugins/expose-action-id.ts

@@ -278,9 +278,7 @@ export function exposeActionId(): Plugin {
       if (!rscPluginApi) {
         throw new Error(
           "[rsc-router] Could not find @vitejs/plugin-rsc. " +
-            "@rangojs/router requires the Vite RSC plugin.\n" +
-            "The RSC plugin should be included automatically. If you disabled it with\n" +
-            "rango({ rsc: false }), add rsc() before rango() in your config.",
+            "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
 

package/src/vite/plugins/performance-tracks.ts

@@ -0,0 +1,88 @@
+/**
+ * React Performance Tracks — RSDW client patch
+ *
+ * Patches the RSDW client so _debugInfo recovery works for plain-object
+ * payloads (our RscPayload shape). Without this, the Server Components
+ * track in Chrome DevTools stays empty.
+ *
+ * React's flushComponentPerformance uses splice(0) to empty _debugInfo
+ * after resolution, then recovers it from the resolved value — but only
+ * for arrays, async iterables, React elements, and lazy types. Since our
+ * RscPayload is a plain object, _debugInfo is lost. This patch relaxes
+ * the check so _debugInfo is recovered from any object.
+ */
+
+import type { Plugin } from "vite";
+import { readFile } from "node:fs/promises";
+
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+function buildPatchReplacement(match: string, debugInfoVar: string): string {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
+
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
+}
+
+export function performanceTracksOptimizeDepsPlugin(): {
+  name: string;
+  setup(build: any): void;
+} {
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    setup(build: any): void {
+      build.onLoad(
+        {
+          filter:
+            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
+        },
+        async (args: { path: string }) => {
+          const code = await readFile(args.path, "utf8");
+          const patched = patchRsdwClientDebugInfoRecovery(code);
+          return {
+            contents: patched.code,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+
+    transform(code, id) {
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      if (!patched.debugInfoVar) return;
+      if (process.env.INTERNAL_RANGO_DEBUG)
+        console.log(
+          "[perf-tracks] patched RSDW client (var:",
+          patched.debugInfoVar,
+          ")",
+        );
+      return patched.code;
+    },
+  };
+}

package/src/vite/plugins/refresh-cmd.ts

@@ -0,0 +1,127 @@
+import type { Plugin } from "vite";
+
+/**
+ * Vite plugin that triggers a full browser reload from terminal input.
+ *
+ * This plugin is intentionally passive:
+ * - it never enables raw mode on stdin
+ * - it never restores terminal state
+ * - it reacts to Ctrl+R when that raw byte reaches the process
+ * - it also supports safe line-based fallbacks like "e" + Enter
+ *
+ * Usage:
+ * ```ts
+ * import { poke } from "@rangojs/router/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [rango(), poke()],
+ * });
+ * ```
+ */
+export function poke(): Plugin {
+  return {
+    name: "vite-plugin-poke",
+    apply: "serve",
+
+    configureServer(server) {
+      const stdin = process.stdin;
+      const debug = process.env.RANGO_POKE_DEBUG === "1";
+
+      const triggerReload = (source: string) => {
+        server.hot.send({ type: "full-reload", path: "*" });
+        server.config.logger.info(`  browser reload (${source})`, {
+          timestamp: true,
+        });
+      };
+
+      const toBuffer = (chunk: string | Buffer): Buffer => {
+        return typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+      };
+
+      const formatChunk = (chunk: string | Buffer): string => {
+        const data = toBuffer(chunk);
+        const hex = Array.from(data)
+          .map((byte) => `0x${byte.toString(16).padStart(2, "0")}`)
+          .join(" ");
+        const ascii = Array.from(data)
+          .map((byte) => {
+            if (byte >= 0x20 && byte <= 0x7e) return String.fromCharCode(byte);
+            if (byte === 0x0a) return "\\n";
+            if (byte === 0x0d) return "\\r";
+            if (byte === 0x09) return "\\t";
+            return ".";
+          })
+          .join("");
+        return `len=${data.length} hex=[${hex}] ascii="${ascii}"`;
+      };
+
+      const readCtrlR = (chunk: string | Buffer): boolean => {
+        const data =
+          typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        return data.length === 1 && data[0] === 0x12;
+      };
+
+      const readSubmittedCommands = (chunk: string | Buffer): string[] => {
+        const text = toBuffer(chunk)
+          .toString("utf8")
+          .replace(/\r\n/g, "\n")
+          .replace(/\r/g, "\n");
+
+        if (!text.includes("\n")) return [];
+
+        const lines = text.split("\n");
+        lines.pop();
+        return lines;
+      };
+
+      if (debug) {
+        server.config.logger.info(
+          `  poke debug enabled (isTTY=${stdin.isTTY ? "yes" : "no"}, isRaw=${stdin.isTTY ? (stdin.isRaw ? "yes" : "no") : "n/a"})`,
+          { timestamp: true },
+        );
+      }
+
+      if (stdin.isTTY) {
+        server.config.logger.info(
+          "  poke ready: press e + enter to reload browser (ctrl+r also works when available)",
+          { timestamp: true },
+        );
+      }
+
+      const onData = (data: string | Buffer) => {
+        if (debug) {
+          server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
+            timestamp: true,
+          });
+        }
+
+        // Only react to the exact Ctrl+R byte when some host terminal or
+        // wrapper already delivers it to this process. We intentionally do
+        // not enable raw mode here because that can steal Vite shortcuts
+        // like "r" / "q" and interfere with terminal-level controls.
+        if (readCtrlR(data)) {
+          triggerReload("ctrl+r");
+          return;
+        }
+
+        for (const command of readSubmittedCommands(data)) {
+          if (command === "e") {
+            triggerReload("e+enter");
+            return;
+          }
+
+          if (command === "\u001br") {
+            triggerReload("option+r+enter");
+            return;
+          }
+        }
+      };
+
+      stdin.on("data", onData);
+
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+      });
+    },
+  };
+}

package/src/vite/plugins/version-plugin.ts

@@ -135,8 +135,11 @@ export function createVersionPlugin(): Plugin {
   let server: any = null;
   const clientModuleSignatures = new Map<string, ClientModuleSignature>();
 
+  let versionCounter = 0;
   const bumpVersion = (reason: string) => {
-    currentVersion = Date.now().toString(16);
+    // Use timestamp + counter to guarantee uniqueness even when multiple
+    // bumps happen within the same millisecond (e.g. cascading HMR events).
+    currentVersion = Date.now().toString(16) + String(++versionCounter);
     console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
 
     const rscEnv = server?.environments?.rsc;
@@ -211,6 +214,15 @@ export function createVersionPlugin(): Plugin {
 
       if (!isRscModule) return;
 
+      // Skip re-bumping when the version virtual module itself is invalidated
+      // (our own bumpVersion() invalidates it, which re-triggers hotUpdate).
+      if (
+        ctx.modules.length === 1 &&
+        ctx.modules[0].id === "\0" + VIRTUAL_IDS.version
+      ) {
+        return;
+      }
+
       if (isCodeModule(ctx.file)) {
         const filePath = normalizeModuleId(ctx.file);
         const previousSignature = clientModuleSignatures.get(filePath);