@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/vite/discovery/prerender-collection.ts

@@ -9,16 +9,18 @@
 import { contextSet } from "../../context-var.js";
 import {
   encodePathParam,
-  escapeRegExp,
+  substituteRouteParams,
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
+  stageBuildAssetModule,
 } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
  * Expand prerender routes into concrete URLs and render them via the
- * RSC runner. Stores collected data in state.prerenderCollectedData.
+ * RSC runner. Stages asset modules and stores key-to-file entries in
+ * state.prerenderManifestEntries.
  */
 export async function expandPrerenderRoutes(
   state: DiscoveryState,
@@ -33,6 +35,7 @@ export async function expandPrerenderRoutes(
     routeName: string;
     concurrency: number;
     buildVars?: Record<string, any>;
+    isPassthroughRoute?: boolean;
   };
   const entries: PrerenderEntry[] = [];
 
@@ -44,19 +47,8 @@ export async function expandPrerenderRoutes(
   const getParamsReverse = (name: string, params?: Record<string, string>) => {
     const pattern = allRoutes[name];
     if (!pattern) throw new Error(`Unknown route: "${name}"`);
-    let result = pattern;
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        // Strip constraint syntax: :param(a|b) -> value
-        const escaped = escapeRegExp(key);
-        result = result.replace(
-          new RegExp(`:${escaped}(\\([^)]*\\))?`),
-          encodeURIComponent(value),
-        );
-        result = result.replace(`*${key}`, encodeURIComponent(value));
-      }
-    }
-    return result;
+    if (!params) return pattern;
+    return substituteRouteParams(pattern, params);
   };
 
   for (const { manifest } of allManifests) {
@@ -65,6 +57,8 @@ export async function expandPrerenderRoutes(
     for (const routeName of manifest.prerenderRoutes) {
       const pattern = manifest.routeManifest[routeName];
       if (!pattern) continue;
+      const def = defs[routeName];
+      const isPassthroughRoute = !!def?.options?.passthrough;
       const hasDynamic = pattern.includes(":") || pattern.includes("*");
       if (!hasDynamic) {
         // Static route: use pattern directly (strip trailing slash for URL)
@@ -72,10 +66,10 @@ export async function expandPrerenderRoutes(
           urlPath: pattern.replace(/\/$/, "") || "/",
           routeName,
           concurrency: 1,
+          isPassthroughRoute,
         });
       } else {
         // Dynamic route: call getParams() to enumerate param combinations
-        const def = defs[routeName];
         if (def?.getParams) {
           try {
             const buildVars: Record<string, any> = {};
@@ -92,19 +86,11 @@ export async function expandPrerenderRoutes(
               Object.keys(buildVars).length > 0 ||
               Object.getOwnPropertySymbols(buildVars).length > 0;
             for (const params of paramsList) {
-              let url = pattern;
-              for (const [key, value] of Object.entries(
+              let url = substituteRouteParams(
+                pattern,
                 params as Record<string, string>,
-              )) {
-                const encoded = encodePathParam(value);
-                // Strip constraint syntax: :param(a|b) -> value
-                const escaped = escapeRegExp(key);
-                url = url.replace(
-                  new RegExp(`:${escaped}(\\([^)]*\\))?`),
-                  encoded,
-                );
-                url = url.replace(`*${key}`, encoded);
-              }
+                encodePathParam,
+              );
               // Anonymous wildcard fallback: use conventional keys if provided
               if (url.includes("*")) {
                 const wildcardValue =
@@ -119,6 +105,7 @@ export async function expandPrerenderRoutes(
                 routeName,
                 concurrency,
                 ...(hasBuildVars ? { buildVars } : {}),
+                isPassthroughRoute,
               });
             }
           } catch (err: any) {
@@ -165,7 +152,7 @@ export async function expandPrerenderRoutes(
 
   const { hashParams } = await rscEnv.runner.import("@rangojs/router/build");
 
-  const collectedData: Record<string, any> = {};
+  const manifestEntries: Record<string, string> = {};
   let doneCount = 0;
   let skipCount = 0;
   const startTotal = performance.now();
@@ -187,21 +174,45 @@ export async function expandPrerenderRoutes(
               entry.urlPath,
               {},
               entry.buildVars,
+              entry.isPassthroughRoute,
             );
             if (!result) continue;
+
+            // Handler returned ctx.passthrough() — skip manifest entry
+            if (result.passthrough) {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
+              );
+              doneCount++;
+              break;
+            }
+
             const paramHash = hashParams(result.params || {});
-            collectedData[`${result.routeName}/${paramHash}`] = {
+            const mainKey = `${result.routeName}/${paramHash}`;
+            const mainValue = JSON.stringify({
               segments: result.segments,
               handles: result.handles,
-            };
+            });
+            manifestEntries[mainKey] = stageBuildAssetModule(
+              state.projectRoot,
+              "__pr",
+              mainValue,
+            );
             if (result.interceptSegments?.length) {
-              collectedData[`${result.routeName}/${paramHash}/i`] = {
+              const interceptKey = `${result.routeName}/${paramHash}/i`;
+              const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
                 handles: {
                   ...result.handles,
                   ...(result.interceptHandles || {}),
                 },
-              };
+              });
+              manifestEntries[interceptKey] = stageBuildAssetModule(
+                state.projectRoot,
+                "__pr",
+                interceptValue,
+              );
             }
             const elapsed = (performance.now() - startUrl).toFixed(0);
             console.log(
@@ -247,7 +258,7 @@ export async function expandPrerenderRoutes(
 
   const totalElapsed = (performance.now() - startTotal).toFixed(0);
   if (doneCount > 0) {
-    state.prerenderCollectedData = collectedData;
+    state.prerenderManifestEntries = manifestEntries;
   }
   const parts = [`${doneCount} done`];
   if (skipCount > 0) parts.push(`${skipCount} skipped`);
@@ -259,7 +270,8 @@ export async function expandPrerenderRoutes(
 /**
  * Render Static handlers at build time. Each Static handler is called
  * with a synthetic BuildContext and its output is RSC-serialized.
- * Stores collected data in state.staticCollectedData.
+ * Stages asset modules and stores handlerId-to-file entries in
+ * state.staticManifestEntries.
  */
 export async function renderStaticHandlers(
   state: DiscoveryState,
@@ -273,10 +285,7 @@ export async function renderStaticHandlers(
   )
     return;
 
-  const collected: Record<
-    string,
-    { encoded: string; handles: Record<string, unknown[]> }
-  > = {};
+  const manifestEntries: Record<string, string> = {};
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
@@ -319,7 +328,15 @@ export async function renderStaticHandlers(
             (def as any).$$routePrefix,
           );
           if (result) {
-            collected[def.$$id] = result;
+            const hasHandles = Object.keys(result.handles).length > 0;
+            const exportValue = hasHandles
+              ? JSON.stringify(result)
+              : JSON.stringify(result.encoded);
+            manifestEntries[def.$$id] = stageBuildAssetModule(
+              state.projectRoot,
+              "__st",
+              exportValue,
+            );
             const elapsed = (performance.now() - startHandler).toFixed(0);
             console.log(
               `[rsc-router]   OK   ${name.padEnd(40)} (${elapsed}ms)`,
@@ -358,7 +375,7 @@ export async function renderStaticHandlers(
 
   const totalStaticElapsed = (performance.now() - startStatic).toFixed(0);
   if (staticDone > 0) {
-    state.staticCollectedData = collected;
+    state.staticManifestEntries = manifestEntries;
   }
   const staticParts = [`${staticDone} done`];
   if (staticSkip > 0) staticParts.push(`${staticSkip} skipped`);

package/src/vite/discovery/route-types-writer.ts

@@ -15,20 +15,20 @@ import {
 } from "../../build/generate-route-types.js";
 import type { DiscoveryState } from "./state.js";
 import { markSelfGenWrite } from "./self-gen-tracking.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
 
 /**
  * Filter out auto-generated route names from a manifest.
- * Routes with names starting with "$" are internal (auto-generated from
- * patterns for unnamed routes) and should not appear in the typed gen file.
- * This keeps the runtime writer's output consistent with the static parser,
- * which never produces these names.
+ * Unnamed routes get "$path_"-prefixed names at runtime (see path-helper.ts).
+ * These should not appear in the typed gen file. User-defined names
+ * containing "$" (e.g. "$admin") are valid and preserved.
  */
 function filterUserNamedRoutes(
   manifest: Record<string, string>,
 ): Record<string, string> {
   const filtered: Record<string, string> = {};
   for (const [name, pattern] of Object.entries(manifest)) {
-    if (!name.startsWith("$")) {
+    if (!isAutoGeneratedRouteName(name)) {
       filtered[name] = pattern;
     }
   }
@@ -222,8 +222,8 @@ export function supplementGenFilesWithRuntimeRoutes(
     };
 
     for (const [name, pattern] of Object.entries(routeManifest)) {
-      // Skip auto-generated names
-      if (name.startsWith("$")) continue;
+      // Skip internal runtime-only names from unnamed routes/includes.
+      if (isAutoGeneratedRouteName(name)) continue;
       const dotIdx = name.indexOf(".");
       if (dotIdx <= 0) continue;
       const prefix = name.substring(0, dotIdx + 1);

package/src/vite/discovery/state.ts

@@ -13,8 +13,6 @@ export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 export interface PluginOptions {
   enableBuildPrerender?: boolean;
   staticRouteTypesGeneration?: boolean;
-  include?: string[];
-  exclude?: string[];
   // Mutable ref for deferred auto-discovery (node preset).
   // The auto-discover config() hook populates this before configResolved.
   routerPathRef?: { path?: string };
@@ -56,11 +54,8 @@ export interface DiscoveryState {
   perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
   perRouterManifestDataMap: Map<string, Record<string, string>>;
 
-  prerenderCollectedData: Record<string, any> | null;
-  staticCollectedData: Record<
-    string,
-    { encoded: string; handles: Record<string, unknown[]> }
-  > | null;
+  prerenderManifestEntries: Record<string, string> | null;
+  staticManifestEntries: Record<string, string> | null;
   handlerChunkInfo: ChunkInfo | null;
   staticHandlerChunkInfo: ChunkInfo | null;
   rscEntryFileName: string | null;
@@ -96,8 +91,8 @@ export function createDiscoveryState(
     perRouterPrecomputedMap: new Map(),
     perRouterManifestDataMap: new Map(),
 
-    prerenderCollectedData: null,
-    staticCollectedData: null,
+    prerenderManifestEntries: null,
+    staticManifestEntries: null,
     handlerChunkInfo: null,
     staticHandlerChunkInfo: null,
     rscEntryFileName: null,

package/src/vite/discovery/virtual-module-codegen.ts

@@ -42,7 +42,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         const genPath = join(
           routerDir,
           `${routerBasename}.named-routes.gen.js`,
-        );
+        ).replaceAll("\\", "/");
         const varName = `_r${varIdx++}`;
         genFileImports.push(
           `import { NamedRoutes as ${varName} } from ${JSON.stringify(genPath)};`,
@@ -176,7 +176,10 @@ export function generatePerRouterModule(
       /\.(tsx?|jsx?)$/,
       "",
     );
-    const genPath = join(routerDir, `${routerBasename}.named-routes.gen.js`);
+    const genPath = join(
+      routerDir,
+      `${routerBasename}.named-routes.gen.js`,
+    ).replaceAll("\\", "/");
     lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
     lines.push(
       `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,

package/src/vite/index.ts

@@ -1,12 +1,13 @@
 /**
  * Public API for @rangojs/router/vite
  *
- * Only the rango() plugin factory and its option types are part of the
- * public API. All other utilities are internal implementation details
- * consumed via direct imports within the package.
+ * 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";
 
 export type {
   RangoNodeOptions,

package/src/vite/plugin-types.ts

@@ -1,39 +1,3 @@
-/**
- * RSC plugin entry points configuration.
- * All entries use virtual modules by default. Specify a path to use a custom entry file.
- */
-export interface RscEntries {
-  /**
-   * Path to a custom browser/client entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  client?: string;
-
-  /**
-   * Path to a custom SSR entry file.
-   * If not specified, a default virtual entry is used.
-   */
-  ssr?: string;
-
-  /**
-   * Path to a custom RSC entry file.
-   * If not specified, a default virtual entry is used that imports the router from the `entry` option.
-   */
-  rsc?: string;
-}
-
-/**
- * Options for @vitejs/plugin-rsc integration
- */
-export interface RscPluginOptions {
-  /**
-   * Entry points for client, ssr, and rsc environments.
-   * All entries use virtual modules by default.
-   * Specify paths only when you need custom entry files.
-   */
-  entries?: RscEntries;
-}
-
 /**
  * Base options shared by all presets
  */
@@ -51,21 +15,6 @@ interface RangoBaseOptions {
    * @default true
    */
   staticRouteTypesGeneration?: boolean;
-
-  /**
-   * Glob patterns for files to include in route type scanning.
-   * Only files matching at least one pattern will be scanned.
-   * Patterns are relative to the project root.
-   * When unset, all .ts/.tsx files are scanned.
-   */
-  include?: string[];
-
-  /**
-   * Glob patterns for files to exclude from route type scanning.
-   * Takes precedence over `include`. Patterns are relative to the project root.
-   * Defaults to common test/build directories.
-   */
-  exclude?: string[];
 }
 
 /**
@@ -76,38 +25,6 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
-
-  /**
-   * Path to your router configuration file that exports the route tree.
-   * This file must export a `router` object created with `createRouter()`.
-   *
-   * When omitted, auto-discovers the router by scanning for files containing
-   * `createRouter`. If exactly one is found, it is used automatically.
-   * If multiple are found, an error is thrown with the list of candidates.
-   *
-   * @example
-   * ```ts
-   * rango({ router: './src/router.tsx' })
-   * // or simply:
-   * rango()
-   * ```
-   */
-  router?: string;
-
-  /**
-   * RSC plugin configuration. By default, rsc-router includes @vitejs/plugin-rsc
-   * with sensible defaults.
-   *
-   * Entry files (browser, ssr, rsc) are optional - if they don't exist,
-   * virtual defaults are used.
-   *
-   * - Omit or pass `true`/`{}` to use defaults (recommended)
-   * - Pass `{ entries: {...} }` to customize entry paths
-   * - Pass `false` to disable (for manual @vitejs/plugin-rsc configuration)
-   *
-   * @default true
-   */
-  rsc?: boolean | RscPluginOptions;
 }
 
 /**

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-action-id.ts

@@ -278,9 +278,7 @@ export function exposeActionId(): Plugin {
       if (!rscPluginApi) {
         throw new Error(
           "[rsc-router] Could not find @vitejs/plugin-rsc. " +
-            "@rangojs/router requires the Vite RSC plugin.\n" +
-            "The RSC plugin should be included automatically. If you disabled it with\n" +
-            "rango({ rsc: false }), add rsc() before rango() in your config.",
+            "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
 

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

@@ -0,0 +1,88 @@
+/**
+ * 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";
+
+const RSDW_PATCH_RE =
+  /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
+
+function buildPatchReplacement(match: string, debugInfoVar: string): string {
+  return `${match}
+if (${debugInfoVar} && 0 === ${debugInfoVar}.length && "fulfilled" === root.status) {
+  var _resolved = "function" === typeof resolveLazy ? resolveLazy(root.value) : root.value;
+  if ("object" === typeof _resolved && null !== _resolved && isArrayImpl(_resolved._debugInfo)) {
+    ${debugInfoVar} = _resolved._debugInfo;
+  }
+}`;
+}
+
+export function patchRsdwClientDebugInfoRecovery(code: string): {
+  code: string;
+  debugInfoVar: string | null;
+} {
+  const match = code.match(RSDW_PATCH_RE);
+  if (!match) {
+    return { code, debugInfoVar: null };
+  }
+
+  return {
+    code: code.replace(match[1]!, buildPatchReplacement(match[1]!, match[2]!)),
+    debugInfoVar: match[2]!,
+  };
+}
+
+export function performanceTracksOptimizeDepsPlugin(): {
+  name: string;
+  setup(build: any): void;
+} {
+  return {
+    name: "@rangojs/router:performance-tracks-optimize-deps",
+    setup(build: any): void {
+      build.onLoad(
+        {
+          filter:
+            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
+        },
+        async (args: { path: string }) => {
+          const code = await readFile(args.path, "utf8");
+          const patched = patchRsdwClientDebugInfoRecovery(code);
+          return {
+            contents: patched.code,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+export function performanceTracksPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:performance-tracks",
+
+    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;
+    },
+  };
+}