@rangojs/router 0.5.0 → 0.5.2

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

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

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

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

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

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

package/src/vite/rango.ts

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

package/src/vite/router-discovery.ts

@@ -45,6 +45,8 @@ import {
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
 import { hashClientRefs } from "./plugins/client-ref-hashing.js";
+import { hashServerRefs } from "./plugins/server-ref-hashing.js";
+import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
   createDiscoveryState,
@@ -224,9 +226,26 @@ async function createTempRscServer(
           ssr: "virtual:entry-ssr",
           rsc: state.resolvedEntryPath!,
         },
+        // The temp server renders Static/Prerender output and encrypts inline-
+        // action bound args. Give it the SAME key as the main build/dev runtime
+        // (defineEncryptionKeyExpr is process-cached) so those args decrypt at
+        // invocation. Unconditional, NOT build-only: under Cloudflare/workerd dev
+        // the RSC env has no module runner, so prerender is rendered by THIS temp
+        // server (via /__rsc_prerender), and the action decrypts in the main
+        // runtime with the rango.ts key -- gating on forceBuild left dev encrypting
+        // with the temp server's own random key, failing decryptActionBoundArgs.
+        // (hashServerRefs stays build-only: dev keeps dev-style ids the dev runtime
+        // resolves directly.)
+        defineEncryptionKey: defineEncryptionKeyExpr(),
       }),
-      // hashClientRefs only in build mode — production bundles need hashed refs
-      ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
+      // hashClientRefs/hashServerRefs only in build mode — production bundles
+      // need hashed refs. hashServerRefs is the server-side analog: it rewrites
+      // registerServerReference dev-style ids to production hashes so a
+      // server-created action embedded in prerendered/static Flight resolves
+      // against the production manifest on a build-time-cache hit.
+      ...(options.forceBuild
+        ? [hashClientRefs(state.projectRoot), hashServerRefs(state.projectRoot)]
+        : []),
       createVersionPlugin(),
       // Before the stub plugin, so "virtual:entry-ssr" resolves to the real
       // SSR entry when the shell endpoint needs it (see the option doc).

package/src/vite/utils/shared-utils.ts

@@ -249,16 +249,21 @@ export function onwarn(
   defaultHandler(warning);
 }
 
+/**
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
+ */
 export function getManualChunks(id: string): string | undefined {
   const normalized = Vite.normalizePath(id);
 
-  if (
-    /\/browser\/prefetch\/(?:runtime|fetch|queue|observer|policy|resource-ready)\.[cm]?[jt]sx?(?:[?#].*)?$/.test(
-      normalized,
-    )
-  ) {
-    return undefined;
-  }
   if (
     normalized.includes("node_modules/react/") ||
     normalized.includes("node_modules/react-dom/") ||