@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.b02a2fec

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

@@ -1,8 +1,13 @@
 import type { Plugin } from "vite";
 
 /**
- * Vite plugin that triggers a full browser reload when Ctrl+R is pressed
- * in the terminal running the dev server.
+ * 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
@@ -20,35 +25,95 @@ export function poke(): Plugin {
 
     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 },
+        );
+      }
 
-      // Raw mode delivers individual keystrokes as immediate single-byte
-      // events instead of waiting for Enter (cooked/line-buffered mode).
-      // Without it, Ctrl+R (0x12) is never delivered as a discrete byte.
-      // When stdin is a pipe (CI, spawned process) setRawMode is unavailable
-      // but data already arrives unbuffered, so the isTTY guard suffices.
-      const previousRawMode = stdin.isTTY ? stdin.isRaw : null;
       if (stdin.isTTY) {
-        stdin.setRawMode(true);
+        server.config.logger.info(
+          "  poke ready: press e + enter to reload browser (ctrl+r also works when available)",
+          { timestamp: true },
+        );
       }
 
-      const onData = (data: Buffer) => {
-        if (data.length !== 1) return;
+      const onData = (data: string | Buffer) => {
+        if (debug) {
+          server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
+            timestamp: true,
+          });
+        }
 
-        // Ctrl+C (0x03) — defensive fallback. This plugin enables raw mode
-        // before Vite's internal stdin handler is registered (user plugins
-        // run first), so there is a brief window where Ctrl+C would be
-        // swallowed. Re-emit SIGINT so the process exits as expected.
-        if (data[0] === 0x03) {
-          process.emit("SIGINT", "SIGINT");
+        // 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;
         }
 
-        // Ctrl+R = 0x12 in raw mode
-        if (data[0] === 0x12) {
-          server.hot.send({ type: "full-reload", path: "*" });
-          server.config.logger.info("  browser reload (ctrl+r)", {
-            timestamp: true,
-          });
+        for (const command of readSubmittedCommands(data)) {
+          if (command === "e") {
+            triggerReload("e+enter");
+            return;
+          }
+
+          if (command === "\u001br") {
+            triggerReload("option+r+enter");
+            return;
+          }
         }
       };
 
@@ -56,9 +121,6 @@ export function poke(): Plugin {
 
       server.httpServer?.on("close", () => {
         stdin.off("data", onData);
-        if (stdin.isTTY && previousRawMode !== null) {
-          stdin.setRawMode(previousRawMode);
-        }
       });
     },
   };

package/src/vite/rango.ts

@@ -61,7 +61,16 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
   // Get package resolution info (workspace vs npm install)
   const rangoAliases = getPackageAliases();
-  const excludeDeps = getExcludeDeps();
+  const excludeDeps = [
+    ...getExcludeDeps(),
+    // The public browser entry re-exports the RSDW browser client.
+    // Excluding both keeps Vite from freezing the unpatched bundle into
+    // .vite/deps before our source transforms run.
+    "@vitejs/plugin-rsc/browser",
+    // Keep the browser RSDW client out of Vite's dep optimizer so our
+    // cjs-to-esm transform can patch the real file.
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
+  ];
 
   // Mutable ref for router path (node preset only).
   // Set immediately when user-specified, or populated by the auto-discover
@@ -183,6 +192,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
     plugins.push(createVirtualEntriesPlugin(finalEntries));
 
+    // Dev-only: RSDW client patch for React Performance Tracks
+    plugins.push(performanceTracksPlugin());
+
     // Add RSC plugin with cloudflare-specific options
     // Note: loadModuleDevProxy should NOT be used with childEnvironments
     // since SSR runs in workerd alongside RSC
@@ -335,6 +347,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     // Add virtual entries plugin (RSC entry generated lazily from routerRef)
     plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
 
+    // Dev-only: RSDW client patch for React Performance Tracks
+    plugins.push(performanceTracksPlugin());
+
     plugins.push(
       rsc({
         entries: finalEntries,
@@ -438,12 +453,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     createRouterDiscoveryPlugin(discoveryEntryPath, {
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
-      staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
+      buildEnv: options?.buildEnv,
+      preset,
     }),
   );
 
-  // Dev-only: React Performance Tracks (debugChannel transport via HMR WS)
-  plugins.push(performanceTracksPlugin());
-
   return plugins;
 }

package/src/vite/router-discovery.ts

@@ -10,6 +10,8 @@ import type { Plugin } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
@@ -94,6 +96,105 @@ async function createTempRscServer(
   });
 }
 
+// ============================================================================
+// Build-Time Env Resolution
+// ============================================================================
+
+import type {
+  BuildEnvOption,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
+} from "./plugin-types.js";
+
+/**
+ * Resolve the buildEnv option into a concrete { env, dispose? } result.
+ * Handles all four input shapes: false, "auto", factory, plain object.
+ */
+async function resolveBuildEnv(
+  option: BuildEnvOption | undefined,
+  factoryCtx: BuildEnvFactoryContext,
+): Promise<BuildEnvResult | null> {
+  if (!option) return null;
+
+  if (option === "auto") {
+    if (factoryCtx.preset !== "cloudflare") {
+      throw new Error(
+        '[rsc-router] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
+          "Use a factory function or plain object for other presets.",
+      );
+    }
+    try {
+      // Resolve wrangler from the user's project root (not the router package)
+      const userRequire = createRequire(
+        resolve(factoryCtx.root, "package.json"),
+      );
+      const wranglerPath = userRequire.resolve("wrangler");
+      const { getPlatformProxy } = (await import(
+        pathToFileURL(wranglerPath).href
+      )) as {
+        getPlatformProxy: (opts?: any) => Promise<any>;
+      };
+      const proxy = await getPlatformProxy();
+      return {
+        env: proxy.env as Record<string, unknown>,
+        dispose: proxy.dispose,
+      };
+    } catch (err: any) {
+      throw new Error(
+        '[rsc-router] buildEnv: "auto" requires wrangler to be installed.\n' +
+          `Install it with: pnpm add -D wrangler\n${err.message}`,
+      );
+    }
+  }
+
+  if (typeof option === "function") {
+    return await option(factoryCtx);
+  }
+
+  // Plain object
+  return { env: option };
+}
+
+/**
+ * Acquire build-time env bindings and store on discovery state.
+ * Returns true if env was acquired, false if buildEnv is disabled.
+ */
+async function acquireBuildEnv(
+  s: DiscoveryState,
+  command: "serve" | "build",
+  mode: string,
+): Promise<boolean> {
+  const option = s.opts?.buildEnv;
+  if (!option) return false;
+
+  const result = await resolveBuildEnv(option, {
+    root: s.projectRoot,
+    mode,
+    command,
+    preset: s.opts?.preset ?? "node",
+  });
+  if (!result) return false;
+
+  s.resolvedBuildEnv = result.env;
+  s.buildEnvDispose = result.dispose ?? null;
+  return true;
+}
+
+/**
+ * Release build-time env resources and clear state.
+ */
+async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
+  if (s.buildEnvDispose) {
+    try {
+      await s.buildEnvDispose();
+    } catch (err: any) {
+      console.warn(`[rsc-router] buildEnv dispose failed: ${err.message}`);
+    }
+    s.buildEnvDispose = null;
+  }
+  s.resolvedBuildEnv = undefined;
+}
+
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *
@@ -111,6 +212,8 @@ export function createRouterDiscoveryPlugin(
   opts?: PluginOptions,
 ): Plugin {
   const s = createDiscoveryState(entryPath, opts);
+  let viteCommand: "serve" | "build" = "build";
+  let viteMode = "production";
 
   return {
     name: "@rangojs/router:discovery",
@@ -121,32 +224,20 @@ export function createRouterDiscoveryPlugin(
           __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG),
         },
       };
-      if (opts?.enableBuildPrerender) {
-        config.environments = {
-          rsc: {
-            build: {
-              rollupOptions: {
-                output: {
-                  manualChunks(id: string) {
-                    if (s.resolvedPrerenderModules?.has(id)) {
-                      return "__prerender-handlers";
-                    }
-                    if (s.resolvedStaticModules?.has(id)) {
-                      return "__static-handlers";
-                    }
-                  },
-                },
-              },
-            },
-          },
-        };
-      }
+      // Prerender/static handler modules are bundled naturally with the
+      // rest of the RSC entry.  A previous design forced them into dedicated
+      // __prerender-handlers / __static-handlers chunks via manualChunks,
+      // but Rollup hoisted all shared dependencies into those chunks,
+      // inflating them to ~1 MB with active runtime code.  Handler code is
+      // evicted in closeBundle regardless of which chunk it lands in.
       return config;
     },
 
     configResolved(config) {
       s.projectRoot = config.root;
       s.isBuildMode = config.command === "build";
+      viteCommand = config.command as "serve" | "build";
+      viteMode = config.mode;
       // Capture user's resolve aliases for the temp server
       s.userResolveAlias = config.resolve.alias;
       // Node preset: pick up auto-discovered router path from the config() hook.
@@ -217,12 +308,13 @@ export function createRouterDiscoveryPlugin(
       let prerenderTempServer: any = null;
       let prerenderNodeRegistry: Map<string, any> | null = null;
 
-      // Clean up the temporary server when the dev server shuts down
+      // Clean up the temporary server and build env when the dev server shuts down
       server.httpServer?.on("close", () => {
         if (prerenderTempServer) {
           prerenderTempServer.close().catch(() => {});
           prerenderTempServer = null;
         }
+        releaseBuildEnv(s).catch(() => {});
       });
 
       async function getOrCreateTempServer(): Promise<any | null> {
@@ -262,6 +354,9 @@ export function createRouterDiscoveryPlugin(
           // Create a temp Node.js server to run runtime discovery and generate
           // named route types (static parser can't resolve factory calls).
           try {
+            // Acquire build-time env bindings for dev prerender
+            await acquireBuildEnv(s, viteCommand, viteMode);
+
             const tempRscEnv = await getOrCreateTempServer();
             if (tempRscEnv) {
               await discoverRouters(s, tempRscEnv);
@@ -278,6 +373,9 @@ export function createRouterDiscoveryPlugin(
         }
 
         try {
+          // Acquire build-time env bindings for dev prerender (Node.js path)
+          await acquireBuildEnv(s, viteCommand, viteMode);
+
           // Set the readiness gate BEFORE discovery so early requests
           // block until manifest is populated
           const serverMod = await rscEnv.runner.import(
@@ -382,9 +480,31 @@ export function createRouterDiscoveryPlugin(
           return;
         }
 
-        // Prefer the main server's registry (Node.js preset: module runner available).
-        // Fall back to a temp server for Cloudflare where the main RSC env uses workerd.
-        let registry = mainRegistry;
+        // Import the user's entry module to force re-evaluation of any
+        // HMR-invalidated modules in the chain (entry → router → urls → handlers).
+        // This ensures createRouter() re-runs with updated handler code before
+        // we read RouterRegistry. Without this, edits to prerender handler files
+        // produce stale content because the old router instance remains registered.
+        const rscEnv = (server.environments as any)?.rsc;
+        let registry: Map<string, any> | null = null;
+        if (rscEnv?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnv.runner.import(s.resolvedEntryPath);
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server",
+            );
+            registry = serverMod.RouterRegistry ?? null;
+          } catch (err: any) {
+            console.warn(
+              `[rsc-router] Dev prerender module refresh failed: ${err.message}`,
+            );
+            res.statusCode = 500;
+            res.end(`Prerender handler error: ${err.message}`);
+            return;
+          }
+        } else {
+          registry = mainRegistry;
+        }
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).
@@ -413,6 +533,8 @@ export function createRouterDiscoveryPlugin(
               {},
               undefined,
               wantPassthrough,
+              s.resolvedBuildEnv,
+              true, // devMode: check getParams for passthrough routes
             );
             if (!result) continue;
             if (result.passthrough) continue;
@@ -601,6 +723,9 @@ export function createRouterDiscoveryPlugin(
       s.prerenderManifestEntries = null;
       s.staticManifestEntries = null;
 
+      // Acquire build-time env bindings if configured
+      await acquireBuildEnv(s, viteCommand, viteMode);
+
       let tempServer: any = null;
       // Signal to user-space code (e.g. reverse.ts) that build-time discovery
       // is active. Uses globalThis because the temp server's module runner
@@ -659,6 +784,7 @@ export function createRouterDiscoveryPlugin(
         if (tempServer) {
           await tempServer.close();
         }
+        await releaseBuildEnv(s);
       }
     },
 
@@ -719,33 +845,40 @@ export function createRouterDiscoveryPlugin(
       if (!s.resolvedPrerenderModules?.size && !s.resolvedStaticModules?.size)
         return;
 
+      // Clear maps at the start of each RSC generateBundle pass.
+      // Vite 6 multi-environment builds run RSC twice (analysis + production);
+      // clearing prevents stale/duplicate records from the analysis pass.
+      s.handlerChunkInfoMap.clear();
+      s.staticHandlerChunkInfoMap.clear();
+
       for (const [fileName, chunk] of Object.entries(bundle) as [
         string,
         any,
       ][]) {
         if (chunk.type !== "chunk") continue;
 
-        // Prerender handlers chunk
-        if (
-          fileName.includes("__prerender-handlers") &&
-          s.resolvedPrerenderModules?.size
-        ) {
+        // Scan all chunks for handler exports (handlers may land in any chunk)
+        if (s.resolvedPrerenderModules?.size) {
           const handlers = extractHandlerExportsFromChunk(
             chunk.code,
             s.resolvedPrerenderModules,
             "Prerender",
-            true,
+            false,
           );
           if (handlers.length > 0) {
-            s.handlerChunkInfo = { fileName, exports: handlers };
+            const existing = s.handlerChunkInfoMap.get(fileName);
+            if (existing) {
+              existing.exports.push(...handlers);
+            } else {
+              s.handlerChunkInfoMap.set(fileName, {
+                fileName,
+                exports: handlers,
+              });
+            }
           }
         }
 
-        // Static handlers chunk
-        if (
-          fileName.includes("__static-handlers") &&
-          s.resolvedStaticModules?.size
-        ) {
+        if (s.resolvedStaticModules?.size) {
           const handlers = extractHandlerExportsFromChunk(
             chunk.code,
             s.resolvedStaticModules,
@@ -753,7 +886,15 @@ export function createRouterDiscoveryPlugin(
             false,
           );
           if (handlers.length > 0) {
-            s.staticHandlerChunkInfo = { fileName, exports: handlers };
+            const existing = s.staticHandlerChunkInfoMap.get(fileName);
+            if (existing) {
+              existing.exports.push(...handlers);
+            } else {
+              s.staticHandlerChunkInfoMap.set(fileName, {
+                fileName,
+                exports: handlers,
+              });
+            }
           }
         }
       }

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

@@ -31,6 +31,7 @@ export function encodePathParam(value: unknown): string {
 /**
  * Substitute route params into a pattern, stripping constraint and optional
  * syntax (:param(a|b)? -> value). Also handles wildcard params (*key).
+ * Optional params not present in `params` are removed from the output.
  */
 export function substituteRouteParams(
   pattern: string,
@@ -38,6 +39,9 @@ export function substituteRouteParams(
   encode: (value: string) => string = encodeURIComponent,
 ): string {
   let result = pattern;
+  let hadOmittedOptional = false;
+
+  // First pass: substitute provided params
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
     result = result.replace(
@@ -46,6 +50,20 @@ export function substituteRouteParams(
     );
     result = result.replace(`*${key}`, encode(value));
   }
+
+  // Second pass: strip remaining optional param placeholders not in params
+  result = result.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\?/g, () => {
+    hadOmittedOptional = true;
+    return "";
+  });
+
+  // Clean up slashes from omitted optional segments
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
   return result;
 }
 

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

@@ -1,6 +1,7 @@
 import type { Plugin } 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,
@@ -35,9 +36,9 @@ const versionEsbuildPlugin = {
  * Includes the version stub plugin for all environments.
  */
 export const sharedEsbuildOptions: {
-  plugins: (typeof versionEsbuildPlugin)[];
+  plugins: any[];
 } = {
-  plugins: [versionEsbuildPlugin],
+  plugins: [versionEsbuildPlugin, performanceTracksOptimizeDepsPlugin()],
 };
 
 /**

package/src/browser/debug-channel.ts

@@ -1,93 +0,0 @@
-/**
- * Client-side debug channel for React Performance Tracks.
- *
- * Creates a bidirectional channel that communicates with the server-side
- * debug channel via Vite's HMR WebSocket. Used with createFromFetch()
- * so Chrome DevTools can display Server Components in the Performance tab.
- *
- * Dev-only — gated behind import.meta.hot.
- */
-
-export const DEBUG_ID_HEADER = "X-RSC-Debug-Id";
-const DEBUG_S2C_EVENT = "rango:perf-s2c";
-const DEBUG_C2S_EVENT = "rango:perf-c2s";
-
-type DebugPayload =
-  | { i: string; b: string } // chunk (base64)
-  | { i: string; d: true }; // done
-
-const bytesToBase64 = (bytes: Uint8Array) => {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]!);
-  }
-  return btoa(binary);
-};
-
-const base64ToBytes = (base64: string) =>
-  Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
-
-/**
- * Create a client-side debug channel for the given debugId.
- * The channel communicates with the server via Vite's HMR WebSocket.
- */
-export function createClientDebugChannel(debugId: string): {
-  readable: ReadableStream<Uint8Array>;
-  writable: WritableStream<Uint8Array>;
-} | null {
-  const hot = (import.meta as any).hot;
-  if (!hot) return null;
-
-  let closed = false;
-  let onServerData: ((payload: DebugPayload) => void) | undefined;
-
-  const cleanup = (notify?: boolean) => {
-    if (closed) return;
-    closed = true;
-    if (onServerData) {
-      hot.off(DEBUG_S2C_EVENT, onServerData);
-    }
-    if (notify) {
-      hot.send(DEBUG_C2S_EVENT, { i: debugId, d: true } satisfies DebugPayload);
-    }
-  };
-
-  // Readable: receives server-to-client debug data via HMR WS
-  const readable = new ReadableStream<Uint8Array>({
-    start(controller) {
-      onServerData = (payload: DebugPayload) => {
-        if (closed || payload.i !== debugId) return;
-        if ("b" in payload) {
-          controller.enqueue(base64ToBytes(payload.b));
-        }
-        if ("d" in payload) {
-          cleanup();
-          controller.close();
-        }
-      };
-      hot.on(DEBUG_S2C_EVENT, onServerData);
-    },
-    cancel() {
-      cleanup(true);
-    },
-  });
-
-  // Writable: sends client-to-server commands via HMR WS
-  const writable = new WritableStream<Uint8Array>({
-    write(chunk) {
-      if (closed) throw new TypeError("Channel is closed");
-      hot.send(DEBUG_C2S_EVENT, {
-        i: debugId,
-        b: bytesToBase64(chunk),
-      } satisfies DebugPayload);
-    },
-    close() {
-      cleanup(true);
-    },
-    abort() {
-      cleanup(true);
-    },
-  });
-
-  return { readable, writable };
-}