@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

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,
@@ -138,7 +144,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 +198,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 +321,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.
  */
@@ -541,6 +594,10 @@ export function createRouterDiscoveryPlugin(
         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;
@@ -1057,6 +1114,204 @@ 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;
+        }
+        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;
+        if (rscEnvMain?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnvMain.runner.import(s.resolvedEntryPath);
+          } catch (err: any) {
+            res.statusCode = 500;
+            res.end(`Shell capture module refresh failed: ${err.message}`);
+            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 tempRscEnv = await getOrCreateTempServer();
+          if (tempRscEnv) {
+            try {
+              await importEntryAndRegistry(tempRscEnv);
+            } catch (err: any) {
+              res.statusCode = 500;
+              res.end(`Shell capture module refresh failed: ${err.message}`);
+              return;
+            }
+          }
+          rscRealm = tempRscEnv;
+          ssrRealm = (prerenderTempServer?.environments as any)?.ssr;
+          ssrEntryId = "virtual:entry-ssr";
+        }
+        if (!rscRealm?.runner || !ssrRealm?.runner) {
+          res.statusCode = 503;
+          res.end("Shell capture runners not available");
+          return;
+        }
+        let registry: Map<string, any> | null = null;
+        try {
+          const serverMod = await rscRealm.runner.import(
+            "@rangojs/router/server",
+          );
+          registry = serverMod.RouterRegistry ?? null;
+        } catch {
+          registry = null;
+        }
+        if (!registry || registry.size === 0) {
+          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) {
+            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 +1685,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 +1756,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 +1780,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/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>,