@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.80daa23e

package/src/vite/plugins/client-ref-dedup.ts

@@ -1,24 +1,27 @@
+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";
+
+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 {
@@ -41,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.
@@ -62,6 +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",
@@ -69,45 +290,91 @@ export function clientRefDedup(): Plugin {
     apply: "serve",
 
     configResolved(config: ResolvedConfig) {
-      // Respect user's optimizeDeps.exclude — if a package is explicitly
-      // excluded from pre-bundling, we shouldn't redirect it there.
       const clientEnv = config.environments?.["client"];
       clientExclude =
         clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
+      rootImporter = join(config.root, "index.html");
+      resolvePackage = config.createResolver({ scan: true });
+    },
+
+    buildEnd() {
+      if (debug && dedupedPackages.size > 0) {
+        debug(
+          "client-ref-dedup: redirected %d package(s) (%s)",
+          dedupedPackages.size,
+          [...dedupedPackages].join(","),
+        );
+      }
     },
 
     resolveId(source, importer, options) {
-      // Only intercept in the client environment
       if (this.environment?.name !== "client") return;
 
-      // Only handle imports from client-in-server-package-proxy virtual modules
       if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
 
-      // Only handle absolute node_modules paths
       if (!source.includes("/node_modules/")) return;
 
-      // Must have an importer
-      if (!importer) return;
+      const cleanSource = stripQueryAndHash(source);
+      const packageName = extractPackageName(cleanSource);
+      if (!packageName || !resolvePackage) return;
 
-      const packageName = extractPackageName(source);
-      if (!packageName) return;
-
-      // Don't redirect packages that are excluded from optimization
       if (clientExclude.includes(packageName)) return;
 
-      // Return a virtual module that re-exports via bare specifier
-      return `\0rango:dedup/${packageName}`;
+      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 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;
+      }
 
-      // Re-export via bare specifier so Vite routes through pre-bundling
       return [
-        `export * from ${JSON.stringify(packageName)};`,
-        `import * as __all__ from ${JSON.stringify(packageName)};`,
+        `export * from ${JSON.stringify(specifier)};`,
+        `import * as __all__ from ${JSON.stringify(specifier)};`,
         `export default __all__.default;`,
       ].join("\n");
     },

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

@@ -1,8 +1,10 @@
 import type { Plugin } from "vite";
 import { relative } from "node:path";
 import { createHash } from "node:crypto";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
-// Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
 const CLIENT_PKG_PROXY_PREFIX =
   "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
 const CLIENT_IN_SERVER_PKG_PROXY_PREFIX =
@@ -19,6 +21,17 @@ const FS_PREFIX = "/@fs/";
  * Returns the input unchanged if it doesn't match a known dev-mode pattern
  * (e.g., already a production hash).
  */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export function hashRefKey(relativeId: string): string {
+  return createHash("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+
 export function computeProductionHash(
   projectRoot: string,
   refKey: string,
@@ -26,32 +39,24 @@ export function computeProductionHash(
   let toHash: string;
 
   if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
-    // /@id/__x00__virtual:vite-rsc/client-package-proxy/<pkg> -> hash("<pkg>")
     toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
   } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
-    // /@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/<encodedAbsPath>
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length),
     );
     toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
-    // /@fs/abs/path.tsx -> hash(relative(root, "/abs/path.tsx"))
     const absPath = refKey.slice(FS_PREFIX.length - 1); // keep leading /
     toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
-    // /src/Button.tsx -> hash("src/Button.tsx")
     toHash = refKey.slice(1);
   } else {
-    // Already hashed or unknown format — return unchanged
     return refKey;
   }
 
-  return createHash("sha256").update(toHash).digest("hex").slice(0, 12);
+  return hashRefKey(toHash);
 }
 
-// Regex to match registerClientReference() calls as emitted by @vitejs/plugin-rsc.
-// Captures the reference key (second argument) from the call.
-// Handles two proxy forms: parenthesized expression `(expr)` and arrow-throw `() => { ... }`.
 const REGISTER_CLIENT_REF_RE =
   /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
 
@@ -89,17 +94,25 @@ export function transformClientRefs(
  * regex replacement of Flight payloads.
  */
 export function hashClientRefs(projectRoot: string): Plugin {
+  const counter = createCounter(debug, "hash-client-refs");
   return {
     name: "@rangojs/router:hash-client-refs",
-    // Run after the RSC plugin's transform (default enforce is normal)
     enforce: "post",
     applyToEnvironment(env) {
       return env.name === "rsc";
     },
-    transform(code, _id) {
-      const result = transformClientRefs(code, projectRoot);
-      if (result === null) return;
-      return { code: result, map: null };
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }

package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts

@@ -0,0 +1,23 @@
+export interface LoaderResolveContext {
+  parentURL?: string;
+  conditions?: readonly string[];
+  importAttributes?: Record<string, string>;
+}
+
+export interface LoaderResolveResult {
+  shortCircuit?: boolean;
+  url: string;
+  format?: "module" | "commonjs" | "json" | "wasm" | null;
+  importAttributes?: Record<string, string>;
+}
+
+export type NextResolve = (
+  specifier: string,
+  context?: LoaderResolveContext,
+) => Promise<LoaderResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: LoaderResolveContext,
+  nextResolve: NextResolve,
+): Promise<LoaderResolveResult>;

package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}