@rangojs/router 0.5.2 → 0.7.0

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/plugins/client-ref-dedup.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, normalize, relative } from "node:path";
 import type { Plugin, ResolvedConfig } from "vite";
 import { createRangoDebugger, NS } from "../debug.js";
 
@@ -5,23 +7,21 @@ const debug = createRangoDebugger(NS.transform);
 
 const CLIENT_IN_SERVER_PROXY_PREFIX =
   "virtual:vite-rsc/client-in-server-package-proxy/";
+const DEDUP_PREFIX = "\0rango:dedup/";
+
+interface PackageMetadata {
+  root: string;
+  selfName: string;
+  exports: unknown;
+}
+
+type PackageResolver = ReturnType<ResolvedConfig["createResolver"]>;
 
 /**
  * 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 {
@@ -44,6 +44,219 @@ export function extractPackageName(absolutePath: string): string | null {
   return name || null;
 }
 
+function stripQueryAndHash(id: string): string {
+  const suffixIndex = id.search(/[?#]/);
+  return suffixIndex === -1 ? id : id.slice(0, suffixIndex);
+}
+
+function getPackageRoot(source: string): string | undefined {
+  const packageName = extractPackageName(source);
+  if (!packageName) return;
+
+  const marker = "/node_modules/";
+  const markerIndex = source.lastIndexOf(marker);
+  return source.slice(0, markerIndex + marker.length) + packageName;
+}
+
+function readPackageMetadata(
+  source: string,
+  cache: Map<string, PackageMetadata | null>,
+): PackageMetadata | undefined {
+  const root = getPackageRoot(source);
+  if (!root) return;
+
+  const cached = cache.get(root);
+  if (cached !== undefined) return cached ?? undefined;
+
+  const packageJsonPath = join(root, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    cache.set(root, null);
+    return;
+  }
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      name?: unknown;
+      exports?: unknown;
+    };
+    if (typeof packageJson.name !== "string" || !packageJson.name) {
+      cache.set(root, null);
+      return;
+    }
+    const metadata = {
+      root,
+      selfName: packageJson.name,
+      exports: packageJson.exports,
+    } satisfies PackageMetadata;
+    cache.set(root, metadata);
+    return metadata;
+  } catch {
+    cache.set(root, null);
+    return;
+  }
+}
+
+function collectStringTargets(value: unknown, targets: string[]): void {
+  if (typeof value === "string") {
+    targets.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectStringTargets(item, targets);
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const target of Object.values(value)) {
+    collectStringTargets(target, targets);
+  }
+}
+
+function singleStarParts(value: string): [string, string] | undefined {
+  const starIndex = value.indexOf("*");
+  if (starIndex === -1 || value.indexOf("*", starIndex + 1) !== -1) return;
+  return [value.slice(0, starIndex), value.slice(starIndex + 1)];
+}
+
+function targetCanMapToSource(target: string, sourceRelative: string): boolean {
+  const targetStar = singleStarParts(target);
+  if (!targetStar) return target === sourceRelative;
+  const [prefix, suffix] = targetStar;
+  return (
+    sourceRelative.startsWith(prefix) &&
+    sourceRelative.endsWith(suffix) &&
+    sourceRelative.length >= prefix.length + suffix.length
+  );
+}
+
+function getPublicSpecifierCandidates(
+  metadata: PackageMetadata,
+  packageSpecifier: string,
+  source: string,
+): string[] {
+  if (
+    typeof metadata.exports !== "object" ||
+    metadata.exports === null ||
+    Array.isArray(metadata.exports)
+  ) {
+    return [];
+  }
+
+  const candidates = new Set<string>();
+  const sourceRelative = `./${relative(metadata.root, source).replaceAll("\\", "/")}`;
+  if (
+    sourceRelative.startsWith("./../") ||
+    isAbsolute(sourceRelative.slice(2))
+  ) {
+    return [];
+  }
+
+  for (const [exportKey, target] of Object.entries(metadata.exports)) {
+    if (!exportKey.startsWith("./") || exportKey === ".") continue;
+
+    const keyStar = singleStarParts(exportKey);
+    if (!keyStar) {
+      const targets: string[] = [];
+      collectStringTargets(target, targets);
+      if (
+        targets.some((target) => targetCanMapToSource(target, sourceRelative))
+      ) {
+        candidates.add(`${packageSpecifier}${exportKey.slice(1)}`);
+      }
+      continue;
+    }
+
+    const captures = new Set<string>();
+    const targets: string[] = [];
+    collectStringTargets(target, targets);
+    for (const targetPattern of targets) {
+      const targetStar = singleStarParts(targetPattern);
+      if (!targetStar) continue;
+      const [prefix, suffix] = targetStar;
+      if (
+        !sourceRelative.startsWith(prefix) ||
+        !sourceRelative.endsWith(suffix) ||
+        sourceRelative.length < prefix.length + suffix.length
+      ) {
+        continue;
+      }
+      captures.add(
+        sourceRelative.slice(
+          prefix.length,
+          sourceRelative.length - suffix.length,
+        ),
+      );
+    }
+
+    if (captures.size === 1) {
+      const capture = captures.values().next().value;
+      if (capture !== undefined) {
+        const publicSubpath = `${keyStar[0]}${capture}${keyStar[1]}`;
+        candidates.add(`${packageSpecifier}${publicSubpath.slice(1)}`);
+      }
+    }
+  }
+
+  return [...candidates];
+}
+
+function belongsToPackage(resolvedId: string, packageRoot: string): boolean {
+  return normalize(getPackageRoot(resolvedId) ?? "") === normalize(packageRoot);
+}
+
+async function resolvePublicSpecifier(
+  source: string,
+  metadata: PackageMetadata,
+  installedSpecifier: string,
+  resolvePackage: PackageResolver,
+  importer: string,
+): Promise<string | undefined> {
+  const packageSpecifiers =
+    installedSpecifier === metadata.selfName
+      ? [installedSpecifier]
+      : [installedSpecifier, metadata.selfName];
+
+  for (const packageSpecifier of packageSpecifiers) {
+    for (const candidate of getPublicSpecifierCandidates(
+      metadata,
+      packageSpecifier,
+      source,
+    )) {
+      try {
+        const resolved = await resolvePackage(candidate, importer);
+        if (!resolved) continue;
+        const resolvedId = stripQueryAndHash(resolved);
+        if (
+          normalize(resolvedId) === normalize(source) &&
+          belongsToPackage(resolvedId, metadata.root)
+        ) {
+          return candidate;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    // Fallback: the pre-exports-map behavior, and it is LOSSY. When no public
+    // subpath maps back to this exact file, re-export from the bare package
+    // root — correct only for packages that barrel-export their "use client"
+    // symbols from the entry point (the common component-library shape).
+    // A deep module whose symbols are NOT re-exported from the root loses
+    // them silently after this rewrite; the exports-map resolution above
+    // exists precisely to make that case rare.
+    try {
+      const rootResolved = await resolvePackage(packageSpecifier, importer);
+      if (
+        rootResolved &&
+        belongsToPackage(stripQueryAndHash(rootResolved), metadata.root)
+      ) {
+        return packageSpecifier;
+      }
+    } catch {
+      continue;
+    }
+  }
+}
+
 /**
  * Vite plugin that deduplicates client references from third-party packages
  * in dev mode.
@@ -65,7 +278,11 @@ export function extractPackageName(absolutePath: string): string | null {
  */
 export function clientRefDedup(): Plugin {
   let clientExclude: string[] = [];
+  let rootImporter = "";
+  let resolvePackage: PackageResolver | undefined;
   const dedupedPackages = new Set<string>();
+  const packageMetadataCache = new Map<string, PackageMetadata | null>();
+  const publicSpecifierCache = new Map<string, Promise<string | undefined>>();
 
   return {
     name: "@rangojs/router:client-ref-dedup",
@@ -76,6 +293,8 @@ export function clientRefDedup(): Plugin {
       const clientEnv = config.environments?.["client"];
       clientExclude =
         clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
+      rootImporter = join(config.root, "index.html");
+      resolvePackage = config.createResolver({ scan: true });
     },
 
     buildEnd() {
@@ -95,24 +314,67 @@ export function clientRefDedup(): Plugin {
 
       if (!source.includes("/node_modules/")) return;
 
-      const packageName = extractPackageName(source);
-      if (!packageName) return;
+      const cleanSource = stripQueryAndHash(source);
+      const packageName = extractPackageName(cleanSource);
+      if (!packageName || !resolvePackage) return;
 
       if (clientExclude.includes(packageName)) return;
 
-      if (debug) dedupedPackages.add(packageName);
+      const metadata = readPackageMetadata(cleanSource, packageMetadataCache);
+      if (!metadata || clientExclude.includes(metadata.selfName)) return;
+
+      let specifierPromise = publicSpecifierCache.get(cleanSource);
+      if (!specifierPromise) {
+        specifierPromise = resolvePublicSpecifier(
+          cleanSource,
+          metadata,
+          packageName,
+          resolvePackage,
+          rootImporter,
+        );
+        publicSpecifierCache.set(cleanSource, specifierPromise);
+        // Only SUCCESSFUL resolutions stay cached. A failed one is evicted so
+        // the next resolveId retries — deliberate: dev-time failures can be
+        // transient (a dependency installed mid-session, an exports map fixed
+        // on disk). The cost is a repeated candidate scan per unresolvable
+        // module, bounded by resolveId call frequency in dev.
+        void specifierPromise.then(
+          (specifier) => {
+            if (
+              !specifier &&
+              publicSpecifierCache.get(cleanSource) === specifierPromise
+            ) {
+              publicSpecifierCache.delete(cleanSource);
+            }
+          },
+          () => {
+            if (publicSpecifierCache.get(cleanSource) === specifierPromise) {
+              publicSpecifierCache.delete(cleanSource);
+            }
+          },
+        );
+      }
 
-      return `\0rango:dedup/${packageName}`;
+      return specifierPromise.then((specifier) => {
+        if (!specifier) return;
+        if (debug) dedupedPackages.add(packageName);
+        return `${DEDUP_PREFIX}${encodeURIComponent(specifier)}`;
+      });
     },
 
     load(id) {
-      if (!id.startsWith("\0rango:dedup/")) return;
+      if (!id.startsWith(DEDUP_PREFIX)) return;
 
-      const packageName = id.slice("\0rango:dedup/".length);
+      let specifier: string;
+      try {
+        specifier = decodeURIComponent(id.slice(DEDUP_PREFIX.length));
+      } catch {
+        return;
+      }
 
       return [
-        `export * from ${JSON.stringify(packageName)};`,
-        `import * as __all__ from ${JSON.stringify(packageName)};`,
+        `export * from ${JSON.stringify(specifier)};`,
+        `import * as __all__ from ${JSON.stringify(specifier)};`,
         `export default __all__.default;`,
       ].join("\n");
     },

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

@@ -1,4 +1,5 @@
 import type { Plugin, ResolvedConfig } from "vite";
+import { getPluginApi } from "@vitejs/plugin-rsc";
 import MagicString from "magic-string";
 import path from "node:path";
 import fs from "node:fs";
@@ -8,15 +9,15 @@ import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
 
+interface ServerReferenceMeta {
+  importId: string;
+  referenceKey: string;
+  exportNames: string[];
+}
+
 interface RscPluginManager {
-  serverReferenceMetaMap: Record<
-    string,
-    {
-      importId: string;
-      referenceKey: string;
-      exportNames: string[];
-    }
-  >;
+  serverReferenceMetaMap?: Record<string, ServerReferenceMeta>;
+  serverReferences?: { metaMap: Map<string, ServerReferenceMeta> };
   config: ResolvedConfig;
 }
 
@@ -24,21 +25,44 @@ interface RscPluginApi {
   manager: RscPluginManager;
 }
 
+function getServerReferenceMetaEntries(
+  manager: RscPluginManager | undefined,
+): Iterable<[string, ServerReferenceMeta]> {
+  if (manager?.serverReferences?.metaMap) {
+    return manager.serverReferences.metaMap;
+  }
+
+  if (manager?.serverReferenceMetaMap) {
+    return Object.entries(manager.serverReferenceMetaMap);
+  }
+
+  throw new Error(
+    "[rango] Unsupported @vitejs/plugin-rsc server reference metadata shape. " +
+      "Expected manager.serverReferences.metaMap or manager.serverReferenceMetaMap.",
+  );
+}
+
 function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
-  let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
+  const pluginApi = getPluginApi(config) as RscPluginApi | undefined;
+  if (pluginApi) {
+    return pluginApi;
+  }
 
-  if (!plugin) {
-    plugin = config.plugins.find(
-      (p) =>
-        (p.api as RscPluginApi | undefined)?.manager?.serverReferenceMetaMap !==
-        undefined,
-    );
-    if (plugin) {
-      console.warn(
-        `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
-          `Consider updating the name lookup if the plugin was renamed.`,
+  const plugin = config.plugins.find((p) => {
+    try {
+      getServerReferenceMetaEntries(
+        (p.api as RscPluginApi | undefined)?.manager,
       );
+      return true;
+    } catch {
+      return false;
     }
+  });
+  if (plugin) {
+    console.warn(
+      `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
+        `Consider updating the name lookup if the plugin was renamed.`,
+    );
   }
 
   return plugin?.api as RscPluginApi | undefined;
@@ -233,10 +257,8 @@ export function exposeActionId(): Plugin {
       if (!isBuild) return;
 
       hashToFileMap = new Map();
-      const { serverReferenceMetaMap } = rscPluginApi.manager;
-
-      for (const [absolutePath, meta] of Object.entries(
-        serverReferenceMetaMap,
+      for (const [absolutePath, meta] of getServerReferenceMetaEntries(
+        rscPluginApi.manager,
       )) {
         // Only include module-level "use server" files
         // Inline actions (defined in RSC components) should keep hashed IDs for client security

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.