@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

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

@@ -0,0 +1,89 @@
+/**
+ * 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;
+  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 };
+    },
+  };
+}
+
+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
@@ -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);
-        }
       });
     },
   };

package/src/vite/plugins/server-ref-hashing.ts

@@ -0,0 +1,74 @@
+import type { Plugin } from "vite";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import { computeProductionHash } from "./client-ref-hashing.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+/**
+ * Replace dev-style server-reference ids with their production hashes. The temp
+ * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
+ * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
+ * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
+ */
+export function transformServerRefs(
+  code: string,
+  projectRoot: string,
+): string | null {
+  if (!code.includes("registerServerReference")) return null;
+
+  let hasReplacement = false;
+  const result = code.replace(
+    registerServerReferenceRegex(),
+    (match, _value: string, refKey: string) => {
+      // The temp server is not a long-lived HMR server, so ids are bare; strip a
+      // query suffix defensively so the hash matches plugin-rsc's manifest key.
+      const cleanKey = refKey.split("?")[0]!;
+      const hash = computeProductionHash(projectRoot, cleanKey);
+      if (hash === cleanKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    },
+  );
+
+  return hasReplacement ? result : null;
+}
+
+/**
+ * Server-side analog of hashClientRefs. Runs in the build-discovery temp server
+ * (a dev/serve Vite server, where plugin-rsc mints dev-style ids), rewriting
+ * registerServerReference ids to production hashes AFTER plugin-rsc's
+ * rsc:use-server transform (enforce:"post"), so the Flight serializer bakes the
+ * production hash into the stored prerender/static payloads.
+ *
+ * Without this, a server-created action embedded in a prerendered/static Flight
+ * is stored with a dev-style id that the production hash-keyed server-references
+ * manifest cannot resolve -> "server reference not found" on a build-time-cache
+ * hit. Mirrors hashClientRefs, which already does exactly this for the client
+ * half of the same payload (which is why client refs in stored Flight are
+ * already production hashes while server refs were not).
+ */
+export function hashServerRefs(projectRoot: string): Plugin {
+  const counter = createCounter(debug, "hash-server-refs");
+  return {
+    name: "@rangojs/router:hash-server-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformServerRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    },
+  };
+}

package/src/vite/plugins/server-reference-pattern.ts

@@ -0,0 +1,10 @@
+// plugin-rsc's rsc:use-server transform emits inline/exported server references
+// as `registerServerReference(<value>, "<id>", "<name>")`, where <value> is a
+// hoisted identifier (no top-level comma) and a trailing `.bind(null,
+// encryptActionBoundArgs(...))` lies OUTSIDE the call. Two plugins parse this
+// same shape -- expose-action-id ($id wrapping) and server-ref-hashing (id ->
+// production hash) -- so the pattern has a single owner here. Returns a fresh
+// /g RegExp per call to avoid sharing lastIndex state across callers.
+export function registerServerReferenceRegex(): RegExp {
+  return /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+}

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";
 
@@ -27,11 +30,14 @@ const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 // and should not be wrapped (children can't be cache-keyed).
 const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
+export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
+
 export function useCacheTransform(): Plugin {
   let projectRoot = "";
   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 +48,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 +65,60 @@ 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 {
+        if (!rscTransforms) {
+          try {
+            rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+          } catch {
+            return;
+          }
+        }
+
+        const {
+          hasDirective,
+          transformWrapExport,
+          transformHoistInlineDirective,
+        } = rscTransforms;
+
+        let ast: any;
         try {
-          rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+          const { parseAst } = await import("vite");
+          ast = parseAst(code, { lang: "tsx" });
         } 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);
+
+        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(
+        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));
+        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
-      if (functionResult) return functionResult;
+        if (functionResult) return functionResult;
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }
@@ -125,8 +132,7 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
-  // Collect non-function exports to report after wrapping
-  const nonFunctionExports: string[] = [];
+  const unconfirmedExports: string[] = [];
 
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value: string, name: string) => {
@@ -135,30 +141,38 @@ function transformFileLevelUseCache(
     },
     rejectNonAsyncFunction: false,
     filter: (name: string, meta: { isFunction?: boolean }) => {
-      // Skip default export of layout/template files (they receive children)
       if (name === "default" && isLayoutOrTemplate) return false;
-      // Non-function exports cannot be wrapped with registerCachedFunction
-      if (meta.isFunction === false) {
-        nonFunctionExports.push(name);
+      // isFunction is boolean | undefined: true = confirmed function, false =
+      // confirmed non-function, undefined = cannot tell statically (e.g. a
+      // factory/HOF initializer `const x = makeCached(fn)`). Deliberate policy:
+      // require a confirmed function and reject everything else, including
+      // indeterminate initializers that may be functions at runtime -- rewrite
+      // those as direct async functions. (Pre-#1246 plugin-rsc reported false,
+      // not undefined, here, so === false would wrongly wrap them post-bump.)
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
         return false;
       }
       return true;
     },
   });
 
-  if (nonFunctionExports.length > 0) {
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
     throw new Error(
-      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
-        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
-        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
-        `Only function exports can be cached. Either remove "use cache" from ` +
-        `the file level and add it inside individual functions, or move the ` +
-        `non-function exports to a separate module.`,
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps ` +
+        `exports that are statically-confirmed functions. ` +
+        `${plural ? "These exports are" : "This export is"} not: ` +
+        `${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Declare them directly (export async function foo() {} or ` +
+        `export const foo = async () => {}). A factory or otherwise ` +
+        `statically-indeterminate initializer (export const foo = makeCached(fn)) ` +
+        `is rejected even if it returns a function at runtime -- rewrite it as a ` +
+        `direct async function, or move non-function exports to a separate module.`,
     );
   }
 
   if (exportNames.length === 0) {
-    // Even if no exports were wrapped, strip the directive
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {
@@ -175,12 +189,10 @@ function transformFileLevelUseCache(
     return;
   }
 
-  // Prepend the import
   output.prepend(
     `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
   );
 
-  // Replace the directive with a comment
   const directive = findFileLevelDirective(ast);
   if (directive) {
     output.overwrite(
@@ -206,7 +218,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (
         value: string,
         name: string,
@@ -224,9 +236,6 @@ function transformFunctionLevelUseCache(
 
     if (names.length === 0) return;
 
-    // Use a top-level import instead of await import() — the hoisted wrapper
-    // may be placed in a non-async context (e.g., inside a synchronous
-    // urls() callback) where await is not allowed.
     output.prepend(
       `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
     );
@@ -241,9 +250,6 @@ function transformFunctionLevelUseCache(
   }
 }
 
-/**
- * Find the file-level "use cache" directive AST node for removal.
- */
 function findFileLevelDirective(
   ast: any,
 ): { start: number; end: number } | null {
@@ -260,23 +266,8 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
- */
-const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
-
-/**
- * Regex for near-miss: starts with "use cache:" but has invalid tokens.
- */
 const NEAR_MISS_RE = /^use cache:\s*.+$/;
 
-/**
- * Walk the AST looking for string literals that look like malformed
- * "use cache" directives and emit a Vite warning for each.
- *
- * This catches cases like `"use cache: bad.name"` or `"use cache: "`
- * that the transform regex silently ignores.
- */
 function warnOnNearMissDirectives(
   ast: any,
   fileId: string,
@@ -294,7 +285,7 @@ function warnOnNearMissDirectives(
       if (
         value.startsWith("use cache") &&
         NEAR_MISS_RE.test(value) &&
-        !VALID_DIRECTIVE_RE.test(value)
+        !USE_CACHE_DIRECTIVE_RE.test(value)
       ) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
@@ -304,7 +295,6 @@ function warnOnNearMissDirectives(
       }
     }
 
-    // Walk into function bodies where directives appear
     for (const key of Object.keys(node)) {
       const child = node[key];
       if (Array.isArray(child)) {