@rangojs/router 0.0.0-experimental.002d056c

package/src/vite/discovery/state.ts

@@ -0,0 +1,108 @@
+/**
+ * Discovery State
+ *
+ * Shared mutable state for the router discovery plugin.
+ * Created once by createRouterDiscoveryPlugin() and passed
+ * to all extracted helper functions.
+ */
+
+import type { ScanFilter } from "../../build/generate-route-types.js";
+
+export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+
+export interface PluginOptions {
+  enableBuildPrerender?: boolean;
+  staticRouteTypesGeneration?: boolean;
+  // Mutable ref for deferred auto-discovery (node preset).
+  // The auto-discover config() hook populates this before configResolved.
+  routerPathRef?: { path?: string };
+}
+
+export interface PrecomputedEntry {
+  staticPrefix: string;
+  routes: Record<string, string>;
+}
+
+export interface ChunkInfo {
+  fileName: string;
+  exports: Array<{ name: string; handlerId: string; passthrough: boolean }>;
+}
+
+export interface PerRouterManifestEntry {
+  id: string;
+  routeManifest: Record<string, string>;
+  routeSearchSchemas?: Record<string, Record<string, string>>;
+  sourceFile?: string;
+  factoryOnlyPrefixes?: Set<string>;
+}
+
+export interface DiscoveryState {
+  resolvedEntryPath: string | undefined;
+  projectRoot: string;
+  isBuildMode: boolean;
+  userResolveAlias: any;
+  scanFilter: ScanFilter | undefined;
+  cachedRouterFiles: string[] | undefined;
+  opts: PluginOptions | undefined;
+
+  mergedRouteManifest: Record<string, string> | null;
+  perRouterManifests: PerRouterManifestEntry[];
+  mergedPrecomputedEntries: PrecomputedEntry[] | null;
+  mergedRouteTrie: any;
+
+  perRouterTrieMap: Map<string, any>;
+  perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
+  perRouterManifestDataMap: Map<string, Record<string, string>>;
+
+  prerenderManifestEntries: Record<string, string> | null;
+  staticManifestEntries: Record<string, string> | null;
+  handlerChunkInfo: ChunkInfo | null;
+  staticHandlerChunkInfo: ChunkInfo | null;
+  rscEntryFileName: string | null;
+  resolvedPrerenderModules: Map<string, string[]> | undefined;
+  resolvedStaticModules: Map<string, string[]> | undefined;
+
+  discoveryDone: Promise<void> | null;
+  devServerOrigin: string | null;
+  devServer: any;
+  selfWrittenGenFiles: Map<string, { at: number; hash: string }>;
+  SELF_WRITE_WINDOW_MS: number;
+}
+
+export function createDiscoveryState(
+  entryPath: string | undefined,
+  opts: PluginOptions | undefined,
+): DiscoveryState {
+  return {
+    resolvedEntryPath: entryPath,
+    projectRoot: "",
+    isBuildMode: false,
+    userResolveAlias: undefined,
+    scanFilter: undefined,
+    cachedRouterFiles: undefined,
+    opts,
+
+    mergedRouteManifest: null,
+    perRouterManifests: [],
+    mergedPrecomputedEntries: null,
+    mergedRouteTrie: null,
+
+    perRouterTrieMap: new Map(),
+    perRouterPrecomputedMap: new Map(),
+    perRouterManifestDataMap: new Map(),
+
+    prerenderManifestEntries: null,
+    staticManifestEntries: null,
+    handlerChunkInfo: null,
+    staticHandlerChunkInfo: null,
+    rscEntryFileName: null,
+    resolvedPrerenderModules: undefined,
+    resolvedStaticModules: undefined,
+
+    discoveryDone: null,
+    devServerOrigin: null,
+    devServer: null,
+    selfWrittenGenFiles: new Map(),
+    SELF_WRITE_WINDOW_MS: 5_000,
+  };
+}

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

@@ -0,0 +1,203 @@
+/**
+ * Virtual Module Code Generation
+ *
+ * Generates the code for virtual:rsc-router/routes-manifest and
+ * per-router virtual modules used by the load() hook.
+ */
+
+import { dirname, basename, join } from "node:path";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
+import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
+import type { DiscoveryState } from "./state.js";
+
+/**
+ * Generate the code for the main virtual:rsc-router/routes-manifest module.
+ */
+export function generateRoutesManifestModule(state: DiscoveryState): string {
+  const hasManifest =
+    state.mergedRouteManifest &&
+    Object.keys(state.mergedRouteManifest).length > 0;
+
+  if (hasManifest) {
+    // Build gen file import statements for each router with a sourceFile.
+    // This creates a dependency in Vite's module graph: when the gen file
+    // changes (e.g. after HMR route edits), Vite invalidates this virtual
+    // module and re-evaluates it on the next request, calling
+    // setCachedManifest() with fresh data. No manual sync needed.
+    const genFileImports: string[] = [];
+    const genFileVars: string[] = [];
+    const routersWithoutGenFile: Array<{
+      id: string;
+      manifest: Record<string, string>;
+    }> = [];
+    let varIdx = 0;
+
+    for (const entry of state.perRouterManifests) {
+      if (entry.sourceFile) {
+        const routerDir = dirname(entry.sourceFile);
+        const routerBasename = basename(entry.sourceFile).replace(
+          /\.(tsx?|jsx?)$/,
+          "",
+        );
+        const genPath = join(
+          routerDir,
+          `${routerBasename}.named-routes.gen.js`,
+        ).replaceAll("\\", "/");
+        const varName = `_r${varIdx++}`;
+        genFileImports.push(
+          `import { NamedRoutes as ${varName} } from ${JSON.stringify(genPath)};`,
+        );
+        genFileVars.push(varName);
+      } else {
+        // Routers without sourceFile: inline their manifest data directly
+        routersWithoutGenFile.push({
+          id: entry.id,
+          manifest: entry.routeManifest,
+        });
+      }
+    }
+
+    const lines = [
+      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      ...genFileImports,
+      // Clear stale per-router cached data (manifest, trie, precomputed entries)
+      // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
+      // this virtual module but the route-map-builder singleton retains old data
+      // because it's not in the HMR invalidation chain. Without this clear, the
+      // handler finds stale trie data and never rebuilds from updated urlpatterns.
+      `clearAllRouterData();`,
+    ];
+
+    // Flatten NamedRoutes entries: search schema objects -> plain string paths
+    if (genFileVars.length > 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; }`,
+      );
+    }
+
+    // Build the merged manifest from gen file imports + inlined data
+    if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
+      lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
+    } else {
+      const parts: string[] = [];
+      for (const v of genFileVars) parts.push(`...__flat(${v})`);
+      for (const { manifest } of routersWithoutGenFile)
+        parts.push(`...${jsonParseExpression(manifest)}`);
+      lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
+    }
+
+    // Set per-router manifests
+    let genVarIdx = 0;
+    for (const entry of state.perRouterManifests) {
+      if (entry.sourceFile) {
+        const varName = genFileVars[genVarIdx++];
+        lines.push(
+          `setRouterManifest(${JSON.stringify(entry.id)}, __flat(${varName}));`,
+        );
+      } else {
+        lines.push(
+          `setRouterManifest(${JSON.stringify(entry.id)}, ${jsonParseExpression(entry.routeManifest)});`,
+        );
+      }
+    }
+
+    // In dev mode, skip trie and precomputed entries injection. These are
+    // computed once during initial discovery and become stale after route
+    // changes. A stale trie would incorrectly match removed routes. The
+    // handler falls back to Phase 2 regex matching against the live
+    // router.urlpatterns, which is always correct after a program reload.
+    // In build mode, the trie is always fresh (built from the final route
+    // tree) so it's safe to inject.
+    if (state.isBuildMode) {
+      if (
+        state.mergedPrecomputedEntries &&
+        state.mergedPrecomputedEntries.length > 0
+      ) {
+        lines.push(
+          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`,
+        );
+      }
+      if (state.mergedRouteTrie) {
+        lines.push(
+          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`,
+        );
+      }
+    }
+
+    // Register lazy loaders for per-router manifest modules.
+    // Each import() uses a static string literal so Rollup creates separate chunks.
+    for (const routerId of state.perRouterManifestDataMap.keys()) {
+      lines.push(
+        `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
+      );
+    }
+    if (!state.isBuildMode && state.devServerOrigin) {
+      lines.push(
+        `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(state.devServerOrigin)};`,
+      );
+    }
+    return lines.join("\n");
+  }
+
+  // No manifest: either discovery hasn't completed or no runner (Cloudflare dev).
+  // Still inject __PRERENDER_DEV_URL so the prerender store can fetch on-demand.
+  // Re-resolve origin now since the server is listening by module load time.
+  if (!state.isBuildMode) {
+    const origin =
+      state.devServerOrigin ||
+      state.devServer?.resolvedUrls?.local?.[0]?.replace(/\/$/, "") ||
+      (state.devServer &&
+        `http://localhost:${state.devServer.config.server.port || 5173}`);
+    if (origin) {
+      state.devServerOrigin = origin;
+      return `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(origin)};`;
+    }
+  }
+  return `// Route manifest will be populated at runtime`;
+}
+
+/**
+ * Generate the code for a per-router virtual module.
+ */
+export function generatePerRouterModule(
+  state: DiscoveryState,
+  routerId: string,
+): string {
+  // Find the per-router entry to get the gen file path
+  const routerEntry = state.perRouterManifests.find((e) => e.id === routerId);
+  const trie = state.perRouterTrieMap.get(routerId);
+  const entries = state.perRouterPrecomputedMap.get(routerId);
+  const lines: string[] = [];
+
+  if (routerEntry?.sourceFile) {
+    // Import manifest from the gen file so HMR auto-propagates
+    const routerDir = dirname(routerEntry.sourceFile);
+    const routerBasename = basename(routerEntry.sourceFile).replace(
+      /\.(tsx?|jsx?)$/,
+      "",
+    );
+    const genPath = join(
+      routerDir,
+      `${routerBasename}.named-routes.gen.js`,
+    ).replaceAll("\\", "/");
+    lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
+    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; }`,
+    );
+    lines.push(`export const manifest = __flat(_r);`);
+  } else {
+    const manifest = state.perRouterManifestDataMap.get(routerId);
+    if (manifest) {
+      lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
+    }
+  }
+  if (trie) {
+    lines.push(`export const trie = ${jsonParseExpression(trie)};`);
+  }
+  if (entries && entries.length > 0) {
+    lines.push(
+      `export const precomputedEntries = ${jsonParseExpression(entries)};`,
+    );
+  }
+  return lines.join("\n") || "// empty router manifest";
+}

package/src/vite/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public API for @rangojs/router/vite
+ *
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
+ */
+
+export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
+
+export type {
+  RangoNodeOptions,
+  RangoCloudflareOptions,
+  RangoOptions,
+} from "./plugin-types.js";

package/src/vite/plugin-types.ts

@@ -0,0 +1,48 @@
+/**
+ * Base options shared by all presets
+ */
+interface RangoBaseOptions {
+  /**
+   * Show startup banner. Set to false to disable.
+   * @default true
+   */
+  banner?: boolean;
+
+  /**
+   * Generate named-routes.gen.ts by parsing url modules at startup.
+   * Provides type-safe Handler<"name"> and href() without executing router code.
+   * Set to `false` to disable (run `npx rango extract-names` manually instead).
+   * @default true
+   */
+  staticRouteTypesGeneration?: boolean;
+}
+
+/**
+ * Options for Node.js deployment (default)
+ */
+export interface RangoNodeOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset. Defaults to 'node' when not specified.
+   */
+  preset?: "node";
+}
+
+/**
+ * Options for Cloudflare Workers deployment
+ */
+export interface RangoCloudflareOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset for Cloudflare Workers.
+   * When using cloudflare preset:
+   * - @vitejs/plugin-rsc is NOT added (cloudflare plugin adds it)
+   * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
+   * - Browser and SSR use virtual entries
+   * - Build-time manifest generation is auto-detected from the resolved RSC environment config
+   */
+  preset: "cloudflare";
+}
+
+/**
+ * Options for rango() Vite plugin
+ */
+export type RangoOptions = RangoNodeOptions | RangoCloudflareOptions;

package/src/vite/plugins/cjs-to-esm.ts

@@ -0,0 +1,93 @@
+import type { Plugin } from "vite";
+
+/**
+ * Transform CJS vendor files from @vitejs/plugin-rsc to ESM for browser compatibility.
+ * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
+ */
+export function createCjsToEsmPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:cjs-to-esm",
+    enforce: "pre",
+    transform(code, id) {
+      const cleanId = id.split("?")[0];
+
+      // Transform the client.browser.js entry point to re-export from CJS
+      if (
+        cleanId.includes("vendor/react-server-dom/client.browser.js") ||
+        cleanId.includes("vendor\\react-server-dom\\client.browser.js")
+      ) {
+        const isProd = process.env.NODE_ENV === "production";
+        const cjsFile = isProd
+          ? "./cjs/react-server-dom-webpack-client.browser.production.js"
+          : "./cjs/react-server-dom-webpack-client.browser.development.js";
+
+        return {
+          code: `export * from "${cjsFile}";`,
+          map: null,
+        };
+      }
+
+      // Transform the actual CJS files to ESM
+      if (
+        (cleanId.includes("vendor/react-server-dom/cjs/") ||
+          cleanId.includes("vendor\\react-server-dom\\cjs\\")) &&
+        cleanId.includes("client.browser")
+      ) {
+        let transformed = code;
+
+        // Extract the license comment to preserve it
+        const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
+        const license = licenseMatch ? licenseMatch[0] : "";
+        if (license) {
+          transformed = transformed.slice(license.length);
+        }
+
+        // Remove "use strict" (both dev and prod have this)
+        transformed = transformed.replace(/^\s*["']use strict["'];\s*/, "");
+
+        // Remove the conditional IIFE wrapper (development only)
+        transformed = transformed.replace(
+          /^\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
+          "",
+        );
+
+        // Remove the closing of the conditional IIFE at the end (development only)
+        transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
+
+        // Replace require('react') and require('react-dom') with imports (development)
+        transformed = transformed.replace(
+          /var\s+React\s*=\s*require\s*\(\s*["']react["']\s*\)\s*,[\s\n]+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import React from "react";\nimport ReactDOM from "react-dom";\nvar ',
+        );
+
+        // Replace require('react-dom') only (production - doesn't import React)
+        transformed = transformed.replace(
+          /var\s+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import ReactDOM from "react-dom";\nvar ',
+        );
+
+        // Transform exports.xyz = function() to export function xyz()
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=\s*function\s*\(/g,
+          "export function $1(",
+        );
+
+        // Transform exports.xyz = value to export const xyz = value
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=/g,
+          "export const $1 =",
+        );
+
+        // Reconstruct with license at the top
+        transformed = license + "\n" + transformed;
+
+        return {
+          code: transformed,
+          map: null,
+        };
+      }
+
+      return null;
+    },
+  };
+}

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

@@ -0,0 +1,115 @@
+import type { Plugin, ResolvedConfig } from "vite";
+
+const CLIENT_IN_SERVER_PROXY_PREFIX =
+  "virtual:vite-rsc/client-in-server-package-proxy/";
+
+/**
+ * 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 {
+  // Find the last /node_modules/ segment (handles nested node_modules)
+  const marker = "/node_modules/";
+  const idx = absolutePath.lastIndexOf(marker);
+  if (idx === -1) return null;
+
+  const afterModules = absolutePath.slice(idx + marker.length);
+
+  if (afterModules.startsWith("@")) {
+    // Scoped package: @org/name
+    const parts = afterModules.split("/");
+    if (parts.length < 2 || !parts[1]) return null;
+    return `${parts[0]}/${parts[1]}`;
+  }
+
+  // Unscoped package: name
+  const name = afterModules.split("/")[0];
+  return name || null;
+}
+
+/**
+ * Vite plugin that deduplicates client references from third-party packages
+ * in dev mode.
+ *
+ * When @vitejs/plugin-rsc encounters a "use client" submodule inside a
+ * package imported from a server component, it creates a
+ * client-in-server-package-proxy virtual module that re-exports from the
+ * absolute file path. In the client environment, this absolute path bypasses
+ * Vite's pre-bundling, while direct client imports of the same package go
+ * through .vite/deps/. Two separate module instances are created, breaking
+ * React contexts (createContext runs twice, provider/consumer mismatch).
+ *
+ * This plugin intercepts absolute node_modules imports from proxy modules
+ * in the client environment and rewrites them to bare specifier imports
+ * that go through pre-bundling, ensuring a single module instance.
+ *
+ * Dev-only: production builds use the SSR manifest which handles module
+ * identity correctly.
+ */
+export function clientRefDedup(): Plugin {
+  let clientExclude: string[] = [];
+
+  return {
+    name: "@rangojs/router:client-ref-dedup",
+    enforce: "pre",
+    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 ?? [];
+    },
+
+    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 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}`;
+    },
+
+    load(id) {
+      if (!id.startsWith("\0rango:dedup/")) return;
+
+      const packageName = id.slice("\0rango:dedup/".length);
+
+      // 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 default __all__.default;`,
+      ].join("\n");
+    },
+  };
+}

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

@@ -0,0 +1,105 @@
+import type { Plugin } from "vite";
+import { relative } from "node:path";
+import { createHash } from "node:crypto";
+
+// 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 =
+  "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
+const FS_PREFIX = "/@fs/";
+
+/**
+ * Compute the production SHA-256 hash for a dev-mode client reference key.
+ * Mirrors the hashing logic in @vitejs/plugin-rsc's build mode:
+ *   - Local files: hashString(toRelativeId(id)) where toRelativeId = relative(root, id)
+ *   - Package proxies: hashString(packageSource)
+ *   - client-in-server-package proxies: hashString(relative(root, decodedAbsPath))
+ *
+ * Returns the input unchanged if it doesn't match a known dev-mode pattern
+ * (e.g., already a production hash).
+ */
+export function computeProductionHash(
+  projectRoot: string,
+  refKey: string,
+): string {
+  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);
+}
+
+// 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;
+
+/**
+ * Transform source code by replacing dev-mode client reference keys with
+ * production hashes. Exported for testing; used internally by hashClientRefs.
+ * Returns null if no replacements were made.
+ */
+export function transformClientRefs(
+  code: string,
+  projectRoot: string,
+): string | null {
+  if (!code.includes("registerClientReference")) return null;
+
+  let hasReplacement = false;
+  const result = code.replace(
+    REGISTER_CLIENT_REF_RE,
+    (match, refKey: string) => {
+      const hash = computeProductionHash(projectRoot, refKey);
+      if (hash === refKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    },
+  );
+
+  return hasReplacement ? result : null;
+}
+
+/**
+ * Vite plugin that rewrites registerClientReference() calls in the RSC
+ * environment, replacing dev-mode reference keys with production hashes.
+ *
+ * This runs AFTER the RSC plugin's transform so the Flight serializer
+ * naturally emits production IDs, eliminating the need for post-build
+ * regex replacement of Flight payloads.
+ */
+export function hashClientRefs(projectRoot: string): Plugin {
+  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 };
+    },
+  };
+}