@rangojs/router 0.0.0-experimental.39 → 0.0.0-experimental.3b1deca8

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

@@ -0,0 +1,235 @@
+/**
+ * React Performance Tracks — Vite plugin
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import type { Plugin } from "vite";
+
+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"));
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+    apply: "serve",
+    enforce: "pre",
+
+    configureServer(server) {
+      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;
+          },
+        });
+
+        // Writable: React writes debug data here, we forward to client via WS
+        const writable = new WritableStream<Uint8Array>({
+          write(chunk) {
+            if (session!.pendingChunks) {
+              session!.pendingChunks.push(chunk);
+            } else {
+              sendChunk(debugId, chunk);
+            }
+          },
+          close() {
+            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) {
+          if (session.pendingChunks) {
+            for (const chunk of session.pendingChunks) {
+              sendChunk(payload.i, chunk);
+            }
+            delete session.pendingChunks;
+          }
+          cleanupIfEnded(payload.i, session);
+        } else {
+          sessions.set(payload.i, { ended: false });
+        }
+      });
+
+      // Register middleware directly (not as post-hook) so it runs
+      // BEFORE the RSC handler — the channel must exist before rendering.
+      server.middlewares.use((req: any, _res: any, next: any) => {
+        const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()] as string;
+        const isHtml = req.headers.accept?.includes("text/html");
+
+        if (!existingId && !isHtml) {
+          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);
+          }
+        }
+
+        registerDebugChannel(debugId);
+        console.log(
+          "[perf-tracks] middleware: created channel for",
+          debugId,
+          "from",
+          existingId ? "client header" : "SSR inject",
+        );
+        next();
+      });
+    },
+  };
+}

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);

package/src/vite/rango.ts

@@ -13,10 +13,7 @@ import {
   getExcludeDeps,
   getPackageAliases,
 } from "./utils/package-resolution.js";
-import {
-  createScanFilter,
-  findRouterFiles,
-} from "../build/generate-route-types.js";
+import { findRouterFiles } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import {
   sharedEsbuildOptions,
@@ -24,15 +21,12 @@ import {
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
-import type {
-  RangoOptions,
-  RangoNodeOptions,
-  RscPluginOptions,
-} from "./plugin-types.js";
+import type { RangoOptions } from "./plugin-types.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
+import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
 
 /**
  * Vite plugin for @rangojs/router.
@@ -43,7 +37,7 @@ import { createRouterDiscoveryPlugin } from "./router-discovery.js";
  * @example Node.js (default)
  * ```ts
  * export default defineConfig({
- *   plugins: [react(), rango({ router: './src/router.tsx' })],
+ *   plugins: [react(), rango()],
  * });
  * ```
  *
@@ -69,9 +63,6 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const rangoAliases = getPackageAliases();
   const excludeDeps = getExcludeDeps();
 
-  // Track RSC entry path for version injection
-  let rscEntryPath: string | null = null;
-
   // Mutable ref for router path (node preset only).
   // Set immediately when user-specified, or populated by the auto-discover
   // config() hook using Vite's resolved root.
@@ -207,198 +198,148 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     // packages that are also imported directly by client components.
     plugins.push(clientRefDedup());
   } else {
-    // Node preset: full RSC plugin integration
-    const nodeOptions = resolvedOptions as RangoNodeOptions;
+    // Auto-discover router using Vite's resolved root (not process.cwd())
+    plugins.push({
+      name: "@rangojs/router:auto-discover",
+      config(userConfig) {
+        if (routerRef.path) return;
+        const root = userConfig.root
+          ? resolve(process.cwd(), userConfig.root)
+          : process.cwd();
+        const candidates = findRouterFiles(root);
+        if (candidates.length === 1) {
+          const abs = candidates[0];
+          routerRef.path = (
+            abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs
+          ).replaceAll("\\", "/");
+        } else if (candidates.length > 1) {
+          const list = candidates
+            .map(
+              (f) =>
+                "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f),
+            )
+            .join("\n");
+          throw new Error(`[rsc-router] Multiple routers found:\n${list}`);
+        }
+        // 0 found: routerRef.path stays undefined, warn at startup via discovery plugin
+      },
+    });
 
-    routerRef.path = nodeOptions.router;
+    // Always use virtual entries for client, ssr, and rsc
+    const finalEntries = {
+      client: VIRTUAL_IDS.browser,
+      ssr: VIRTUAL_IDS.ssr,
+      rsc: VIRTUAL_IDS.rsc,
+    };
 
-    // Auto-discover router using Vite's resolved root (not process.cwd())
-    if (!routerRef.path) {
-      plugins.push({
-        name: "@rangojs/router:auto-discover",
-        config(userConfig) {
-          if (routerRef.path) return;
-          const root = userConfig.root
-            ? resolve(process.cwd(), userConfig.root)
-            : process.cwd();
-          const filter = createScanFilter(root, {
-            include: resolvedOptions.include,
-            exclude: resolvedOptions.exclude,
-          });
-          const candidates = findRouterFiles(root, filter);
-          if (candidates.length === 1) {
-            const abs = candidates[0];
-            routerRef.path = (
-              abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs
-            ).replaceAll("\\", "/");
-          } else if (candidates.length > 1) {
-            const list = candidates
-              .map(
-                (f) =>
-                  "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f),
-              )
-              .join("\n");
-            throw new Error(
-              `[rsc-router] Multiple routers found. Specify \`router\` to choose one:\n${list}`,
-            );
-          }
-          // 0 found: routerRef.path stays undefined, warn at startup via discovery plugin
-        },
-      });
-    }
-
-    const rscOption = nodeOptions.rsc ?? true;
-
-    // Add RSC plugin by default (can be disabled with rsc: false)
-    if (rscOption !== false) {
-      // Dynamically import @vitejs/plugin-rsc
-      const { default: rsc } = await import("@vitejs/plugin-rsc");
-
-      // Resolve entry paths: use explicit config or virtual modules
-      const userEntries =
-        typeof rscOption === "boolean" ? {} : rscOption.entries || {};
-      const finalEntries = {
-        client: userEntries.client ?? VIRTUAL_IDS.browser,
-        ssr: userEntries.ssr ?? VIRTUAL_IDS.ssr,
-        rsc: userEntries.rsc ?? VIRTUAL_IDS.rsc,
-      };
-
-      // Track RSC entry for version injection (only if custom entry provided)
-      rscEntryPath = userEntries.rsc ?? null;
-
-      // Create wrapper plugin that checks for duplicates
-      let hasWarnedDuplicate = false;
-
-      plugins.push({
-        name: "@rangojs/router:rsc-integration",
-        enforce: "pre",
-
-        config() {
-          // Configure environments for RSC
-          // When using virtual entries, we need to explicitly configure optimizeDeps
-          // so Vite pre-bundles React before processing the virtual modules.
-          // Without this, the dep optimizer may run multiple times with different hashes,
-          // causing React instance mismatches.
-          const useVirtualClient = finalEntries.client === VIRTUAL_IDS.browser;
-          const useVirtualSSR = finalEntries.ssr === VIRTUAL_IDS.ssr;
-          const useVirtualRSC = finalEntries.rsc === VIRTUAL_IDS.rsc;
-
-          return {
-            // Exclude rsc-router modules from optimization to prevent module duplication
-            // This ensures the same Context instance is used by both browser entry and RSC proxy modules
-            optimizeDeps: {
-              exclude: excludeDeps,
-              esbuildOptions: sharedEsbuildOptions,
-            },
-            build: {
-              rollupOptions: { onwarn },
-            },
-            resolve: {
-              alias: rangoAliases,
-            },
-            environments: {
-              client: {
-                build: {
-                  rollupOptions: {
-                    output: {
-                      manualChunks: getManualChunks,
-                    },
+    // Dynamically import @vitejs/plugin-rsc
+    const { default: rsc } = await import("@vitejs/plugin-rsc");
+
+    let hasWarnedDuplicate = false;
+
+    plugins.push({
+      name: "@rangojs/router:rsc-integration",
+      enforce: "pre",
+
+      config() {
+        return {
+          optimizeDeps: {
+            exclude: excludeDeps,
+            esbuildOptions: sharedEsbuildOptions,
+          },
+          build: {
+            rollupOptions: { onwarn },
+          },
+          resolve: {
+            alias: rangoAliases,
+          },
+          environments: {
+            client: {
+              build: {
+                rollupOptions: {
+                  output: {
+                    manualChunks: getManualChunks,
                   },
                 },
-                // Always exclude rsc-router modules, conditionally add virtual entry
-                optimizeDeps: {
-                  // Pre-bundle React and rsc-html-stream to prevent late discovery
-                  // triggering ERR_OUTDATED_OPTIMIZED_DEP on cold starts
-                  include: [
-                    "react",
-                    "react-dom",
-                    "react/jsx-runtime",
-                    "react/jsx-dev-runtime",
-                    "rsc-html-stream/client",
-                  ],
-                  exclude: excludeDeps,
-                  esbuildOptions: sharedEsbuildOptions,
-                  ...(useVirtualClient && {
-                    // Tell Vite to scan the virtual entry for dependencies
-                    entries: [VIRTUAL_IDS.browser],
-                  }),
-                },
               },
-              ...(useVirtualSSR && {
-                ssr: {
-                  optimizeDeps: {
-                    entries: [VIRTUAL_IDS.ssr],
-                    // Pre-bundle all SSR deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
-                    include: [
-                      "react",
-                      "react-dom",
-                      "react-dom/server.edge",
-                      "react-dom/static.edge",
-                      "react/jsx-runtime",
-                      "react/jsx-dev-runtime",
-                      "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
-                    ],
-                    exclude: excludeDeps,
-                    esbuildOptions: sharedEsbuildOptions,
-                  },
-                },
-              }),
-              ...(useVirtualRSC && {
-                rsc: {
-                  optimizeDeps: {
-                    entries: [VIRTUAL_IDS.rsc],
-                    // Pre-bundle all RSC deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
-                    include: [
-                      "react",
-                      "react/jsx-runtime",
-                      "react/jsx-dev-runtime",
-                      "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
-                    ],
-                    esbuildOptions: sharedEsbuildOptions,
-                  },
-                },
-              }),
+              optimizeDeps: {
+                include: [
+                  "react",
+                  "react-dom",
+                  "react/jsx-runtime",
+                  "react/jsx-dev-runtime",
+                  "rsc-html-stream/client",
+                ],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions,
+                entries: [VIRTUAL_IDS.browser],
+              },
             },
-          };
-        },
-
-        configResolved(config) {
-          if (showBanner) {
-            const mode =
-              config.command === "serve"
-                ? process.argv.includes("preview")
-                  ? "preview"
-                  : "dev"
-                : "build";
-            printBanner(mode, "node", rangoVersion);
-          }
-
-          // Count how many RSC base plugins there are (rsc:minimal is the main one)
-          const rscMinimalCount = config.plugins.filter(
-            (p) => p.name === "rsc:minimal",
-          ).length;
-
-          if (rscMinimalCount > 1 && !hasWarnedDuplicate) {
-            hasWarnedDuplicate = true;
-            console.warn(
-              "[rsc-router] Duplicate @vitejs/plugin-rsc detected. " +
-                "Remove rsc() from your config or use rango({ rsc: false }) for manual configuration.",
-            );
-          }
-        },
-      });
-
-      // Add virtual entries plugin (RSC entry generated lazily from routerRef)
-      plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
-
-      // Add the RSC plugin directly
-      // Cast to PluginOption to handle type differences between bundled vite types
-      plugins.push(
-        rsc({
-          entries: finalEntries,
-        }) as PluginOption,
-      );
-    }
+            ssr: {
+              optimizeDeps: {
+                entries: [VIRTUAL_IDS.ssr],
+                include: [
+                  "react",
+                  "react-dom",
+                  "react-dom/server.edge",
+                  "react-dom/static.edge",
+                  "react/jsx-runtime",
+                  "react/jsx-dev-runtime",
+                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                ],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions,
+              },
+            },
+            rsc: {
+              optimizeDeps: {
+                entries: [VIRTUAL_IDS.rsc],
+                include: [
+                  "react",
+                  "react/jsx-runtime",
+                  "react/jsx-dev-runtime",
+                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                ],
+                esbuildOptions: sharedEsbuildOptions,
+              },
+            },
+          },
+        };
+      },
+
+      configResolved(config) {
+        if (showBanner) {
+          const mode =
+            config.command === "serve"
+              ? process.argv.includes("preview")
+                ? "preview"
+                : "dev"
+              : "build";
+          printBanner(mode, "node", rangoVersion);
+        }
+
+        const rscMinimalCount = config.plugins.filter(
+          (p) => p.name === "rsc:minimal",
+        ).length;
+
+        if (rscMinimalCount > 1 && !hasWarnedDuplicate) {
+          hasWarnedDuplicate = true;
+          console.warn(
+            "[rsc-router] Duplicate @vitejs/plugin-rsc detected. " +
+              "Remove rsc() from your vite config — rango() includes it automatically.",
+          );
+        }
+      },
+    });
+
+    // Add virtual entries plugin (RSC entry generated lazily from routerRef)
+    plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+
+    plugins.push(
+      rsc({
+        entries: finalEntries,
+      }) as PluginOption,
+    );
 
     // Deduplicate client references from third-party packages in dev mode.
     // Prevents module duplication when server components import "use client"
@@ -479,14 +420,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   // Ref for deferred auto-discovery (node preset only, undefined for cloudflare)
   const discoveryRouterRef = preset !== "cloudflare" ? routerRef : undefined;
 
-  // Version injector: auto-injects VERSION and routes-manifest into custom entry.rsc files.
-  // Only applies when there's an explicit rscEntryPath or for cloudflare preset (resolved
-  // lazily in configResolved). For node preset without a custom entry, the router file
-  // must NOT be transformed — injecting routes-manifest there creates a circular dependency.
-  const injectorEntryPath =
-    rscEntryPath ?? (preset === "cloudflare" ? undefined : null);
-  if (injectorEntryPath !== null) {
-    plugins.push(createVersionInjectorPlugin(injectorEntryPath));
+  // Version injector: auto-injects VERSION and routes-manifest into the RSC entry.
+  // For cloudflare preset, the entry is resolved lazily in configResolved.
+  // For node preset, the virtual entry already includes these imports.
+  if (preset === "cloudflare") {
+    plugins.push(createVersionInjectorPlugin(undefined));
   }
 
   // Transform CJS vendor files to ESM for browser compatibility
@@ -501,10 +439,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
       staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
-      include: resolvedOptions.include,
-      exclude: resolvedOptions.exclude,
     }),
   );
 
+  // Dev-only: React Performance Tracks (debugChannel transport via HMR WS)
+  plugins.push(performanceTracksPlugin());
+
   return plugins;
 }