@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/vite/router-discovery.ts

@@ -19,11 +19,16 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
+import {
+  DEV_SHELL_PROBE_TIMEOUT_MS,
+  normalizeCaptureTimeout,
+} from "../rsc/shell-serve.js";
 import {
   injectClientDebugFlag,
   internalDebugNoCacheMiddleware,
 } from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
+import { getVirtualEntrySSR, VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
   BUILD_ENV_GLOBAL_KEY,
@@ -46,6 +51,7 @@ import {
   peekSelfGenWrite,
 } from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
+import { runShellPrerenderPhase } from "./discovery/shell-prerender-phase.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import {
   createDevPrerenderCache,
@@ -125,6 +131,30 @@ function ensureCloudflareProtocolLoaderRegistered(): void {
 // Temp Server Factory
 // ============================================================================
 
+/**
+ * Outcome of getOrCreateTempServer. `env` is the temp RSC environment on
+ * success, else null with `error` carrying WHY the create/import failed — or
+ * null when createServer resolved cleanly but attached no runner (terminal, but
+ * not an exception). The dev /__rsc_shell endpoint runs `error` through the
+ * SAME reoptimization classifier the import sites use: only a transient Vite
+ * re-optimization is signalled NOT-READY (client re-polls); every terminal
+ * failure fails fast so the read-through MISSes immediately instead of
+ * re-polling a permanently-broken realm for the full readiness deadline
+ * (issue #719 P2).
+ */
+type TempServerResult = { env: any; error: unknown };
+
+/**
+ * Test-only one-shot boot-race injection (issue #719 P3). When
+ * RANGO_E2E_INJECT_SHELL_NOTREADY=1, the dev /__rsc_shell endpoint emits a
+ * single reoptimization-class NOT-READY per pathname before serving, so an e2e
+ * can drive the REAL endpoint + real client re-poll deterministically — a
+ * natural cold race settles too fast on quick machines to guard the regression.
+ * Keyed per pathname so the read-through's re-poll finds it already fired and
+ * gets the HIT. Never engaged without the env flag.
+ */
+const injectedShellNotReadyPaths = new Set<string>();
+
 /**
  * Create a minimal Vite server for router discovery.
  *
@@ -138,7 +168,21 @@ function ensureCloudflareProtocolLoaderRegistered(): void {
  */
 async function createTempRscServer(
   state: DiscoveryState,
-  options: { forceBuild?: boolean; cacheDir?: string } = {},
+  options: {
+    forceBuild?: boolean;
+    cacheDir?: string;
+    /**
+     * Serve the REAL rango SSR entry (getVirtualEntrySSR) for
+     * "virtual:entry-ssr" instead of the discovery stub, so the dev
+     * /__rsc_shell endpoint can drive captureShellHTML in this server's SSR
+     * realm. Dev-correct by construction: the entry's bootstrap resolves to
+     * plugin-rsc's stable virtual browser-entry URL, which the MAIN dev
+     * server serves to the browser. Loaded lazily — discovery never imports
+     * the SSR entry, so the temp server stays as light as before until a
+     * shell capture actually runs.
+     */
+    realSsrEntry?: boolean;
+  } = {},
 ) {
   // Install the Node ESM loader hook before any module evaluation so
   // `cloudflare:*` specifiers in externalized/loader-delegated modules
@@ -178,6 +222,26 @@ async function createTempRscServer(
       // hashClientRefs only in build mode — production bundles need hashed refs
       ...(options.forceBuild ? [hashClientRefs(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).
+      ...(options.realSsrEntry
+        ? [
+            {
+              name: "@rangojs/router:temp-real-ssr-entry",
+              enforce: "pre" as const,
+              resolveId(id: string) {
+                return id === "virtual:entry-ssr"
+                  ? "\0rango-temp-real-ssr-entry"
+                  : null;
+              },
+              load(id: string) {
+                return id === "\0rango-temp-real-ssr-entry"
+                  ? getVirtualEntrySSR(state.opts?.headScripts)
+                  : null;
+              },
+            } satisfies import("vite").Plugin,
+          ]
+        : []),
       createVirtualStubPlugin(),
       createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
@@ -281,6 +345,19 @@ async function acquireBuildEnv(
   return true;
 }
 
+/**
+ * Reset the per-build prerender collection state. A helper (not inline
+ * assignments in buildStart) so TS's property narrowing does not pin
+ * `s.shellCandidates` to `null` across the discovery call that repopulates
+ * it — the finally block re-reads it to decide the temp-server keep-alive.
+ */
+function resetPrerenderCollection(s: DiscoveryState): void {
+  s.prerenderManifestEntries = null;
+  s.staticManifestEntries = null;
+  s.shellCandidates = null;
+  s.prerenderPayloadValues = null;
+}
+
 /**
  * Release build-time env resources and clear state.
  */
@@ -480,7 +557,7 @@ export function createRouterDiscoveryPlugin(
         }
       }
 
-      async function getOrCreateTempServer(): Promise<any | null> {
+      async function getOrCreateTempServer(): Promise<TempServerResult> {
         // Reuse path: if a temp server is already alive, prefer reusing
         // it over orphaning the existing instance and spinning up a new
         // one. This handles two cases:
@@ -501,7 +578,7 @@ export function createRouterDiscoveryPlugin(
               debugDiscovery?.(
                 "getOrCreateTempServer: cached temp runner reused",
               );
-              return existingEnv;
+              return { env: existingEnv, error: null };
             }
             // Server alive but registry missing — likely after a prior
             // refresh's invalidate + import threw. Try to re-import.
@@ -510,7 +587,7 @@ export function createRouterDiscoveryPlugin(
             );
             try {
               await importEntryAndRegistry(existingEnv);
-              return existingEnv;
+              return { env: existingEnv, error: null };
             } catch (err: any) {
               debugDiscovery?.(
                 "getOrCreateTempServer: reuse import failed (%s) — closing orphan and creating fresh",
@@ -538,20 +615,30 @@ export function createRouterDiscoveryPlugin(
           "getOrCreateTempServer: creating new temp server, entry=%s",
           s.resolvedEntryPath ?? "(unset)",
         );
+        // Surface the create/import cause to the caller (issue #719 P2): a
+        // transient re-optimization is re-pollable, a terminal fault is not. A
+        // clean createServer that yields no runner leaves this null — terminal,
+        // but not an exception.
+        let createError: unknown = null;
         try {
           prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender",
+            // The dev /__rsc_shell endpoint drives captureShellHTML in this
+            // server's SSR realm; the entry is only imported when a shell
+            // capture runs, so discovery cost is unchanged.
+            realSsrEntry: true,
           });
 
           const tempRscEnv = (prerenderTempServer.environments as any)?.rsc;
           if (tempRscEnv?.runner) {
             await importEntryAndRegistry(tempRscEnv);
-            return tempRscEnv;
+            return { env: tempRscEnv, error: null };
           }
           debugDiscovery?.(
             "getOrCreateTempServer: tempRscEnv.runner unavailable",
           );
         } catch (err: any) {
+          createError = err;
           debugDiscovery?.(
             "getOrCreateTempServer: FAILED message=%s",
             err.message,
@@ -566,7 +653,7 @@ export function createRouterDiscoveryPlugin(
         await prerenderTempServer?.close().catch(() => {});
         prerenderTempServer = null;
         prerenderNodeRegistry = null;
-        return null;
+        return { env: null, error: createError };
       }
 
       // Clear the package-level singleton registries that survive a Vite
@@ -619,7 +706,7 @@ export function createRouterDiscoveryPlugin(
       // versions / preset configurations may differ in which graph carries
       // the module-runner cache).
       async function refreshTempRscEnv(): Promise<any | null> {
-        let tempRscEnv = await getOrCreateTempServer();
+        const tempRscEnv = (await getOrCreateTempServer()).env;
         if (!tempRscEnv) return null;
 
         // Module-runner cache is on the per-environment graph in Vite 6+;
@@ -645,7 +732,7 @@ export function createRouterDiscoveryPlugin(
             prerenderTempServer = null;
             prerenderNodeRegistry = null;
           }
-          return await getOrCreateTempServer();
+          return (await getOrCreateTempServer()).env;
         }
 
         debugDiscovery?.(
@@ -718,11 +805,11 @@ export function createRouterDiscoveryPlugin(
               acquireBuildEnv(s, viteCommand, viteMode),
             );
 
-            tempRscEnv = await timed(
-              debugDiscovery,
-              "getOrCreateTempServer",
-              () => getOrCreateTempServer(),
-            );
+            tempRscEnv = (
+              await timed(debugDiscovery, "getOrCreateTempServer", () =>
+                getOrCreateTempServer(),
+              )
+            ).env;
             if (tempRscEnv) {
               optimizerHashBefore =
                 tempRscEnv.depsOptimizer?.metadata?.browserHash;
@@ -949,7 +1036,7 @@ export function createRouterDiscoveryPlugin(
           // instances. Before #654 the cached registry was only refreshed on
           // route-file edits, so handler-only edits served stale prerender
           // content on this path. Warm-cache re-imports are module-cache hits.
-          const tempRscEnv = await getOrCreateTempServer();
+          const tempRscEnv = (await getOrCreateTempServer()).env;
           if (tempRscEnv) {
             try {
               await importEntryAndRegistry(tempRscEnv);
@@ -1057,6 +1144,283 @@ export function createRouterDiscoveryPlugin(
         logResult(404, "no match");
       });
 
+      // Dev on-demand PPR shell production (producer B, #699). There is no
+      // build manifest in dev, so the serve path's read-through
+      // (rsc/shell-build-manifest.ts) fetches the shell entry from here on a
+      // Prerender+ppr route's first request — dev serves x-rango-shell: HIT
+      // from request one, mirroring production. Memoized per router HMR
+      // generation AND per caller version (a client-module edit bumps the
+      // version without rotating the router instance; the stale entry would
+      // fail the serve gate forever). The endpoint is policy-free: the caller
+      // (the serve gate, which resolved the route's ppr option) sends
+      // ttl/swr/tags/version. Only prerender-backed routes produce entries —
+      // the /__rsc_prerender pre-flight below both warms the payload memo the
+      // capture's dev store fetch will hit AND refuses non-prerenderable
+      // routes (a live-handler render must never be served as a baked shell).
+      server.middlewares.use("/__rsc_shell", async (req: any, res: any) => {
+        await s.discoveryDone;
+        const url = new URL(req.url ?? "", "http://localhost");
+        const pathname = url.searchParams.get("pathname");
+        const routeName = url.searchParams.get("routeName");
+        const version = url.searchParams.get("version");
+        // ttl is required like the identifiers: the endpoint is policy-free
+        // (the serve gate resolved the route's ppr option and always sends
+        // it), so there is deliberately no default to drift from
+        // resolvePprConfig's.
+        const ttlRaw = url.searchParams.get("ttl");
+        if (!pathname || !routeName || !version || !ttlRaw) {
+          res.statusCode = 400;
+          res.end("Missing pathname/routeName/version/ttl");
+          return;
+        }
+
+        // Boot-race readiness signal (issue #719): the capture realm is stood
+        // up lazily on the first hit (temp server, registry import, and a Vite
+        // dep re-optimization the first shell-capture import can trigger). All
+        // are TRANSIENT — a retry seconds later succeeds. Tagging them 503 +
+        // x-rango-shell-dev: NOT-READY lets the read-through re-poll ONLY these
+        // (a bounded await of readiness) instead of mapping the boot window to
+        // a hard first-request MISS. Genuine negatives (404) stay untagged so a
+        // non-baked route never stalls the foreground.
+        const sendNotReady = (detail: string): void => {
+          res.statusCode = 503;
+          res.setHeader("x-rango-shell-dev", "NOT-READY");
+          res.end(detail);
+        };
+        // A Vite dependency re-optimization surfaces as ERR_OUTDATED_OPTIMIZED_DEP
+        // (import throws once, then re-imports clean) — retryable, unlike a real
+        // module fault (syntax error, missing export), which stays a hard 500.
+        // The message-regex fallback is NOT gratuitous: err.code is stripped when
+        // the error serializes across the module-runner/workerd RPC boundary (the
+        // message survives), so under the Cloudflare preset .code alone misses it.
+        const isReoptimizing = (err: any): boolean =>
+          err?.code === "ERR_OUTDATED_OPTIMIZED_DEP" ||
+          /Outdated Optimize Dep|optimized dependency|new dependencies optimized/i.test(
+            String(err?.message ?? ""),
+          );
+        // Fold the reoptimize-guard pasted at all three import/capture catch
+        // sites: emit NOT-READY + report handled for a transient re-optimization,
+        // else leave the caller to send its own terminal (500 for an entry
+        // import, 404 for a mid-capture failure that keeps runtime capture).
+        const handledAsReoptimizing = (err: any): boolean => {
+          if (!isReoptimizing(err)) return false;
+          sendNotReady(`Shell capture re-optimizing: ${err.message}`);
+          return true;
+        };
+        // Both entry-import sites (main-server rsc env, temp Node server) fail
+        // identically: reoptimize → NOT-READY, else → hard 500.
+        const handleShellImportError = (err: any): void => {
+          if (handledAsReoptimizing(err)) return;
+          res.statusCode = 500;
+          res.end(`Shell capture module refresh failed: ${err.message}`);
+        };
+        // Deterministic boot-race injection for e2e (issue #719 P3): fire ONE
+        // reopt-class NOT-READY per pathname through the REAL classifier so the
+        // read-through's re-poll path is exercised end-to-end (not just the
+        // unit-mocked fetch), then serve normally on the re-poll. Env-gated —
+        // inert in every non-test run.
+        if (
+          process.env.RANGO_E2E_INJECT_SHELL_NOTREADY === "1" &&
+          !injectedShellNotReadyPaths.has(pathname)
+        ) {
+          injectedShellNotReadyPaths.add(pathname);
+          const injected = Object.assign(
+            new Error("Outdated Optimize Dep (injected boot-race)"),
+            { code: "ERR_OUTDATED_OPTIMIZED_DEP" },
+          );
+          if (handledAsReoptimizing(injected)) return;
+        }
+        const ttl = Number(ttlRaw);
+        const swrRaw = url.searchParams.get("swr");
+        const swr = swrRaw === null ? undefined : Number(swrRaw);
+        const tagsRaw = url.searchParams.get("tags");
+        const tags = tagsRaw ? tagsRaw.split(",") : undefined;
+        const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+        const maxSnapshotBytes =
+          maxSnapshotBytesRaw === null
+            ? undefined
+            : Number(maxSnapshotBytesRaw);
+        // Boundary revalidation via the SHARED normalizer (shell-serve.ts):
+        // the param crossed an HTTP query string, and a garbage value must
+        // fall back to the capture default, never reach setTimeout as NaN
+        // (which Node clamps to ~1ms — an instant abort).
+        const captureTimeout = normalizeCaptureTimeout(
+          Number(url.searchParams.get("captureTimeout")),
+        );
+
+        // Resolve the capture realms: main-server envs (Node preset) or the
+        // shared temp Node server (Cloudflare preset — no main RSC runner).
+        // Entry re-import per request picks up HMR edits, exactly like the
+        // prerender endpoint above.
+        const rscEnvMain = (server.environments as any)?.rsc;
+        let rscRealm: any = null;
+        let ssrRealm: any = null;
+        let ssrEntryId: string;
+        // Why the temp-server path returned no runner, if it did: a transient
+        // re-optimization is re-pollable (NOT-READY), a terminal create/import
+        // fault is not. Carried from getOrCreateTempServer to the readiness
+        // check below so only reopt re-polls (issue #719 P2).
+        let tempServerError: unknown = null;
+        if (rscEnvMain?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnvMain.runner.import(s.resolvedEntryPath);
+          } catch (err: any) {
+            handleShellImportError(err);
+            return;
+          }
+          rscRealm = rscEnvMain;
+          ssrRealm = (server.environments as any)?.ssr;
+          ssrEntryId =
+            (server.environments as any)?.ssr?.config?.build?.rollupOptions
+              ?.input?.index ?? VIRTUAL_IDS.ssr;
+        } else {
+          const tempResult = await getOrCreateTempServer();
+          if (tempResult.env) {
+            try {
+              await importEntryAndRegistry(tempResult.env);
+            } catch (err: any) {
+              handleShellImportError(err);
+              return;
+            }
+          } else {
+            tempServerError = tempResult.error;
+          }
+          rscRealm = tempResult.env;
+          ssrRealm = (prerenderTempServer?.environments as any)?.ssr;
+          ssrEntryId = "virtual:entry-ssr";
+        }
+        if (!rscRealm?.runner || !ssrRealm?.runner) {
+          // Reoptimization is the ONLY transient class: re-poll it (NOT-READY).
+          // A terminal temp-server create/import fault, or an SSR runner absent
+          // after a clean createServer, fails fast with a plain 503 (no
+          // NOT-READY header) so the read-through MISSes on its first attempt
+          // instead of re-polling a permanently-broken realm for the full
+          // readiness deadline (issue #719 P2).
+          if (tempServerError && handledAsReoptimizing(tempServerError)) return;
+          res.statusCode = 503;
+          res.end("Shell capture runners not available");
+          return;
+        }
+        let registry: Map<string, any> | null = null;
+        let registryError: unknown = null;
+        try {
+          const serverMod = await rscRealm.runner.import(
+            "@rangojs/router/server",
+          );
+          registry = serverMod.RouterRegistry ?? null;
+        } catch (err: any) {
+          registryError = err;
+          registry = null;
+        }
+        if (!registry || registry.size === 0) {
+          // Same rule as the runner check: a re-optimization mid-import is
+          // re-pollable (NOT-READY); a terminal import fault or a genuinely
+          // empty registry (no routers registered) fails fast (issue #719 P2).
+          if (registryError && handledAsReoptimizing(registryError)) return;
+          res.statusCode = 503;
+          res.end("Shell capture registry not available");
+          return;
+        }
+
+        // Memo sweep FIRST: after request one the common case is a memo HIT
+        // (this fetch blocks a foreground document request), and the memoized
+        // body needs neither the pre-flight round-trip nor a capture. Keyed
+        // per router instance (= HMR generation) like the prerender memo.
+        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|c=${captureTimeout ?? ""}|v=${version}`;
+        for (const [, routerInstance] of registry) {
+          if (typeof routerInstance.match !== "function") continue;
+          const cached = devPrerenderCache.get(routerInstance, cacheKey);
+          if (cached !== undefined) {
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-shell-dev", "HIT");
+            res.end(cached);
+            return;
+          }
+        }
+
+        // Pre-flight: the route must be prerender-backed. Warms the payload
+        // memo the capture's dev prerender store will fetch, and closes the
+        // live-handler-bake hole (a non-pr route 404s here).
+        if (s.devServerOrigin) {
+          try {
+            const probe = await fetch(
+              `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
+              { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) },
+            );
+            if (!probe.ok) {
+              res.statusCode = 404;
+              res.end("Route is not prerenderable");
+              return;
+            }
+          } catch {
+            res.statusCode = 404;
+            res.end("Prerender pre-flight failed");
+            return;
+          }
+        }
+
+        for (const [, routerInstance] of registry) {
+          if (typeof routerInstance.match !== "function") continue;
+          try {
+            const ssrModule = await ssrRealm.runner.import(ssrEntryId);
+            if (typeof ssrModule?.captureShellHTML !== "function") {
+              res.statusCode = 404;
+              res.end("SSR entry has no captureShellHTML");
+              return;
+            }
+            const captureMod = await rscRealm.runner.import(
+              "@rangojs/router/build/shell-capture",
+            );
+            const result = await captureMod.captureShellForBuild({
+              router: routerInstance,
+              urlPath: pathname,
+              routeName,
+              key: `${pathname}:shell`,
+              ttl,
+              swr,
+              tags,
+              maxSnapshotBytes,
+              captureTimeout,
+              buildEnv: s.resolvedBuildEnv,
+              buildVersion: version,
+              captureShellHTML: ssrModule.captureShellHTML,
+              debug: !!debugDiscovery,
+            });
+            if (result.outcome === "route-mismatch") continue;
+            if (result.outcome !== "stored" || !result.entry) {
+              res.statusCode = 404;
+              res.end(`Shell capture ${result.outcome}`);
+              return;
+            }
+            const body = JSON.stringify({
+              entry: result.entry,
+              ttl,
+              swr,
+              tags: result.tags,
+              routeName,
+            });
+            devPrerenderCache.set(routerInstance, cacheKey, body);
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-shell-dev", "MISS");
+            res.end(body);
+            return;
+          } catch (err: any) {
+            // A dep re-optimization mid-capture is a boot-race, not a capture
+            // failure: signal NOT-READY so the read-through re-polls instead of
+            // conceding a first-request MISS (issue #719).
+            if (handledAsReoptimizing(err)) return;
+            console.warn(
+              `[rango] Dev shell capture error for ${pathname} (route keeps runtime capture): ${err.message}`,
+            );
+            res.statusCode = 404;
+            res.end(`Shell capture error: ${err.message}`);
+            return;
+          }
+        }
+        res.statusCode = 404;
+        res.end("No router matched");
+      });
+
       // Watch url module and router files for changes and regenerate named-routes.gen.ts.
       // Process files containing urls( or createRouter( to update the combined route map.
       if (opts?.staticRouteTypesGeneration !== false) {
@@ -1430,8 +1794,7 @@ export function createRouterDiscoveryPlugin(
       const buildStartTime = performance.now();
       debugDiscovery?.("build: start (env=%s)", this.environment?.name ?? "?");
       resetStagedBuildAssets(s.projectRoot);
-      s.prerenderManifestEntries = null;
-      s.staticManifestEntries = null;
+      resetPrerenderCollection(s);
 
       // Acquire build-time env bindings if configured
       await timed(debugDiscovery, "build acquireBuildEnv", () =>
@@ -1502,12 +1865,23 @@ export function createRouterDiscoveryPlugin(
         );
       } finally {
         delete (globalThis as any).__rscRouterDiscoveryActive;
-        if (tempServer) {
-          await timed(debugDiscovery, "build tempServer.close", () =>
-            tempServer.close(),
-          );
+        if (tempServer && s.shellCandidates?.length) {
+          // Prerender+ppr candidates exist: keep the temp server (and its
+          // realm — tries installed, registry populated) alive for the
+          // post-build shell capture phase (buildApp post, producer B #699).
+          // The prelude embeds built client asset URLs, so the capture can
+          // only run after the client build; that phase closes the server.
+          // buildEnv release is deferred with it — a bake-lane loader
+          // executing during the capture may read ctx.env.
+          s.shellPhaseTempServer = tempServer;
+        } else {
+          if (tempServer) {
+            await timed(debugDiscovery, "build tempServer.close", () =>
+              tempServer.close(),
+            );
+          }
+          await releaseBuildEnv(s);
         }
-        await releaseBuildEnv(s);
         debugDiscovery?.(
           "build discovery done (%sms)",
           (performance.now() - buildStartTime).toFixed(1),
@@ -1515,6 +1889,43 @@ export function createRouterDiscoveryPlugin(
       }
     },
 
+    // Post-build PPR shell capture (producer B, #699): runs after EVERY
+    // environment bundle is written — the shell prelude embeds built client
+    // asset URLs (bootstrap entry), which do not exist at buildStart. The
+    // kept temp server and the buildEnv were deferred AS A PAIR in
+    // buildStart's finally; this finally is the pair's success-path owner
+    // (buildEnd below owns the aborted-build path) — the phase itself is a
+    // pure producer and tears down only the globals it installs.
+    buildApp: {
+      order: "post",
+      async handler(builder) {
+        try {
+          await runShellPrerenderPhase(s, builder as any);
+        } finally {
+          if (s.isBuildMode) {
+            const tempServer = s.shellPhaseTempServer;
+            s.shellPhaseTempServer = null;
+            if (tempServer) await tempServer.close();
+            await releaseBuildEnv(s);
+          }
+        }
+      },
+    },
+
+    // An environment build failure aborts the builder before the buildApp
+    // post hook — never leak the kept temp server (open handles hang the CLI)
+    // or the deferred buildEnv (a live miniflare proxy).
+    async buildEnd(error) {
+      if (!error || !s.shellPhaseTempServer) return;
+      const tempServer = s.shellPhaseTempServer;
+      s.shellPhaseTempServer = null;
+      try {
+        await tempServer.close();
+      } finally {
+        await releaseBuildEnv(s);
+      }
+    },
+
     // Suppress vite's HMR cascade for our own gen-file writes.
     //
     // After every cf HMR cycle, refreshTempRscEnv → writeRouteTypesFiles

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

@@ -74,6 +74,7 @@ export function getPackageAliases(): Record<string, string> {
 
 export function getVendorAliases(): Record<string, string> {
   const specs = [
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
   ];

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

@@ -207,20 +207,27 @@ export function resetStagedBuildAssets(projectRoot: string): void {
   rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
 }
 
-export function stageBuildAssetModule(
-  projectRoot: string,
-  prefix: "__pr" | "__st",
+/**
+ * Write one content-hashed `export default <value>;` asset module into `dir`
+ * (created if needed) and return its file name. Identical payloads dedupe to
+ * one file (the hash is the content). Shared by the staged prerender/static
+ * flow (stageBuildAssetModule below) and the shell prerender phase, which
+ * writes directly into the final RSC assets dir — it runs after buildApp,
+ * past the staging/copy window.
+ */
+export function writeBuildAssetModule(
+  dir: string,
+  prefix: "__pr" | "__st" | "__ps",
   exportValue: string,
 ): string {
-  const stagedDir = getStagedAssetDir(projectRoot);
-  mkdirSync(stagedDir, { recursive: true });
+  mkdirSync(dir, { recursive: true });
 
   const contentHash = createHash("sha256")
     .update(exportValue)
     .digest("hex")
     .slice(0, 8);
   const fileName = `${prefix}-${contentHash}.js`;
-  const filePath = resolve(stagedDir, fileName);
+  const filePath = resolve(dir, fileName);
 
   if (!existsSync(filePath)) {
     writeFileSync(filePath, `export default ${exportValue};\n`);
@@ -229,6 +236,18 @@ export function stageBuildAssetModule(
   return fileName;
 }
 
+export function stageBuildAssetModule(
+  projectRoot: string,
+  prefix: "__pr" | "__st",
+  exportValue: string,
+): string {
+  return writeBuildAssetModule(
+    getStagedAssetDir(projectRoot),
+    prefix,
+    exportValue,
+  );
+}
+
 export function copyStagedBuildAssets(
   projectRoot: string,
   fileNames: Iterable<string>,