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

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

@@ -1,195 +1,89 @@
 /**
- * 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.
+ * 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, ViteDevServer } from "vite";
+import type { Plugin } from "vite";
+import { readFile } from "node:fs/promises";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
-export const DEBUG_ID_HEADER = "X-RSC-Debug-Id";
-const DEBUG_S2C_EVENT = "rango:perf-s2c";
-const DEBUG_C2S_EVENT = "rango:perf-c2s";
+const debug = createRangoDebugger(NS.transform);
 
-type DebugPayload =
-  | { i: string; b: string } // chunk (base64)
-  | { i: string; d: true }; // done
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
 
-interface DebugSession {
-  // Server → Client: writable that React writes to, we read and forward via WS
-  // Server → Client: readable that client commands come into
-  cmdController?: ReadableStreamDefaultController<Uint8Array>;
-  pendingChunks?: Uint8Array[];
-  ended: boolean;
+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;
+  }
+}`;
 }
 
-const bytesToBase64 = (bytes: Uint8Array) =>
-  Buffer.from(bytes).toString("base64");
-
-const base64ToBytes = (base64: string) =>
-  new Uint8Array(Buffer.from(base64, "base64"));
-
-// Module-level registry shared with RSC handler code (same Node.js process in dev)
-let devServer: ViteDevServer | null = null;
-const sessions = new Map<string, DebugSession>();
-
-/**
- * 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.
- */
-export function createServerDebugChannel(debugId: string): {
-  readable: ReadableStream<Uint8Array>;
-  writable: WritableStream<Uint8Array>;
-} | null {
-  if (!devServer) return null;
-
-  const hot = devServer.environments.client.hot;
-  let session = sessions.get(debugId);
-  if (!session) {
-    session = { pendingChunks: [], ended: false };
-    sessions.set(debugId, session);
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
   }
 
-  const sendChunk = (chunk: Uint8Array) => {
-    hot.send(DEBUG_S2C_EVENT, {
-      i: debugId,
-      b: bytesToBase64(chunk),
-    } satisfies DebugPayload);
-  };
-
-  const flushPendingChunks = () => {
-    if (!session!.pendingChunks) return;
-    for (const chunk of session!.pendingChunks) {
-      sendChunk(chunk);
-    }
-    delete session!.pendingChunks;
-  };
-
-  const cleanupIfEnded = () => {
-    if (session!.pendingChunks || !session!.ended) return;
-    sessions.delete(debugId);
-    hot.send(DEBUG_S2C_EVENT, {
-      i: debugId,
-      d: true,
-    } satisfies DebugPayload);
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
   };
+}
 
-  // Readable: receives client-to-server commands via WS
-  const readable = new ReadableStream<Uint8Array>({
-    start(controller) {
-      session!.cmdController = controller;
-      // If client already sent "ready", flush buffered data
-      flushPendingChunks();
-      cleanupIfEnded();
-    },
-    cancel() {
-      delete session!.cmdController;
-    },
-  });
-
-  // Writable: React writes debug data here, we forward to client via WS
-  const writable = new WritableStream<Uint8Array>({
-    write(chunk) {
-      if (session!.pendingChunks) {
-        // Client not connected yet — buffer
-        session!.pendingChunks.push(chunk);
-      } else {
-        sendChunk(chunk);
-      }
-    },
-    close() {
-      session!.ended = true;
-      cleanupIfEnded();
-    },
-    abort() {
-      session!.ended = true;
-      cleanupIfEnded();
+export function performanceTracksOptimizeDepsPlugin(): {
+  name: string;
+  load(id: string): Promise<{ code: string } | null>;
+} {
+  const RSDW_CLIENT_RE =
+    /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    async load(id: string): Promise<{ code: string } | null> {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!RSDW_CLIENT_RE.test(cleanId)) return null;
+      const code = await readFile(cleanId, "utf8");
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      return { code: patched.code };
     },
-  });
-
-  return { readable, writable };
+  };
 }
 
 export function performanceTracksPlugin(): Plugin {
+  const counter = createCounter(debug, "performance-tracks");
   return {
     name: "@rangojs/router:performance-tracks",
-    apply: "serve",
-
-    configureServer(server) {
-      devServer = server;
-      const hot = server.environments.client.hot;
 
-      // Listen for client-to-server debug messages
-      hot.on(DEBUG_C2S_EVENT, (payload: DebugPayload) => {
-        const session = sessions.get(payload.i);
-
-        if ("d" in payload) {
-          // Client closed channel
-          if (session?.cmdController) {
-            try {
-              session.cmdController.close();
-            } catch {
-              // ignore
-            }
-            delete session.cmdController;
-          }
-          return;
-        }
-
-        if ("b" in payload) {
-          // Client sent command data
-          if (session?.cmdController) {
-            try {
-              session.cmdController.enqueue(base64ToBytes(payload.b));
-            } catch {
-              delete session!.cmdController;
-            }
-          }
-          return;
-        }
-      });
-
-      // Intercept requests to inject debugId
-      return () => {
-        server.middlewares.use((req, _res, next) => {
-          const existingId = req.headers[
-            DEBUG_ID_HEADER.toLowerCase()
-          ] as string;
-          const isHtml = req.headers.accept?.includes("text/html");
-
-          if (!existingId && !isHtml) {
-            next();
-            return;
-          }
-
-          // Use existing debugId from client or generate one for SSR
-          const debugId = existingId || crypto.randomUUID();
-          if (!existingId) {
-            // Inject header so the RSC handler can read it
-            const lowerName = DEBUG_ID_HEADER.toLowerCase();
-            req.headers[lowerName] = debugId;
-            if (req.rawHeaders) {
-              req.rawHeaders.push(DEBUG_ID_HEADER, debugId);
-            }
-          }
-
-          // Pre-create session so the channel is ready when handler runs
-          if (!sessions.has(debugId)) {
-            sessions.set(debugId, { pendingChunks: [], ended: false });
-          }
+    buildEnd() {
+      counter?.flush();
+    },
 
-          next();
-        });
-      };
+    transform(code, id) {
+      if (!id.includes("react-server-dom") || !id.includes("client")) return;
+      const start = counter ? performance.now() : 0;
+      try {
+        const patched = patchRsdwClientDebugInfoRecovery(code);
+        if (!patched.debugInfoVar) return;
+        debug?.("patched RSDW client (var: %s)", patched.debugInfoVar);
+        return patched.code;
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }

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
@@ -15,40 +20,100 @@ import type { Plugin } from "vite";
  */
 export function poke(): Plugin {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router: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 },
+        );
+      }
 
-      // 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);
-        }
       });
     },
   };