@rangojs/router 0.24.3 → 0.25.0

package/src/vite/plugins/client-urls-revalidate-hoist.ts

@@ -1,10 +1,17 @@
-import type { Plugin } from "vite";
+import type { EnvironmentModuleNode, Plugin } from "vite";
 import { normalizePath, parseAst } from "vite";
 import MagicString from "magic-string";
 import { createHash } from "node:crypto";
 import { relative } from "node:path";
 import { hasDirective } from "@vitejs/plugin-rsc/transforms";
 import { HOISTED_REVALIDATE_KEY } from "../../client-urls/hoisted-revalidate.js";
+import {
+  CLIENT_IMPORT_RE,
+  CLIENT_URLS_REVALIDATE_QUERY,
+  componentUseSignature,
+  hoistedRevalidateId,
+} from "../discovery/client-urls-projection.js";
+import type { ClientUrlRevalidateIndex } from "../discovery/state.js";
 import { hasUseClientDirective } from "../utils/directive-prologue.js";
 import { offsetToLineColumn } from "./expose-ids/export-analysis.js";
 import {
@@ -31,13 +38,15 @@ import {
   resolveSourceTarget,
   SOURCE_FILE_RE,
   type EmittedEntry,
+  type SourceResolver,
 } from "./hoist/source.js";
 
 /**
  * clientUrls() loader `revalidate()` runs on the server, with the arguments a
- * urls() loader's predicate gets. The predicate is declared in a
- * "use client" module, so the build moves it into a server module (the
- * reverse of transition-when-hoist.ts):
+ * urls() loader's predicate gets. The predicate is declared in client code (a
+ * "use client" group, or a component's `.use` in any module the group
+ * imports), so the build moves it into a server module (the reverse of
+ * transition-when-hoist.ts):
  *
  *   loader(CartLoader, () => [
  *     revalidate((ctx) => ctx.isAction(Cart) ? ctx.actionResult?.ok : undefined),
@@ -56,31 +65,47 @@ import {
  *
  * plugin-rsc replaces the RSC copy of a "use client" module with client
  * reference proxies and drops everything else, so a post transform appends
- * `import "<file>?rango-revalidate"` to the proxy: the predicates register
- * when the group's module loads on the server (a lazy include stays lazy).
- * Route discovery serializes the SSR copy, so the projection carries the
- * keys; materialization (client-urls/server-projection.ts) attaches the
- * registered predicates to the loader stubs.
+ * `import "<file>?rango-revalidate"` to the proxy of every group (a
+ * "use client" module calling clientUrls()). The proxy has none of the
+ * group's imports, and a component's `.use` may sit in any module the group
+ * reaches. Route discovery serializes the group's SSR copy, so its projection
+ * carries every key the group reads, and the transform records each key's
+ * file in every environment (ClientUrlRevalidateIndex): discovery assigns
+ * the group the files of its keys as it installs the projection
+ * (discovery/client-urls-projection.ts), and the group's `?rango-revalidate`
+ * module imports theirs. Their registrations load with the group and nothing
+ * else of those files does, so no client code loads on the server and a lazy
+ * include stays lazy, wherever the file sits: behind barrels or in another
+ * workspace package. Materialization
+ * (client-urls/server-projection.ts) attaches the registered predicates to
+ * the loader stubs; a key nothing registered fails loudly there.
  *
  * A key hashes the project-relative file and the predicate's syntax tree
  * (formatting, comments and TypeScript excluded, so a re-printing transform
  * in one environment keeps it): two environments that saw a different
  * predicate fail loudly at materialization instead of pairing a loader with
- * the wrong one.
+ * the wrong one. A module several groups import registers once.
+ *
+ * Keyed on calls of the `revalidate` helper from "@rangojs/router/client":
+ * imported directly (a component's `.use`), or handed out by a clientUrls()
+ * builder callback (destructured, renamed, or as `helpers.revalidate`). The
+ * argument may reference imports and globals only: a binding of the module
+ * or of an enclosing function, `this`/`arguments`/`super`/`new.target`,
+ * `import()`, `import.meta` other than `import.meta.env`, a browser-only
+ * global, an `async` or generator function, or an import of a "use client"
+ * module is a LOUD error naming file:line. Imports stay in the client module
+ * too (they are not pruned). Vitest does not run the plugin, so in unit
+ * tests the predicate stays a plain function.
  *
- * Keyed on calls of the `revalidate` helper a clientUrls() builder callback
- * receives (destructured, renamed, or as `helpers.revalidate`), with
- * clientUrls imported from "@rangojs/router/client". The argument may
- * reference imports and globals only: a binding of the module or of an
- * enclosing function, `this`/`arguments`/`super`/`new.target`, `import()`,
- * `import.meta` other than `import.meta.env`, a browser-only global, an
- * `async` or generator function, or an import of a "use client" module is a
- * LOUD error naming file:line. Imports stay in the "use client" module too
- * (they are not pruned). Vitest does not run the plugin, so in unit tests the
- * predicate stays a plain function.
+ * `revalidate(true)` / `revalidate(false)` LITERALS stay in place: the
+ * projection carries the boolean and materialization turns it into the
+ * constant predicate. Any other argument is hoisted whatever it evaluates
+ * to, because an imported boolean and an imported predicate are both
+ * identifiers to the build: the server evaluates the expression, and a
+ * boolean result means the same constant answer (`revalidate(FLAG)` with an
+ * imported `FLAG`). Materialization rejects a value that is neither.
  */
 
-const CLIENT_URLS_REVALIDATE_QUERY = "rango-revalidate";
 const REGISTER = "__rango_registerClientUrlRevalidators";
 
 const CLIENT_SOURCES: ReadonlySet<string> = new Set(["@rangojs/router/client"]);
@@ -120,19 +145,24 @@ const CAPTURE_MESSAGES: LexicalCaptureMessages = {
     "loads a module at run time, which the build cannot check is server-safe.",
 };
 
-// Cheap pre-filter: every site needs a "use client" module (the directive's
-// text), clientUrls imported from the router, and a `revalidate` helper. The
-// AST walk is the authority.
+// Cheap pre-filters: a site imports the router's client entry and names a
+// `revalidate` helper; a group also names clientUrls. The AST walk is the
+// authority.
 const CLIENT_URLS_RE = /\bclientUrls\b/;
-const CLIENT_IMPORT_RE = /["']@rangojs\/router\/client["']/;
 const REVALIDATE_RE = /\brevalidate\b/;
+const CANDIDATE_RE = /\b(?:clientUrls|revalidate)\b/;
 
 function mayHoist(code: string): boolean {
+  return CLIENT_IMPORT_RE.test(code) && REVALIDATE_RE.test(code);
+}
+
+/** A clientUrls() group: its RSC proxy imports the registrations. */
+function isGroupModule(code: string): boolean {
   return (
     code.includes("use client") &&
     CLIENT_URLS_RE.test(code) &&
     CLIENT_IMPORT_RE.test(code) &&
-    REVALIDATE_RE.test(code)
+    hasUseClientDirective(code)
   );
 }
 
@@ -253,9 +283,9 @@ interface HoistClientUrlsRevalidateResult {
 }
 
 /**
- * Hoist every clientUrls() `revalidate()` predicate of a "use client"
- * module. Returns null when there is none. Throws, naming file:line, for a
- * predicate that is not pure.
+ * Hoist every clientUrls() `revalidate()` predicate of a module. Returns null
+ * when there is none (boolean literals stay in place). Throws, naming
+ * file:line, for a predicate that is not pure.
  */
 export async function hoistClientUrlsRevalidates(
   code: string,
@@ -264,21 +294,15 @@ export async function hoistClientUrlsRevalidates(
 ): Promise<HoistClientUrlsRevalidateResult | null> {
   if (!mayHoist(code)) return null;
   const file = normalizePath(id.split("?", 1)[0]!);
-  let program: Node;
-  try {
-    program = parseAst(code, { lang: parseLang(file) });
-  } catch {
-    return null;
-  }
-  if (!hasDirective(program.body, "use client")) return null;
-
+  const program = parseProgram(code, file);
+  if (!program) return null;
   const { moduleScope, references, scopeOf } = analyzeScopes(program);
   const imports = collectImports(program);
   const calls = findHelperCalls(program, scopeOf, moduleScope, imports, {
     sources: CLIENT_SOURCES,
     builder: "clientUrls",
     helper: "revalidate",
-    directImport: false,
+    directImport: true,
   });
   if (calls.length === 0) return null;
 
@@ -294,16 +318,18 @@ export async function hoistClientUrlsRevalidates(
         file,
         code,
         call,
-        "`revalidate()` takes exactly one predicate.",
+        "`revalidate()` takes exactly one predicate or boolean.",
       );
     }
     const value = unwrapExpression(arg);
+    // The same constant in every environment: nothing to move.
+    if (value.type === "Literal" && typeof value.value === "boolean") continue;
     if (NOT_A_FUNCTION.has(value.type)) {
       throw revalidateError(
         file,
         code,
         value,
-        "`revalidate()` expects a predicate function.",
+        "`revalidate()` expects a predicate function or a boolean.",
       );
     }
     if (isFunctionLiteral(value) && (value.async || value.generator)) {
@@ -336,9 +362,12 @@ export async function hoistClientUrlsRevalidates(
         code,
         binding.node,
         binding.scope.lookup(name) === moduleScope
-          ? `\`${name}\` is declared in this "use client" module. Move the ` +
-              'predicate to its own module (without "use client") and ' +
-              "import it, or write it inline."
+          ? `\`${name}\` is declared in this ` +
+              (hasDirective(program.body, "use client")
+                ? '"use client" module'
+                : "module") +
+              ". Move the predicate to its own module (without " +
+              '"use client") and import it, or write it inline.'
           : `\`${name}\` is a binding of the enclosing function. Read what ` +
               "you need from the predicate's argument (`currentParams`, " +
               "`nextUrl`, `context`, `actionResult`, ...).",
@@ -391,6 +420,8 @@ export async function hoistClientUrlsRevalidates(
     );
   }
 
+  if (entries.size === 0) return null;
+
   const importLines = await emitImports(used, imports, () => {});
   const module = [
     `import { registerClientUrlRevalidators as ${REGISTER} } from "@rangojs/router/server";`,
@@ -421,6 +452,14 @@ async function isClientOnly(
   );
 }
 
+function parseProgram(code: string, file: string): Node | null {
+  try {
+    return parseAst(code, { lang: parseLang(file) });
+  } catch {
+    return null;
+  }
+}
+
 /** The file a `?rango-revalidate` id names, or null. */
 export function parseHoistedRevalidateId(id: string): string | null {
   const q = id.indexOf("?");
@@ -436,27 +475,43 @@ const HOISTED_ID_RE = new RegExp(
 );
 const SOURCE_ID_RE = /\.[cm]?[jt]sx?(?:\?|$)/;
 const NODE_MODULES_RE = /\/node_modules\//;
+const USE_ASSIGNMENT_RE = /\.use\s*=/;
 
 /**
  * The plugins: a pre transform that hoists in every environment (markers in
- * the client and SSR copies, the server module recorded from the RSC
- * transform) and serves `?rango-revalidate`, and a post transform that
- * appends its import to the RSC client-reference proxy.
+ * the client and SSR copies, each key's file in `index`, the server module
+ * recorded from the RSC transform, the groups noted) and serves
+ * `?rango-revalidate`, a post transform that appends its import to the RSC
+ * client-reference proxy of each group, and in dev the client's `.use`
+ * update propagation. Pass one `index` to every instance of one rango():
+ * discovery's temp server records keys the dev server or build reads.
+ *
+ * `load` serves the registrations the RSC transform emitted, which hoisted
+ * the pipeline code; the disk source is re-hoisted when the transform has not
+ * seen the current file (loadEmittedOrDisk), which is always the case for a
+ * component module: the RSC environment never transforms a module only a
+ * group imports. A group's module also imports the registrations of the
+ * files discovery assigned it. A file with neither serves an empty module.
  *
- * `load` serves the module the RSC transform emitted, which hoisted the
- * pipeline code; the disk source is re-hoisted only when the transform has
- * not seen the current file (loadEmittedOrDisk). A file whose edit removed
- * every predicate serves an empty module to a proxy that still imports it.
+ * A component module that exports only components is a Fast Refresh
+ * boundary, so a `.use` edit would leave the browser's group records stale
+ * (the group never re-evaluates). In dev, an update that changes a module's
+ * componentUseSignature also updates its importers, as a group edit does;
+ * any other edit keeps Fast Refresh.
  *
- * The transform's code filter skips a module that never mentions clientUrls,
- * so a file that stops doing so would keep its `emitted` entry: watchChange
- * drops it, together with the cached "use client" answer for an edited
- * dependency (isClientModule memoizes per resolved file; buildStart resets
- * it).
+ * The transform's code filter skips a module that names neither clientUrls
+ * nor revalidate, so a file that stops doing so would keep its `emitted`
+ * entry: watchChange drops it, its group mark, and the cached "use client"
+ * answer for an edited dependency (isClientModule memoizes per resolved
+ * file; buildStart resets it).
  */
-export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
+export function clientUrlsRevalidateHoistPlugin(
+  index: ClientUrlRevalidateIndex,
+): Plugin[] {
   const emitted = new Map<string, EmittedEntry<string>>();
+  const groups = new Set<string>();
   const clientModules = new Map<string, Promise<boolean>>();
+  const useSignatures = new Map<string, string>();
   let root = process.cwd();
 
   const isClientFile = (file: string): Promise<boolean> => {
@@ -472,6 +527,14 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
     }
     return known;
   };
+  const clientModuleCheck =
+    (ctx: SourceResolver, importer: string) =>
+    async (source: string): Promise<boolean> => {
+      const target = await resolveSourceTarget(ctx, source, importer, {
+        skipNodeModules: false,
+      });
+      return target !== null && (await isClientFile(target));
+    };
 
   return [
     {
@@ -479,7 +542,7 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
       enforce: "pre",
 
       configResolved(config) {
-        root = config.root;
+        root = normalizePath(config.root);
       },
 
       buildStart() {
@@ -490,6 +553,7 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
         const file = normalizePath(id);
         clientModules.delete(file);
         emitted.delete(file);
+        groups.delete(file);
       },
 
       load: {
@@ -497,14 +561,34 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
         async handler(id) {
           const hoistedFile = parseHoistedRevalidateId(id);
           if (hoistedFile === null) return;
-          const module = await loadEmittedOrDisk(
+          const file = normalizePath(hoistedFile);
+          const registrations = await loadEmittedOrDisk(
             emitted,
-            hoistedFile,
-            async (disk) =>
-              (await hoistClientUrlsRevalidates(disk, hoistedFile, { root }))
-                ?.module,
+            file,
+            await readSource(file),
+            async (source) =>
+              (
+                await hoistClientUrlsRevalidates(source, file, {
+                  root,
+                  isClientModule: clientModuleCheck(this, file),
+                })
+              )?.module,
           );
-          return module ?? "export {};\n";
+          const assigned = index.filesByGroup.get(file) ?? [];
+          const code =
+            registrations === undefined && assigned.length === 0
+              ? "export {};\n"
+              : [
+                  registrations ?? "",
+                  ...assigned.map(
+                    (target) =>
+                      `import ${JSON.stringify(hoistedRevalidateId(target))};\n`,
+                  ),
+                ].join("");
+          // Reached only through bare imports, and the id names an app file,
+          // so the app's package.json `"sideEffects": false` would let the
+          // build drop the registrations (#1149). load outranks that field.
+          return { code, moduleSideEffects: "no-treeshake" };
         },
       },
 
@@ -514,7 +598,7 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
             include: SOURCE_ID_RE,
             exclude: [NODE_MODULES_RE, HOISTED_ID_RE],
           },
-          code: CLIENT_URLS_RE,
+          code: CANDIDATE_RE,
         },
         async handler(code, id) {
           if (id.includes("/node_modules/") || parseHoistedRevalidateId(id)) {
@@ -523,19 +607,17 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
           const file = normalizePath(id.split("?", 1)[0]!);
           if (!SOURCE_FILE_RE.test(file)) return;
           const rsc = this.environment?.name === "rsc";
-          if (rsc) emitted.delete(file);
+          if (rsc) {
+            emitted.delete(file);
+            if (isGroupModule(code)) groups.add(file);
+            else groups.delete(file);
+          }
           const result = await hoistClientUrlsRevalidates(code, id, {
             root,
-            isClientModule: rsc
-              ? async (source) => {
-                  const target = await resolveSourceTarget(this, source, id, {
-                    skipNodeModules: false,
-                  });
-                  return target !== null && (await isClientFile(target));
-                }
-              : undefined,
+            isClientModule: rsc ? clientModuleCheck(this, id) : undefined,
           });
           if (!result) return;
+          for (const key of result.keys) index.fileByKey.set(key, file);
           if (rsc) await recordEmitted(emitted, file, result.module);
           return { code: result.code, map: result.map };
         },
@@ -551,14 +633,45 @@ export function clientUrlsRevalidateHoistPlugin(): Plugin[] {
         handler(code, id) {
           if (parseHoistedRevalidateId(id)) return;
           const file = normalizePath(id.split("?", 1)[0]!);
-          if (!emitted.has(file)) return;
+          if (!groups.has(file)) return;
           const s = new MagicString(code);
-          s.append(
-            `\nimport ${JSON.stringify(`${file}?${CLIENT_URLS_REVALIDATE_QUERY}`)};\n`,
-          );
+          s.append(`\nimport ${JSON.stringify(hoistedRevalidateId(file))};\n`);
           return { code: s.toString(), map: s.generateMap({ hires: true }) };
         },
       },
     },
+    {
+      name: "@rangojs/router:client-urls-component-use-hmr",
+      apply: "serve",
+      applyToEnvironment: (env) => env.name === "client",
+
+      transform: {
+        filter: {
+          id: { include: SOURCE_ID_RE, exclude: [NODE_MODULES_RE] },
+          code: USE_ASSIGNMENT_RE,
+        },
+        async handler(_code, id) {
+          // The disk source, as hotUpdate reads it: an earlier transform may
+          // re-print the module.
+          const file = normalizePath(id.split("?", 1)[0]!);
+          const disk = await readSource(file);
+          const signature = disk && componentUseSignature(disk, file);
+          if (signature) useSignatures.set(file, signature);
+        },
+      },
+
+      async hotUpdate({ file, modules, read }) {
+        if (modules.length === 0 || !SOURCE_FILE_RE.test(file)) return;
+        const next = componentUseSignature(await read(), file);
+        if (next === useSignatures.get(file)) return;
+        if (next === undefined) useSignatures.delete(file);
+        else useSignatures.set(file, next);
+        const updated = new Set<EnvironmentModuleNode>(modules);
+        for (const mod of modules) {
+          for (const importer of mod.importers) updated.add(importer);
+        }
+        return [...updated];
+      },
+    },
   ];
 }

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

@@ -187,6 +187,49 @@ export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
 
   const counter = createCounter(debug, "expose-internal-ids");
 
+  /** The virtual:rsc-router/loader-manifest module. */
+  function loaderManifestCode(): string {
+    if (!isBuild) {
+      return `import { setLoaderImports } from "@rangojs/router/server";
+
+// Dev mode: empty map, loaders are resolved dynamically via path parsing
+setLoaderImports({});
+`;
+    }
+
+    // Build mode: generate lazy import map. Sorted by id: the registry fills
+    // in directory-scan order (the pre-scan below) and transform order, both
+    // of which vary between machines and runs, and this module's bytes feed
+    // the cache version of every router bundled with it
+    // (discovery/build-versions.ts).
+    const lazyImports: string[] = [];
+    const sortedLoaders = [...loaderRegistry].sort(([a], [b]) =>
+      compareStrings(a, b),
+    );
+
+    for (const [hashedId, { filePath, exportName }] of sortedLoaders) {
+      lazyImports.push(
+        `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`,
+      );
+    }
+
+    if (lazyImports.length === 0) {
+      return `import { setLoaderImports } from "@rangojs/router/server";
+
+// No fetchable loaders discovered during build
+setLoaderImports({});
+`;
+    }
+
+    return `import { setLoaderImports } from "@rangojs/router/server";
+
+// Lazy import map - loaders are loaded on-demand when first requested
+setLoaderImports({
+${lazyImports.join(",\n")}
+});
+`;
+  }
+
   return {
     name: "@rangojs/router:expose-internal-ids",
     enforce: "post",
@@ -239,46 +282,9 @@ export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
       }
 
       if (id !== RESOLVED_VIRTUAL_LOADER_MANIFEST) return;
-
-      if (!isBuild) {
-        return `import { setLoaderImports } from "@rangojs/router/server";
-
-// Dev mode: empty map, loaders are resolved dynamically via path parsing
-setLoaderImports({});
-`;
-      }
-
-      // Build mode: generate lazy import map. Sorted by id: the registry fills
-      // in directory-scan order (the pre-scan below) and transform order, both
-      // of which vary between machines and runs, and this module's bytes feed
-      // the cache version of every router bundled with it
-      // (discovery/build-versions.ts).
-      const lazyImports: string[] = [];
-      const sortedLoaders = [...loaderRegistry].sort(([a], [b]) =>
-        compareStrings(a, b),
-      );
-
-      for (const [hashedId, { filePath, exportName }] of sortedLoaders) {
-        lazyImports.push(
-          `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`,
-        );
-      }
-
-      if (lazyImports.length === 0) {
-        return `import { setLoaderImports } from "@rangojs/router/server";
-
-// No fetchable loaders discovered during build
-setLoaderImports({});
-`;
-      }
-
-      return `import { setLoaderImports } from "@rangojs/router/server";
-
-// Lazy import map - loaders are loaded on-demand when first requested
-setLoaderImports({
-${lazyImports.join(",\n")}
-});
-`;
+      // Only ever a bare import (the RSC entry's), so a build whose
+      // treeshake.moduleSideEffects is false would drop it; load outranks it.
+      return { code: loaderManifestCode(), moduleSideEffects: "no-treeshake" };
     },
 
     // --------------- Loader pre-scan (build mode) ---------------

package/src/vite/plugins/hoist/source.ts

@@ -65,19 +65,20 @@ export async function recordEmitted<T>(
 }
 
 /**
- * What a `?rango-*` load serves for `hoistedFile`: the transform's emission
- * when it saw the current disk source (or the file is gone), else
- * `rehoist(disk)`. The transform hoists the pipeline code, which an earlier
- * plugin may have changed, so re-hoisting the disk source is the fallback only
- * for an environment loading before the RSC transform ran or for an edit the
- * RSC environment has not re-transformed yet. Undefined when neither exists.
+ * What a `?rango-*` load serves for `hoistedFile`, whose source on disk is
+ * `disk` (readSource): the transform's emission when it saw that source (or
+ * the file is gone), else `rehoist(disk)`. The transform hoists the pipeline
+ * code, which an earlier plugin may have changed, so re-hoisting the disk
+ * source is the fallback only for an environment loading before the RSC
+ * transform ran or for an edit the RSC environment has not re-transformed
+ * yet. Undefined when neither exists.
  */
 export async function loadEmittedOrDisk<T>(
   emitted: ReadonlyMap<string, EmittedEntry<T>>,
   hoistedFile: string,
+  disk: string | null,
   rehoist: (disk: string) => Promise<T | undefined>,
 ): Promise<T | undefined> {
-  const disk = await readSource(hoistedFile);
   const entry = emitted.get(normalizePath(hoistedFile));
   if (entry && (disk === null || entry.disk === disk)) return entry.value;
   return disk === null ? undefined : rehoist(disk);

package/src/vite/plugins/transition-when-hoist.ts

@@ -362,6 +362,7 @@ export function transitionWhenHoistPlugin(): Plugin {
       const modules = await loadEmittedOrDisk(
         emitted,
         hoisted.file,
+        await readSource(hoisted.file),
         async (disk) =>
           (await hoistTransitionWhens(disk, hoisted.file))?.modules,
       );

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

@@ -2,6 +2,7 @@ import { parseAst, type Plugin } from "vite";
 import {
   VIRTUAL_IDS,
   getVirtualBuildVersionContent,
+  getVirtualPackageVersionContent,
   getVirtualVersionContent,
 } from "./virtual-entries.js";
 import { hasUseClientDirective } from "../utils/directive-prologue.js";
@@ -170,6 +171,12 @@ export function createVersionPlugin(): Plugin {
 
     load(id) {
       if (id === "\0" + VIRTUAL_IDS.version) {
+        const environment = this?.environment?.name;
+        // The browser gets PACKAGE_VERSION only (ROUTER_VERSIONS is filled in
+        // server chunks); every other environment keeps the full module.
+        if (environment === "client") {
+          return getVirtualPackageVersionContent();
+        }
         return isDev
           ? getVirtualVersionContent(currentVersion)
           : getVirtualBuildVersionContent();

package/src/vite/plugins/version.d.ts

@@ -16,6 +16,13 @@ declare module "@rangojs/router:version" {
    */
   export const VERSION: string;
 
+  /**
+   * The npm semver of @rangojs/router (`1.2.3`). Informational: the browser
+   * entry publishes it as `window.__rango`. Every environment exports it; only
+   * the RSC environment also exports `VERSION` and `ROUTER_VERSIONS`.
+   */
+  export const PACKAGE_VERSION: string;
+
   /**
    * Per-router cache versions computed at build time: router id to
    * `[data, document]`, with `"*"` holding the whole-build pair.

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

@@ -1,5 +1,6 @@
 import type { HeadScriptsOption } from "../plugin-types.js";
 import { DEFAULT_ROUTER_VERSIONS_KEY } from "../../router-versions.js";
+import { rangoVersion } from "../utils/banner.js";
 
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
@@ -320,9 +321,27 @@ export const VIRTUAL_IDS = {
   version: "@rangojs/router:version",
 } as const;
 
+/**
+ * The npm semver of @rangojs/router, for the informational `window.__rango`
+ * marker (browser/rsc-router.tsx). Not a cache or build version.
+ */
+function getPackageVersionExport(): string {
+  return `export const PACKAGE_VERSION = ${JSON.stringify(rangoVersion)};`;
+}
+
+/**
+ * Non-RSC environments (client, ssr) get only PACKAGE_VERSION: the build
+ * module's ROUTER_VERSIONS token is replaced in server chunks only, so a
+ * client import of the full module would throw a ReferenceError.
+ */
+export function getVirtualPackageVersionContent(): string {
+  return getPackageVersionExport();
+}
+
 /** Dev: one stamp for both versions of every router, bumped on RSC edits. */
 export function getVirtualVersionContent(version: string): string {
   return [
+    getPackageVersionExport(),
     `export const VERSION = ${JSON.stringify(version)};`,
     `export const ROUTER_VERSIONS = undefined;`,
   ].join("\n");
@@ -346,6 +365,7 @@ export const ROUTER_VERSIONS_PLACEHOLDER = "__RANGO_ROUTER_VERSIONS__";
  */
 export function getVirtualBuildVersionContent(): string {
   return [
+    getPackageVersionExport(),
     `export const ROUTER_VERSIONS = ${ROUTER_VERSIONS_PLACEHOLDER};`,
     `export const VERSION = ROUTER_VERSIONS[${JSON.stringify(DEFAULT_ROUTER_VERSIONS_KEY)}][1];`,
   ].join("\n");