@rangojs/router 0.0.0-experimental.8678bb02 → 0.0.0-experimental.87

package/src/vite/plugins/expose-internal-ids.ts

@@ -2,7 +2,12 @@ import type { Plugin, ResolvedConfig } from "vite";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 import path from "node:path";
-import { normalizePath, hashId, detectImports } from "./expose-id-utils.js";
+import {
+  normalizePath,
+  hashId,
+  makeStubId,
+  detectImports,
+} from "./expose-id-utils.js";
 import {
   transformInlineHandlers,
   type VirtualHandlerEntry,
@@ -23,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
   hasCreateLoaderImport,
@@ -34,6 +40,7 @@ import {
   transformLocationState,
   generateWholeFileStubs,
   generateExprStubs,
+  stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 
@@ -385,7 +392,9 @@ ${lazyImports.join(",\n")}
         if (stubResult) return stubResult;
       }
 
-      // --- PrerenderHandler: non-RSC stub replacement ---
+      // --- PrerenderHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Prerender() calls, replace the entire file.
+      // Mixed-export files are handled in the unified pipeline below.
       if (hasPrerenderHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -397,16 +406,6 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
-
-        const exprStubs = generateExprStubs(
-          PRERENDER_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
       }
 
       // --- PrerenderHandler: RSC build module tracking ---
@@ -467,7 +466,8 @@ ${lazyImports.join(",\n")}
         }
       }
 
-      // --- StaticHandler: non-RSC stub replacement ---
+      // --- StaticHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Static() calls, replace the entire file.
       if (hasStaticHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -479,16 +479,212 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
+      }
 
-        const exprStubs = generateExprStubs(
-          STATIC_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
+      // --- Mixed-type whole-file stub replacement (non-RSC) ---
+      // When the individual whole-file checks above fail (each only checks
+      // one type), the file has mixed exports (e.g. createLoader + Prerender).
+      // Gather ALL stub-safe bindings and check if they cover every export.
+      // If yes, replace the entire file with stubs — this strips server-only
+      // imports (node:fs, DB clients, etc.) that would crash in the browser.
+      //
+      // Only applies when the file contains Prerender/Static (the handler
+      // types that bring server-only code). Files with only loaders, handles,
+      // or locationState are handled correctly by the unified pipeline below.
+      //
+      // Loader, Prerender, and Static exports become plain { __brand, $$id }
+      // stubs. createHandle and createLocationState need their create*()
+      // functions to execute (collect registration / __rsc_ls_key), so their
+      // call expressions are preserved with only a @rangojs/router import.
+      // This strips all server-only imports while keeping the correct
+      // client contract for every export type.
+      if (!isRscEnv && (hasPrerenderHandlerCode || hasStaticHandlerCode)) {
+        const prerenderFnNames = hasPrerenderHandlerCode
+          ? getFnNames(PRERENDER_CONFIG.fnName)
+          : [];
+        const staticFnNames = hasStaticHandlerCode
+          ? getFnNames(STATIC_CONFIG.fnName)
+          : [];
+        const loaderFnNames = hasLoaderCode ? getFnNames("createLoader") : [];
+        const handleFnNames = hasHandleCode ? getFnNames("createHandle") : [];
+        const lsFnNames = hasLocationStateCode
+          ? getFnNames("createLocationState")
+          : [];
+
+        // Collect ALL recognized bindings to check export coverage
+        const allBindings: CreateExportBinding[] = [];
+        for (const fnNames of [
+          prerenderFnNames,
+          staticFnNames,
+          loaderFnNames,
+          handleFnNames,
+          lsFnNames,
+        ]) {
+          if (fnNames.length > 0) {
+            allBindings.push(...getBindings(code, fnNames));
+          }
+        }
+
+        // Check if preserved createHandle/createLocationState calls
+        // reference non-exported locals (e.g. helper functions, constants).
+        // If so, the whole-file stub would strip those locals, breaking
+        // the call. Fall through to the unified pipeline instead.
+        let canStubWholeFile =
+          allBindings.length > 0 && isExportOnlyFile(code, allBindings);
+
+        if (
+          canStubWholeFile &&
+          (handleFnNames.length > 0 || lsFnNames.length > 0)
+        ) {
+          const exportedLocals = new Set(allBindings.map((b) => b.localName));
+          // Collect bindings that would be stripped by whole-file replacement:
+          // local declarations and imported bindings from non-@rangojs/router
+          // modules. This is a regex-based heuristic — it intentionally skips
+          // edge cases (class decls, destructured bindings, combined
+          // default+named imports) since those rarely appear in route files.
+          const strippedBindings: string[] = [];
+
+          // Skip React Fast Refresh temporaries (_c, _c2, ...) which are
+          // injected by @vitejs/plugin-react in the client environment and
+          // would falsely trigger the bailout.
+          const localDeclPattern =
+            /(?:^|;|\n)\s*(?:const|let|var|function)\s+(\w+)/g;
+          let declMatch: RegExpExecArray | null;
+          while ((declMatch = localDeclPattern.exec(code)) !== null) {
+            const name = declMatch[1];
+            if (!exportedLocals.has(name) && !/^_c\d*$/.test(name)) {
+              strippedBindings.push(name);
+            }
+          }
+
+          const importPattern =
+            /import\s*\{([^}]*)\}\s*from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          let importMatch: RegExpExecArray | null;
+          while ((importMatch = importPattern.exec(code)) !== null) {
+            for (const spec of importMatch[1].split(",")) {
+              const m = spec
+                .trim()
+                .match(/^[A-Za-z_$][\w$]*(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+              if (m) strippedBindings.push(m[1] || m[0].trim().split(/\s/)[0]);
+            }
+          }
+          const defaultImportPattern =
+            /import\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = defaultImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+          const nsImportPattern =
+            /import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = nsImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+
+          if (strippedBindings.length > 0) {
+            const preservedBindings = allBindings.filter((b) => {
+              const fc = code.slice(b.callExprStart, b.callOpenParenPos + 1);
+              return (
+                handleFnNames.some((n) => fc.includes(n)) ||
+                lsFnNames.some((n) => fc.includes(n))
+              );
+            });
+            const strippedRe = new RegExp(
+              `\\b(?:${strippedBindings.join("|")})\\b`,
+            );
+            canStubWholeFile = !preservedBindings.some((b) => {
+              const expr = code.slice(b.callExprStart, b.callCloseParenPos + 1);
+              return strippedRe.test(expr);
+            });
+          }
+        }
+
+        if (canStubWholeFile) {
+          const lines: string[] = [];
+          const neededImports: string[] = [];
+          if (handleFnNames.length > 0) neededImports.push("createHandle");
+          if (lsFnNames.length > 0) neededImports.push("createLocationState");
+          if (neededImports.length > 0) {
+            lines.push(
+              `import { ${neededImports.join(", ")} } from "@rangojs/router";`,
+            );
+          }
+
+          for (const binding of allBindings) {
+            const fnCall = code.slice(
+              binding.callExprStart,
+              binding.callOpenParenPos + 1,
+            );
+            const isHandle = handleFnNames.some((n) => fnCall.includes(n));
+            const isLocationState = lsFnNames.some((n) => fnCall.includes(n));
+
+            // Aliases share the primary name's ID (matches server transforms).
+            const primaryName = binding.exportNames[0];
+            const stubId = makeStubId(filePath, primaryName, isBuild);
+
+            if (isHandle || isLocationState) {
+              // Rewrite alias to canonical name since the stub file only
+              // imports canonical names from @rangojs/router.
+              // Strip React Fast Refresh `_c = ` wrappers from args
+              // (e.g. `_c = (segments) => ...` → `(segments) => ...`)
+              const rawArgs = code
+                .slice(binding.callOpenParenPos + 1, binding.callCloseParenPos)
+                .replace(/\b_c\d*\s*=\s*/g, "");
+              const canonicalName = isHandle
+                ? "createHandle"
+                : "createLocationState";
+              const activeFnNames = isHandle ? handleFnNames : lsFnNames;
+
+              // Reconstruct the function name (handling aliases + generics)
+              let rawCallee = code.slice(
+                binding.callExprStart,
+                binding.callOpenParenPos,
+              );
+              for (const alias of activeFnNames) {
+                if (alias !== canonicalName && rawCallee.startsWith(alias)) {
+                  rawCallee = canonicalName + rawCallee.slice(alias.length);
+                  break;
+                }
+              }
+
+              if (isHandle) {
+                // createHandle checks __injectedId DURING the call, so $$id
+                // must be a parameter, not a post-call property assignment.
+                const idParam =
+                  binding.argCount === 0
+                    ? `undefined, "${stubId}"`
+                    : `, "${stubId}"`;
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs}${idParam});`,
+                );
+                lines.push(`${primaryName}.$$id = "${stubId}";`);
+              } else {
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs});`,
+                );
+                lines.push(
+                  `${primaryName}.__rsc_ls_key = "__rsc_ls_${stubId}";`,
+                );
+              }
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            } else {
+              let brand = "loader";
+              if (prerenderFnNames.some((n) => fnCall.includes(n))) {
+                brand = PRERENDER_CONFIG.brand;
+              } else if (staticFnNames.some((n) => fnCall.includes(n))) {
+                brand = STATIC_CONFIG.brand;
+              }
+              lines.push(
+                `export const ${primaryName} = { __brand: "${brand}", $$id: "${stubId}" };`,
+              );
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            }
+          }
+
+          return { code: lines.join("\n") + "\n", map: null };
+        }
       }
 
       // --- StaticHandler: RSC build module tracking ---
@@ -535,27 +731,48 @@ ${lazyImports.join(",\n")}
             isBuild,
           ) || changed;
       }
-      if (hasPrerenderHandlerCode && isRscEnv) {
+      if (hasPrerenderHandlerCode) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            PRERENDER_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          // Non-RSC mixed-export file: replace Prerender() calls with stubs
+          // on the shared MagicString so sourcemaps stay accurate.
+          changed =
+            stubHandlerExprs(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        }
       }
-      if (hasStaticHandlerCode && isRscEnv) {
+      if (hasStaticHandlerCode) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            STATIC_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              STATIC_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          changed =
+            stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
+            changed;
+        }
       }
 
       if (!changed) return;

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

@@ -1,230 +1,88 @@
 /**
- * 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";
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
 
-type DebugPayload =
-  | { i: string; b: string } // chunk (base64)
-  | { i: string; d: true }; // done
-
-interface DebugSession {
-  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;
+  }
+}`;
 }
 
-type DebugChannelRegistry = {
-  channels: Map<
-    string,
-    {
-      readable: ReadableStream<Uint8Array>;
-      writable: WritableStream<Uint8Array>;
-    }
-  >;
-  sessions: Map<string, DebugSession>;
-};
-
-const GLOBAL_KEY = "__RANGO_DEBUG_CHANNELS__";
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
 
-// 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(),
-  });
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
 }
 
-/**
- * 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;
+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",
+          };
+        },
+      );
+    },
+  };
 }
 
-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",
-    // Only configureServer hook — naturally dev-only
-
-    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;
-          },
-        });
-
-        // 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 for ALL requests — create a debug channel so
-      // the RSC handler can attach it to renderToReadableStream.
-      server.middlewares.use((req: any, _res: any, next: any) => {
-        const existingId = req.headers[DEBUG_ID_HEADER.toLowerCase()] as string;
-        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);
+    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:",
-          req.url?.slice(0, 60),
-          existingId ? "(client)" : "(server-generated)",
+          "[perf-tracks] patched RSDW client (var:",
+          patched.debugInfoVar,
+          ")",
         );
-        next();
-      });
+      return patched.code;
     },
   };
 }