@rangojs/router 0.5.1 → 0.6.0

package/src/vite/discovery/state.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ScanFilter } from "../../build/generate-route-types.js";
+import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 
 export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 
@@ -79,6 +80,11 @@ export interface ShellPrerenderCandidate {
     | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number };
 }
 
+export interface ClientUrlDiscoveryState {
+  clientUrlSourceByReferenceId: Map<string, string>;
+  clientUrlProjectionMap: Map<string, ClientUrlProjection>;
+}
+
 export interface DiscoveryState {
   resolvedEntryPath: string | undefined;
   projectRoot: string;
@@ -109,6 +115,8 @@ export interface DiscoveryState {
   perRouterTrieMap: Map<string, any>;
   perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
   perRouterManifestDataMap: Map<string, Record<string, string>>;
+  clientUrlSourceByReferenceId?: Map<string, string>;
+  clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
 
   prerenderManifestEntries: Record<string, string> | null;
   staticManifestEntries: Record<string, string> | null;
@@ -164,7 +172,7 @@ export interface DiscoveryState {
 export function createDiscoveryState(
   entryPath: string | undefined,
   opts: PluginOptions | undefined,
-): DiscoveryState {
+): DiscoveryState & ClientUrlDiscoveryState {
   return {
     resolvedEntryPath: entryPath,
     projectRoot: "",
@@ -182,6 +190,8 @@ export function createDiscoveryState(
     perRouterTrieMap: new Map(),
     perRouterPrecomputedMap: new Map(),
     perRouterManifestDataMap: new Map(),
+    clientUrlSourceByReferenceId: new Map(),
+    clientUrlProjectionMap: new Map(),
 
     prerenderManifestEntries: null,
     staticManifestEntries: null,

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

@@ -44,6 +44,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   const hasManifest =
     state.mergedRouteManifest &&
     Object.keys(state.mergedRouteManifest).length > 0;
+  const hasClientUrlModules = Boolean(state.clientUrlSourceByReferenceId?.size);
 
   if (hasManifest) {
     // Build gen file import statements for each router with a sourceFile.
@@ -83,6 +84,9 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       "setRouterManifest",
       ...(state.isBuildMode ? ["registerRouterManifestLoader"] : []),
       "clearAllRouterData",
+      ...(hasClientUrlModules
+        ? ["clearClientUrlProjections", "setClientUrlProjection"]
+        : []),
     ];
     const lines = [
       `import { ${serverImports.join(", ")} } from "@rangojs/router/server";`,
@@ -95,6 +99,16 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
+    if (hasClientUrlModules) {
+      lines.push(`clearClientUrlProjections();`);
+      for (const [referenceId, projection] of state.clientUrlProjectionMap ??
+        []) {
+        lines.push(
+          `setClientUrlProjection(${JSON.stringify(referenceId)}, ${jsonParseExpression(projection)});`,
+        );
+      }
+    }
+
     if (varIdx > 0) {
       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; }`,
@@ -169,6 +183,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   }
 
   const lines: string[] = [];
+  if (hasClientUrlModules) {
+    lines.push(
+      `import { clearClientUrlProjections } from "@rangojs/router/server";`,
+      `clearClientUrlProjections();`,
+    );
+  }
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||

package/src/vite/encryption-key.ts

@@ -0,0 +1,29 @@
+import { randomBytes } from "node:crypto";
+
+// plugin-rsc encrypts inline-action bound args with a key read from
+// `virtual:vite-rsc/encryption-key`, which defaults to a fresh random key PER
+// plugin instance. The build-discovery temp server (which renders Static/
+// Prerender output) is a separate plugin instance from the main build, so by
+// default it encrypts prerendered bound args with a key the runtime never has --
+// `decryptActionBoundArgs` then fails on invocation. We hand both the SAME key
+// via plugin-rsc's `defineEncryptionKey` so build-time-encrypted bound args
+// decrypt at runtime.
+//
+// Cached per process so the temp server (created during the main build's
+// buildStart) and the main build share one key. Overridable via
+// RANGO_ENCRYPTION_KEY for a stable key across builds/deploys; otherwise a fresh
+// key is generated per build (matching plugin-rsc's default posture, where the
+// key is emitted into the build output regardless).
+let cachedKey: string | undefined;
+
+export function buildEncryptionKey(): string {
+  cachedKey ??=
+    process.env.RANGO_ENCRYPTION_KEY ?? randomBytes(32).toString("base64");
+  return cachedKey;
+}
+
+// The value plugin-rsc inlines as `export default () => (<expr>)`. A JSON string
+// literal, so the emitted runtime key module is a plain base64 string.
+export function defineEncryptionKeyExpr(): string {
+  return JSON.stringify(buildEncryptionKey());
+}

package/src/vite/plugins/expose-action-id.ts

@@ -3,6 +3,7 @@ import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
 import { normalizePath } from "./expose-id-utils.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
 import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
@@ -133,8 +134,7 @@ function applyRegisterReferenceWrapping(
     return false;
   }
 
-  const pattern =
-    /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const pattern = registerServerReferenceRegex();
 
   let hasChanges = false;
   let match: RegExpExecArray | null;

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

@@ -68,6 +68,52 @@ const VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
 // Consolidated plugin
 // ---------------------------------------------------------------------------
 
+interface RscScanPluginApi {
+  manager?: { isScanBuild?: boolean };
+}
+
+/**
+ * Stub export-only loader modules before plugin-rsc reduces scan modules to
+ * imports. The regular post transform remains authoritative outside scan builds.
+ *
+ * Handles and location-state definitions are intentionally excluded: handle
+ * collect functions run in the browser, and location-state definitions are
+ * callable browser objects. Their dependencies must remain visible to non-RSC
+ * validation rather than being hidden behind an opaque scan stub.
+ */
+export function createLoaderScanStubPlugin(): Plugin {
+  let projectRoot = "";
+  let rscApi: RscScanPluginApi | undefined;
+
+  return {
+    name: "@rangojs/router:loader-scan-stubs",
+    apply: "build",
+    configResolved(config) {
+      projectRoot = config.root;
+      rscApi = config.plugins.find((plugin) => plugin.name === "rsc:minimal")
+        ?.api as RscScanPluginApi | undefined;
+    },
+    transform(code, id) {
+      if (
+        !rscApi?.manager?.isScanBuild ||
+        this.environment?.name === "rsc" ||
+        id.includes("/node_modules/") ||
+        !code.includes("createLoader") ||
+        !hasCreateLoaderImport(code)
+      ) {
+        return;
+      }
+
+      const fnNames = getImportedFnNames(code, "createLoader");
+      const bindings = collectCreateExportBindings(code, fnNames);
+      const filePath = normalizePath(path.relative(projectRoot, id));
+      return (
+        generateClientLoaderStubs(bindings, code, filePath, true) ?? undefined
+      );
+    },
+  };
+}
+
 export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
   let config: ResolvedConfig;
   let isBuild = false;

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

@@ -0,0 +1,74 @@
+import type { Plugin } from "vite";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import { computeProductionHash } from "./client-ref-hashing.js";
+import { registerServerReferenceRegex } from "./server-reference-pattern.js";
+
+const debug = createRangoDebugger(NS.transform);
+
+/**
+ * Replace dev-style server-reference ids with their production hashes. The temp
+ * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
+ * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
+ * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
+ */
+export function transformServerRefs(
+  code: string,
+  projectRoot: string,
+): string | null {
+  if (!code.includes("registerServerReference")) return null;
+
+  let hasReplacement = false;
+  const result = code.replace(
+    registerServerReferenceRegex(),
+    (match, _value: string, refKey: string) => {
+      // The temp server is not a long-lived HMR server, so ids are bare; strip a
+      // query suffix defensively so the hash matches plugin-rsc's manifest key.
+      const cleanKey = refKey.split("?")[0]!;
+      const hash = computeProductionHash(projectRoot, cleanKey);
+      if (hash === cleanKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    },
+  );
+
+  return hasReplacement ? result : null;
+}
+
+/**
+ * Server-side analog of hashClientRefs. Runs in the build-discovery temp server
+ * (a dev/serve Vite server, where plugin-rsc mints dev-style ids), rewriting
+ * registerServerReference ids to production hashes AFTER plugin-rsc's
+ * rsc:use-server transform (enforce:"post"), so the Flight serializer bakes the
+ * production hash into the stored prerender/static payloads.
+ *
+ * Without this, a server-created action embedded in a prerendered/static Flight
+ * is stored with a dev-style id that the production hash-keyed server-references
+ * manifest cannot resolve -> "server reference not found" on a build-time-cache
+ * hit. Mirrors hashClientRefs, which already does exactly this for the client
+ * half of the same payload (which is why client refs in stored Flight are
+ * already production hashes while server refs were not).
+ */
+export function hashServerRefs(projectRoot: string): Plugin {
+  const counter = createCounter(debug, "hash-server-refs");
+  return {
+    name: "@rangojs/router:hash-server-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformServerRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    },
+  };
+}

package/src/vite/plugins/server-reference-pattern.ts

@@ -0,0 +1,10 @@
+// plugin-rsc's rsc:use-server transform emits inline/exported server references
+// as `registerServerReference(<value>, "<id>", "<name>")`, where <value> is a
+// hoisted identifier (no top-level comma) and a trailing `.bind(null,
+// encryptActionBoundArgs(...))` lies OUTSIDE the call. Two plugins parse this
+// same shape -- expose-action-id ($id wrapping) and server-ref-hashing (id ->
+// production hash) -- so the pattern has a single owner here. Returns a fresh
+// /g RegExp per call to avoid sharing lastIndex state across callers.
+export function registerServerReferenceRegex(): RegExp {
+  return /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+}

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

@@ -154,14 +154,23 @@ import {
   decodeAction,
   decodeFormState,
 } from "@rangojs/router/internal/deps/rsc";
-import { router } from "${routerPath}";
-import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
-import { VERSION } from "@rangojs/router:version";
 
 // Startup bootstrap imports (routes + loader manifests). See
 // RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+//
+// ORDER IS LOAD-BEARING: the bootstrap imports MUST precede the router import.
+// The routes-manifest module installs client URL projections
+// (setClientUrlProjection), and createRouter().routes(clientUrlsReference)
+// consults them at router-module evaluation. Router-first would silently push
+// every clientUrls() app onto the deferred-subscription path and change mount
+// registration order with no error. The custom-entry injector keeps the same
+// guarantee by PREPENDING this list at file top (version-injector.ts).
 ${bootstrapImports}
 
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
 // re-evaluate before router.tsx finishes, leaving the import undefined.

package/src/vite/rango.ts

@@ -2,7 +2,9 @@ import { type PluginOption } from "vite";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
+import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import {
+  createLoaderScanStubPlugin,
   exposeInternalIds,
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
@@ -275,6 +277,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
         entries: finalEntries,
         serverHandler: false,
         clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }) as PluginOption,
     );
     plugins.push(clientRefDedup());
@@ -521,6 +526,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       rsc({
         entries: finalEntries,
         clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }) as PluginOption,
     );
     plugins.push(clientRefDedup());
@@ -551,6 +559,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     },
   });
 
+  plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());
   plugins.push(exposeInternalIds());

package/src/vite/router-discovery.ts

@@ -45,6 +45,8 @@ import {
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
 import { hashClientRefs } from "./plugins/client-ref-hashing.js";
+import { hashServerRefs } from "./plugins/server-ref-hashing.js";
+import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
   createDiscoveryState,
@@ -57,6 +59,10 @@ import {
   peekSelfGenWrite,
 } from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
+import {
+  recordClientUrlsModule,
+  refreshRecordedClientUrlProjections,
+} from "./discovery/client-urls-projection.js";
 import { runShellPrerenderPhase } from "./discovery/shell-prerender-phase.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import {
@@ -224,9 +230,26 @@ async function createTempRscServer(
           ssr: "virtual:entry-ssr",
           rsc: state.resolvedEntryPath!,
         },
+        // The temp server renders Static/Prerender output and encrypts inline-
+        // action bound args. Give it the SAME key as the main build/dev runtime
+        // (defineEncryptionKeyExpr is process-cached) so those args decrypt at
+        // invocation. Unconditional, NOT build-only: under Cloudflare/workerd dev
+        // the RSC env has no module runner, so prerender is rendered by THIS temp
+        // server (via /__rsc_prerender), and the action decrypts in the main
+        // runtime with the rango.ts key -- gating on forceBuild left dev encrypting
+        // with the temp server's own random key, failing decryptActionBoundArgs.
+        // (hashServerRefs stays build-only: dev keeps dev-style ids the dev runtime
+        // resolves directly.)
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }),
-      // hashClientRefs only in build mode — production bundles need hashed refs
-      ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
+      // hashClientRefs/hashServerRefs only in build mode — production bundles
+      // need hashed refs. hashServerRefs is the server-side analog: it rewrites
+      // registerServerReference dev-style ids to production hashes so a
+      // server-created action embedded in prerendered/static Flight resolves
+      // against the production manifest on a build-time-cache hit.
+      ...(options.forceBuild
+        ? [hashClientRefs(state.projectRoot), hashServerRefs(state.projectRoot)]
+        : []),
       createVersionPlugin(),
       // Before the stub plugin, so "virtual:entry-ssr" resolves to the real
       // SSR entry when the shell endpoint needs it (see the option doc).
@@ -254,6 +277,13 @@ async function createTempRscServer(
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
       exposeRouterId(),
+      {
+        name: "@rangojs/router:client-urls-source-tracking",
+        enforce: "pre",
+        transform(code, id) {
+          recordClientUrlsModule(state, code, id);
+        },
+      },
       // Forwarded user resolution plugins (e.g. vite-tsconfig-paths). Stripped
       // to resolveId/load and placed last so framework resolution runs first;
       // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
@@ -408,8 +438,12 @@ export function createRouterDiscoveryPlugin(
     // internal-debug module so FE debug no longer depends on Vite delivering the
     // `__RANGO_DEBUG__` define to the client (which it does only as an injected
     // global whose presence varies across consumer setups). Runs in dev and build.
-    transform(_code, id) {
-      return injectClientDebugFlag(id);
+    transform: {
+      order: "pre",
+      handler(code, id) {
+        recordClientUrlsModule(s, code, id);
+        return injectClientDebugFlag(id);
+      },
     },
 
     configResolved(config) {
@@ -861,7 +895,11 @@ export function createRouterDiscoveryPlugin(
               optimizerHashBefore =
                 tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
-                discoverRouters(s, tempRscEnv),
+                discoverRouters(
+                  s,
+                  tempRscEnv,
+                  (prerenderTempServer?.environments as any)?.ssr,
+                ),
               );
               timedSync(debugDiscovery, "writeRouteTypesFiles", () =>
                 writeRouteTypesFiles(s),
@@ -916,7 +954,7 @@ export function createRouterDiscoveryPlugin(
           // requests during discovery on the Node path, so arming
           // manifestReadyPromise after discovery is sufficient here.
           const serverMod = await timed(debugDiscovery, "discoverRouters", () =>
-            discoverRouters(s, rscEnv),
+            discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
@@ -1533,7 +1571,7 @@ export function createRouterDiscoveryPlugin(
             try {
               if (hasMainRunner) {
                 await timed(debugDiscovery, "hmr discoverRouters", () =>
-                  discoverRouters(s, rscEnv),
+                  discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
                 );
                 timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
                   writeRouteTypesFiles(s),
@@ -1560,7 +1598,12 @@ export function createRouterDiscoveryPlugin(
                 await timed(
                   debugDiscovery,
                   "hmr discoverRouters (cloudflare)",
-                  () => discoverRouters(s, tempRscEnv),
+                  () =>
+                    discoverRouters(
+                      s,
+                      tempRscEnv,
+                      (prerenderTempServer?.environments as any)?.ssr,
+                    ),
                 );
                 timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
                   writeRouteTypesFiles(s),
@@ -1705,12 +1748,54 @@ export function createRouterDiscoveryPlugin(
 
         const scheduleRouteRegeneration = () => {
           clearTimeout(routeChangeTimer);
-          routeChangeTimer = setTimeout(() => {
+          routeChangeTimer = setTimeout(async () => {
             routeChangeTimer = undefined;
             const regenStart = debugDiscovery ? performance.now() : 0;
             const rscEnv = (server.environments as any)?.rsc;
             const skipStaticWrite =
               !rscEnv?.runner && s.perRouterManifests.length > 0;
+            // Refresh clientUrls projections + state BEFORE any gen-file
+            // write below: the write invalidates the routes-manifest virtual
+            // module, whose regenerated code replays state.clientUrlProjectionMap
+            // (clear + set). A stale map at that moment bakes stale literals
+            // that clobber the runtime registry before the re-discovery entry
+            // import materializes the client mount (node HMR served old
+            // client-urls patterns until restart). Lenient: import failures
+            // keep last-known state; discoverRouters' strict pass reports.
+            if (rscEnv?.runner && s.clientUrlSourceByReferenceId?.size) {
+              try {
+                const serverMod = await rscEnv.runner.import(
+                  "@rangojs/router/server",
+                );
+                await refreshRecordedClientUrlProjections(
+                  s,
+                  (server.environments as any)?.ssr,
+                  serverMod,
+                );
+                // Force the routes-manifest virtual module to re-transform:
+                // its generated code REPLAYS projections (clear + set) on
+                // every rsc program reload, and self-gen-write suppression
+                // keeps its cached transform alive through this cycle — a
+                // stale replay after propagateDiscoveryState would clobber
+                // the refreshed registry as the realm's last write and the
+                // next router evaluation would materialize the old mount.
+                for (const virtualId of [
+                  VIRTUAL_ROUTES_MANIFEST_ID,
+                  `\0${VIRTUAL_ROUTES_MANIFEST_ID}`,
+                ]) {
+                  const virtualMod =
+                    rscEnv.moduleGraph?.getModuleById?.(virtualId);
+                  if (virtualMod) {
+                    rscEnv.moduleGraph.invalidateModule(virtualMod);
+                  }
+                }
+              } catch (err: any) {
+                debugDiscovery?.(
+                  "watcher: clientUrls projection pre-refresh failed: %s",
+                  err?.message,
+                );
+              }
+            }
             try {
               // In cloudflare dev with a populated runtime manifest, the
               // static parser produces a strictly smaller (and actively
@@ -1799,7 +1884,19 @@ export function createRouterDiscoveryPlugin(
             const isUseClient =
               trimmed.startsWith('"use client"') ||
               trimmed.startsWith("'use client'");
-            if (!inRecoveryMode && isUseClient) return;
+            // clientUrls() modules are "use client" by contract yet define
+            // routes: their edits must re-run discovery (server projection +
+            // generated types), so only bail on use-client files WITHOUT a
+            // clientUrls() definition. Scar: before this carve-out, editing a
+            // clientUrls module's route shape in dev left the serving router on
+            // the stale projection — the old pattern kept matching and the new
+            // one 404ed until a full restart.
+            let hasClientUrls = source.includes("clientUrls(");
+            if (hasClientUrls) {
+              hasClientUrls =
+                firstCodeMatchIndex(source, /\bclientUrls\(/g) >= 0;
+            }
+            if (!inRecoveryMode && isUseClient && !hasClientUrls) return;
             // Cheap raw pre-check first; only when a candidate token is present
             // do we confirm it occurs in real code (not a comment/string) via a
             // single allocation-free code-region scan. Most saved files contain
@@ -1813,24 +1910,97 @@ export function createRouterDiscoveryPlugin(
               hasCreateRouter =
                 firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
             }
-            if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
+            // hasClientUrls counts here too: in a clientUrls() module the only
+            // `urls(` token sits INSIDE the `clientUrls(` identifier, which the
+            // code scan correctly rejects as a sub-identifier match — so
+            // without this the file would silently fail the sniff.
+            if (
+              !inRecoveryMode &&
+              !hasUrls &&
+              !hasCreateRouter &&
+              !hasClientUrls
+            ) {
+              return;
+            }
             if (inRecoveryMode) {
               debugDiscovery?.(
-                "watcher: recovery rediscovery for %s (urls=%s, router=%s, useClient=%s) [LASTERR %s]",
+                "watcher: recovery rediscovery for %s (urls=%s, router=%s, clientUrls=%s, useClient=%s) [LASTERR %s]",
                 filePath,
                 hasUrls,
                 hasCreateRouter,
+                hasClientUrls,
                 isUseClient,
                 s.lastDiscoveryError!.message,
               );
             } else {
               debugDiscovery?.(
-                "watcher: %s matches (urls=%s, router=%s)",
+                "watcher: %s matches (urls=%s, router=%s, clientUrls=%s)",
                 filePath,
                 hasUrls,
                 hasCreateRouter,
+                hasClientUrls,
               );
             }
+            // A "use client" clientUrls module is an HMR-accepted client
+            // boundary in the rsc graph: its edit never invalidates the router
+            // module that materialized its projection, so the re-discovery
+            // entry import would cache-hit and keep serving the stale mount
+            // (old patterns 200, new patterns 404 until restart). Invalidate
+            // the entry + router sources so the import re-creates the routers
+            // against the refreshed projection (installed by the pre-entry
+            // refresh in discover-routers.ts).
+            if (isUseClient && hasClientUrls) {
+              const rscGraph = (server.environments as any)?.rsc?.moduleGraph;
+              if (rscGraph?.getModulesByFile) {
+                // Importers must be invalidated too: the virtual RSC entry
+                // holds a live `import { router }` binding, and re-evaluating
+                // router.tsx alone leaves that binding on the OLD instance —
+                // the request pipeline would keep serving the stale mount.
+                // Same blast radius as a server urls edit (Vite's own
+                // file-change invalidation propagates upward identically).
+                const invalidateWithImporters = (
+                  mod: any,
+                  seen: Set<any>,
+                ): void => {
+                  if (!mod || seen.has(mod)) return;
+                  seen.add(mod);
+                  rscGraph.invalidateModule(mod);
+                  for (const importer of mod.importers ?? []) {
+                    invalidateWithImporters(importer, seen);
+                  }
+                };
+                const routerSourceFiles = new Set<string>();
+                if (s.resolvedEntryPath) {
+                  routerSourceFiles.add(resolve(s.resolvedEntryPath));
+                }
+                for (const entry of s.perRouterManifests) {
+                  if (entry.sourceFile) {
+                    routerSourceFiles.add(resolve(entry.sourceFile));
+                  }
+                }
+                const seen = new Set<any>();
+                for (const file of routerSourceFiles) {
+                  const mods = rscGraph.getModulesByFile(
+                    file.replaceAll("\\", "/"),
+                  );
+                  if (!mods) {
+                    debugDiscovery?.(
+                      "watcher: clientUrls invalidation found no rsc modules for %s",
+                      file,
+                    );
+                    continue;
+                  }
+                  for (const mod of mods) {
+                    invalidateWithImporters(mod, seen);
+                  }
+                }
+                debugDiscovery?.(
+                  "watcher: clientUrls edit invalidated %d rsc module(s) for %d router file(s)",
+                  seen.size,
+                  routerSourceFiles.size,
+                );
+              }
+            }
             // Invalidate cache when a router file changes (new router added/removed)
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
@@ -1943,7 +2113,7 @@ export function createRouterDiscoveryPlugin(
         }
 
         await timed(debugDiscovery, "build discoverRouters", () =>
-          discoverRouters(s, rscEnv),
+          discoverRouters(s, rscEnv, (tempServer.environments as any)?.ssr),
         );
         // Update named-routes.gen.ts from runtime discovery.
         // The runtime manifest includes dynamically generated routes