@rangojs/router 0.0.0-experimental.fa8a383a → 0.0.0-experimental.fb4fdc18

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

@@ -0,0 +1,96 @@
+/**
+ * React Performance Tracks — RSDW client patch
+ *
+ * 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.
+ *
+ * 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";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+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;
+  }
+}`;
+}
+
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: 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",
+          };
+        },
+      );
+    },
+  };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  const counter = createCounter(debug, "performance-tracks");
+  return {
+    name: "@rangojs/router:performance-tracks",
+
+    buildEnd() {
+      counter?.flush();
+    },
+
+    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
@@ -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/plugins/use-cache-transform.ts

@@ -20,6 +20,9 @@ import type { Plugin } from "vite";
 import path from "node:path";
 import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 
@@ -32,6 +35,7 @@ export function useCacheTransform(): Plugin {
   let isBuild = false;
   let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null =
     null;
+  const counter = createCounter(debug, "use-cache");
 
   return {
     name: "@rangojs/router:use-cache",
@@ -42,6 +46,10 @@ export function useCacheTransform(): Plugin {
       isBuild = config.command === "build";
     },
 
+    buildEnd() {
+      counter?.flush();
+    },
+
     async transform(code, id) {
       // Only process in RSC environment
       if (this.environment?.name !== "rsc") return;
@@ -55,63 +63,68 @@ export function useCacheTransform(): Plugin {
       // Only JS/TS files
       if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
 
-      // Lazy-load transform helpers
-      if (!rscTransforms) {
+      const start = counter ? performance.now() : 0;
+      try {
+        // Lazy-load transform helpers
+        if (!rscTransforms) {
+          try {
+            rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+          } catch {
+            return;
+          }
+        }
+
+        const {
+          hasDirective,
+          transformWrapExport,
+          transformHoistInlineDirective,
+        } = rscTransforms;
+
+        // Parse AST
+        let ast: any;
         try {
-          rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+          const { parseAst } = await import("vite");
+          ast = parseAst(code);
         } catch {
           return;
         }
-      }
-
-      const {
-        hasDirective,
-        transformWrapExport,
-        transformHoistInlineDirective,
-      } = rscTransforms;
 
-      // Parse AST
-      let ast: any;
-      try {
-        const { parseAst } = await import("vite");
-        ast = parseAst(code);
-      } catch {
-        return;
-      }
-
-      const filePath = normalizePath(path.relative(projectRoot, id));
-      const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+        const filePath = normalizePath(path.relative(projectRoot, id));
+        const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+
+        // Check for file-level "use cache"
+        if (hasDirective(ast.body, "use cache")) {
+          return transformFileLevelUseCache(
+            code,
+            ast,
+            filePath,
+            id,
+            isBuild,
+            isLayoutOrTemplate,
+            transformWrapExport,
+          );
+        }
 
-      // Check for file-level "use cache"
-      if (hasDirective(ast.body, "use cache")) {
-        return transformFileLevelUseCache(
+        // Check for function-level "use cache" / "use cache: profileName"
+        // (only if there's no file-level directive but code still contains the string)
+        const functionResult = transformFunctionLevelUseCache(
           code,
           ast,
           filePath,
           id,
           isBuild,
-          isLayoutOrTemplate,
-          transformWrapExport,
+          transformHoistInlineDirective,
         );
-      }
-
-      // Check for function-level "use cache" / "use cache: profileName"
-      // (only if there's no file-level directive but code still contains the string)
-      const functionResult = transformFunctionLevelUseCache(
-        code,
-        ast,
-        filePath,
-        id,
-        isBuild,
-        transformHoistInlineDirective,
-      );
 
-      // Always check for near-miss directives, even when valid directives
-      // exist. A file may contain both valid and invalid "use cache" directives
-      // in different functions — the invalid ones should still warn.
-      warnOnNearMissDirectives(ast, id, this.warn.bind(this));
+        // Always check for near-miss directives, even when valid directives
+        // exist. A file may contain both valid and invalid "use cache" directives
+        // in different functions — the invalid ones should still warn.
+        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
-      if (functionResult) return functionResult;
+        if (functionResult) return functionResult;
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }

package/src/vite/plugins/version-injector.ts

@@ -47,16 +47,26 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      // Prepend imports at the top of the file. ES imports are hoisted
-      // by the module system, so source position is irrelevant.
-      const prepend: string[] = [];
-      let newCode = code;
-
-      if (!code.includes("virtual:rsc-router/routes-manifest")) {
-        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
-      }
+      // Always prepend `import "virtual:rsc-router/routes-manifest"` as the
+      // first side-effect import. The manifest virtual module's `load()` hook
+      // awaits `s.discoveryDone` so that, by the time the rest of the entry
+      // including any module-level `router.reverse()` calls under `./router.js`
+      // evaluates, runtime discovery has rewritten `router.named-routes.gen.ts`
+      // with the full route table.
+      //
+      // ES module evaluation order matters here: while imports are *parsed*
+      // hoisted, side-effect imports are evaluated in source order in the
+      // dependency graph. A user-authored `import "virtual:rsc-router/..."`
+      // placed after `import "./router.js"` runs too late: the manifest
+      // gate fires after router.tsx has already crashed on a stale gen file.
+      // We always prepend; ESM dedups any user-written duplicate, so module
+      // initialization still runs once.
+      const prepend: string[] = [
+        `import "virtual:rsc-router/routes-manifest";`,
+      ];
 
       // Auto-inject VERSION if file uses createRSCHandler without version
+      let newCode = code;
       const needsVersion =
         code.includes("createRSCHandler") &&
         !code.includes("@rangojs/router:version") &&
@@ -70,9 +80,25 @@ export function createVersionInjectorPlugin(
         );
       }
 
-      if (prepend.length === 0 && newCode === code) return null;
-
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      // Insert after any leading `/// <reference ... />` triple-slash
+      // directives (and surrounding blank lines). TypeScript requires those
+      // directives to precede all other code; putting our imports above
+      // them silently demotes the directives to plain comments.
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt]!.trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt),
+      ].join("\n");
 
       return {
         code: newCode,

package/src/vite/rango.ts

@@ -12,6 +12,8 @@ import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
   getExcludeDeps,
   getPackageAliases,
+  getPublishedPackageName,
+  getVendorAliases,
 } from "./utils/package-resolution.js";
 import { findRouterFiles } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
@@ -26,6 +28,10 @@ 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";
+import { createRangoDebugger, NS } from "./debug.js";
+
+const debugConfig = createRangoDebugger(NS.config);
 
 /**
  * Vite plugin for @rangojs/router.
@@ -52,15 +58,40 @@ import { createRouterDiscoveryPlugin } from "./router-discovery.js";
  * ```
  */
 export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
+  const rangoStart = performance.now();
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
+  debugConfig?.("rango(%s) setup start", preset);
 
   const plugins: PluginOption[] = [];
 
-  // Get package resolution info (workspace vs npm install)
-  const rangoAliases = getPackageAliases();
-  const excludeDeps = getExcludeDeps();
+  // Get package resolution info (workspace vs npm install).
+  // Vendor aliases redirect the bare plugin-rsc vendor specs (which plugin-rsc
+  // itself injects into optimizeDeps.include) to absolute paths resolved from
+  // this package — so strict-pnpm consumers don't hit "Failed to resolve
+  // dependency" warnings when those deps aren't hoisted to their app root.
+  const rangoAliases = { ...getPackageAliases(), ...getVendorAliases() };
+  const excludeDeps = [
+    ...getExcludeDeps(),
+    // plugin-rsc itself injects these into the client env's
+    // optimizeDeps.include, which overrides exclude for the dep's own
+    // pre-bundle entry. What exclude still controls is how *other*
+    // pre-bundled deps treat imports of these specs (external vs inlined)
+    // via esbuildCjsExternalPlugin. The cjs-to-esm transform in
+    // plugins/cjs-to-esm.ts is the fallback for strict-pnpm consumers,
+    // where client.browser's bare include fails to resolve and Vite ends up
+    // serving the raw CJS file at dev-serve time.
+    "@vitejs/plugin-rsc/browser",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
+  ];
+
+  // Vite supports a nested `A > B` syntax in optimizeDeps.include that resolves
+  // B from A's location. We anchor transitive deps (rsc-html-stream,
+  // @vitejs/plugin-rsc/vendor/*) to @rangojs/router so pnpm consumers — where
+  // these aren't visible at the app root — can still pre-bundle them.
+  const pkg = getPublishedPackageName();
+  const nested = (spec: string) => `${pkg} > ${spec}`;
 
   // Mutable ref for router path (node preset only).
   // Set immediately when user-specified, or populated by the auto-discover
@@ -116,7 +147,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               // Pre-bundle rsc-html-stream to prevent discovery during first request
               // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
-                include: ["rsc-html-stream/client"],
+                include: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
               },
@@ -141,8 +172,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/server",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested("rsc-html-stream/server"),
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -157,7 +190,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -182,6 +217,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
@@ -267,7 +305,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "rsc-html-stream/client",
+                  nested("rsc-html-stream/client"),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -284,7 +322,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react-dom/static.edge",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+                  ),
                 ],
                 exclude: excludeDeps,
                 esbuildOptions: sharedEsbuildOptions,
@@ -297,7 +337,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                   "react",
                   "react/jsx-runtime",
                   "react/jsx-dev-runtime",
-                  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  nested(
+                    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+                  ),
                 ],
                 esbuildOptions: sharedEsbuildOptions,
               },
@@ -334,6 +376,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,
@@ -437,9 +482,16 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     createRouterDiscoveryPlugin(discoveryEntryPath, {
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
-      staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
+      buildEnv: options?.buildEnv,
+      preset,
     }),
   );
 
+  debugConfig?.(
+    "rango(%s) setup done: %d plugin(s) (%sms)",
+    preset,
+    plugins.length,
+    (performance.now() - rangoStart).toFixed(1),
+  );
   return plugins;
 }