feat(build): add transport-neutral worker stages

knip.ts

@@ -92,7 +92,10 @@ export default {
         "src/server/app-page-element-builder.ts",
         "src/server/app-hook-warning-suppression.ts",
         "src/server/app-post-middleware-context.ts",
+        "src/server/app-request-stage-context.ts",
+        "src/server/app-request-stage-independent-entry.ts",
         "src/server/app-request-context.ts",
+        "src/server/app-route-handler-middleware-context.ts",
         "src/server/app-rsc-error-handler.ts",
         "src/server/isr-cache.ts",
         "src/server/rsc-stream-hints.ts",

packages/cloudflare/src/cache/cdn-adapter.runtime.ts

@@ -183,6 +183,10 @@ function formatCacheTag(tags: readonly string[]): string | null {
 
 export class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   readonly requiresCompletedResponseAdmission = true;
+  readonly responsePolicyHeaderNames = [
+    "CDN-Cache-Control",
+    "Cloudflare-CDN-Cache-Control",
+  ] as const;
   readonly responseVary = "verbatim" as const;
 
   constructor(

packages/cloudflare/src/cache/cdn-adapter.ts

@@ -50,6 +50,7 @@ export function cdnAdapter(options?: CdnAdapterOptions) {
     options,
     capabilities: {
       buildIdentity: "response-header" as const,
+      responsePolicyHeaderNames: ["CDN-Cache-Control", "Cloudflare-CDN-Cache-Control"] as const,
       responseVary: "verbatim" as const,
       routeCacheability: "probe-manifest" as const,
     },

packages/cloudflare/src/deploy.ts

@@ -35,6 +35,7 @@ import {
   findVinextPrerenderConfigInPlugins,
   findVinextRouteRootConfigInPlugins,
   formatVinextPrerenderLabel,
+  getConfiguredCdnResponsePolicyHeaderNames,
   hasBuildIdentityResponseHeader,
   hasVerbatimResponseVary,
   requiresRouteCacheabilityProbeManifest,
@@ -1921,6 +1922,9 @@ export async function deploy(options: DeployOptions): Promise<void> {
       nextConfig,
       buildIdentity: hasBuildIdentityHeader ? "response-header" : undefined,
       responseVary: hasStrictResponseVary ? "verbatim" : undefined,
+      responsePolicyHeaderNames: getConfiguredCdnResponsePolicyHeaderNames(
+        viteConfigMetadata.cacheConfig,
+      ),
       routeRootConfig: viteConfigMetadata.routeRootConfig,
     });
   }
@@ -1993,6 +1997,9 @@ export async function deploy(options: DeployOptions): Promise<void> {
           nextConfig,
           buildIdentity: hasBuildIdentityHeader ? "response-header" : undefined,
           responseVary: hasStrictResponseVary ? "verbatim" : undefined,
+          responsePolicyHeaderNames: getConfiguredCdnResponsePolicyHeaderNames(
+            viteConfigMetadata.cacheConfig,
+          ),
           routeRootConfig: viteConfigMetadata.routeRootConfig,
           pathDiscoveryTarget: {
             baseUrl: targetUrl,

packages/vinext/package.json

@@ -68,6 +68,18 @@
       "types": "./dist/server/fetch-handler.d.ts",
       "import": "./dist/server/fetch-handler.js"
     },
+    "./server/multi-stage": {
+      "types": "./dist/server/multi-stage.d.ts",
+      "import": "./dist/server/multi-stage.js"
+    },
+    "./server/request-stage": {
+      "types": "./dist/server/request-stage.d.ts",
+      "import": "./dist/server/request-stage.js"
+    },
+    "./server/response-stage": {
+      "types": "./dist/server/response-stage.d.ts",
+      "import": "./dist/server/response-stage.js"
+    },
     "./server/app-router-entry": {
       "types": "./dist/server/app-router-entry.d.ts",
       "import": "./dist/server/app-router-entry.js"

packages/vinext/src/build/client-build-config.ts

@@ -236,6 +236,23 @@ export function isRscFrameworkModule(id: string): boolean {
   return pkg !== null && (FRAMEWORK_PACKAGES as readonly string[]).includes(pkg);
 }
 
+/**
+ * Keep virtual entry ids out of emitted RSC chunk filenames.
+ *
+ * Rolldown's entries-aware chunk names can contain the `\\0` virtual-id marker,
+ * which is not a portable module-specifier or filesystem name. Preserve every
+ * other character and remove both the printable and actual-NUL forms.
+ */
+export function sanitizeRscChunkFileName(name: string): string {
+  const withoutVirtualMarkers = name.replaceAll("\\0", "");
+  const invalid = new Set(["<", ">", ":", '"', "/", "\\", "|", "?", "*"]);
+  let sanitized = "";
+  for (const character of withoutVirtualMarkers) {
+    sanitized += character.charCodeAt(0) <= 31 || invalid.has(character) ? "_" : character;
+  }
+  return sanitized;
+}
+
 /**
  * Output config that isolates React (and the RSC flight runtime) into a
  * dedicated "framework" chunk in the RSC server build. See
@@ -245,6 +262,7 @@ export function isRscFrameworkModule(id: string): boolean {
  */
 export function createRscFrameworkChunkOutputConfig() {
   return {
+    sanitizeFileName: sanitizeRscChunkFileName,
     codeSplitting: {
       groups: [
         {
@@ -287,3 +305,67 @@ export function withBuildBundlerOptions(
 ): Partial<VinextBuildConfig> {
   return { rolldownOptions: bundlerOptions };
 }
+
+type VinextBuildOutput = Exclude<
+  NonNullable<VinextBuildBundlerOptions["output"]>,
+  readonly unknown[]
+>;
+type VinextCodeSplittingConfig = Exclude<NonNullable<VinextBuildOutput["codeSplitting"]>, boolean>;
+type ChunkFileNames = NonNullable<VinextBuildOutput["chunkFileNames"]>;
+type ChunkFileNameFunction = Exclude<ChunkFileNames, string>;
+
+/**
+ * Keep vinext modules partitioned by the stage entries that actually use them.
+ * Without an entry-aware catch-all, Rolldown may merge a small helper shared by
+ * request/response entries into a response-heavy chunk; importing that helper
+ * then evaluates React and renderer code on a request-stage cache hit.
+ */
+export function createMultiStageCodeSplittingConfig(
+  existing: VinextBuildOutput["codeSplitting"],
+): VinextCodeSplittingConfig & { groups: NonNullable<VinextCodeSplittingConfig["groups"]> } {
+  const base = existing && typeof existing === "object" ? existing : {};
+  return {
+    ...base,
+    groups: [
+      {
+        name: "vinext-stage-runtime",
+        test: /(?:^|[/\\])(?:packages[/\\]vinext[/\\]src|(?:packages[/\\]vinext|node_modules[/\\](?:\.pnpm[/\\][^/\\]+[/\\]node_modules[/\\])?vinext)[/\\]dist)[/\\]/,
+        entriesAware: true,
+      },
+      ...(base.groups ?? []),
+    ],
+  };
+}
+
+/**
+ * Keep router stage chunks beside the server entry so their generated
+ * `./vinext-client-assets.js` external continues to resolve. Other chunks keep
+ * the host's existing output pattern (or vinext's server-assets default).
+ */
+export function createMultiStageChunkFileNames(
+  assetsDir: string,
+  existing: VinextBuildOutput["chunkFileNames"],
+): ChunkFileNameFunction {
+  return (chunk) => {
+    const name = sanitizeRscChunkFileName(chunk.name);
+    if (
+      chunk.moduleIds?.some((id) =>
+        /\/server\/app-ssr-entry\.[cm]?[jt]sx?$/.test(toSlash(id.split("?", 1)[0] ?? "")),
+      ) ||
+      [
+        "app-router-entry",
+        "pages-router-entry",
+        "app-response-stage-entry",
+        "pages-request-stage-entry",
+        "pages-response-stage-entry",
+        "virtual_vinext-rsc-entry",
+        "virtual_vinext-response-stage",
+      ].some((entryName) => name.includes(entryName))
+    ) {
+      return `${name}-[hash].js`;
+    }
+    if (typeof existing === "function") return existing({ ...chunk, name });
+    const pattern = existing ?? joinAssetFileNamePattern(assetsDir, "[name]-[hash].js");
+    return pattern.replaceAll("[name]", name);
+  };
+}

packages/vinext/src/build/inject-pregenerated-paths.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "pathslash";
 import { readPrerenderManifest } from "../server/prerender-manifest.js";
+import { PREGENERATED_CONCRETE_PATHS_MODULE } from "../server/pregenerated-concrete-paths.js";
 import { escapeRegExp } from "../utils/regex.js";
 
 declare global {
@@ -15,14 +16,33 @@ const VINEXT_PREGEN_RE = new RegExp(
 );
 
 export function injectPregeneratedConcretePaths(root: string): void {
-  const workerEntry = path.resolve(root, "dist", "server", "index.js");
-  if (!fs.existsSync(workerEntry)) return;
+  const serverDir = path.resolve(root, "dist", "server");
+  const workerEntry = path.join(serverDir, "index.js");
+  const manifest = readPrerenderManifest(path.join(serverDir, "vinext-prerender.json"));
+  const table = manifest?.pregeneratedConcretePaths ?? [];
 
-  let code = fs.readFileSync(workerEntry, "utf-8").replace(VINEXT_PREGEN_RE, "");
-  const manifest = readPrerenderManifest(
-    path.join(root, "dist", "server", "vinext-prerender.json"),
+  // Response-stage entries can be deployed independently of index.js. Keep the
+  // table in a stable side-effect module imported by every generated App
+  // response graph so those deployments retain the same PPR fallback guard.
+  // The file is emitted during the server build; writing it after prerendering
+  // updates the artifact without rebuilding or coupling core to a host
+  // transport.
+  const runtimeModule = path.join(serverDir, PREGENERATED_CONCRETE_PATHS_MODULE);
+  fs.mkdirSync(serverDir, { recursive: true });
+  fs.writeFileSync(
+    runtimeModule,
+    table.length > 0
+      ? `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n`
+      : "delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;\n",
   );
-  const table = manifest?.pregeneratedConcretePaths ?? [];
+
+  if (!fs.existsSync(workerEntry)) {
+    if (table.length > 0) globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = table;
+    else delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;
+    return;
+  }
+
+  let code = fs.readFileSync(workerEntry, "utf-8").replace(VINEXT_PREGEN_RE, "");
 
   if (table.length > 0) {
     globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = table;