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

package/src/vite/rango.ts

@@ -1,11 +1,13 @@
 import type { PluginOption } from "vite";
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
 import {
   exposeInternalIds,
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
 import { useCacheTransform } from "./plugins/use-cache-transform.js";
+import { clientRefDedup } from "./plugins/client-ref-dedup.js";
 import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
   getExcludeDeps,
@@ -70,8 +72,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   // Track RSC entry path for version injection
   let rscEntryPath: string | null = null;
 
-  // Resolved router path (node preset only, may be auto-discovered)
-  let routerPath: string | undefined;
+  // Mutable ref for router path (node preset only).
+  // Set immediately when user-specified, or populated by the auto-discover
+  // config() hook using Vite's resolved root.
+  const routerRef: { path: string | undefined } = { path: undefined };
 
   // Build-time prerendering is enabled for both presets.
   // Collection runs in-process via the RSC dev environment runner during discoverRouters().
@@ -193,43 +197,54 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     // since SSR runs in workerd alongside RSC
     plugins.push(
       rsc({
-        get entries() {
-          return finalEntries;
-        },
+        entries: finalEntries,
         serverHandler: false,
       }) as PluginOption,
     );
+
+    // Deduplicate client references from third-party packages in dev mode.
+    // Prevents module duplication when server components import "use client"
+    // packages that are also imported directly by client components.
+    plugins.push(clientRefDedup());
   } else {
     // Node preset: full RSC plugin integration
     const nodeOptions = resolvedOptions as RangoNodeOptions;
-    routerPath = nodeOptions.router;
 
-    // Auto-discover router when not specified
-    if (!routerPath) {
-      const earlyFilter = createScanFilter(process.cwd(), {
-        include: resolvedOptions.include,
-        exclude: resolvedOptions.exclude,
+    routerRef.path = nodeOptions.router;
+
+    // Auto-discover router using Vite's resolved root (not process.cwd())
+    if (!routerRef.path) {
+      plugins.push({
+        name: "@rangojs/router:auto-discover",
+        config(userConfig) {
+          if (routerRef.path) return;
+          const root = userConfig.root
+            ? resolve(process.cwd(), userConfig.root)
+            : process.cwd();
+          const filter = createScanFilter(root, {
+            include: resolvedOptions.include,
+            exclude: resolvedOptions.exclude,
+          });
+          const candidates = findRouterFiles(root, filter);
+          if (candidates.length === 1) {
+            const abs = candidates[0];
+            routerRef.path = (
+              abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs
+            ).replaceAll("\\", "/");
+          } else if (candidates.length > 1) {
+            const list = candidates
+              .map(
+                (f) =>
+                  "  - " + (f.startsWith(root) ? f.slice(root.length + 1) : f),
+              )
+              .join("\n");
+            throw new Error(
+              `[rsc-router] Multiple routers found. Specify \`router\` to choose one:\n${list}`,
+            );
+          }
+          // 0 found: routerRef.path stays undefined, warn at startup via discovery plugin
+        },
       });
-      const candidates = findRouterFiles(process.cwd(), earlyFilter);
-      if (candidates.length === 1) {
-        // Convert absolute path to relative ./path
-        const abs = candidates[0];
-        const rel = abs.startsWith(process.cwd())
-          ? "./" + abs.slice(process.cwd().length + 1)
-          : abs;
-        routerPath = rel;
-      } else if (candidates.length > 1) {
-        const cwd = process.cwd();
-        const list = candidates
-          .map(
-            (f) => "  - " + (f.startsWith(cwd) ? f.slice(cwd.length + 1) : f),
-          )
-          .join("\n");
-        throw new Error(
-          `[rsc-router] Multiple routers found. Specify \`router\` to choose one:\n${list}`,
-        );
-      }
-      // 0 found: routerPath stays undefined, warn at startup via discovery plugin
     }
 
     const rscOption = nodeOptions.rsc ?? true;
@@ -373,8 +388,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         },
       });
 
-      // Add virtual entries plugin
-      plugins.push(createVirtualEntriesPlugin(finalEntries, routerPath));
+      // Add virtual entries plugin (RSC entry generated lazily from routerRef)
+      plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
 
       // Add the RSC plugin directly
       // Cast to PluginOption to handle type differences between bundled vite types
@@ -384,6 +399,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         }) as PluginOption,
       );
     }
+
+    // Deduplicate client references from third-party packages in dev mode.
+    // Prevents module duplication when server components import "use client"
+    // packages that are also imported directly by client components.
+    plugins.push(clientRefDedup());
   }
 
   // Fix HMR for "use client" components.
@@ -451,10 +471,13 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   // Add version virtual module plugin for cache invalidation
   plugins.push(createVersionPlugin());
 
-  // Entry path for discovery and version injection.
-  // Node preset: uses the (possibly auto-discovered) router path.
+  // Entry path for discovery: user-specified value (if any) or undefined.
+  // Auto-discovered path is passed separately via routerRef.
   // Cloudflare preset: deferred to configResolved (read from resolved Vite env config).
-  const discoveryEntryPath = preset !== "cloudflare" ? routerPath : undefined;
+  const discoveryEntryPath =
+    preset !== "cloudflare" ? routerRef.path : undefined;
+  // Ref for deferred auto-discovery (node preset only, undefined for cloudflare)
+  const discoveryRouterRef = preset !== "cloudflare" ? routerRef : undefined;
 
   // Version injector: auto-injects VERSION and routes-manifest into custom entry.rsc files.
   // Only applies when there's an explicit rscEntryPath or for cloudflare preset (resolved
@@ -472,8 +495,10 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
   // Router discovery plugin for build-time manifest generation.
   // For cloudflare, the entry is resolved lazily in configResolved from the RSC environment.
+  // For node, discoveryRouterRef provides the auto-discovered path when not user-specified.
   plugins.push(
     createRouterDiscoveryPlugin(discoveryEntryPath, {
+      routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
       staticRouteTypesGeneration: resolvedOptions.staticRouteTypesGeneration,
       include: resolvedOptions.include,

package/src/vite/router-discovery.ts

@@ -11,6 +11,8 @@ import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import {
+  formatNestedRouterConflictError,
+  findNestedRouterConflict,
   findRouterFiles,
   createScanFilter,
 } from "../build/generate-route-types.js";
@@ -25,6 +27,7 @@ import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
   createDiscoveryState,
   VIRTUAL_ROUTES_MANIFEST_ID,
+  type DiscoveryState,
   type PluginOptions,
 } from "./discovery/state.js";
 import { consumeSelfGenWrite } from "./discovery/self-gen-tracking.js";
@@ -39,9 +42,59 @@ import {
   generatePerRouterModule,
 } from "./discovery/virtual-module-codegen.js";
 import { postprocessBundle } from "./discovery/bundle-postprocess.js";
+import { resetStagedBuildAssets } from "./utils/prerender-utils.js";
 
 export { VIRTUAL_ROUTES_MANIFEST_ID };
 
+// ============================================================================
+// Temp Server Factory
+// ============================================================================
+
+/**
+ * Create a minimal Vite server for router discovery.
+ *
+ * Both dev-mode prerender and build-mode discovery need a temp RSC server
+ * to import user router files via module runner. This factory centralizes
+ * the shared config and the mode-specific differences:
+ * - Dev: path-based IDs (no forceBuild), separate cacheDir
+ * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
+ *
+ * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ */
+async function createTempRscServer(
+  state: DiscoveryState,
+  options: { forceBuild?: boolean; cacheDir?: string } = {},
+) {
+  const { default: rsc } = await import("@vitejs/plugin-rsc");
+  return createViteServer({
+    root: state.projectRoot,
+    configFile: false,
+    server: { middlewareMode: true },
+    appType: "custom",
+    logLevel: "silent",
+    resolve: { alias: state.userResolveAlias },
+    esbuild: { jsx: "automatic", jsxImportSource: "react" },
+    ...(options.cacheDir && { cacheDir: options.cacheDir }),
+    plugins: [
+      rsc({
+        entries: {
+          client: "virtual:entry-client",
+          ssr: "virtual:entry-ssr",
+          rsc: state.resolvedEntryPath!,
+        },
+      }),
+      // hashClientRefs only in build mode — production bundles need hashed refs
+      ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
+      createVersionPlugin(),
+      createVirtualStubPlugin(),
+      // Dev prerender must use dev-mode IDs (path-based) to match the workerd
+      // runtime. forceBuild produces hashed IDs for production bundle consistency.
+      exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
+      exposeRouterId(),
+    ],
+  });
+}
+
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *
@@ -97,6 +150,12 @@ export function createRouterDiscoveryPlugin(
       s.isBuildMode = config.command === "build";
       // Capture user's resolve aliases for the temp server
       s.userResolveAlias = config.resolve.alias;
+      // Node preset: pick up auto-discovered router path from the config() hook.
+      // The auto-discover plugin runs in config() using Vite's resolved root,
+      // populating the mutable ref before configResolved fires.
+      if (!s.resolvedEntryPath && opts?.routerPathRef?.path) {
+        s.resolvedEntryPath = opts.routerPathRef.path;
+      }
       // 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.
@@ -179,32 +238,8 @@ export function createRouterDiscoveryPlugin(
           return (prerenderTempServer.environments as any)?.rsc ?? null;
         }
         try {
-          const { default: rsc } = await import("@vitejs/plugin-rsc");
-          prerenderTempServer = await createViteServer({
-            root: s.projectRoot,
-            configFile: false,
-            server: { middlewareMode: true },
-            appType: "custom",
-            logLevel: "silent",
+          prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender",
-            resolve: { alias: s.userResolveAlias },
-            esbuild: { jsx: "automatic", jsxImportSource: "react" },
-            plugins: [
-              rsc({
-                entries: {
-                  client: "virtual:entry-client",
-                  ssr: "virtual:entry-ssr",
-                  rsc: s.resolvedEntryPath!,
-                },
-              }),
-              createVersionPlugin(),
-              createVirtualStubPlugin(),
-              // Dev prerender must use dev-mode IDs (path-based) to match the
-              // workerd runtime. forceBuild would produce hashed IDs causing
-              // handle data key mismatches when replayed into the runtime store.
-              exposeInternalIds(),
-              exposeRouterId(),
-            ],
           });
 
           const tempRscEnv = (prerenderTempServer.environments as any)?.rsc;
@@ -260,10 +295,7 @@ export function createRouterDiscoveryPlugin(
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
 
-          const serverModAfterDiscovery = await discoverRouters(s, rscEnv);
-
-          // Save registry for the /__rsc_prerender endpoint (avoids creating a temp server)
-          mainRegistry = serverModAfterDiscovery?.RouterRegistry ?? null;
+          await discoverRouters(s, rscEnv);
 
           // Store server origin for dev prerender endpoint (virtual module injection)
           s.devServerOrigin = getDevServerOrigin();
@@ -275,37 +307,8 @@ export function createRouterDiscoveryPlugin(
           // won't cause unnecessary HMR triggers.
           writeRouteTypesFiles(s);
 
-          // Populate the route map in the RSC env
-          if (s.mergedRouteManifest && serverMod?.setCachedManifest) {
-            serverMod.setCachedManifest(s.mergedRouteManifest);
-          }
-          if (
-            s.mergedPrecomputedEntries &&
-            s.mergedPrecomputedEntries.length > 0 &&
-            serverMod?.setPrecomputedEntries
-          ) {
-            serverMod.setPrecomputedEntries(s.mergedPrecomputedEntries);
-          }
-          if (s.mergedRouteTrie && serverMod?.setRouteTrie) {
-            serverMod.setRouteTrie(s.mergedRouteTrie);
-          }
-          // Populate per-router isolated data eagerly in dev (HMR).
-          // In production builds, per-router data is loaded lazily via import().
-          if (serverMod?.setRouterManifest) {
-            for (const [routerId, manifest] of s.perRouterManifestDataMap) {
-              serverMod.setRouterManifest(routerId, manifest);
-            }
-          }
-          if (serverMod?.setRouterTrie) {
-            for (const [routerId, trie] of s.perRouterTrieMap) {
-              serverMod.setRouterTrie(routerId, trie);
-            }
-          }
-          if (serverMod?.setRouterPrecomputedEntries) {
-            for (const [routerId, entries] of s.perRouterPrecomputedMap) {
-              serverMod.setRouterPrecomputedEntries(routerId, entries);
-            }
-          }
+          // Populate the route map and per-router data in the RSC env
+          await propagateDiscoveryState(rscEnv);
         } catch (err: any) {
           console.warn(
             `[rsc-router] Router discovery failed: ${err.message}\n${err.stack}`,
@@ -333,6 +336,49 @@ export function createRouterDiscoveryPlugin(
       // Registry from the main server's RSC environment (populated by discoverRouters)
       let mainRegistry: Map<string, any> | null = null;
 
+      // Push discovery state (manifest, trie, precomputed entries) to the
+      // server module so runtime request handling uses the current routes.
+      // Shared by initial discovery and HMR-triggered re-discovery.
+      const propagateDiscoveryState = async (rscEnv: any) => {
+        const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+        if (!serverMod) return;
+        // Clear stale per-router and global route data before repopulating.
+        // Without this, removed routers/routes survive in the per-router maps
+        // and shrunk precomputed entries or tries are never purged.
+        if (serverMod.clearAllRouterData) {
+          serverMod.clearAllRouterData();
+        }
+        mainRegistry = serverMod.RouterRegistry ?? null;
+        if (s.mergedRouteManifest && serverMod.setCachedManifest) {
+          serverMod.setCachedManifest(s.mergedRouteManifest);
+        }
+        if (
+          s.mergedPrecomputedEntries &&
+          s.mergedPrecomputedEntries.length > 0 &&
+          serverMod.setPrecomputedEntries
+        ) {
+          serverMod.setPrecomputedEntries(s.mergedPrecomputedEntries);
+        }
+        if (s.mergedRouteTrie && serverMod.setRouteTrie) {
+          serverMod.setRouteTrie(s.mergedRouteTrie);
+        }
+        if (serverMod.setRouterManifest) {
+          for (const [routerId, manifest] of s.perRouterManifestDataMap) {
+            serverMod.setRouterManifest(routerId, manifest);
+          }
+        }
+        if (serverMod.setRouterTrie) {
+          for (const [routerId, trie] of s.perRouterTrieMap) {
+            serverMod.setRouterTrie(routerId, trie);
+          }
+        }
+        if (serverMod.setRouterPrecomputedEntries) {
+          for (const [routerId, entries] of s.perRouterPrecomputedMap) {
+            serverMod.setRouterPrecomputedEntries(routerId, entries);
+          }
+        }
+      };
+
       server.middlewares.use("/__rsc_prerender", async (req: any, res: any) => {
         if (s.discoveryDone) await s.discoveryDone;
 
@@ -364,12 +410,24 @@ export function createRouterDiscoveryPlugin(
         }
 
         const wantIntercept = url.searchParams.get("intercept") === "1";
+        const wantRouteName = url.searchParams.get("routeName");
+        const wantPassthrough = url.searchParams.get("passthrough") === "1";
 
         for (const [, routerInstance] of registry) {
           if (!routerInstance.matchForPrerender) continue;
           try {
-            const result = await routerInstance.matchForPrerender(pathname, {});
+            const result = await routerInstance.matchForPrerender(
+              pathname,
+              {},
+              undefined,
+              wantPassthrough,
+            );
             if (!result) continue;
+            if (result.passthrough) continue;
+            // When routeName is specified, only accept a match for that route.
+            // This prevents returning the wrong entry when multiple routers
+            // have prerenderable routes sharing the same pathname.
+            if (wantRouteName && result.routeName !== wantRouteName) continue;
             res.setHeader("content-type", "application/json");
             let payload: Record<string, unknown>;
             if (wantIntercept && result.interceptSegments?.length) {
@@ -417,6 +475,13 @@ export function createRouterDiscoveryPlugin(
         ): boolean => {
           if (!isGeneratedRouteFile(filePath)) return false;
           if (consumeSelfGenWrite(s, filePath)) return true;
+          // In Cloudflare dev (no module runner), perRouterManifests is never
+          // refreshed after HMR so regenerateGeneratedRouteFiles() would use
+          // stale data and revert user edits. Source files own route state;
+          // gen files are derived output. Skip regeneration and let the next
+          // source-file change rebuild them from the static parser.
+          const hasRunner = !!(server.environments as any)?.rsc?.runner;
+          if (!hasRunner) return true;
           regenerateGeneratedRouteFiles();
           return true;
         };
@@ -427,6 +492,26 @@ export function createRouterDiscoveryPlugin(
         // only the expensive regeneration is debounced.
         let routeChangeTimer: ReturnType<typeof setTimeout> | undefined;
 
+        // Re-run runtime discovery so factory-generated routes that the
+        // static parser cannot see are refreshed after source changes.
+        let runtimeRediscoveryInProgress = false;
+        const refreshRuntimeDiscovery = async () => {
+          const rscEnv = (server.environments as any)?.rsc;
+          if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
+          runtimeRediscoveryInProgress = true;
+          try {
+            await discoverRouters(s, rscEnv);
+            writeRouteTypesFiles(s);
+            await propagateDiscoveryState(rscEnv);
+          } catch (err: any) {
+            console.warn(
+              `[rsc-router] Runtime re-discovery failed: ${err.message}`,
+            );
+          } finally {
+            runtimeRediscoveryInProgress = false;
+          }
+        };
+
         const scheduleRouteRegeneration = () => {
           clearTimeout(routeChangeTimer);
           routeChangeTimer = setTimeout(() => {
@@ -441,6 +526,15 @@ export function createRouterDiscoveryPlugin(
                 `[rsc-router] Route regeneration error: ${err.message}`,
               );
             }
+            // Async: re-run runtime discovery to refresh factory-generated
+            // routes that the static parser cannot resolve.
+            if (s.perRouterManifests.length > 0) {
+              refreshRuntimeDiscovery().catch((err: any) => {
+                console.warn(
+                  `[rsc-router] Runtime re-discovery error: ${err.message}`,
+                );
+              });
+            }
           }, 100);
         };
 
@@ -468,6 +562,16 @@ export function createRouterDiscoveryPlugin(
             if (!hasUrls && !hasCreateRouter) return;
             // Invalidate cache when a router file changes (new router added/removed)
             if (hasCreateRouter) {
+              const nestedRouterConflict = findNestedRouterConflict([
+                ...(s.cachedRouterFiles ?? []),
+                resolve(filePath),
+              ]);
+              if (nestedRouterConflict) {
+                server.config.logger.error(
+                  formatNestedRouterConflictError(nestedRouterConflict),
+                );
+                return;
+              }
               s.cachedRouterFiles = undefined;
             }
             scheduleRouteRegeneration();
@@ -483,8 +587,12 @@ export function createRouterDiscoveryPlugin(
         server.watcher.on("change", handleRouteFileChange);
 
         // Regenerate gen files when they are deleted (e.g. manual cleanup).
+        // Same no-runner guard as change/add: stale perRouterManifests would
+        // reintroduce reverted content.
         server.watcher.on("unlink", (filePath) => {
           if (!isGeneratedRouteFile(filePath)) return;
+          const hasRunner = !!(server.environments as any)?.rsc?.runner;
+          if (!hasRunner) return;
           regenerateGeneratedRouteFiles();
         });
       }
@@ -497,6 +605,9 @@ export function createRouterDiscoveryPlugin(
       if (!s.isBuildMode) return;
       // Only run once across environment builds
       if (s.mergedRouteManifest !== null) return;
+      resetStagedBuildAssets(s.projectRoot);
+      s.prerenderManifestEntries = null;
+      s.staticManifestEntries = null;
 
       let tempServer: any = null;
       // Signal to user-space code (e.g. reverse.ts) that build-time discovery
@@ -505,45 +616,7 @@ export function createRouterDiscoveryPlugin(
       // between the vite plugin and user code loaded via runner.import().
       (globalThis as any).__rscRouterDiscoveryActive = true;
       try {
-        // Create a minimal Vite server with just the RSC plugin.
-        // We bypass the user's config file because:
-        // - Custom environments (e.g., CloudflareDevEnvironment) may not expose
-        //   a module runner compatible with runner.import()
-        // - The temp server only needs RSC conditions to import the router
-        const { default: rsc } = await import("@vitejs/plugin-rsc");
-        tempServer = await createViteServer({
-          root: s.projectRoot,
-          configFile: false,
-          server: { middlewareMode: true },
-          appType: "custom",
-          logLevel: "silent",
-          // Use the resolved aliases from the real config (includes user's path aliases
-          // like @/ -> src/ AND package aliases from rsc-router)
-          resolve: { alias: s.userResolveAlias },
-          // Enable automatic JSX runtime so .tsx files don't need `import React`.
-          // Without this, esbuild defaults to classic mode (React.createElement)
-          // which fails when lazy host-router handlers load sub-app modules with JSX.
-          esbuild: { jsx: "automatic", jsxImportSource: "react" },
-          plugins: [
-            rsc({
-              entries: {
-                client: "virtual:entry-client",
-                ssr: "virtual:entry-ssr",
-                rsc: s.resolvedEntryPath!,
-              },
-            }),
-            hashClientRefs(s.projectRoot),
-            createVersionPlugin(),
-            // Stub virtual modules that the RSC entry may import
-            // (e.g., virtual:rsc-router/routes-manifest, virtual:rsc-router/loader-manifest)
-            createVirtualStubPlugin(),
-            // Inject handle + router IDs so prerender-collected handle data uses
-            // the same hashed keys as the production client/SSR bundles, and
-            // build-time router IDs match runtime IDs across environments.
-            exposeInternalIds({ forceBuild: true }),
-            exposeRouterId(),
-          ],
-        });
+        tempServer = await createTempRscServer(s, { forceBuild: true });
 
         const rscEnv = (tempServer.environments as any)?.rsc;
         if (!rscEnv?.runner) {

package/src/vite/utils/prerender-utils.ts

@@ -1,3 +1,14 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
 /**
  * Escape special RegExp characters in a string for safe interpolation
  * into new RegExp() patterns.
@@ -17,6 +28,27 @@ export function encodePathParam(value: unknown): string {
     .join("/");
 }
 
+/**
+ * Substitute route params into a pattern, stripping constraint and optional
+ * syntax (:param(a|b)? -> value). Also handles wildcard params (*key).
+ */
+export function substituteRouteParams(
+  pattern: string,
+  params: Record<string, string>,
+  encode: (value: string) => string = encodeURIComponent,
+): string {
+  let result = pattern;
+  for (const [key, value] of Object.entries(params)) {
+    const escaped = escapeRegExp(key);
+    result = result.replace(
+      new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+      encode(value),
+    );
+    result = result.replace(`*${key}`, encode(value));
+  }
+  return result;
+}
+
 /**
  * Run an async function over items with bounded concurrency.
  * Errors propagate immediately and abort remaining work.
@@ -106,3 +138,52 @@ export function notifyOnError(
     break; // Only notify the first router with onError
   }
 }
+
+function getStagedAssetDir(projectRoot: string): string {
+  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+}
+
+export function resetStagedBuildAssets(projectRoot: string): void {
+  rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
+}
+
+export function stageBuildAssetModule(
+  projectRoot: string,
+  prefix: "__pr" | "__st",
+  exportValue: string,
+): string {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  mkdirSync(stagedDir, { recursive: true });
+
+  const contentHash = createHash("sha256")
+    .update(exportValue)
+    .digest("hex")
+    .slice(0, 8);
+  const fileName = `${prefix}-${contentHash}.js`;
+  const filePath = resolve(stagedDir, fileName);
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, `export default ${exportValue};\n`);
+  }
+
+  return fileName;
+}
+
+export function copyStagedBuildAssets(
+  projectRoot: string,
+  fileNames: Iterable<string>,
+): number {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  const distAssetsDir = resolve(projectRoot, "dist/rsc/assets");
+  mkdirSync(distAssetsDir, { recursive: true });
+
+  let totalBytes = 0;
+  for (const fileName of new Set(fileNames)) {
+    const stagedPath = resolve(stagedDir, fileName);
+    const distPath = resolve(distAssetsDir, fileName);
+    copyFileSync(stagedPath, distPath);
+    totalBytes += statSync(stagedPath).size;
+  }
+
+  return totalBytes;
+}