@uniflowed/vite 0.0.0-alpha.7 → 0.0.0-alpha.8

package/index.js

@@ -16,6 +16,10 @@
 //                 that hydrates it, and the server entry that renders it. In
 //                 development it also renders every HTML request on the
 //                 server, so `uf dev` serves the same markup `uf build` writes.
+//                 The client's copy of the route table is not the server's:
+//                 `internal/rsc.js` reads the RSC analysis and leaves out the
+//                 page of every route no client boundary reaches, so that
+//                 route's modules never enter the browser bundle.
 // * `uf:mdx`    — `@mdx-js/rollup`, configured for React with GitHub-flavoured
 //                 markdown, front matter, heading ids and build-time syntax
 //                 highlighting, so `.mdx` works with
@@ -30,7 +34,7 @@ import path from "node:path";
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
 
-import { reportRenderError } from "./internal/events.js";
+import { emit, reportRenderError } from "./internal/events.js";
 import { highlightPlugin } from "./internal/highlight.js";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
@@ -43,6 +47,7 @@ import {
   preambleCode,
   refreshRuntimeSource,
 } from "./internal/refresh.js";
+import { RSC_MANIFEST_ENV, clientRouteFilter, readRscManifest } from "./internal/rsc.js";
 import {
   RESERVED,
   VIRTUAL,
@@ -52,6 +57,8 @@ import {
   serverModuleSource,
 } from "./internal/routes.js";
 import { TransformService, isFlowModule } from "@uniflowed/host/transform";
+import { send, toRequest } from "./internal/http.js";
+import { withRequest } from "./internal/serve.js";
 
 /** A resolved virtual id: Vite's convention is a leading NUL byte. */
 const resolved = (id) => `\0${id}`;
@@ -138,6 +145,32 @@ function flowPlugin({ routerRoot, appEntry, command }) {
     return service;
   };
 
+  /**
+   * The browser's copy of the route table.
+   *
+   * The manifest is read here rather than once at start-up because `uf dev`
+   * rewrites it whenever the graph moves, and this hook runs again when it
+   * does — a table built from a manifest read at start-up would be the answer
+   * for the project as it was when the server started.
+   *
+   * The count is emitted rather than computed on the Rust side, and that is
+   * the point of it: `uf build` prints what the table it just generated
+   * contains, not what a second implementation of this decision predicted it
+   * would. Only for a build — a dev server has no summary to be true in.
+   */
+  const clientRoutesModule = (table) => {
+    const shipsPage = clientRouteFilter(
+      readRscManifest(process.env[RSC_MANIFEST_ENV]),
+      root,
+      table,
+    );
+    const kept = new Set(table.routes.filter(shipsPage));
+    if (server == null) {
+      emit("rsc-split", { pages: kept.size, routes: table.routes.length });
+    }
+    return routesModuleSource(table, { shipsPage: (route) => kept.has(route) });
+  };
+
   return {
     name: "uf:flow",
     enforce: "pre",
@@ -194,9 +227,16 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       return null;
     },
 
-    load(id) {
+    load(id, loadOptions) {
       if (id === RUNTIME_RESOLVED_ID) return refreshRuntimeSource();
-      if (id === resolved(VIRTUAL.routes)) return routesModuleSource(scanRoutes(appRoot));
+      if (id === resolved(VIRTUAL.routes)) {
+        const table = scanRoutes(appRoot);
+        // The server renders every route, so the server's table is the whole
+        // one and is generated with no filter at all. Only the browser's copy
+        // is split.
+        if (isSsr(this, loadOptions)) return routesModuleSource(table);
+        return clientRoutesModule(table);
+      }
       if (id === resolved(VIRTUAL.client)) return clientModuleSource(entryPath);
       if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
       if (id.startsWith(STYLE_PREFIX)) return styles.get(id) ?? "";
@@ -308,6 +348,27 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       devServer.watcher.on("add", onRouteFile);
       devServer.watcher.on("unlink", onRouteFile);
 
+      // The same problem one level up. Adding `"use client"` to a module, or
+      // deleting the import that reached it, changes which routes the browser
+      // is given a page for — and touches no reserved file name, so nothing
+      // above notices. `uf dev` rewrites the RSC manifest when the analysis
+      // moves and only then, so this fires when the answer changed rather than
+      // on every keystroke. Watched explicitly because the file is uf's own
+      // artefact and is in no module graph.
+      const manifestFile = process.env[RSC_MANIFEST_ENV];
+      if (manifestFile != null && manifestFile !== "") {
+        const manifestPath = path.resolve(manifestFile);
+        devServer.watcher.add(manifestPath);
+        const onManifest = (file) => {
+          if (path.resolve(file) !== manifestPath) return;
+          const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
+          if (routes) devServer.moduleGraph.invalidateModule(routes);
+          devServer.ws.send({ type: "full-reload", path: "*" });
+        };
+        devServer.watcher.on("add", onManifest);
+        devServer.watcher.on("change", onManifest);
+      }
+
       // After Vite's own middlewares, so `/@vite/client`, `/@id/...` and
       // static files are served first and only a document request reaches
       // the renderer.
@@ -316,20 +377,47 @@ function flowPlugin({ routerRoot, appEntry, command }) {
           if (!wantsDocument(request)) return next();
           try {
             const url = request.url ?? "/";
-            const { render } = await importServerEntry(devServer);
-            const result = await render(url, {
-              scripts: [devUrlFor(VIRTUAL.client)],
-              styles: [],
-              preloads: [],
+            const entry = await importServerEntry(devServer);
+            const asRequest = await toRequest(request, devServer.config);
+
+            // One request, owned here and settled once the document has been
+            // written — the same lifecycle `driver.js` gives `uf dev` and
+            // `internal/serve.js` gives `uf preview` and `uf start`. A project
+            // driving Vite itself must not get a different answer about when
+            // `after()` runs than the same project run through `uf dev`; see
+            // `internal/serve.js` and ubugeeei-prod/uf#389.
+            //
+            // Only document requests reach here, so unlike `driver.js` there is
+            // no path where uf hands the response back to Vite's chain: what is
+            // below either writes it or throws.
+            await withRequest(entry, asRequest, async () => {
+              // Before the page: a middleware guards a subtree, and a page
+              // rendered while the guard on it had not run is the whole of
+              // ubugeeei-prod/uf#260. Only document requests reach here, so this
+              // is the page half of the guarantee; `driver.js` makes the same
+              // call above the route handlers, for every method.
+              const guarded = await entry.runMiddleware(asRequest);
+              if (guarded != null) {
+                await send(response, guarded);
+                return;
+              }
+
+              const result = await entry.render(
+                url,
+                { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
+                { onError: (error) => reportRenderError(devServer, url, error) },
+              );
+              if (result.error != null) reportRenderError(devServer, url, result.error);
+              // Collected rather than piped, for the reason `driver.js` gives at
+              // step 4: `transformIndexHtml` is a whole-document hook.
+              const html = await devServer.transformIndexHtml(url, await result.text());
+              response.statusCode = result.status;
+              response.setHeader("Content-Type", "text/html; charset=utf-8");
+              for (const [name, value] of Object.entries(result.headers ?? {})) {
+                response.setHeader(name, value);
+              }
+              response.end(html);
             });
-            if (result.error != null) reportRenderError(devServer, url, result.error);
-            const html = await devServer.transformIndexHtml(url, result.html);
-            response.statusCode = result.status;
-            response.setHeader("Content-Type", "text/html; charset=utf-8");
-            for (const [name, value] of Object.entries(result.headers ?? {})) {
-              response.setHeader(name, value);
-            }
-            response.end(html);
           } catch (error) {
             devServer.ssrFixStacktrace(error);
             next(error);
@@ -513,6 +601,16 @@ function packageOf(file) {
   return up === -1 ? parts.slice(0, -1).join("/") || file : parts.slice(up, up + 2).join("/");
 }
 
+/**
+ * Whether a hook is running for the server environment.
+ *
+ * Both spellings, for the reason `transform` above checks both: Vite 6 moved
+ * the answer onto the plugin context and the `ssr` option is the older one.
+ */
+function isSsr(context, options) {
+  return options?.ssr === true || context?.environment?.name === "ssr";
+}
+
 function cleanId(id) {
   const at = id.indexOf("?");
   return at === -1 ? id : id.slice(0, at);

package/internal/http.js

@@ -0,0 +1,79 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// Node's request and response objects on one side, the platform's `Request`
+// and `Response` on the other.
+//
+// uf's server contracts are the platform's — a route handler and a middleware
+// both take a `Request` and return a `Response`, because that is what runs
+// unchanged on Node.js, Bun, Deno and a Cloudflare Worker. Node's dev server
+// speaks `IncomingMessage` and `ServerResponse`, so exactly one place has to
+// translate.
+//
+// It is a module rather than two functions in `driver.js` because there are
+// two dev servers: `driver.js` is what `uf dev` spawns, and the `uf:flow`
+// plugin's own `configureServer` is what a project using Vite directly gets.
+// Both have to run the same middleware before the same request, and a second
+// copy of this translation is how the two would come to disagree about, say,
+// whether a repeated header is joined or appended.
+
+/**
+ * A Node request as a `Request`.
+ *
+ * The body is read as a stream where the host supports it, because a handler
+ * that accepts an upload should not need the whole thing buffered before it
+ * starts.
+ *
+ * @param {import("node:http").IncomingMessage} incoming
+ * @param {{server?: {https?: unknown}} | undefined} config the resolved Vite config
+ */
+export async function toRequest(incoming, config) {
+  const host = incoming.headers.host ?? "localhost";
+  const protocol = config?.server?.https == null ? "http" : "https";
+  const url = new URL(incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
+
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(incoming.headers)) {
+    if (value == null) continue;
+    for (const entry of Array.isArray(value) ? value : [value]) {
+      headers.append(name, entry);
+    }
+  }
+
+  const method = (incoming.method ?? "GET").toUpperCase();
+  const init = { method, headers };
+  if (method !== "GET" && method !== "HEAD") {
+    // `duplex` is required by the specification whenever a body is a stream,
+    // and Node throws without it.
+    init.body = incoming;
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+
+/**
+ * Write a `Response` to a Node response.
+ *
+ * One implementation, reached late. This was a second copy of the loop in
+ * `@uniflowed/server`'s `node.js`, and the two drifted the moment the shared
+ * one moved: `uf start` and every adapter lost the socket pacing and the
+ * hang-up cancel while `uf dev` and `uf preview` kept them, which is a
+ * deployment whose memory profile differs from the one that was checked. See
+ * ubugeeei-prod/uf#400.
+ *
+ * The import is inside the function, and that is not a style choice.
+ * `driver.js` imports this module *statically* and registers the Flow loader
+ * hooks in its own body, so anything reachable from a static import here is
+ * read by Node before there is anything to compile Flow with —
+ * `@uniflowed/server/node` is Flow source, and a static re-export of it makes
+ * every `uf build` die on `import type` with a `SyntaxError`. `loadBuild` in
+ * `internal/serve.js` defers for the same reason and says so.
+ *
+ * @param {import("node:http").ServerResponse} outgoing
+ * @param {Response} result
+ */
+export async function send(outgoing, result) {
+  const { send: write } = await import("@uniflowed/server/node");
+  await write(outgoing, result);
+}

package/internal/routes.js

@@ -24,6 +24,7 @@ export const RESERVED = Object.freeze({
   middleware: "_uf.middleware",
   notFound: "_uf.not-found",
   error: "_uf.error",
+  loading: "_uf.loading",
   route: "_uf.route",
 });
 
@@ -43,10 +44,27 @@ const MAX_DEPTH = 32;
  * @property {ReadonlyArray<{name: string, catchAll: boolean}>} params
  * @property {string} page absolute path of the page module
  * @property {ReadonlyArray<string>} layouts absolute paths, root first
- * @property {ReadonlyArray<string>} middleware absolute paths, root first
+ * @property {ReadonlyArray<{above: number, module: string}>} loading the
+ *   `<Suspense>` boundaries in scope, root first; `above` is how many of
+ *   `layouts` are outside each one
  * @property {boolean} mdx whether the page is MDX content
  */
 
+/**
+ * One middleware — everything under a directory, guarded before it answers.
+ *
+ * A flat table keyed by the directory's route path, rather than an array on
+ * every route the way layouts are accumulated. That was the first shape and it
+ * left two holes: `/dashboard/typo` matches no route, so a per-route array
+ * would have rendered the 404 with the guard skipped, and a route handler is
+ * in a table of its own, so guarding pages would have guarded half of them.
+ * The path is the matcher, so the path is what the table carries.
+ *
+ * @typedef {object} Middleware
+ * @property {string} path route path of the directory it guards, `/` at the root
+ * @property {string} module absolute path of the middleware module
+ */
+
 /**
  * One route handler — a path that answers a request instead of rendering.
  *
@@ -89,6 +107,28 @@ const MAX_DEPTH = 32;
  * @property {ReadonlyArray<string>} layouts absolute paths, root first
  */
 
+/**
+ * One loading boundary — the fallback for the segment that declares it.
+ *
+ * Not the nearest-ancestor shape the other two boundaries have, and the
+ * difference is the whole of what a fallback is. A not-found or an error
+ * boundary is *chosen*: one of them renders, and the resolver picks the
+ * nearest above the path. Loading boundaries *nest*: `app/_uf.loading.js` and
+ * `app/docs/_uf.loading.js` are two `<Suspense>` elements on one route, one
+ * inside the other, and both are in the tree at once. So they accumulate down
+ * the walk the way layouts do rather than being matched afterwards, and each
+ * route carries the list that applies to it.
+ *
+ * `above` is the count of the route's `layouts` that sit outside the boundary
+ * — the layouts that render immediately, which is what "the shell around a
+ * slow page" means. It is the same number, spelled the same way, as
+ * `ResolvedRoute["errorBoundary"].above` in the router runtime.
+ *
+ * @typedef {object} LoadingBoundary
+ * @property {number} above how many of the route's layouts are outside it
+ * @property {string} module absolute path of the loading module
+ */
+
 /**
  * Scan `appRoot` for routes.
  *
@@ -97,25 +137,49 @@ const MAX_DEPTH = 32;
  * library project has no router root, and that is not a mistake.
  *
  * @param {string} appRoot absolute path of the router root (`app/`)
- * @returns {{routes: Route[], handlers: Handler[], notFound: NotFoundBoundary[], errors: ErrorBoundary[]}}
+ * @returns {{
+ *   routes: Route[],
+ *   handlers: Handler[],
+ *   middleware: Middleware[],
+ *   notFound: NotFoundBoundary[],
+ *   errors: ErrorBoundary[],
+ * }}
  */
 export function scanRoutes(appRoot) {
   const routes = [];
   const handlers = [];
+  const middleware = [];
   const notFound = [];
   const errors = [];
-  if (!isDirectory(appRoot)) return { routes, handlers, notFound, errors };
+  if (!isDirectory(appRoot)) return { routes, handlers, middleware, notFound, errors };
 
-  const walk = (directory, segments, layouts, middleware, depth) => {
+  const walk = (directory, segments, layouts, loading, depth) => {
     if (depth > MAX_DEPTH) return;
     const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
       a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
     );
 
     const ownLayout = findModule(directory, RESERVED.layout, MODULE_EXTENSIONS);
-    const ownMiddleware = findModule(directory, RESERVED.middleware, MODULE_EXTENSIONS);
     const nextLayouts = ownLayout ? [...layouts, ownLayout] : layouts;
-    const nextMiddleware = ownMiddleware ? [...middleware, ownMiddleware] : middleware;
+
+    // Inside this directory's own layout, which is where Next.js puts it and
+    // the only placement that makes sense: the fallback is what shows *within*
+    // the frame this segment draws, so the frame has to be outside it.
+    // `nextLayouts.length` is therefore the count taken after the own layout is
+    // added, not before. A segment with a loading file and no layout of its own
+    // still gets a boundary — it just shares its parent's frame.
+    const ownLoading = findModule(directory, RESERVED.loading, MODULE_EXTENSIONS);
+    const nextLoading = ownLoading
+      ? [...loading, { above: nextLayouts.length, module: ownLoading }]
+      : loading;
+
+    // A middleware guards this directory and everything below it, whether or
+    // not this directory is itself a route: `app/dashboard/_uf.middleware.js`
+    // with no `_uf.page.js` beside it still guards `/dashboard/settings`.
+    const ownMiddleware = findModule(directory, RESERVED.middleware, MODULE_EXTENSIONS);
+    if (ownMiddleware) {
+      middleware.push({ path: routeFromSegments(segments).path, module: ownMiddleware });
+    }
 
     const page = findModule(directory, RESERVED.page, PAGE_EXTENSIONS);
     if (page) {
@@ -126,7 +190,7 @@ export function scanRoutes(appRoot) {
         params,
         page,
         layouts: nextLayouts,
-        middleware: nextMiddleware,
+        loading: nextLoading,
         mdx: page.endsWith(".mdx"),
       });
     }
@@ -173,7 +237,7 @@ export function scanRoutes(appRoot) {
         path.join(directory, entry.name),
         [...segments, entry.name],
         nextLayouts,
-        nextMiddleware,
+        nextLoading,
         depth + 1,
       );
     }
@@ -183,6 +247,10 @@ export function scanRoutes(appRoot) {
   const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   routes.sort(byPath);
   handlers.sort(byPath);
+  // Sorted for a table that does not churn between builds, and for nothing
+  // else: `createMiddlewareRunner` re-orders the table root first, because
+  // what a chain of guards runs in is depth, not name.
+  middleware.sort(byPath);
   // Sorted by path, not by which is nearest: the resolver picks the longest
   // path that covers the URL, so it does not depend on this order, and sorting
   // by nearness would hide that.
@@ -196,7 +264,7 @@ export function scanRoutes(appRoot) {
   // parallel-route trees uf does not have yet; see ubugeeei-prod/uf#267.
   notFound.sort(byPath);
   errors.sort(byPath);
-  return { routes, handlers, notFound, errors };
+  return { routes, handlers, middleware, notFound, errors };
 }
 
 function isDirectory(candidate) {
@@ -260,11 +328,55 @@ export const VIRTUAL = Object.freeze({
  *
  * Each page and layout is a lazy `import()`, so a route is a chunk of its own.
  * Layouts are deduplicated into one table so a layout shared by fifty routes
- * is one dynamic import, not fifty.
+ * is one dynamic import, not fifty. Middleware needs no deduplication: it is
+ * already one entry per file, keyed by the path it guards.
+ *
+ * # The client's copy is not the server's
+ *
+ * `shipsPage` is how the server/client split reaches the bundle. A route it
+ * answers `false` for keeps its path and its parameters — the router still has
+ * to *match* the URL, so that a link into it can hand the navigation back to
+ * the browser — and loses its `page`, its `layouts` and its `loading`
+ * boundaries, which are the only `import()` calls in this table. Nothing in
+ * the browser can then reach the module through the router, so Rollup emits no
+ * chunk for it and none for anything only it reached.
+ *
+ * Omitted by leaving the key out rather than by writing `page: null`, because
+ * the two say different things to a bundler: a property whose value is an
+ * `import()` is a chunk whether or not anything reads it.
  *
- * @param {{routes: Route[], handlers?: Handler[], notFound?: NotFoundBoundary[], errors?: ErrorBoundary[]}} table
+ * # Except for its styles
+ *
+ * A route that ships no JavaScript still has to *look* right, and a uf build
+ * takes its stylesheets from the client graph: `assetsFromManifest` walks the
+ * client entry's imports and links the CSS it finds, so a module removed from
+ * that graph takes its rules out of every page in the site. That is a silent
+ * visual break, and it is worse than shipping the module.
+ *
+ * So each module a dropped route was the only reader of comes back at the top
+ * of this file as a bare `import <file>;` — a side-effect import, with no
+ * binding read from it. Its stylesheet is a side effect and survives; its
+ * components, its helpers and everything only they referenced are unused
+ * exports and do not. A layout a *kept* route still uses is left out of that
+ * list: it is already here as a lazy import, and a static one as well would
+ * pull it into the entry chunk.
+ *
+ * The default answers `true` for every route, which is the whole table, no
+ * side-effect imports, and exactly what this emitted before the split existed.
+ * `virtual:uf/server` is generated with the default and always will be: the
+ * server renders every route, so its table is the complete one.
+ *
+ * @param {{
+ *   routes: Route[],
+ *   handlers?: Handler[],
+ *   middleware?: Middleware[],
+ *   notFound?: NotFoundBoundary[],
+ *   errors?: ErrorBoundary[],
+ * }} table
+ * @param {{shipsPage?: (route: Route) => boolean}} [options]
  */
-export function routesModuleSource(table) {
+export function routesModuleSource(table, options = {}) {
+  const shipsPage = options.shipsPage ?? (() => true);
   const layoutIds = new Map();
   const layoutImports = [];
   const layoutId = (file) => {
@@ -277,8 +389,44 @@ export function routesModuleSource(table) {
     return id;
   };
 
+  // Loading modules are deduplicated into a table of their own, for the reason
+  // layouts are: one `app/_uf.loading.js` is the fallback of every route under
+  // it, and fifty copies of the same `import()` would be fifty chunks of the
+  // same file.
+  //
+  // They are static imports rather than lazy ones, and that is not an
+  // oversight. React decides to show a fallback *synchronously*, during the
+  // render that suspended, so a fallback still waiting on its own `import()` is
+  // a fallback that is not there at the only moment it is wanted — the same
+  // reasoning as the error boundaries below, arrived at from the other
+  // direction. `resolveMatch` awaits them with the layouts, before it renders.
+  const loadingIds = new Map();
+  const loadingImports = [];
+  const loadingId = (file) => {
+    let id = loadingIds.get(file);
+    if (id === undefined) {
+      id = `loading${loadingIds.size}`;
+      loadingIds.set(file, id);
+      loadingImports.push(`const ${id} = () => import(${JSON.stringify(file)});`);
+    }
+    return id;
+  };
+
   const entries = table.routes.map((route) => {
+    if (!shipsPage(route)) {
+      return `  {
+    path: ${JSON.stringify(route.path)},
+    params: ${JSON.stringify(route.params)},
+    mdx: ${route.mdx},
+    file: ${JSON.stringify(route.page)},
+    layouts: [],
+    loading: [],
+  }`;
+    }
     const layouts = route.layouts.map(layoutId);
+    const loading = (route.loading ?? []).map(
+      (boundary) => `{ above: ${boundary.above}, module: ${loadingId(boundary.module)} }`,
+    );
     return `  {
     path: ${JSON.stringify(route.path)},
     params: ${JSON.stringify(route.params)},
@@ -286,6 +434,7 @@ export function routesModuleSource(table) {
     file: ${JSON.stringify(route.page)},
     page: () => import(${JSON.stringify(route.page)}),
     layouts: [${layouts.join(", ")}],
+    loading: [${loading.join(", ")}],
   }`;
   });
 
@@ -328,13 +477,48 @@ export function routesModuleSource(table) {
   }`,
   );
 
-  return `${layoutImports.join("\n")}
+  // Middleware is a table of its own for the same reason, and for a stronger
+  // one: it is where an application puts the check it does not want a user to
+  // read. `clientModuleSource` imports `routes`, `notFound` and `errors` and
+  // nothing else, so a middleware module is reachable from the server entry
+  // alone.
+  const middlewareEntries = (table.middleware ?? []).map(
+    (entry) => `  {
+    path: ${JSON.stringify(entry.path)},
+    file: ${JSON.stringify(entry.module)},
+    load: () => import(${JSON.stringify(entry.module)}),
+  }`,
+  );
+
+  // Last, because it is defined by what everything above did *not* import: a
+  // layout a kept route also uses is already in the graph as a lazy chunk, and
+  // importing it here as well would pull it into the entry chunk instead.
+  const carried = new Set([...layoutIds.keys(), ...loadingIds.keys()]);
+  const styleOnlyImports = [];
+  for (const route of table.routes) {
+    if (shipsPage(route)) {
+      continue;
+    }
+    const files = [route.page, ...route.layouts, ...(route.loading ?? []).map((it) => it.module)];
+    for (const file of files) {
+      if (carried.has(file)) {
+        continue;
+      }
+      carried.add(file);
+      styleOnlyImports.push(`import ${JSON.stringify(file)};`);
+    }
+  }
+
+  return `${[...styleOnlyImports, ...layoutImports, ...loadingImports].join("\n")}
 export const routes = [
 ${entries.join(",\n")}
 ];
 export const handlers = [
 ${handlerEntries.join(",\n")}
 ];
+export const middleware = [
+${middlewareEntries.join(",\n")}
+];
 export const notFound = [
 ${notFoundEntries.join(",\n")}
 ];
@@ -361,14 +545,56 @@ hydrate({ App, routes, notFound, errors });
 }
 
 /**
- * The source of `virtual:uf/server`: render one URL to HTML.
+ * The source of `virtual:uf/server`: answer one request.
+ *
+ * Three exports, and the order a host calls them in is the whole of how the
+ * two halves of the table compose. `runMiddleware` first, because a middleware
+ * guards a *path* — it has to run for a page, for a route handler, and for a
+ * path under it that matches neither, so it belongs above route resolution
+ * rather than inside it. `notFound` and `errors` go the other way: they are
+ * boundaries chosen *during* a render, once resolution knows which route was
+ * asked for and whether it threw, which is why they are `createRenderer`'s
+ * arguments and not a step of their own. The two never compete for the same
+ * request — one decides whether the router is reached at all, the others
+ * decide what the router renders when it is.
+ *
+ * `internal/serve.js` and `driver.js` call them in that order, and
+ * `packages/vite/index.js` does the same for a project driving Vite itself.
+ *
+ * `render` and `prerender` are two exports rather than one with a flag, because
+ * a host is one or the other: a server streams, a build writes files. See the
+ * header of `packages/router/server.js` for why React needs both told apart.
+ *
+ * `beginRequest` is the fourth, and it is re-exported rather than imported by
+ * the host for a reason that is easy to get wrong: `@uniflowed/server` keeps
+ * the request in an `AsyncLocalStorage` held by *its module*, and a bundled
+ * application has its own copy of that module inlined. A host that imported
+ * `beginRequest` from its own `node_modules` would establish a request in a
+ * second storage, and every `cookies()` in the application would still be
+ * outside one. So the bundle hands the host the entry point that belongs to
+ * the bundle. `uf preview`, `uf start`, `uf dev` and the compiled binary all
+ * take it from here; see ubugeeei-prod/uf#389.
+ *
+ * Through `@uniflowed/router/server` rather than `@uniflowed/server/host`,
+ * because this source is resolved from the *project's* directory and a project
+ * depends on the router, not on the router's own dependency. It is also the
+ * shorter proof of the paragraph above: the copy the router dispatches and
+ * renders with is by construction the copy the host is handed.
  */
 export function serverModuleSource(appEntry) {
-  return `import { createDispatcher, createRenderer } from "@uniflowed/router/server";
-import { routes, handlers, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
+  return `import {
+  createDispatcher,
+  createMiddlewareRunner,
+  createRenderer,
+} from "@uniflowed/router/server";
+import { routes, handlers, middleware, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-export { routes, handlers, notFound, errors };
-export const render = createRenderer({ App, routes, notFound, errors });
+export { routes, handlers, middleware, notFound, errors };
+export { beginRequest } from "@uniflowed/router/server";
+const renderer = createRenderer({ App, routes, notFound, errors });
+export const render = renderer.render;
+export const prerender = renderer.prerender;
 export const dispatch = createDispatcher({ handlers });
+export const runMiddleware = createMiddlewareRunner({ middleware });
 `;
 }