feat: lazy per-route cache seeding for Workers

packages/vinext/package.json

@@ -52,6 +52,10 @@
     "./server/worker-utils": {
       "types": "./dist/server/worker-utils.d.ts",
       "import": "./dist/server/worker-utils.js"
+    },
+    "./server/seed-cache-workers": {
+      "types": "./dist/server/seed-cache-workers.d.ts",
+      "import": "./dist/server/seed-cache-workers.js"
     }
   },
   "scripts": {

packages/vinext/src/deploy.ts

@@ -453,6 +453,7 @@ import { setCacheHandler } from "vinext/shims/cache";
  */
 import { handleImageOptimization, DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES } from "vinext/server/image-optimization";
 import type { ImageConfig } from "vinext/server/image-optimization";
+import { seedRouteFromAssets } from "vinext/server/seed-cache-workers";
 import handler from "vinext/server/app-router-entry";
 ${isrImports}
 interface Env {
@@ -495,6 +496,11 @@ ${isrSetup}    const url = new URL(request.url);
       }, allowedWidths);
     }
 
+    // Seed the memory cache from pre-rendered assets (lazy, per-route).
+    // Blocking (not waitUntil) so the RSC handler sees the seeded cache.
+    // seedRouteFromAssets handles errors internally — never throws.
+    await seedRouteFromAssets(url.pathname, (p) => env.ASSETS.fetch(new Request(new URL(p, request.url))));
+
     // Delegate everything else to vinext, forwarding ctx so that
     // ctx.waitUntil() is available to background cache writes and
     // other deferred work via getRequestExecutionContext().
@@ -1199,6 +1205,44 @@ export function buildWranglerDeployArgs(
   return { args, env };
 }
 
+/**
+ * Copy pre-rendered files to dist/client/__prerender/ so they're deployed
+ * as static assets and accessible via env.ASSETS.fetch() at runtime.
+ * No-op if no prerender manifest exists.
+ */
+export function copyPrerenderToAssets(root: string, basePath = ""): void {
+  const serverDir = path.join(root, "dist", "server");
+  const manifestPath = path.join(serverDir, "vinext-prerender.json");
+  if (!fs.existsSync(manifestPath)) return;
+
+  const targetDir = path.join(root, "dist", "client", "__prerender");
+  fs.mkdirSync(targetDir, { recursive: true });
+  const targetManifestPath = path.join(targetDir, "vinext-prerender.json");
+
+  // Copy manifest, enriching with basePath for Workers-side cache lookup.
+  if (!basePath) {
+    fs.copyFileSync(manifestPath, targetManifestPath);
+  } else {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+      manifest.basePath = basePath;
+      fs.writeFileSync(targetManifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    } catch {
+      // Best-effort enrichment only. If parse fails, preserve the source bytes.
+      fs.copyFileSync(manifestPath, targetManifestPath);
+    }
+  }
+
+  // Copy prerendered HTML/RSC files
+  const sourceDir = path.join(serverDir, "prerendered-routes");
+  if (!fs.existsSync(sourceDir)) return;
+
+  fs.cpSync(sourceDir, targetDir, { recursive: true });
+}
+
 function runWranglerDeploy(root: string, options: Pick<DeployOptions, "preview" | "env">): string {
   // Walk up ancestor directories so the binary is found even when node_modules
   // is hoisted to the workspace root in a monorepo.
@@ -1327,22 +1371,20 @@ export async function deploy(options: DeployOptions): Promise<void> {
     console.log("\n  Skipping build (--skip-build)");
   }
 
+  const rawNextConfig = await loadNextConfig(info.root);
+  const nextConfig = await resolveNextConfig(rawNextConfig, info.root);
+
   // Step 6a: prerender — render every discovered route into dist.
   // Triggered by --prerender-all, or automatically when next.config.js
   // sets `output: 'export'` (every route must be statically exportable).
-  {
-    const rawNextConfig = await loadNextConfig(info.root);
-    const nextConfig = await resolveNextConfig(rawNextConfig, info.root);
-    const isStaticExport = nextConfig.output === "export";
-
-    if (options.prerenderAll || isStaticExport) {
-      const label =
-        isStaticExport && !options.prerenderAll
-          ? "Pre-rendering all routes (output: 'export')..."
-          : "Pre-rendering all routes...";
-      console.log(`\n  ${label}`);
-      await runPrerender({ root: info.root });
-    }
+  const isStaticExport = nextConfig.output === "export";
+  if (options.prerenderAll || isStaticExport) {
+    const label =
+      isStaticExport && !options.prerenderAll
+        ? "Pre-rendering all routes (output: 'export')..."
+        : "Pre-rendering all routes...";
+    console.log(`\n  ${label}`);
+    await runPrerender({ root: info.root });
   }
 
   // Step 6b: TPR — pre-render hot pages into KV cache (experimental, opt-in)
@@ -1360,6 +1402,12 @@ export async function deploy(options: DeployOptions): Promise<void> {
     }
   }
 
+  // Step 6c: Copy prerender data to dist/client/__prerender/ so the Worker
+  // can access it via env.ASSETS.fetch() for lazy per-route cache seeding.
+  // With not_found_handling: "none", these files are never auto-served —
+  // only accessible programmatically through the assets binding.
+  copyPrerenderToAssets(root, nextConfig.basePath);
+
   // Step 7: Deploy via wrangler
   const url = runWranglerDeploy(root, {
     preview: options.preview ?? false,

packages/vinext/src/server/seed-cache-shared.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared types and helpers for seed-cache modules (Node.js and Workers).
+ *
+ * Both `seed-cache.ts` (eager, fs-based) and `seed-cache-workers.ts`
+ * (lazy, fetch-based) read the same vinext-prerender.json manifest and
+ * produce identical cache entries. This module holds the shared contract.
+ */
+
+import type { CachedAppPageValue } from "../shims/cache.js";
+
+// ─── Manifest types ──────────────────────────────────────────────────────────
+
+export type PrerenderManifest = {
+  buildId: string;
+  basePath?: string;
+  trailingSlash?: boolean;
+  routes: PrerenderManifestRoute[];
+};
+
+export type PrerenderManifestRoute = {
+  route: string;
+  status: string;
+  revalidate?: number | false;
+  path?: string;
+  router?: "app" | "pages";
+};
+
+// ─── Cache value construction ────────────────────────────────────────────────
+
+/**
+ * Build the CacheHandler context object from a revalidate value.
+ * `revalidate: undefined` (static routes) → empty context → no expiry.
+ */
+export function revalidateCtx(seconds: number | undefined): Record<string, unknown> {
+  return seconds !== undefined ? { revalidate: seconds } : {};
+}
+
+/** Build an APP_PAGE cache value for an HTML entry. */
+export function makeHtmlCacheValue(html: string): CachedAppPageValue {
+  return {
+    kind: "APP_PAGE",
+    html,
+    rscData: undefined,
+    headers: undefined,
+    postponed: undefined,
+    status: undefined,
+  };
+}
+
+/** Build an APP_PAGE cache value for an RSC entry. */
+export function makeRscCacheValue(rscData: ArrayBuffer): CachedAppPageValue {
+  return {
+    kind: "APP_PAGE",
+    html: "",
+    rscData,
+    headers: undefined,
+    postponed: undefined,
+    status: undefined,
+  };
+}