@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/vite/index.ts

@@ -1,57 +1,16 @@
-// Plugins
-export { exposeActionId } from "./plugins/expose-action-id.js";
-export {
-  exposeInternalIds,
-  exposeRouterId,
-} from "./plugins/expose-internal-ids.js";
-export type { ExposeInternalIdsApi } from "./plugins/expose-internal-ids.js";
-export { createVersionPlugin } from "./plugins/version-plugin.js";
-export { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
-export {
-  computeProductionHash,
-  transformClientRefs,
-  hashClientRefs,
-} from "./plugins/client-ref-hashing.js";
-export { createVersionInjectorPlugin } from "./plugins/version-injector.js";
-export { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
+/**
+ * Public API for @rangojs/router/vite
+ *
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
+ */
+
+export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
 
-// Types
 export type {
-  RscEntries,
-  RscPluginOptions,
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
 } from "./plugin-types.js";
-
-// Utils
-export {
-  sharedEsbuildOptions,
-  createVirtualEntriesPlugin,
-  onwarn,
-  getManualChunks,
-} from "./utils/shared-utils.js";
-export {
-  flattenLeafEntries,
-  buildRouteToStaticPrefix,
-  jsonParseExpression,
-} from "./utils/manifest-utils.js";
-export {
-  findMatchingParenInBundle,
-  extractHandlerExportsFromChunk,
-  evictHandlerCode,
-} from "./utils/bundle-analysis.js";
-export {
-  encodePathParam,
-  runWithConcurrency,
-  groupByConcurrency,
-  notifyOnError,
-} from "./utils/prerender-utils.js";
-export { printBanner, rangoVersion } from "./utils/banner.js";
-
-// Core
-export {
-  createRouterDiscoveryPlugin,
-  VIRTUAL_ROUTES_MANIFEST_ID,
-} from "./router-discovery.js";
-export { rango } from "./rango.js";

package/src/vite/plugins/client-ref-dedup.ts

@@ -0,0 +1,115 @@
+import type { Plugin, ResolvedConfig } from "vite";
+
+const CLIENT_IN_SERVER_PROXY_PREFIX =
+  "virtual:vite-rsc/client-in-server-package-proxy/";
+
+/**
+ * Extract the bare package name from an absolute node_modules path.
+ * Handles scoped packages (@org/name) and nested node_modules.
+ * Returns null if the path doesn't contain a valid package reference.
+ *
+ * NOTE: This is a lossy transformation. It maps a specific submodule path
+ * (e.g., pkg/internal/context.js) to the package root (pkg). The load()
+ * hook then re-exports via the bare specifier, which resolves to the
+ * package entry point. This works for packages that barrel-export their
+ * "use client" symbols from the root, which covers the common case
+ * (component libraries like @mantine/core, @chakra-ui/react, etc.).
+ * Packages whose client symbols are only available from deep subpaths
+ * (not re-exported from the root) would lose those symbols after the
+ * rewrite. A more precise approach would resolve through the package's
+ * exports map to find the correct entry point, but that adds significant
+ * complexity for a rare edge case.
+ * See: https://github.com/cloudflare/vinext/pull/413
+ */
+export function extractPackageName(absolutePath: string): string | null {
+  // Find the last /node_modules/ segment (handles nested node_modules)
+  const marker = "/node_modules/";
+  const idx = absolutePath.lastIndexOf(marker);
+  if (idx === -1) return null;
+
+  const afterModules = absolutePath.slice(idx + marker.length);
+
+  if (afterModules.startsWith("@")) {
+    // Scoped package: @org/name
+    const parts = afterModules.split("/");
+    if (parts.length < 2 || !parts[1]) return null;
+    return `${parts[0]}/${parts[1]}`;
+  }
+
+  // Unscoped package: name
+  const name = afterModules.split("/")[0];
+  return name || null;
+}
+
+/**
+ * Vite plugin that deduplicates client references from third-party packages
+ * in dev mode.
+ *
+ * When @vitejs/plugin-rsc encounters a "use client" submodule inside a
+ * package imported from a server component, it creates a
+ * client-in-server-package-proxy virtual module that re-exports from the
+ * absolute file path. In the client environment, this absolute path bypasses
+ * Vite's pre-bundling, while direct client imports of the same package go
+ * through .vite/deps/. Two separate module instances are created, breaking
+ * React contexts (createContext runs twice, provider/consumer mismatch).
+ *
+ * This plugin intercepts absolute node_modules imports from proxy modules
+ * in the client environment and rewrites them to bare specifier imports
+ * that go through pre-bundling, ensuring a single module instance.
+ *
+ * Dev-only: production builds use the SSR manifest which handles module
+ * identity correctly.
+ */
+export function clientRefDedup(): Plugin {
+  let clientExclude: string[] = [];
+
+  return {
+    name: "@rangojs/router:client-ref-dedup",
+    enforce: "pre",
+    apply: "serve",
+
+    configResolved(config: ResolvedConfig) {
+      // Respect user's optimizeDeps.exclude — if a package is explicitly
+      // excluded from pre-bundling, we shouldn't redirect it there.
+      const clientEnv = config.environments?.["client"];
+      clientExclude =
+        clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
+    },
+
+    resolveId(source, importer, options) {
+      // Only intercept in the client environment
+      if (this.environment?.name !== "client") return;
+
+      // Only handle imports from client-in-server-package-proxy virtual modules
+      if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
+
+      // Only handle absolute node_modules paths
+      if (!source.includes("/node_modules/")) return;
+
+      // Must have an importer
+      if (!importer) return;
+
+      const packageName = extractPackageName(source);
+      if (!packageName) return;
+
+      // Don't redirect packages that are excluded from optimization
+      if (clientExclude.includes(packageName)) return;
+
+      // Return a virtual module that re-exports via bare specifier
+      return `\0rango:dedup/${packageName}`;
+    },
+
+    load(id) {
+      if (!id.startsWith("\0rango:dedup/")) return;
+
+      const packageName = id.slice("\0rango:dedup/".length);
+
+      // Re-export via bare specifier so Vite routes through pre-bundling
+      return [
+        `export * from ${JSON.stringify(packageName)};`,
+        `import * as __all__ from ${JSON.stringify(packageName)};`,
+        `export default __all__.default;`,
+      ].join("\n");
+    },
+  };
+}

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

@@ -1,5 +1,5 @@
 import type { Plugin } from "vite";
-import { relative, posix } from "node:path";
+import { relative } from "node:path";
 import { createHash } from "node:crypto";
 
 // Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
@@ -33,11 +33,11 @@ export function computeProductionHash(
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length),
     );
-    toHash = posix.normalize(relative(projectRoot, absPath));
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
     // /@fs/abs/path.tsx -> hash(relative(root, "/abs/path.tsx"))
     const absPath = refKey.slice(FS_PREFIX.length - 1); // keep leading /
-    toHash = posix.normalize(relative(projectRoot, absPath));
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
     // /src/Button.tsx -> hash("src/Button.tsx")
     toHash = refKey.slice(1);

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

@@ -170,6 +170,8 @@ ${lazyImports.join(",\n")}
 
       const fs = await import("node:fs/promises");
 
+      const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
+
       async function scanDir(dir: string): Promise<string[]> {
         const results: string[] = [];
         try {
@@ -177,7 +179,7 @@ ${lazyImports.join(",\n")}
           for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-              if (entry.name !== "node_modules") {
+              if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
                 results.push(...(await scanDir(fullPath)));
               }
             } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
@@ -191,8 +193,7 @@ ${lazyImports.join(",\n")}
       }
 
       try {
-        const srcDir = path.join(projectRoot, "src");
-        const files = await scanDir(srcDir);
+        const files = await scanDir(projectRoot);
 
         for (const filePath of files) {
           const content = await fs.readFile(filePath, "utf-8");

package/src/vite/plugins/refresh-cmd.ts

@@ -0,0 +1,65 @@
+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.
+ *
+ * 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;
+
+      // 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);
+      }
+
+      const onData = (data: Buffer) => {
+        if (data.length !== 1) return;
+
+        // 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");
+          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,
+          });
+        }
+      };
+
+      stdin.on("data", onData);
+
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+        if (stdin.isTTY && previousRawMode !== null) {
+          stdin.setRawMode(previousRawMode);
+        }
+      });
+    },
+  };
+}

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

@@ -97,7 +97,7 @@ export function useCacheTransform(): Plugin {
 
       // Check for function-level "use cache" / "use cache: profileName"
       // (only if there's no file-level directive but code still contains the string)
-      return transformFunctionLevelUseCache(
+      const functionResult = transformFunctionLevelUseCache(
         code,
         ast,
         filePath,
@@ -105,6 +105,13 @@ export function useCacheTransform(): Plugin {
         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));
+
+      if (functionResult) return functionResult;
     },
   };
 }
@@ -118,19 +125,38 @@ function transformFileLevelUseCache(
   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) => {
+    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);
@@ -180,7 +206,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*\w+)?$/,
+      directive: /^use cache(:\s*[\w-]+)?$/,
       runtime: (
         value: string,
         name: string,
@@ -233,3 +259,65 @@ 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,
+  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) &&
+        !VALID_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-plugin.ts

@@ -1,6 +1,116 @@
-import type { Plugin } from "vite";
+import { parseAst, type Plugin } from "vite";
 import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
 
+interface ClientModuleSignature {
+  key: string;
+}
+
+function isCodeModule(id: string): boolean {
+  return /\.(tsx?|jsx?)($|\?)/.test(id);
+}
+
+function normalizeModuleId(id: string): string {
+  return id.split("?", 1)[0];
+}
+
+function getClientModuleSignature(
+  source: string,
+): ClientModuleSignature | undefined {
+  let program: any;
+  try {
+    program = parseAst(source, { jsx: true });
+  } 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;
+
+  const collectBindingNames = (pattern: any) => {
+    if (!pattern) return;
+    if (pattern.type === "Identifier") {
+      exports.add(pattern.name);
+    } else if (pattern.type === "ObjectPattern") {
+      for (const prop of pattern.properties ?? []) {
+        if (prop?.type === "RestElement") {
+          collectBindingNames(prop.argument);
+        } else {
+          collectBindingNames(prop?.value);
+        }
+      }
+    } else if (pattern.type === "ArrayPattern") {
+      for (const el of pattern.elements ?? []) {
+        if (el?.type === "RestElement") {
+          collectBindingNames(el.argument);
+        } else {
+          collectBindingNames(el);
+        }
+      }
+    }
+  };
+
+  const collectDeclarationNames = (declaration: any) => {
+    if (!declaration) return;
+    if (declaration.type === "VariableDeclaration") {
+      for (const decl of declaration.declarations ?? []) {
+        collectBindingNames(decl?.id);
+      }
+      return;
+    }
+    collectBindingNames(declaration.id);
+  };
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") {
+      hasDefault = true;
+      continue;
+    }
+    if (node?.type === "ExportAllDeclaration") {
+      hasExportAll = true;
+      continue;
+    }
+    if (node?.type !== "ExportNamedDeclaration") continue;
+
+    collectDeclarationNames(node.declaration);
+
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") {
+        hasDefault = true;
+      } else if (typeof exportedName === "string") {
+        exports.add(exportedName);
+      }
+    }
+  }
+
+  return {
+    key: JSON.stringify({
+      default: hasDefault,
+      exportAll: hasExportAll,
+      exports: [...exports].sort(),
+    }),
+  };
+}
+
 /**
  * Plugin providing rsc-router:version virtual module.
  * Exports VERSION that changes when RSC modules change (dev) or at build time (production).
@@ -23,6 +133,20 @@ export function createVersionPlugin(): Plugin {
   let currentVersion = buildVersion;
   let isDev = false;
   let server: any = null;
+  const clientModuleSignatures = new Map<string, ClientModuleSignature>();
+
+  const bumpVersion = (reason: string) => {
+    currentVersion = Date.now().toString(16);
+    console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
+
+    const rscEnv = server?.environments?.rsc;
+    const versionMod = rscEnv?.moduleGraph?.getModuleById(
+      "\0" + VIRTUAL_IDS.version,
+    );
+    if (versionMod) {
+      rscEnv.moduleGraph.invalidateModule(versionMod);
+    }
+  };
 
   return {
     name: "@rangojs/router:version",
@@ -34,6 +158,13 @@ export function createVersionPlugin(): Plugin {
 
     configureServer(devServer) {
       server = devServer;
+
+      devServer.watcher.on("unlink", (filePath) => {
+        if (!isDev) return;
+        if (!clientModuleSignatures.has(filePath)) return;
+        clientModuleSignatures.delete(filePath);
+        bumpVersion("Client module removed");
+      });
     },
 
     resolveId(id) {
@@ -50,8 +181,27 @@ export function createVersionPlugin(): Plugin {
       return null;
     },
 
+    transform(code, id) {
+      if (!isDev || !isCodeModule(id)) return null;
+      const normalizedId = normalizeModuleId(id);
+      if (
+        !code.includes("use client") &&
+        !clientModuleSignatures.has(normalizedId)
+      ) {
+        return null;
+      }
+
+      const signature = getClientModuleSignature(code);
+      if (signature) {
+        clientModuleSignatures.set(normalizedId, signature);
+      } else {
+        clientModuleSignatures.delete(normalizedId);
+      }
+      return null;
+    },
+
     // Track RSC module changes and update version
-    hotUpdate(ctx) {
+    async hotUpdate(ctx) {
       if (!isDev) return;
 
       // Check if this is an RSC environment update (not client/ssr)
@@ -59,26 +209,46 @@ export function createVersionPlugin(): Plugin {
       // In Vite 6, environment is accessed via `this.environment`
       const isRscModule = this.environment?.name === "rsc";
 
-      if (isRscModule && ctx.modules.length > 0) {
-        // Update version when RSC modules change
-        currentVersion = Date.now().toString(16);
-        console.log(
-          `[rsc-router] RSC module changed, version updated: ${currentVersion}`,
-        );
-
-        // Invalidate the version module so it gets reloaded with new version
-        if (server) {
-          const rscEnv = server.environments?.rsc;
-          if (rscEnv?.moduleGraph) {
-            const versionMod = rscEnv.moduleGraph.getModuleById(
-              "\0" + VIRTUAL_IDS.version,
-            );
-            if (versionMod) {
-              rscEnv.moduleGraph.invalidateModule(versionMod);
+      if (!isRscModule) return;
+
+      if (isCodeModule(ctx.file)) {
+        const filePath = normalizeModuleId(ctx.file);
+        const previousSignature = clientModuleSignatures.get(filePath);
+        try {
+          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 &&
+              previousSignature.key === nextSignature.key
+            ) {
+              return;
             }
+          } 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.
         }
+      } 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;
       }
+
+      bumpVersion("RSC module changed");
     },
   };
 }