@rangojs/router 0.0.0-experimental.66 → 0.0.0-experimental.66f5aa51

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

@@ -14,6 +14,9 @@
 
 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*[;,])/;
@@ -45,44 +48,42 @@ export function patchRsdwClientDebugInfoRecovery(code: string): {
 
 export function performanceTracksOptimizeDepsPlugin(): {
   name: string;
-  setup(build: any): void;
+  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",
-    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",
-          };
-        },
-      );
+    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 patched = patchRsdwClientDebugInfoRecovery(code);
-      if (!patched.debugInfoVar) return;
-      if (process.env.INTERNAL_RANGO_DEBUG)
-        console.log(
-          "[perf-tracks] patched RSDW client (var:",
-          patched.debugInfoVar,
-          ")",
-        );
-      return patched.code;
+      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

@@ -20,7 +20,7 @@ import type { Plugin } from "vite";
  */
 export function poke(): Plugin {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router:poke",
     apply: "serve",
 
     configureServer(server) {

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

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

@@ -1,6 +1,7 @@
 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.
@@ -20,18 +21,7 @@ export function createVersionInjectorPlugin(
 
     configResolved(config) {
       let entryPath = rscEntryPath;
-      // Cloudflare preset: read entry from resolved environment config.
-      // The @cloudflare/vite-plugin reads wrangler config (toml/json/jsonc)
-      // and sets optimizeDeps.entries on the RSC environment.
-      if (!entryPath) {
-        const rscEnvConfig = (config.environments as any)?.["rsc"];
-        const entries = rscEnvConfig?.optimizeDeps?.entries;
-        if (typeof entries === "string") {
-          entryPath = entries;
-        } else if (Array.isArray(entries) && entries.length > 0) {
-          entryPath = entries[0];
-        }
-      }
+      if (!entryPath) entryPath = resolveRscEntryFromConfig(config);
       if (entryPath) {
         resolvedEntryPath = resolve(config.root, entryPath);
       }
@@ -39,7 +29,6 @@ export function createVersionInjectorPlugin(
 
     transform(code, id) {
       if (!resolvedEntryPath) return null;
-      // Only transform the RSC entry file
       const normalizedId = Vite.normalizePath(id);
       const normalizedEntry = Vite.normalizePath(resolvedEntryPath);
 
@@ -47,16 +36,11 @@ 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";`);
-      }
+      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 +54,21 @@ export function createVersionInjectorPlugin(
         );
       }
 
-      if (prepend.length === 0 && newCode === code) return null;
-
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      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/plugins/version-plugin.ts

@@ -1,5 +1,6 @@
 import { parseAst, type Plugin } from "vite";
 import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
 
 interface ClientModuleSignature {
   key: string;
@@ -16,30 +17,17 @@ function normalizeModuleId(id: string): string {
 function getClientModuleSignature(
   source: string,
 ): ClientModuleSignature | undefined {
+  // Same leading-directive sniff the rango HMR plugin uses (shared helper, so the
+  // two agree on what counts as a client module). A parse failure yields false.
+  if (!hasUseClientDirective(source)) return undefined;
+
   let program: any;
   try {
-    program = parseAst(source, { jsx: true });
+    program = parseAst(source, { lang: "tsx" });
   } catch {
     return undefined;
   }
 
-  let isUseClient = false;
-  for (const node of program.body ?? []) {
-    if (
-      node?.type === "ExpressionStatement" &&
-      node.expression?.type === "Literal" &&
-      typeof node.expression.value === "string"
-    ) {
-      if (node.expression.value === "use client") {
-        isUseClient = true;
-      }
-      continue;
-    }
-    break;
-  }
-
-  if (!isUseClient) return undefined;
-
   const exports = new Set<string>();
   let hasDefault = false;
   let hasExportAll = false;
@@ -133,14 +121,13 @@ export function createVersionPlugin(): Plugin {
   let currentVersion = buildVersion;
   let isDev = false;
   let server: any = null;
+  let resolvedCacheDir: string | undefined;
   const clientModuleSignatures = new Map<string, ClientModuleSignature>();
 
   let versionCounter = 0;
   const bumpVersion = (reason: string) => {
-    // Use timestamp + counter to guarantee uniqueness even when multiple
-    // bumps happen within the same millisecond (e.g. cascading HMR events).
     currentVersion = Date.now().toString(16) + String(++versionCounter);
-    console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
+    console.log(`[rango] ${reason}, version updated: ${currentVersion}`);
 
     const rscEnv = server?.environments?.rsc;
     const versionMod = rscEnv?.moduleGraph?.getModuleById(
@@ -157,6 +144,9 @@ export function createVersionPlugin(): Plugin {
 
     configResolved(config) {
       isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir
+        ? String(config.cacheDir).replace(/\\/g, "/")
+        : undefined;
     },
 
     configureServer(devServer) {
@@ -203,19 +193,15 @@ export function createVersionPlugin(): Plugin {
       return null;
     },
 
-    // Track RSC module changes and update version
     async hotUpdate(ctx) {
       if (!isDev) return;
 
-      // Check if this is an RSC environment update (not client/ssr)
-      // RSC modules affect server-rendered content and cached payloads
-      // In Vite 6, environment is accessed via `this.environment`
       const isRscModule = this.environment?.name === "rsc";
 
       if (!isRscModule) return;
 
-      // Skip re-bumping when the version virtual module itself is invalidated
-      // (our own bumpVersion() invalidates it, which re-triggers hotUpdate).
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
+
       if (
         ctx.modules.length === 1 &&
         ctx.modules[0].id === "\0" + VIRTUAL_IDS.version
@@ -230,9 +216,6 @@ export function createVersionPlugin(): Plugin {
           const source = await ctx.read();
           const nextSignature = getClientModuleSignature(source);
           if (nextSignature) {
-            // "use client" file — compare export signatures.
-            // client-component-hmr may have cleared ctx.modules, so we
-            // cannot rely on ctx.modules.length for these files.
             clientModuleSignatures.set(filePath, nextSignature);
             if (
               previousSignature &&
@@ -243,20 +226,11 @@ export function createVersionPlugin(): Plugin {
           } else {
             clientModuleSignatures.delete(filePath);
             if (!previousSignature) {
-              // Not and never was "use client" — use module graph check.
-              // ctx.modules is reliable for pure server files (only
-              // client-component-hmr clears it for "use client" modules).
               if (ctx.modules.length === 0) return;
             }
-            // Was "use client" but directive removed — boundary changed,
-            // bump below.
           }
-        } catch {
-          // Fail open: if we can't read or parse the update, invalidate.
-        }
+        } catch {}
       } else {
-        // Non-code file (json, css, etc.) — only bump if it's actually
-        // referenced by the RSC module graph.
         if (ctx.modules.length === 0) return;
       }
 
@@ -264,3 +238,26 @@ export function createVersionPlugin(): Plugin {
     },
   };
 }
+
+export function isViteDepCachePath(
+  filePath: string | undefined,
+  cacheDir?: string,
+): boolean {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (
+      normalized === normalizedCacheDir ||
+      normalized.startsWith(normalizedCacheDir + "/")
+    ) {
+      return true;
+    }
+  }
+
+  return (
+    /\/node_modules\/\.vite[^/]*\//.test(normalized) ||
+    normalized.includes("/.vite-isolated/")
+  );
+}

package/src/vite/plugins/virtual-entries.ts

@@ -1,8 +1,3 @@
-/**
- * Default virtual entry file contents for rsc-router.
- * These are used when users don't provide their own entry files.
- */
-
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
   createFromReadableStream,
@@ -14,7 +9,7 @@ import {
 import { createElement, StrictMode } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
-import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
 async function initializeApp() {
   const deps = {
@@ -25,11 +20,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
 
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
 
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(RSCRouter))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
 
@@ -51,9 +51,6 @@ export const renderHTML = createSSRHandler({
 });
 `.trim();
 
-/**
- * Generate the RSC entry content with the specified router path
- */
 export function getVirtualEntryRSC(routerPath: string): string {
   return `
 import {
@@ -87,6 +84,11 @@ export default function handler(request, env) {
     _handler = createRSCHandler({
       router,
       version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
       deps: {
         renderToReadableStream,
         decodeReply,
@@ -104,9 +106,6 @@ export default function handler(request, env) {
 `.trim();
 }
 
-/**
- * Virtual module IDs
- */
 export const VIRTUAL_IDS = {
   browser: "virtual:rsc-router/entry.browser.js",
   ssr: "virtual:rsc-router/entry.ssr.js",
@@ -114,10 +113,6 @@ export const VIRTUAL_IDS = {
   version: "@rangojs/router:version",
 } as const;
 
-/**
- * Virtual module content for version.
- * Exports VERSION - a timestamp that changes on server restart (dev) or at build time (production).
- */
 export function getVirtualVersionContent(version: string): string {
   return `export const VERSION = ${JSON.stringify(version)};`;
 }