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

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

@@ -1,104 +1,20 @@
 /**
- * React Performance Tracks — Vite plugin
+ * React Performance Tracks — RSDW client patch
  *
- * Dev-only plugin that enables Chrome DevTools Performance tab integration
- * for React Server Components. Creates a bidirectional debug channel per
- * RSC request and transports data over Vite's HMR WebSocket.
+ * 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.
  *
- * Architecture:
- * - Server: renderToReadableStream writes timing data to debugChannel.writable
- * - Transport: chunks are base64-encoded and sent via HMR custom events
- * - Client: createFromFetch reads from debugChannel.readable
- *
- * Each request gets a unique debugId (UUID) to correlate the two sides.
- *
- * Uses globalThis to share state between the Vite plugin (main process)
- * and the RSC handler (RSC module graph) — they run in the same Node.js
- * process but different module evaluation contexts.
+ * 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";
 
-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
-
-interface DebugSession {
-  cmdController?: ReadableStreamDefaultController<Uint8Array>;
-  pendingChunks?: Uint8Array[];
-  ended: boolean;
-}
-
-type DebugChannelRegistry = {
-  channels: Map<
-    string,
-    {
-      readable: ReadableStream<Uint8Array>;
-      writable: WritableStream<Uint8Array>;
-    }
-  >;
-  sessions: Map<string, DebugSession>;
-};
-
-const GLOBAL_KEY = "__RANGO_DEBUG_CHANNELS__";
-
-// Use Node.js `Module` built-in as carrier — Vite's RSC module runner
-// uses a separate VM context where both `globalThis` and `process` are
-// different objects, but built-in module singletons ARE shared.
-import { Module } from "node:module";
-function getRegistry(): DebugChannelRegistry {
-  return ((Module as any)[GLOBAL_KEY] ??= {
-    channels: new Map(),
-    sessions: new Map(),
-  });
-}
-
-/**
- * Create a debug channel for a given request.
- * Called by the RSC handler for each request that has a debugId.
- * Returns the { readable, writable } pair for renderToReadableStream.
- *
- * This works across module graphs because the channel is pre-created
- * by the Vite plugin and stored on globalThis.
- */
-export function createServerDebugChannel(debugId: string): {
-  readable: ReadableStream<Uint8Array>;
-  writable: WritableStream<Uint8Array>;
-} | null {
-  const registry = getRegistry();
-  const channel = registry.channels.get(debugId);
-  if (channel) {
-    registry.channels.delete(debugId);
-    console.log("[perf-tracks] debug channel attached for", debugId);
-    return channel;
-  }
-  console.log(
-    "[perf-tracks] no channel found for",
-    debugId,
-    "channels:",
-    registry.channels.size,
-  );
-  return null;
-}
-
-const bytesToBase64 = (bytes: Uint8Array) =>
-  Buffer.from(bytes).toString("base64");
-
-const base64ToBytes = (base64: string) =>
-  new Uint8Array(Buffer.from(base64, "base64"));
-
-// Patch for RSDW client: React's flushComponentPerformance uses splice(0) to
-// empty chunk._debugInfo after resolution, then tries to recover it from the
-// resolved value. The fallback only works for arrays, async iterables, React
-// elements, and lazy types — not plain objects. Since our RscPayload is a
-// plain object, _debugInfo is lost and the Server Components track stays empty.
-// This patch relaxes the check so _debugInfo is recovered from any object.
-//
-// Uses regex to be resilient to Vite's dep optimizer reformatting.
 const RSDW_PATCH_RE =
   /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
 
@@ -112,200 +28,61 @@ if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.stat
 }`;
 }
 
-export function performanceTracksPlugin(): Plugin {
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
   return {
-    name: "@rangojs/router:performance-tracks",
-    // configureServer + transform — naturally dev-only
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
+}
 
-    transform(code, id) {
-      // Only patch RSDW client browser bundle
-      if (!id.includes("react-server-dom") || !id.includes("client")) return;
-      const match = code.match(RSDW_PATCH_RE);
-      if (!match) return;
-      const patched = code.replace(
-        match[1]!,
-        buildPatchReplacement(match[1]!, match[2]!),
-      );
-      console.log(
-        "[perf-tracks] patched RSDW client for plain-object _debugInfo recovery (var:",
-        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",
+          };
+        },
       );
-      return patched;
     },
+  };
+}
 
-    configureServer(server) {
-      console.log("[perf-tracks] plugin loaded, configureServer called");
-      const hot = server.environments.client.hot;
-      const registry = getRegistry();
-      const sessions = registry.sessions;
-
-      const sendChunk = (debugId: string, chunk: Uint8Array) => {
-        hot.send(DEBUG_S2C_EVENT, {
-          i: debugId,
-          b: bytesToBase64(chunk),
-        } satisfies DebugPayload);
-      };
-
-      const cleanupIfEnded = (debugId: string, session: DebugSession) => {
-        if (session.pendingChunks || !session.ended) return;
-        sessions.delete(debugId);
-        hot.send(DEBUG_S2C_EVENT, {
-          i: debugId,
-          d: true,
-        } satisfies DebugPayload);
-      };
-
-      const registerDebugChannel = (debugId: string) => {
-        let session = sessions.get(debugId);
-        if (!session) {
-          session = { pendingChunks: [], ended: false };
-          sessions.set(debugId, session);
-        }
-
-        // Readable: receives client-to-server commands via WS
-        const readable = new ReadableStream<Uint8Array>({
-          start(controller) {
-            session!.cmdController = controller;
-          },
-          cancel() {
-            delete session!.cmdController;
-          },
-        });
-
-        let chunkCount = 0;
-        // Writable: React writes debug data here, we forward to client via WS
-        const writable = new WritableStream<Uint8Array>({
-          write(chunk) {
-            chunkCount++;
-            if (chunkCount <= 3) {
-              console.log(
-                "[perf-tracks] writable: chunk #" + chunkCount,
-                "size:",
-                chunk.byteLength,
-                "for",
-                debugId.slice(0, 8),
-                session!.pendingChunks ? "(buffered)" : "(sent)",
-              );
-            }
-            if (session!.pendingChunks) {
-              session!.pendingChunks.push(chunk);
-            } else {
-              sendChunk(debugId, chunk);
-            }
-          },
-          close() {
-            console.log(
-              "[perf-tracks] writable: closed after",
-              chunkCount,
-              "chunks for",
-              debugId.slice(0, 8),
-            );
-            session!.ended = true;
-            cleanupIfEnded(debugId, session!);
-          },
-          abort() {
-            session!.ended = true;
-            cleanupIfEnded(debugId, session!);
-          },
-        });
-
-        // Store on globalThis so the RSC handler can retrieve it
-        registry.channels.set(debugId, { readable, writable });
-      };
-
-      // Listen for client-to-server debug messages
-      // Payload shapes: { i, d: true } (done), { i, b } (chunk), { i } (ready)
-      hot.on(DEBUG_C2S_EVENT, (raw: unknown) => {
-        const payload = raw as { i: string; b?: string; d?: true };
-        const session = sessions.get(payload.i);
-
-        if (payload.d) {
-          if (session?.cmdController) {
-            try {
-              session.cmdController.close();
-            } catch {
-              // ignore
-            }
-            delete session.cmdController;
-          }
-          return;
-        }
-
-        if (payload.b) {
-          if (session?.cmdController) {
-            try {
-              session.cmdController.enqueue(base64ToBytes(payload.b));
-            } catch {
-              delete session!.cmdController;
-            }
-          }
-          return;
-        }
-
-        // Ready signal — flush pending chunks
-        if (session) {
-          const pending = session.pendingChunks?.length ?? 0;
-          const ended = session.ended;
-          console.log(
-            "[perf-tracks] ready signal for",
-            payload.i.slice(0, 8),
-            "pending:",
-            pending,
-            "ended:",
-            ended,
-          );
-          if (session.pendingChunks) {
-            for (const chunk of session.pendingChunks) {
-              sendChunk(payload.i, chunk);
-            }
-            delete session.pendingChunks;
-          }
-          cleanupIfEnded(payload.i, session);
-        } else {
-          console.log(
-            "[perf-tracks] ready signal for",
-            payload.i.slice(0, 8),
-            "(no session yet)",
-          );
-          sessions.set(payload.i, { ended: false });
-        }
-      });
-
-      // Create debug channels only for RSC-handled requests:
-      // - HTML page requests (SSR)
-      // - RSC partial requests (client navigation)
-      // - Requests with existing debug header (client-initiated)
-      server.middlewares.use((req: any, _res: any, next: any) => {
-        const url: string = req.url || "";
-        const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()] as string;
-        const isHtml = req.headers.accept?.includes("text/html");
-        const isRsc = url.includes("_rsc_partial");
-
-        if (!existingId && !isHtml && !isRsc) {
-          next();
-          return;
-        }
-
-        const debugId = existingId || crypto.randomUUID();
-        if (!existingId) {
-          const lowerName = DEBUG_ID_HEADER.toLowerCase();
-          req.headers[lowerName] = debugId;
-          if (req.rawHeaders) {
-            req.rawHeaders.push(DEBUG_ID_HEADER, debugId);
-          }
-        }
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
 
-        registerDebugChannel(debugId);
+    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] middleware: channel for",
-          debugId,
-          "url:",
-          url.slice(0, 80),
-          existingId ? "(client)" : isHtml ? "(SSR)" : "(RSC partial)",
+          "[perf-tracks] patched RSDW client (var:",
+          patched.debugInfoVar,
+          ")",
         );
-        next();
-      });
+      return patched.code;
     },
   };
 }

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

@@ -55,14 +55,22 @@ import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
 export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
-  console.log("[perf-tracks] rango() called, preset:", preset);
   const showBanner = resolvedOptions.banner ?? true;
 
   const plugins: 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
@@ -184,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
@@ -336,14 +347,8 @@ 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: React Performance Tracks (debugChannel transport via HMR WS)
-    // Must be before rsc() so middleware runs before RSC handler.
-    const perfPlugin = performanceTracksPlugin();
-    console.log(
-      "[perf-tracks] rango: plugin created, has configureServer:",
-      !!perfPlugin.configureServer,
-    );
-    plugins.push(perfPlugin);
+    // Dev-only: RSDW client patch for React Performance Tracks
+    plugins.push(performanceTracksPlugin());
 
     plugins.push(
       rsc({
@@ -448,7 +453,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     createRouterDiscoveryPlugin(discoveryEntryPath, {
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
-      staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
+      buildEnv: options?.buildEnv,
+      preset,
     }),
   );