@uniflowed/vite 0.0.0-alpha.34 → 0.0.0-alpha.37

package/driver.js

@@ -42,26 +42,42 @@
 import { randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { builtinModules, register } from "node:module";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { installFlowHooks } from "@uniflowed/host/internal/sync-hooks.js";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { COMPILE_ASSETS_ID, compileAssetsPlugin } from "./internal/compile-assets.js";
+import {
+  survivingImports,
+  unavailableOnWorkers,
+  workerBuiltinWarnings,
+} from "./internal/worker-builtins.js";
 import { emit, errorEvent, eventLogger } from "./internal/events.js";
 import { loadUfConfig, projectConfig } from "./internal/config.js";
-import { send, toRequest } from "./internal/http.js";
+import { send, toAddressRequest, toRequest } from "./internal/http.js";
 import { createOpenApiDocument } from "./internal/openapi.js";
 import { withProjectConfig } from "./merge.js";
-import { VIRTUAL, resolveRouteTarget, scanRoutes } from "./internal/routes.js";
+import { FLIGHT_VIRTUAL, RSC_ENVIRONMENT } from "./internal/flight.js";
+import { MODULE_GRAPH_FILE, createModuleGraphCollector } from "./internal/module-graph.js";
+import { VIRTUAL, resolveRouteTarget, routingRulesOf, scanRoutes } from "./internal/routes.js";
 import {
   BUILD_ID_FILE,
+  DOCUMENT_ASSETS_FILE,
+  REGENERATED_DIRECTORY,
+  REGENERATION_FILE,
+  answerRouting,
+  answersInFrontOfFiles,
   assetsFromManifest,
   buildIdentity,
   createPrerenderGate,
   createServeHandler,
+  documentAssetsFor,
+  forViteBase,
   loadBuild,
   nodeListener,
   providerSpecifier,
+  readRegeneration,
   withRequest,
 } from "./internal/serve.js";
 
@@ -94,11 +110,23 @@ process.env.UF_PROJECT_ROOT = root;
 // hooks for that; Bun is started with `--preload` on the same package's
 // preload instead, and has no `register`.
 //
+// Deno has no `register` either, and it gets its hooks *here* rather than from
+// a preload, for a reason that is about order. While a Deno `load` hook is
+// registered, `require()` of a native addon fails — and Vite requires one,
+// Rolldown's binding. The static imports above have already loaded Vite by
+// this line, binding included, so hooks installed now see only what is
+// imported after them: the config, and the `@uniflowed/*` modules this driver
+// reaches dynamically. They are the in-thread hooks a new enough Node takes
+// through `@uniflowed/host/register` too; see
+// `@uniflowed/host/internal/sync-hooks.js`.
+//
 // The hooks live in `@uniflowed/host` rather than here: they are how Flow runs
 // on a Capability JS Host, and nothing in them is Vite's. `uf test` reaches for
 // the same package, which is what stopped a test run from depending on a
 // bundler it never loads.
-if (typeof Bun === "undefined" && typeof Deno === "undefined") {
+if (typeof Deno !== "undefined") {
+  installFlowHooks(root);
+} else if (typeof Bun === "undefined") {
   register("@uniflowed/host/internal/node-hooks.js", import.meta.url, { data: { root } });
 }
 
@@ -152,6 +180,15 @@ async function loadConfig() {
   return config;
 }
 
+/**
+ * `app.router.basePath` as the driver uses it: `""` at the root, `"/docs"`
+ * otherwise. Read where the build writes asset URLs and file names, because a
+ * prerendered document is written outside Vite's HTML transform.
+ */
+function basePathOf(config) {
+  return routingRulesOf(config.app?.router).basePath;
+}
+
 /** The Vite inline config a uf config describes. */
 async function viteConfig(config, mode) {
   const { default: uniflowed } = await import("./index.js");
@@ -191,6 +228,9 @@ async function viteConfig(config, mode) {
     configFile: false,
     envDir: false,
     mode,
+    // `app.router.basePath`: where Vite serves the modules in development, and
+    // what it puts in front of every asset URL a build writes.
+    base: basePathOf(config) === "" ? "/" : `${basePathOf(config)}/`,
     clearScreen: false,
     customLogger: eventLogger(argument("--log-level") ?? "info"),
     plugins: [uniflowed({ root, config, target: routeTarget })],
@@ -437,6 +477,37 @@ async function preview() {
   const draftFirst = {
     name: "uf:draft-before-files",
     configurePreviewServer(previewServer) {
+      // `app.router.headers` and `redirects`, first of all: a redirect answers
+      // before a file is looked for, and a header is pinned on the response so
+      // it survives the `writeHead` Vite's file middleware writes its own
+      // with. `uf start` and every adapter put the same two in front of their
+      // static half; the application's own answers get them from
+      // `createServeHandler` behind. See `internal/serve.js`'s `answerRouting`.
+      const routing = build?.entry?.routing;
+      if (answersInFrontOfFiles(routing)) {
+        previewServer.middlewares.use((request, response, next) => {
+          answerRouting(routing, toAddressRequest(request), response)
+            .then((answered) => {
+              if (answered) return;
+              // The bare base path is the root, which Vite only knows as
+              // `/docs/`; see `forViteBase`.
+              forViteBase(routing, request);
+              next();
+            })
+            .catch(next);
+        });
+      }
+      // A prerendered payload is a file whose extension Vite's static middleware
+      // knows no type for, and the router hands bytes to React only when they
+      // are answered as a payload — so a navigation on a preview would silently
+      // become a document load. Set here, in front of the file server, which
+      // keeps a type it did not choose.
+      previewServer.middlewares.use((request, response, next) => {
+        if ((request.url ?? "").split("?")[0].endsWith("/__uf.flight")) {
+          response.setHeader("content-type", "text/x-component");
+        }
+        next();
+      });
       if (handle == null) return;
       const run = answer(previewServer);
       previewServer.middlewares.use((request, response, next) => {
@@ -589,17 +660,60 @@ async function build() {
   const staticBuild = flag("--static-build");
   const because = argument("--because") ?? "this build prerenders every route";
 
+  // 0. The rsc graph, for an application React Server Components render: the
+  //    route table and every server component, resolved under `react-server`.
+  //    First, because it is what finds the client modules the next pass has
+  //    to build; `./internal/flight.js` has the order and the reason for it.
+  const flight = flightStateOf(inline);
+  // `uf build --analyze`: the graph every bundle below is built from, for uf
+  // to attribute to routes; see `./internal/module-graph.js`. A client module
+  // is an entry the browser loads because a server component names it, not on
+  // every page, so it is not one of the client bundle's shared entries.
+  const graph = flag("--analyze")
+    ? createModuleGraphCollector(root, {
+        isReference: (file) => flight?.clientModules.has(file) ?? false,
+      })
+    : null;
+  if (graph != null) {
+    inline.plugins = [...(inline.plugins ?? []), graph.plugin];
+  }
+  const rscDir = path.join(root, ".uf", "build", "rsc");
+  if (flight != null) {
+    emit("phase", { name: "rsc" });
+    await buildRscGraph(vite, inline, flight, { outDir: rscDir, conditions: null });
+  }
+
   // 1. The client: everything the browser loads, with a manifest so the
-  //    server render knows which script and stylesheet tags to write.
+  //    server render knows which script and stylesheet tags to write. Under
+  //    React Server Components that is the entry and one entry per client
+  //    module, each keeping its export names, because a payload asks for a
+  //    chunk by its URL and for a component by its export.
   emit("phase", { name: "client" });
+  const references = flight == null ? [] : [...flight.clientModules].sort();
+  const input = { client: VIRTUAL.client };
+  references.forEach((file, index) => {
+    input[`client-reference-${index}`] = file;
+  });
   await vite.build({
     ...inline,
     build: {
       ...inline.build,
-      rollupOptions: { input: { client: VIRTUAL.client } },
+      rollupOptions:
+        flight == null ? { input } : { input, preserveEntrySignatures: "exports-only" },
     },
   });
   const manifest = readManifest(outDir);
+  if (flight != null) {
+    recordClientChunks(flight, manifest, references, rscDir, basePathOf(config));
+    // What the summary's "pages in the client bundle" reads. None: a browser
+    // that hydrates a payload imports no page, whichever route it is on.
+    emit("rsc-split", {
+      pages: 0,
+      routes: scanRoutes(path.resolve(root, config.app?.router?.root ?? "app"), {
+        target: resolveRouteTarget(config, argument("--target")),
+      }).routes.length,
+    });
+  }
 
   // 2. The server entry, bundled for the host, outside `dist/` so it is never
   //    deployed by accident.
@@ -627,6 +741,9 @@ async function build() {
   // `internal/serve.js`'s `buildIdentity`, which is what reads this.
   writeFileSync(path.join(serverDir, BUILD_ID_FILE), `${mintBuildId()}\n`);
 
+  // Every bundle is built by here, and the prerender below builds none.
+  graph?.write(path.join(root, ".uf", "build", "meta", MODULE_GRAPH_FILE));
+
   // 3. Which routes this build renders when, and every route it renders now.
   //
   //    The decision comes from `uf.config.js` and is made in Rust — see
@@ -635,7 +752,14 @@ async function build() {
   //    arrives here as one word, and this is where it meets the route table.
   emit("phase", { name: "prerender" });
   const server = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
-  const assets = assetsFromManifest(manifest);
+  const assets =
+    flight == null
+      ? assetsFromManifest(manifest, basePathOf(config))
+      : flightAssets(manifest, references, rscDir, outDir, basePathOf(config));
+  // Recorded beside the server bundle, because whatever serves this build
+  // later cannot recompute them from the client manifest alone; see
+  // `documentAssetsFor`.
+  writeFileSync(path.join(serverDir, DOCUMENT_ASSETS_FILE), `${JSON.stringify(assets, null, 2)}\n`);
   const openapi = await createOpenApiDocument(server.handlers);
   const openapiFile = path.join(root, ".uf", "build", "meta", "openapi.json");
   mkdirSync(path.dirname(openapiFile), { recursive: true });
@@ -686,28 +810,86 @@ async function build() {
     failures.push(url);
     emit("page-failed", { url, ...errorEvent(error) });
   };
+  //
+  // Each prerender runs inside a fill that stores nothing, so what a page states
+  // with `cacheLife`, `cacheTag` and `noStore` is something this loop can read
+  // rather than a call that throws for want of a scope.
+  //
+  // A page is written for regeneration when `uf` passed `--regenerate` — `isr`
+  // allowed in `app.rendering.modes`, `rendering.cache.route` on, and a server
+  // deployed to regenerate it — and the page stated a lifetime, called no
+  // `noStore`, and answered 200. Its document goes under
+  // `REGENERATED_DIRECTORY` rather than at its own URL, so no static half
+  // answers the page: the server does, starting from this document, until the
+  // lifetime has passed. What it stated goes into `REGENERATION_FILE` beside the
+  // server bundle. Every other page is the document it has always been.
+  //
+  // A tag without a lifetime is not enough, for the route cache's own reason:
+  // an entry with no end is one another process could serve from its memory
+  // for ever after `revalidateTag` took it out of the shared store.
+  const { collectCacheDeclarations } = await import("@uniflowed/server/cache");
+  const regenerate = flag("--regenerate");
+  const regenerated = {};
   for (const url of pages) {
-    let result;
+    let declared;
+    const renderedAt = Date.now();
     try {
-      result = await server.prerender(url, assets);
+      declared = await collectCacheDeclarations(() => server.prerender(url, assets));
     } catch (error) {
       failed(url, error);
       continue;
     }
+    const result = declared.value;
     if (result.error != null) {
       failed(url, result.error);
       continue;
     }
-    const file = htmlPathFor(outDir, url);
+    const lifetime = declared.lifetime;
+    const regenerates =
+      regenerate && result.status === 200 && declared.denied == null && lifetime != null;
+    // The trailing-slash policy decides a served page's file name; a page the
+    // build regenerates keeps the one layout the regeneration reads.
+    const file = regenerates
+      ? htmlPathFor(path.join(outDir, REGENERATED_DIRECTORY), url)
+      : htmlPathFor(outDir, url, routingRulesOf(config.app?.router).trailingSlash);
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, result.html);
+    // The payload the document was rendered from, beside it: what a browser
+    // navigating to this route fetches, from whatever serves the files. Beside
+    // the document wherever the document went, so a page written for
+    // regeneration leaves no file at its route's own payload URL answering with
+    // the build's copy for ever; the server answers that URL instead.
+    if (result.payload != null) {
+      // Beside the route's directory whatever the document is called:
+      // `guide/index.html` and `guide.html` both put it at `guide/__uf.flight`.
+      const payloadDirectory =
+        path.basename(file) === "index.html" ? path.dirname(file) : file.slice(0, -".html".length);
+      mkdirSync(payloadDirectory, { recursive: true });
+      writeFileSync(path.join(payloadDirectory, "__uf.flight"), result.payload);
+    }
+    if (regenerates) {
+      regenerated[url] = {
+        document: regeneratedDocumentUrl(url),
+        renderedAt,
+        revalidate: lifetime.revalidate,
+        expire: lifetime.expire ?? null,
+        tags: declared.tags,
+      };
+    }
     emit("page", {
       url,
       file: path.relative(root, file),
       status: result.status,
       bytes: Buffer.byteLength(result.html),
+      regenerates,
     });
   }
+  if (Object.keys(regenerated).length > 0) {
+    writeFileSync(
+      path.join(serverDir, REGENERATION_FILE),
+      `${JSON.stringify({ pages: regenerated }, null, 2)}\n`,
+    );
+  }
   // One `404.html`, from the boundary at the router root: a static host serves
   // a single error document for the whole site, so the nested boundaries a
   // project declares are the server's and the client's to render, not
@@ -1039,9 +1221,16 @@ async function compile() {
   mkdirSync(bundleDir, { recursive: true });
   writeFileSync(
     entry,
-    entrySource(path.relative(root, assets), assetsFromManifest(readManifest(outDir))),
+    entrySource(
+      path.relative(root, assets),
+      await documentAssetsFor(path.join(root, ".uf", "build", "server"), readManifest(outDir)),
+    ),
   );
 
+  // The rsc graph `uf build` built, and the client chunks its references name.
+  const flight = flightStateOf(inline);
+  if (flight != null) loadFlightBuild(flight, path.join(root, ".uf", "build", "rsc"));
+
   await vite.build({
     ...inline,
     customLogger: eventLogger("warn"),
@@ -1081,13 +1270,21 @@ async function compile() {
  * `static` is deliberately absent; `uf_config`'s
  * `DeployAdapter::is_implemented` is the other half of that fact and
  * `docs/app/reference/cli/$page.mdx` says why.
+ *
+ * `regenerationStore` is where a target keeps the pages a build regenerates
+ * when `rendering.cache.store` names nothing: a disk for a process with one,
+ * Workers KV for a Worker, and `null` for a Lambda, which keeps nothing between
+ * invocations and is refused by name instead. A regenerated page kept only in
+ * memory would go back to the build's copy on every restart, which is a page
+ * that travels back in time. See [`deploy`].
  */
 const ADAPTERS = {
   node: {
-    entries: (document, cache, build, schedules) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build),
+    entries: (document, cache, build, schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build, regeneration),
       server: nodeEntrySource("./handler.js", schedules),
     }),
+    regenerationStore: "filesystem",
   },
   // The same two files as `node`, with `@uniflowed/server/bun` in place of
   // `@uniflowed/server/node`. That module is `./internal/static.js` for every
@@ -1104,32 +1301,40 @@ const ADAPTERS = {
   // nobody here. `edge` pays that price because it must: there is no
   // `node:stream` in a Worker.
   bun: {
-    entries: (document, cache, build, schedules) => ({
-      handler: handlerEntrySource(document, cache, BUN_CAPABILITIES, build),
+    entries: (document, cache, build, schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, BUN_CAPABILITIES, build, regeneration),
       server: bunEntrySource("./handler.js", schedules),
     }),
+    regenerationStore: "filesystem",
   },
   deno: {
-    entries: (document, cache, build, schedules) => ({
-      handler: handlerEntrySource(document, cache, DENO_CAPABILITIES, build),
+    entries: (document, cache, build, schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, DENO_CAPABILITIES, build, regeneration),
       server: denoEntrySource("./handler.js", schedules),
     }),
+    regenerationStore: "filesystem",
   },
   // The same two files. What `--adapter container` adds is a `Dockerfile` and
   // a `.dockerignore`, and both are plain text that `uf` writes beside this
   // output rather than anything the bundler produces — see `uf_cli`'s
   // `commands::deploy`.
   container: {
-    entries: (document, cache, build, schedules) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build),
+    entries: (document, cache, build, schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build, regeneration),
       server: nodeEntrySource("./handler.js", schedules),
     }),
+    regenerationStore: "filesystem",
   },
   edge: {
-    entries: (document, cache, build, schedules) => ({
-      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES, build),
+    entries: (document, cache, build, schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES, build, regeneration),
       worker: workerEntrySource("./handler.js", schedules),
     }),
+    // Workers KV, through the same module seam a project's own provider goes
+    // through. `packages/server/cache-kv.js` argues KV over the Cache API: the
+    // seam has to find every entry under a tag, and the Cache API cannot list
+    // what it holds.
+    regenerationStore: "@uniflowed/server/cache/kv",
     // `workerd` first, so React resolves to the build that has
     // `renderToReadableStream` and no `node:stream`. `browser` and `module`
     // after it are Vite's own SSR defaults, kept so a dependency with no
@@ -1141,12 +1346,19 @@ const ADAPTERS = {
     // target which cannot provide a durable store says so, and this is the one
     // target that cannot.
     filesystem: false,
+    // And the Node built-ins it has only as stubs, which the link reports by
+    // module and importer. See `./internal/worker-builtins.js`.
+    workerBuiltins: true,
   },
   serverless: {
-    entries: (document, cache, build) => ({
-      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES, build),
+    entries: (document, cache, build, _schedules, regeneration) => ({
+      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES, build, regeneration),
       lambda: lambdaEntrySource("./handler.js"),
     }),
+    // A Lambda's memory lasts one instance and its disk is that instance's
+    // `/tmp`, so neither is somewhere a regenerated page survives. A build that
+    // regenerates pages has to name a provider module; see [`deploy`].
+    regenerationStore: null,
   },
 };
 
@@ -1267,15 +1479,18 @@ async function deploy() {
   // file is the version a person can open when a deployed directory
   // misbehaves.
   mkdirSync(work, { recursive: true });
-  const document = assetsFromManifest(readManifest(outDir));
+  const document = await documentAssetsFor(
+    path.join(root, ".uf", "build", "server"),
+    readManifest(outDir),
+  );
   // Whatever `build` above minted, so a durable cache in the deployed artefact
   // is keyed by the build that produced it and not by the moment it was
   // packaged. Read rather than minted again for exactly that reason: a second
   // `randomUUID()` here would key the adapter's copy differently from the one
   // `uf start` serves out of `.uf/build/`, which is two caches for one build.
   const buildId = await buildIdentity(root, path.join(".uf", "build", "server"));
-  const cacheConfig = config.app?.rendering?.cache;
-  if (shape.filesystem === false && cacheConfig?.store === "filesystem") {
+  const declaredCache = config.app?.rendering?.cache;
+  if (shape.filesystem === false && declaredCache?.store === "filesystem") {
     throw new Error(
       `uf: rendering.cache.store is "filesystem" and \`--adapter ${adapter}\` has no ` +
         "filesystem. Name a module exporting `createCacheProvider` instead — a KV " +
@@ -1283,13 +1498,49 @@ async function deploy() {
         "docs/app/guide/cache.",
     );
   }
-  const entries = shape.entries(document, cacheConfig, buildId, schedules);
+  // The pages this build regenerates, and where this target keeps what it
+  // regenerates when the project named no store: the adapter's
+  // `regenerationStore`. A target with nowhere refuses by name and lists the
+  // pages, rather than deploying pages that every cold start takes back to the
+  // build's copy.
+  const regeneration = await readRegeneration(path.join(root, ".uf", "build", "server"));
+  let cacheConfig = declaredCache;
+  if (regeneration != null && declaredCache?.store == null) {
+    if (shape.regenerationStore == null) {
+      const pages = Object.keys(regeneration.pages);
+      throw new Error(
+        `uf: this build regenerates ${pages.length} ${plural(pages.length, "page")} ` +
+          `(${pages.join(", ")}), and \`--adapter ${adapter}\` has nowhere of its own to keep ` +
+          "a regenerated page: an instance's memory and its /tmp both go with the instance. " +
+          "Name a module exporting `createCacheProvider` in rendering.cache.store, or leave " +
+          "`isr` out of app.rendering.modes to prerender those pages as documents that do not " +
+          "change. See docs/app/guide/rendering.",
+      );
+    }
+    cacheConfig = { ...declaredCache, store: shape.regenerationStore };
+  }
+  const entries = shape.entries(document, cacheConfig, buildId, schedules, regeneration);
   const input = {};
   for (const name of Object.keys(entries)) {
     writeFileSync(path.join(work, `${name}.js`), entries[name]);
     input[name] = path.join(work, `${name}.js`);
   }
 
+  // An application React Server Components render bundles the rsc graph into
+  // its server, and a target with export conditions of its own needs that graph
+  // resolved under them as well: React's Flight server has a Node build and a
+  // worker build, exactly as its HTML renderer does.
+  const flight = flightStateOf(inline);
+  if (flight != null) {
+    loadFlightBuild(flight, path.join(root, ".uf", "build", "rsc"));
+    if (shape.conditions != null) {
+      await buildRscGraph(vite, inline, flight, {
+        outDir: path.join(work, "rsc"),
+        conditions: shape.conditions,
+      });
+    }
+  }
+
   const ssr = { ...(inline.ssr ?? {}), noExternal: true };
   if (shape.conditions != null) {
     // Which build of a dependency this target gets, and it is the difference
@@ -1304,7 +1555,24 @@ async function deploy() {
   await vite.build({
     ...inline,
     customLogger: eventLogger("warn"),
-    plugins: [...inline.plugins, nativeAddonGuard()],
+    plugins: [
+      ...inline.plugins,
+      nativeAddonGuard(),
+      ...(shape.workerBuiltins === true ? [workerBuiltinGuard()] : []),
+    ],
+    // Fixed, because this bundle inlines every dependency and so both of each
+    // React package's builds, and a runtime lookup of `NODE_ENV` in a worker
+    // finds nothing and picks the development one. React's Flight client's
+    // development build constructs a `WeakRef` for every response, which
+    // workerd does not have: every document the edge artefact rendered was a
+    // `ReferenceError`. The production build has none, and is the one a
+    // deployment means.
+    define: {
+      ...(inline.define ?? {}),
+      "process.env.NODE_ENV": JSON.stringify(
+        inline.mode === "development" ? "development" : "production",
+      ),
+    },
     ssr,
     build: {
       ...inline.build,
@@ -1388,7 +1656,7 @@ async function deploy() {
  * `buildIdentity` is where it came from and
  * `packages/server/internal/cache-key.js` is why it exists.
  */
-function handlerEntrySource(document, cache, capabilities, build) {
+function handlerEntrySource(document, cache, capabilities, build, regeneration) {
   const route = cache?.route === true;
   const fetchCache = cache?.fetch === true;
   // Nothing at all when both switches are off, so a default project's
@@ -1402,6 +1670,10 @@ function handlerEntrySource(document, cache, capabilities, build) {
     `document: ${JSON.stringify(document)}`,
     ...(store ? ["cache"] : []),
     "capabilities",
+    // The pages this build regenerates, baked in beside the document and for
+    // the same reason: the manifest exists on the machine doing the build, and
+    // the deployed directory has only what this file carries.
+    ...(store && regeneration != null ? [`regeneration: ${JSON.stringify(regeneration)}`] : []),
   ].join(", ");
   const cacheImport = store ? 'import { createCacheStore } from "@uniflowed/server/cache";\n' : "";
   const providerImport = durable == null ? "" : `${durable.import}\n`;
@@ -1440,8 +1712,11 @@ const capabilities = ${capabilities.name}();
 
 export const fetch = createFetchHandler({ ${options} });
 export const beginRequest = app.beginRequest;
+// \`app.router\`'s redirects and headers, for the entry beside this file to put
+// in front of its static half. Rewrites are \`fetch\`'s own.
+export const routing = app.routing;
 
-export default { fetch, beginRequest };
+export default { fetch, beginRequest, routing };
 `;
 }
 
@@ -1549,7 +1824,7 @@ ${cron.imports}
 // \`@uniflowed/server/node\` above, because the request has to be established in
 // the storage the *application* reads, which is the copy bundled into
 // \`handler.js\`. See ubugeeei-prod/uf#389.
-import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
+import { beginRequest, fetch, routing } from ${JSON.stringify(handlerSpecifier)};
 
 // Resolved from this file and not from the working directory: a process
 // manager, a container entrypoint and a person in a shell each start a server
@@ -1562,7 +1837,7 @@ ${cron.declarations}
 // (ubugeeei-prod/uf#204) and this entry is a module, so it would work; \`.catch\`
 // is the better spelling regardless — a server that cannot take its port should
 // say so and exit non-zero, rather than die as an unhandled rejection.
-serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
+serve({ handle: fetch, staticDir, beginRequest, routing${cron.option} }).catch((error) => {
   process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
   process.exit(1);
 });
@@ -1589,7 +1864,7 @@ ${cron.imports}
 // \`@uniflowed/server/bun\` above, because the request has to be established in
 // the storage the *application* reads, which is the copy bundled into
 // \`handler.js\`. See ubugeeei-prod/uf#389.
-import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
+import { beginRequest, fetch, routing } from ${JSON.stringify(handlerSpecifier)};
 
 // Resolved from this file and not from the working directory: a process
 // manager, a container entrypoint and a person in a shell each start a server
@@ -1598,7 +1873,7 @@ import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
 // trap in it.
 const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
 ${cron.declarations}
-serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
+serve({ handle: fetch, staticDir, beginRequest, routing${cron.option} }).catch((error) => {
   process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
   process.exit(1);
 });
@@ -1636,7 +1911,7 @@ globalThis.Buffer ??= {
 };
 globalThis.setImmediate ??= (callback, ...args) => setTimeout(callback, 0, ...args);
 globalThis.clearImmediate ??= (handle) => clearTimeout(handle);
-const { beginRequest, fetch } = await import(${JSON.stringify(handlerSpecifier)});
+const { beginRequest, fetch, routing } = await import(${JSON.stringify(handlerSpecifier)});
 
 // Resolved from this file and not from the working directory: a process
 // manager and a person in a shell each start a server from wherever they
@@ -1644,7 +1919,7 @@ const { beginRequest, fetch } = await import(${JSON.stringify(handlerSpecifier)}
 // started from inside itself would be a deployment with a trap in it.
 const staticDir = decodeURIComponent(new URL("./static", import.meta.url).pathname);
 ${cron.declarations}
-serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
+serve({ handle: fetch, staticDir, beginRequest, routing${cron.option} }).catch((error) => {
   console.error(\`uf: \${error?.message ?? String(error)}\`);
   Deno.exit(1);
 });
@@ -1671,11 +1946,15 @@ function workerEntrySource(handlerSpecifier, schedules) {
   // would not be there.
   if (declared.length === 0) {
     return `// Generated by \`uf build --adapter edge\`. Not checked in, not edited.
-import { createWorkerFetch } from "@uniflowed/server/edge";
+import { createWorkerFetch, installWorkerLogger } from "@uniflowed/server/edge";
+
+import { beginRequest, fetch as handle, routing } from ${JSON.stringify(handlerSpecifier)};
 
-import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+// After the imports, so a logger the application installed while it loaded is
+// the one that stays; see \`installWorkerLogger\`.
+installWorkerLogger();
 
-export default { fetch: createWorkerFetch({ handle, beginRequest }) };
+export default { fetch: createWorkerFetch({ handle, beginRequest, routing }) };
 `;
   }
 
@@ -1684,16 +1963,20 @@ export default { fetch: createWorkerFetch({ handle, beginRequest }) };
   // `uf` writes both from one list, so the two cannot disagree.
   const routes = Object.fromEntries(declared.map((schedule) => [schedule.cron, schedule.path]));
   return `// Generated by \`uf build --adapter edge\`. Not checked in, not edited.
-import { createWorkerFetch, createWorkerScheduled } from "@uniflowed/server/edge";
+import { createWorkerFetch, createWorkerScheduled, installWorkerLogger } from "@uniflowed/server/edge";
 
-import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+import { beginRequest, fetch as handle, routing } from ${JSON.stringify(handlerSpecifier)};
+
+// After the imports, so a logger the application installed while it loaded is
+// the one that stays; see \`installWorkerLogger\`.
+installWorkerLogger();
 
 // \`triggers.crons\` in the wrangler.json beside this file names these same
 // expressions. See ubugeeei-prod/uf#531.
 const routes = ${JSON.stringify(routes, null, 2)};
 
 export default {
-  fetch: createWorkerFetch({ handle, beginRequest }),
+  fetch: createWorkerFetch({ handle, beginRequest, routing }),
   scheduled: createWorkerScheduled({ handle, beginRequest, routes }),
 };
 `;
@@ -1719,7 +2002,7 @@ import { fileURLToPath } from "node:url";
 
 import { createLambdaHandler } from "@uniflowed/server/lambda";
 
-import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+import { beginRequest, fetch as handle, routing } from ${JSON.stringify(handlerSpecifier)};
 
 // Resolved from this file and not from the working directory: Lambda sets the
 // working directory to the task root today and is under no obligation to keep
@@ -1727,7 +2010,7 @@ import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)
 // deployment with a trap in it.
 const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
 
-export const handler = createLambdaHandler({ handle, beginRequest, staticDir });
+export const handler = createLambdaHandler({ handle, beginRequest, staticDir, routing });
 `;
 }
 
@@ -1803,6 +2086,38 @@ function nativeAddonGuard() {
   };
 }
 
+/**
+ * Say which Node built-ins the Worker being linked reaches and does not have.
+ *
+ * `--adapter edge` only. Every import the bundler resolves passes through here,
+ * and one naming a module `./internal/worker-builtins.js` measured as a stub at
+ * the compatibility date uf writes is kept with the file that imported it. Only
+ * the ones still in the output are reported — see `survivingImports` for the
+ * fixture that showed why — and as warnings rather than a refusal, for the
+ * reason that module gives: a deployment at a newer date may have the module,
+ * and uf cannot see that deployment. What it can do is say, before anything is
+ * uploaded, which request is going to answer 500 and why.
+ */
+function workerBuiltinGuard() {
+  const reached = [];
+  return {
+    name: "uf:worker-builtins",
+    enforce: "pre",
+    resolveId(source, importer) {
+      if (importer != null && unavailableOnWorkers(source) != null) {
+        reached.push({ specifier: source, importer });
+      }
+      return null;
+    },
+    generateBundle(_options, bundle) {
+      const chunks = Object.values(bundle).filter((output) => output.type === "chunk");
+      for (const warning of workerBuiltinWarnings(survivingImports(reached, chunks), root)) {
+        this.warn(warning);
+      }
+    },
+  };
+}
+
 /** `word`, pluralised for `count`. */
 function plural(count, word) {
   return count === 1 ? word : `${word}s`;
@@ -1814,6 +2129,138 @@ async function printConfig() {
   process.exit(0);
 }
 
+/**
+ * The React Server Components state `@uniflowed/vite` shares with this driver,
+ * or `null` for an application rendered from its modules.
+ *
+ * Read off the plugin rather than decided again here: `rendersFlight` in
+ * `./internal/flight.js` decides from the same `uf.config.js`, and a second
+ * reading of it would be the one that drifts.
+ */
+function flightStateOf(inline) {
+  const plugins = (inline.plugins ?? []).flat(Number.POSITIVE_INFINITY);
+  return plugins.find((plugin) => plugin?.name === "uf:flow")?.api?.flight ?? null;
+}
+
+/** What a later command needs of the rsc build, written beside its output. */
+const FLIGHT_BUILD_FILE = "uf-flight.json";
+
+/**
+ * Build the rsc graph into `outDir`.
+ *
+ * `conditions` are a deploy target's own, added to `react-server`; `null` is
+ * the Node server `uf build` writes. Vite's builder rather than `vite.build`,
+ * because the rsc graph is an environment of its own and `vite.build` builds
+ * the two Vite always has.
+ */
+async function buildRscGraph(vite, inline, state, { outDir, conditions }) {
+  const environment = {
+    build: {
+      outDir,
+      emptyOutDir: true,
+      rollupOptions: {
+        input: { index: FLIGHT_VIRTUAL.entry },
+        output: { entryFileNames: "[name].js", format: "es" },
+      },
+    },
+  };
+  if (conditions != null) {
+    environment.resolve = {
+      conditions: ["react-server", ...conditions],
+      externalConditions: ["react-server", ...conditions],
+    };
+  }
+  const builder = await vite.createBuilder({
+    ...inline,
+    customLogger: eventLogger("warn"),
+    environments: { [RSC_ENVIRONMENT]: environment },
+  });
+  await builder.build(builder.environments[RSC_ENVIRONMENT]);
+  state.rscOutput = path.join(outDir, "index.js");
+}
+
+/**
+ * Record the chunk each client module was built into, and write it down.
+ *
+ * Written down because `uf build --adapter` and `uf build --compile` bundle
+ * the server again in a process of their own, and a reference in the rsc
+ * output names its module by path, which only this build's manifest turns
+ * into a URL.
+ */
+function recordClientChunks(state, manifest, references, rscDir, base = "") {
+  for (const file of references) {
+    const key = path.relative(root, file).split(path.sep).join("/");
+    const chunk = manifest[key];
+    if (chunk == null) {
+      throw new Error(
+        `uf: the client build wrote no chunk for ${key}, which a server component renders as a ` +
+          "client component",
+      );
+    }
+    state.chunkUrls.set(file, `${base}/${chunk.file}`);
+  }
+  writeFileSync(
+    path.join(rscDir, FLIGHT_BUILD_FILE),
+    `${JSON.stringify({ chunkUrls: [...state.chunkUrls] }, null, 2)}\n`,
+  );
+}
+
+/** What `recordClientChunks` wrote, for a command that runs after `uf build`. */
+function loadFlightBuild(state, rscDir) {
+  const file = path.join(rscDir, FLIGHT_BUILD_FILE);
+  if (!existsSync(file)) {
+    throw new Error(
+      `uf: ${path.relative(root, file)} is missing, so there is no rsc graph to render routes ` +
+        "with; run `uf build` first",
+    );
+  }
+  state.chunkUrls = new Map(JSON.parse(readFileSync(file, "utf8")).chunkUrls);
+  state.rscOutput = path.join(rscDir, "index.js");
+}
+
+/**
+ * The tags a document React Server Components render needs.
+ *
+ * `assetsFromManifest`'s, with stylesheets from three places in the order they
+ * cascade: the rsc graph's first — every layout's and every server component's
+ * — then the client entry's, then each client module's own, which the client
+ * build emits beside that module's chunk and no import from the entry reaches.
+ *
+ * The rsc build's emitted files are copied under `dist/` so those URLs resolve,
+ * and only its assets: a server bundle's JavaScript is never a deployable file.
+ */
+function flightAssets(manifest, references, rscDir, outDir, base = "") {
+  const assets = assetsFromManifest(manifest, base);
+  const styles = new Set();
+  const rscManifest = path.join(rscDir, ".vite", "manifest.json");
+  if (existsSync(rscManifest)) {
+    const rscStyles = assetsFromManifest(
+      JSON.parse(readFileSync(rscManifest, "utf8")),
+      base,
+    ).styles;
+    for (const href of rscStyles) styles.add(href);
+  }
+  const rscAssets = path.join(rscDir, "assets");
+  if (existsSync(rscAssets)) {
+    cpSync(rscAssets, path.join(outDir, "assets"), {
+      recursive: true,
+      filter: (from) => !/\.(?:[cm]?js|map)$/.test(from),
+    });
+  }
+  for (const href of assets.styles) styles.add(href);
+  const seen = new Set();
+  const visit = (key) => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    const chunk = manifest[key];
+    if (chunk == null) return;
+    for (const css of chunk.css ?? []) styles.add(`${base}/${css}`);
+    for (const imported of chunk.imports ?? []) visit(imported);
+  };
+  for (const file of references) visit(path.relative(root, file).split(path.sep).join("/"));
+  return { ...assets, styles: [...styles] };
+}
+
 function readManifest(outDir) {
   const file = path.join(outDir, ".vite", "manifest.json");
   if (!existsSync(file)) throw new Error(`uf: the client build wrote no manifest at ${file}`);
@@ -1949,6 +2396,21 @@ async function renderingPlan(server, prerender) {
       why: "a middleware guards it, and a middleware runs once per request",
     });
   }
+  // And `app.router`'s three lists, by the source each rule matches: a file
+  // can be neither a redirect nor a rewrite, and a header a file is served
+  // with is the host's to add rather than the file's.
+  for (const [key, what] of [
+    ["redirects", "a redirect"],
+    ["rewrites", "a rewrite"],
+    ["headers", "a response header"],
+  ]) {
+    for (const rule of server.routing?.[key] ?? []) {
+      perRequest.push({
+        path: rule.source,
+        why: `\`app.router.${key}\` names it, and ${what} is answered when a request arrives`,
+      });
+    }
+  }
 
   return { urls, perRequest };
 }
@@ -1970,9 +2432,36 @@ function fillParams(routePath, params) {
     .join("/");
 }
 
-function htmlPathFor(outDir, url) {
-  const pathname = url.split("?")[0].replace(/^\/+/, "");
-  return pathname === ""
-    ? path.join(outDir, "index.html")
+/**
+ * The file a prerendered page is written to.
+ *
+ * `guide/index.html`, which every static host serves at `/guide/` and most at
+ * `/guide`, unless `app.router.trailingSlash` is `"never"` — then `guide.html`,
+ * which the same hosts serve at `/guide` without a redirect to the slash.
+ * Next.js's static export makes the same choice from the same setting.
+ */
+function htmlPathFor(outDir, url, trailingSlash = "ignore") {
+  const pathname = url.split("?")[0].replace(/^\/+/, "").replace(/\/+$/, "");
+  if (pathname === "") return path.join(outDir, "index.html");
+  return trailingSlash === "never"
+    ? path.join(outDir, `${pathname}.html`)
     : path.join(outDir, pathname, "index.html");
 }
+
+/**
+ * The URL path at which a static half answers the document `htmlPathFor`
+ * wrote for `url` under `REGENERATED_DIRECTORY`.
+ *
+ * Ending in a slash, so every host answers it with that directory's
+ * `index.html` in the same way: a Node static half tries `index.html` for such
+ * a path, and a Worker's assets binding serves it without the redirect it
+ * answers `…/index.html` with.
+ */
+function regeneratedDocumentUrl(url) {
+  const pathname = url.split("?")[0].replace(/^\/+/, "").replace(/\/+$/, "");
+  const encoded = pathname
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  return pathname === "" ? `/${REGENERATED_DIRECTORY}/` : `/${REGENERATED_DIRECTORY}/${encoded}/`;
+}