@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

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

@@ -0,0 +1,92 @@
+/**
+ * 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",
+    // Vite 8 optimizes deps with Rolldown (Rollup-style plugin pipeline), so the
+    // pre-bundled RSDW client is patched via load() rather than esbuild's onLoad.
+    // Returning code overrides Rolldown's default filesystem read for the module.
+    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

@@ -0,0 +1,127 @@
+import type { Plugin } from "vite";
+
+/**
+ * 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
+ * import { poke } from "@rangojs/router/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [rango(), poke()],
+ * });
+ * ```
+ */
+export function poke(): Plugin {
+  return {
+    name: "vite-plugin-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 },
+        );
+      }
+
+      if (stdin.isTTY) {
+        server.config.logger.info(
+          "  poke ready: press e + enter to reload browser (ctrl+r also works when available)",
+          { timestamp: true },
+        );
+      }
+
+      const onData = (data: string | Buffer) => {
+        if (debug) {
+          server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
+            timestamp: true,
+          });
+        }
+
+        // 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;
+        }
+
+        for (const command of readSubmittedCommands(data)) {
+          if (command === "e") {
+            triggerReload("e+enter");
+            return;
+          }
+
+          if (command === "\u001br") {
+            triggerReload("option+r+enter");
+            return;
+          }
+        }
+      };
+
+      stdin.on("data", onData);
+
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+      });
+    },
+  };
+}

package/src/vite/plugins/use-cache-transform.ts

@@ -0,0 +1,338 @@
+/**
+ * "use cache" Vite Transform Plugin
+ *
+ * Detects "use cache" directives at file-level and function-level,
+ * then wraps exports with registerCachedFunction() from the cache runtime.
+ *
+ * File-level: "use cache" at top of file wraps all exports (except
+ * layout/template default exports which receive children).
+ *
+ * Function-level: "use cache: profileName" inside a function body
+ * hoists the function and wraps it.
+ *
+ * Uses transform helpers from @vitejs/plugin-rsc/transforms:
+ * - hasDirective() for file-level detection
+ * - transformWrapExport() for file-level wrapping
+ * - transformHoistInlineDirective() for function-level hoisting
+ */
+
+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";
+
+// Files whose default export receives {children} from the framework
+// and should not be wrapped (children can't be cache-keyed).
+const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+
+/**
+ * Grammar for a valid function-level directive: `use cache` optionally followed
+ * by `: <profile-name>`. The single source of truth for both the transform and
+ * the near-miss validator below.
+ */
+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",
+    enforce: "post",
+
+    configResolved(config) {
+      projectRoot = config.root;
+      isBuild = config.command === "build";
+    },
+
+    buildEnd() {
+      counter?.flush();
+    },
+
+    async transform(code, id) {
+      // Only process in RSC environment
+      if (this.environment?.name !== "rsc") return;
+
+      // Quick bail: no "use cache" in source
+      if (!code.includes("use cache")) return;
+
+      // Skip node_modules and virtual modules
+      if (id.includes("/node_modules/") || id.startsWith("\0")) return;
+
+      // Only JS/TS files
+      if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
+
+      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 {
+          const { parseAst } = await import("vite");
+          ast = parseAst(code, { lang: "tsx" });
+        } catch {
+          return;
+        }
+
+        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 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,
+        );
+
+        // Check for near-miss directives on the function-level path. The
+        // file-level branch above returns earlier (it wraps every export
+        // regardless), so this runs only when there is no file-level directive.
+        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
+
+        if (functionResult) return functionResult;
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    },
+  };
+}
+
+function transformFileLevelUseCache(
+  code: string,
+  ast: any,
+  filePath: string,
+  sourceId: string,
+  isBuild: boolean,
+  isLayoutOrTemplate: boolean,
+  transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
+) {
+  // Collect non-function exports to report after wrapping
+  const nonFunctionExports: string[] = [];
+
+  const { exportNames, output } = transformWrapExport(code, ast, {
+    runtime: (value: string, name: string) => {
+      const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
+    },
+    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);
+        return false;
+      }
+      return true;
+    },
+  });
+
+  if (nonFunctionExports.length > 0) {
+    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.`,
+    );
+  }
+
+  if (exportNames.length === 0) {
+    // Even if no exports were wrapped, strip the directive
+    const s = new MagicString(code);
+    const directive = findFileLevelDirective(ast);
+    if (directive) {
+      s.overwrite(
+        directive.start,
+        directive.end,
+        `/* "use cache" -- wrapped by rango */`,
+      );
+      return {
+        code: s.toString(),
+        map: s.generateMap({ source: sourceId, hires: "boundary" }),
+      };
+    }
+    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(
+      directive.start,
+      directive.end,
+      `/* "use cache" -- wrapped by rango */`,
+    );
+  }
+
+  return {
+    code: output.toString(),
+    map: output.generateMap({ source: sourceId, hires: "boundary" }),
+  };
+}
+
+function transformFunctionLevelUseCache(
+  code: string,
+  ast: any,
+  filePath: string,
+  sourceId: string,
+  isBuild: boolean,
+  transformHoistInlineDirective: (typeof import("@vitejs/plugin-rsc/transforms"))["transformHoistInlineDirective"],
+) {
+  try {
+    const { output, names } = transformHoistInlineDirective(code, ast, {
+      directive: USE_CACHE_DIRECTIVE_RE,
+      runtime: (
+        value: string,
+        name: string,
+        meta: { directiveMatch: RegExpMatchArray },
+      ) => {
+        const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+        const profileMatch = meta.directiveMatch[1];
+        const profileName = profileMatch
+          ? profileMatch.replace(/^:\s*/, "").trim()
+          : "default";
+        return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, ${JSON.stringify(profileName)})`;
+      },
+      rejectNonAsyncFunction: false,
+    });
+
+    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`,
+    );
+
+    return {
+      code: output.toString(),
+      map: output.generateMap({ source: sourceId, hires: "boundary" }),
+    };
+  } catch {
+    // Transform failed (e.g., syntax not supported), skip
+    return;
+  }
+}
+
+/**
+ * Find the file-level "use cache" directive AST node for removal.
+ */
+function findFileLevelDirective(
+  ast: any,
+): { start: number; end: number } | null {
+  for (const node of ast.body ?? []) {
+    if (
+      node.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string" &&
+      node.expression.value.startsWith("use cache")
+    ) {
+      return { start: node.start, end: node.end };
+    }
+  }
+  return null;
+}
+
+/**
+ * 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,
+  warn: (message: string) => void,
+): void {
+  const visit = (node: any) => {
+    if (!node || typeof node !== "object") return;
+
+    if (
+      node.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string"
+    ) {
+      const value = node.expression.value;
+      if (
+        value.startsWith("use cache") &&
+        NEAR_MISS_RE.test(value) &&
+        !USE_CACHE_DIRECTIVE_RE.test(value)
+      ) {
+        const profilePart = value.slice("use cache:".length).trim();
+        warn(
+          `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`,
+        );
+      }
+    }
+
+    // Walk into function bodies where directives appear
+    for (const key of Object.keys(node)) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          visit(item);
+        }
+      } else if (child && typeof child === "object" && child.type) {
+        visit(child);
+      }
+    }
+  };
+
+  for (const node of ast.body ?? []) {
+    visit(node);
+  }
+}

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

@@ -0,0 +1,99 @@
+import type { Plugin } from "vite";
+import { resolve } from "node:path";
+import * as Vite from "vite";
+import { resolveRscEntryFromConfig } from "../utils/shared-utils.js";
+
+/**
+ * Plugin that auto-injects VERSION and routes-manifest into custom entry.rsc files.
+ * If a custom entry.rsc file uses createRSCHandler but doesn't pass version,
+ * this transform adds the import and property automatically.
+ * Also ensures the routes-manifest virtual module is always imported.
+ * @internal
+ */
+export function createVersionInjectorPlugin(
+  rscEntryPath: string | undefined,
+): Plugin {
+  let resolvedEntryPath = "";
+
+  return {
+    name: "@rangojs/router:version-injector",
+    enforce: "pre",
+
+    configResolved(config) {
+      let entryPath = rscEntryPath;
+      if (!entryPath) entryPath = resolveRscEntryFromConfig(config);
+      if (entryPath) {
+        resolvedEntryPath = resolve(config.root, entryPath);
+      }
+    },
+
+    transform(code, id) {
+      if (!resolvedEntryPath) return null;
+      // Only transform the RSC entry file
+      const normalizedId = Vite.normalizePath(id);
+      const normalizedEntry = Vite.normalizePath(resolvedEntryPath);
+
+      if (normalizedId !== normalizedEntry) {
+        return null;
+      }
+
+      // 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") &&
+        /createRSCHandler\s*\(\s*\{/.test(code);
+
+      if (needsVersion) {
+        prepend.push(`import { VERSION } from "@rangojs/router:version";`);
+        newCode = newCode.replace(
+          /createRSCHandler\s*\(\s*\{/,
+          "createRSCHandler({\n  version: VERSION,",
+        );
+      }
+
+      // 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,
+        map: null,
+      };
+    },
+  };
+}