@rangojs/router 0.16.0 → 0.18.0

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -1,24 +1,127 @@
-// Stub for `@vitejs/plugin-rsc/rsc` and the split `/rsc/server`, `/rsc/client`
-// entries, shipped so consumers do not have to write a per-file `vi.mock(...)`.
-// Importing a router internal transitively pulls this module, whose real
-// top-level body imports Vite virtuals that do not resolve in plain node. The
-// unit/integration primitives (dispatch/runLoader/runMiddleware) never render
-// RSC, so empty fns suffice.
-export const createFromReadableStream = (): never => {
-  throw new Error("plugin-rsc stub: createFromReadableStream not available");
-};
-export const renderToReadableStream = (): never => {
-  throw new Error("plugin-rsc stub: renderToReadableStream not available");
-};
+/// <reference path="../flight-runtime.d.ts" />
+/**
+ * Stub for `@vitejs/plugin-rsc/rsc` and the split `/rsc/server`, `/rsc/client`
+ * entries, shipped so consumers do not have to write a per-file `vi.mock(...)`.
+ * The real entries top-level import Vite virtuals that do not resolve in plain
+ * node.
+ *
+ * Under the `react-server` condition (the Flight project) the "use cache"
+ * codec runs on real Flight: the vendored react-server-dom `server.edge` /
+ * `client.edge` builds that plugin-rsc's `react/rsc/server` and
+ * `react/rsc/client` wrap, with the same manifests and the same server-side
+ * reference loader (`@vitejs/plugin-rsc/core/rsc` `setRequireModule`), so
+ * keys, writes, hits, value round trips and error rows match a build. The
+ * wrappers are not reused: their manifests read `import.meta.env.DEV`, which
+ * is undefined in a module node loads directly (vitest externalizes
+ * node_modules).
+ *
+ * Without the condition React's server build refuses to load, so the codec
+ * functions throw and a "use cache" call runs uncached. Any other load failure
+ * (a moved vendored path, a missing peer) throws. The action entries stay
+ * inert either way: no primitive decodes an action request.
+ */
+
+/** React's server build throws this on load without the react-server condition. */
+const MISSING_REACT_SERVER_CONDITION =
+  /"react-server" condition must be enabled/;
+
+async function loadFlightRuntime() {
+  // The server build first, alone. `@vitejs/plugin-rsc/core/rsc` statically
+  // imports it, and importing that ESM module after the CJS build failed to
+  // load leaks an unhandled rejection from Node's module loader even when every
+  // import() is caught (Node 22 and 24). So core/rsc loads only once the server
+  // build has.
+  const server =
+    await import("@vitejs/plugin-rsc/vendor/react-server-dom/server.edge").catch(
+      (error: unknown) => {
+        if (
+          error instanceof Error &&
+          MISSING_REACT_SERVER_CONDITION.test(error.message)
+        ) {
+          return undefined;
+        }
+        throw error;
+      },
+    );
+  if (!server) return undefined;
+  const [client, core] = await Promise.all([
+    import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge"),
+    import("@vitejs/plugin-rsc/core/rsc"),
+  ]);
+  await import("../internal/flight-client-globals.js");
+  // Resolves the `$$decode-client:` / `$$preserve:` ids a cached value's client
+  // and server references decode to; any other id would load a server module.
+  core.setRequireModule({
+    load: (id) => {
+      throw new Error(
+        `plugin-rsc stub: server reference module "${id}" is not loadable in a test`,
+      );
+    },
+  });
+  return { server, client, core };
+}
+
+const runtime = await loadFlightRuntime();
+
+/** `<module id>#<export name>` -> manifest entry, as plugin-rsc builds it. */
+function referenceManifest(prefix: string): Record<string, unknown> {
+  return new Proxy(
+    {},
+    {
+      get(_target, $$id) {
+        if (typeof $$id !== "string") return undefined;
+        const [id, name] = $$id.split("#");
+        return { id: prefix + id, name, chunks: [], async: true };
+      },
+    },
+  );
+}
+
+const CLIENT_MANIFEST = referenceManifest("");
+
+function unavailable(name: string): never {
+  throw new Error(
+    `plugin-rsc stub: ${name} needs the react-server condition (the Flight test project)`,
+  );
+}
+
+export const renderToReadableStream = (
+  value: unknown,
+  options?: object,
+): ReadableStream<Uint8Array> =>
+  runtime
+    ? runtime.server.renderToReadableStream(value, CLIENT_MANIFEST, options)
+    : unavailable("renderToReadableStream");
+export const createTemporaryReferenceSet = (): unknown =>
+  runtime ? runtime.server.createTemporaryReferenceSet() : {};
+export const createFromReadableStream = (
+  stream: ReadableStream<Uint8Array>,
+  options?: object,
+  extraOptions?: { preserveServerReferences?: boolean },
+): Promise<unknown> =>
+  runtime
+    ? runtime.client.createFromReadableStream(stream, {
+        serverConsumerManifest: {
+          serverModuleMap: referenceManifest(
+            extraOptions?.preserveServerReferences
+              ? "$$server:$$preserve:"
+              : "$$server:",
+          ),
+          moduleMap: runtime.core.createServerDecodeClientManifest(),
+        },
+        ...options,
+      })
+    : unavailable("createFromReadableStream");
+export const encodeReply = (
+  value: unknown,
+  options?: object,
+): Promise<string | FormData> =>
+  runtime
+    ? runtime.client.encodeReply(value, options)
+    : unavailable("encodeReply");
+export const createClientTemporaryReferenceSet = (): unknown =>
+  runtime ? runtime.client.createTemporaryReferenceSet() : {};
 export const loadServerAction = (): undefined => undefined;
 export const decodeReply = (): undefined => undefined;
 export const decodeAction = (): undefined => undefined;
 export const decodeFormState = (): undefined => undefined;
-export const createTemporaryReferenceSet = (): Record<string, never> => ({});
-export const encodeReply = (): never => {
-  throw new Error("plugin-rsc stub: encodeReply not available");
-};
-export const createClientTemporaryReferenceSet = (): Record<
-  string,
-  never
-> => ({});

package/src/testing/vitest.ts

@@ -78,6 +78,10 @@
 
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  isUseCacheCandidate,
+  transformUseCache,
+} from "../vite/plugins/use-cache-transform.js";
 
 /** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
 export interface TestAlias {
@@ -262,6 +266,7 @@ interface FlightTransformPlugin {
  * import { defineConfig } from "vitest/config";
  * import {
  *   rangoUseClientTransform,
+ *   rangoUseCacheTransform,
  *   rangoTestAliases,
  *   rangoInlineDeps,
  * } from "@rangojs/router/testing/vitest";
@@ -271,7 +276,7 @@ interface FlightTransformPlugin {
  * process.env.NODE_ENV = "production";
  *
  * export default defineConfig({
- *   plugins: [rangoUseClientTransform()],
+ *   plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
  *   resolve: {
  *     conditions: ["react-server"],
  *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
@@ -340,3 +345,59 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
     },
   };
 }
+
+/** The Vite plugin shape {@link rangoUseCacheTransform} returns. */
+interface UseCacheTransformPlugin {
+  name: string;
+  enforce: "post";
+  configResolved(config: { root: string }): void;
+  transform(
+    this: { warn(message: string): void },
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin that applies the rango plugin's `"use cache"` transform in a
+ * Vitest project, so a function written with the directive is wrapped with
+ * `registerCachedFunction` as in dev and a build. `rango()` runs that transform
+ * only in its `rsc` environment and Vitest transforms in `ssr`, so without this
+ * plugin the directive is an inert string and the function runs on every call.
+ *
+ * Add it to the react-server project next to {@link rangoUseClientTransform}
+ * (see that function's config). There, with a seeded `cacheStore`,
+ * `renderHandler` / `runLoader` observe real hits. In the node project the
+ * wrap applies too, but the stubbed Flight serializer cannot write an entry.
+ *
+ * Ids are the ones `vite dev` emits: `<path relative to the Vitest root>#<name>`
+ * (a function-level directive gives `src/data.ts#$$hoist_0_getData`), not the
+ * build's hashed path, so store keys stay readable. `configResolved` sets that
+ * root. If `@vitejs/plugin-rsc/transforms` fails to load, the transform throws
+ * instead of leaving the module unwrapped (which the rango plugin does).
+ */
+export function rangoUseCacheTransform(): UseCacheTransformPlugin {
+  let root = process.cwd();
+  return {
+    name: "rango:testing-use-cache",
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    async transform(code, id) {
+      if (!isUseCacheCandidate(code, id)) return undefined;
+      return transformUseCache(code, id, {
+        root,
+        isBuild: false,
+        warn: (message) => this.warn(message),
+        onTransformsError: (error) => {
+          throw new Error(
+            `rangoUseCacheTransform: @vitejs/plugin-rsc/transforms failed to ` +
+              `load, so "use cache" functions in ${id} would run unwrapped.`,
+            { cause: error },
+          );
+        },
+      });
+    },
+  };
+}

package/src/theme/ThemeProvider.tsx

@@ -133,12 +133,13 @@ export function ThemeProvider({
     setSystemTheme(getSystemTheme());
     // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
     // comes from the payload and can legitimately differ from the visitor's
-    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's theme
-    // (the resume tree must match the frozen prelude; see
-    // ShellCacheEntry.initialTheme). The FOUC script already applied the stored
-    // theme to the document pre-paint; this brings the provider state (toggles,
-    // useTheme readers) in line with it, and is the ONLY place the provider
-    // reads storage (the initializer must not — see the parity note above).
+    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's
+    // initialTheme, the no-cookie default (the resume tree must match the
+    // frozen prelude; see ShellCacheEntry.initialTheme). The FOUC script
+    // already applied the stored theme to the document pre-paint; this brings
+    // the provider state (toggles, useTheme readers) in line with it, and is
+    // the ONLY place the provider reads storage (the initializer must not —
+    // see the parity note above).
     // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
     // fallback must not override a server-provided initialTheme when the
     // visitor never chose a theme.

package/src/theme/ThemeScript.tsx

@@ -8,14 +8,14 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
- * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * Note: when theme is enabled in the router config, `<Html.Meta />` ALREADY
  * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
- * `<MetaTags />`. Rendering both is safe — the inline script guards the
+ * `<Html.Meta />`. Rendering both is safe — the inline script guards the
  * matchMedia listener registration against double-running — but it is redundant.
  *
  * @example
  * ```tsx
- * // In your document component. Use ThemeScript only when you do not render MetaTags.
+ * // In your document component. Use ThemeScript only when you do not render Html.Meta.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {

package/src/types/cache-types.ts

@@ -1,12 +1,13 @@
 /**
- * Context passed to cache condition/key/tags functions.
+ * Context passed to cache condition/key/tags functions (the full
+ * RequestContext).
  *
- * This is a subset of RequestContext that's guaranteed to be available
- * during cache key generation (before middleware runs).
- *
- * Note: While the full RequestContext is passed, middleware-set variables
- * read via `ctx.get()` may not be populated yet since cache lookup happens
- * before middleware execution.
+ * Ordering: global middleware wraps the whole request, and on RSC routes route
+ * middleware wraps the match/render pipeline (rsc/handler.ts executeRender), so
+ * variables they set before `next()` are readable via `ctx.get()`. On response
+ * routes the cache lookup runs BEFORE route middleware, which wraps only the
+ * handler run on a miss (rsc/response-route-handler.ts); only global-middleware
+ * variables are populated there.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 
@@ -109,7 +110,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Return false to skip cache for this request (always fetch fresh).
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -131,7 +133,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Bypasses default key generation AND store's keyGenerator.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -153,7 +156,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
+   * `VercelCacheStore` index by tag.
    * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
    * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
    * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed

package/src/types/handler-context.ts

@@ -342,6 +342,12 @@ export type HandlerContext<
    * Current theme (from cookie or default).
    * Only available when theme is enabled in router config.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it on a
+   * `ppr` route refuses the shell capture, and inside a `cache()` boundary or
+   * a `"use cache"` function it throws (#971). Read it with `useTheme()` in a
+   * client component, or in a live loader, on those routes. A read-only,
+   * non-enumerable getter: `{ ...ctx }` does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -350,7 +356,7 @@ export type HandlerContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
   /**
    * Set the theme (only available when theme is enabled in router config).
    * Sets a cookie with the new theme value.
@@ -455,6 +461,27 @@ export type InternalHandlerContext<
    * table (so a loader cannot await its own in-flight memoized promise).
    */
   _loaderCacheOriginalUse?: (item: any) => any;
+  /**
+   * @internal A loader-cache HIT asks before replaying a loader's recorded
+   * pushes: true when that loader has not run in this request and no other
+   * replay delivered it; its later run then replaces the replayed values
+   * (HandleStore.pushReplayed). One copy per loader per request. See
+   * setupLoaderAccess.
+   */
+  _claimLoaderPushes?: (loaderId: string) => boolean;
+  /**
+   * @internal Run a loader on a fresh executor (own memo map): a loader-cache
+   * stale refresh, whose diverted pushes must not take a dependency's run
+   * from the page. See setupLoaderAccess.
+   */
+  _runLoaderIsolated?: (loader: any) => Promise<any>;
+  /**
+   * @internal A loader's cache() binding started with these cache() tags: an
+   * execution of that loader outside the binding (a reader started it first,
+   * or a stale refresh runs it) answers for them too (#964). See
+   * setupLoaderAccess.
+   */
+  _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
 };
 
 /**

package/src/types/loader-types.ts

@@ -28,9 +28,10 @@ import type { RequestScope } from "./request-scope.js";
  *   return await db.cart.get(user.id);
  * });
  *
- * // With typed params:
- * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  * ```
@@ -243,9 +244,10 @@ export type LoadOptions =
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
- * // With typed params:
- * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * export const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  *

package/src/urls/pattern-types.ts

@@ -59,30 +59,34 @@ export interface PartialPrerenderProps {
   /**
    * Operational tags attached to the captured shell entry for
    * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-   * capture render auto-collects (the shell's own non-loader request tags).
+   * capture collects: its doc record's tags (what the handler layer and the
+   * server components it rendered recorded) and its bake-lane loaders'.
    */
   tags?: string[];
   /**
-   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-   * inside the shell entry. The snapshot duplicates every cache-store value
-   * the capture pinned, so a page over a large cache() segment can push the
-   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-   * Over the cap the snapshot is skipped: the shell is still stored and
-   * served, but pinned reads fall back to the live store, so drifted cached
-   * content can hydration-mismatch and be repaired client-side (the
-   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
+   * data snapshot: the loader records and the cache values loaders read,
+   * duplicated into the shell entry. The doc record (the handler layer every
+   * HIT replays) is exempt. Over the cap the pins are dropped: the shell is
+   * still stored and every HIT still replays the handler layer, but the
+   * pinned loaders read the live store, so drifted cached content can
+   * hydration-mismatch and be repaired client-side. Reported once per key.
+   * Defaults to 8 MiB. The whole entry is bounded separately by the store's
+   * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
    */
   maxSnapshotBytes?: number;
   /**
-   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-   * background capture: the wait for deferred shell material — top-level
-   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-   * are AWAITED and their settled values baked into the stored shell — AND
-   * the fizz prerender deadline. Declare it to tighten the budget below the
-   * default or when a route's shell material takes longer than 15s to
-   * settle. A budget that expires with pushes still pending REFUSES the
-   * capture (the route stays MISS with the once-per-key warning) — a shell
-   * with missing head material is never stored. Capture is background work
+   * Capture settle budget in MILLISECONDS (default 15000). One deadline for
+   * the whole background capture: the match (the handlers, and the loaders
+   * they await), the wait for handler output (handle pushes and the promises
+   * nested in them, bake-lane loaders, and the doc record's encode, which
+   * awaits handler promises and async server components), AND the fizz
+   * prerender. Everything a handler produces is
+   * awaited and baked into the stored shell. Declare it to tighten the
+   * budget below the default or when a route's shell material takes longer
+   * than 15s to settle. A budget that expires before the doc record is
+   * written REFUSES the capture (the route stays MISS with the once-per-key
+   * warning): a shell with missing handler output is never stored. Capture is background work
    * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
    * response; the platform waitUntil lifetime (workerd: ~30s past response
    * completion) is the physical ceiling — the default's derivation lives in

package/src/urls/response-types.ts

@@ -1,5 +1,5 @@
 import type { ContextVar } from "../context-var.js";
-import type { ReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type {
   DefaultReverseRouteMap,
   DefaultVars,
@@ -7,27 +7,6 @@ import type {
 import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
 import type { RequestScope } from "../types/request-scope.js";
 
-/**
- * Reverse function for response handler contexts.
- * Global names get autocomplete and param validation from the generated route map.
- * Local `.name` calls are accepted but not validated (scope unknown at type level).
- */
-type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
-  Record<string, string>,
-]
-  ? (
-      name: string,
-      params?: Record<string, string>,
-      search?: Record<string, unknown>,
-    ) => string
-  : ReverseFunction<DefaultReverseRouteMap> & {
-      (
-        name: `.${string}`,
-        params?: Record<string, string>,
-        search?: Record<string, unknown>,
-      ): string;
-    };
-
 /**
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
@@ -99,7 +78,8 @@ export interface ResponseHandlerContext<
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  reverse: ResponseReverseFunction;
+  /** Global route names only; see {@link GlobalReverseFunction}. */
+  reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;

package/src/use-loader.tsx

@@ -117,6 +117,14 @@ export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
 export interface UseLoaderResult<T> {
   data: T;
+  /**
+   * True while this loader family (`loader.$$id`) is in flight: a `load()` /
+   * group refresh, or a held navigation still streaming a re-run of this
+   * loader. Family-keyed, not segment-keyed: a layout `useLoader` of the same
+   * `createLoader` the child route is re-running also reports true, even if
+   * the layout copy is not replaced. Not used for the initial streamed read
+   * (that suspends).
+   */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -125,6 +133,7 @@ export interface UseLoaderResult<T> {
 
 export interface UseFetchLoaderResult<T> {
   data: T | undefined;
+  /** Same family-keyed contract as {@link UseLoaderResult.isLoading}. */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -560,7 +569,7 @@ function useLoaderInternal<T>(
  * @example Basic usage - accessing route loader data
  * ```tsx
  * "use client";
- * import { useLoader } from "rsc-router/client";
+ * import { useLoader } from "@rangojs/router/client";
  * import { CartLoader } from "../loaders/cart";
  *
  * // In route definition: loader(CartLoader)
@@ -608,7 +617,7 @@ export function useLoader<T>(
  * @example On-demand fetching
  * ```tsx
  * "use client";
- * import { useFetchLoader } from "rsc-router/client";
+ * import { useFetchLoader } from "@rangojs/router/client";
  * import { SearchLoader } from "../loaders/search";
  *
  * export function SearchResults() {
@@ -670,7 +679,7 @@ export function useFetchLoader<T>(
  * @example
  * ```tsx
  * "use client";
- * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ * import { useLoader, useRefreshLoaders } from "@rangojs/router/client";
  *
  * function Profile() {
  *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });

package/src/vite/discovery/shell-prerender-phase.ts

@@ -64,6 +64,14 @@ export async function runShellPrerenderPhase(
   const startTotal = performance.now();
   console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
 
+  // Hold the process open for the phase. The capture's waits are unref'd
+  // timers (retry delay, Flight quiesce hops) so a runtime capture never keeps
+  // Node alive; every bundle is already written and the build temp server has
+  // no file watcher (#947). Its only remaining handle is the HMR WebSocket on
+  // 24678, which fails to bind silently when another Vite server holds the
+  // port; `vite build` then exited 0 mid-phase without writing
+  // __shell-manifest.js.
+  const keepAlive = setInterval(() => {}, 60_000);
   let restoreClientRequire: (() => void) | undefined;
   try {
     // Runner access needs the RunnableDevEnvironment surface; the environments
@@ -343,6 +351,7 @@ export async function runShellPrerenderPhase(
     // buildApp post hook's finally on success, buildEnd on an aborted build.
     delete (globalThis as any).__loadPrerenderManifestModule;
     restoreClientRequire?.();
+    clearInterval(keepAlive);
   }
 }