@uniflowed/vite 0.0.0-alpha.9 → 0.2.0

package/index.js

@@ -14,8 +14,12 @@
 //                 development and the virtual modules that make a directory
 //                 of pages an application: the route table, the client entry
 //                 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.
+//                 development it also answers every request the way a
+//                 deployment does — the guard, a server action, a route
+//                 handler, then the renderer — so `uf dev` serves what
+//                 `uf start` serves rather than an approximation of it, and it
+//                 serves the two `/__uf/` paths a browser reports to (see
+//                 `internal/diagnostics.js`).
 //                 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
@@ -24,6 +28,11 @@
 //                 markdown, front matter, heading ids and build-time syntax
 //                 highlighting, so `.mdx` works with
 //                 no configuration.
+// * `uf:barrel-imports` — a named import from `@uniflowed/ui` becomes an import
+//                 from the file that defines the name, in every environment,
+//                 so a page using one component loads that component's module
+//                 rather than every module the barrel re-exports. See
+//                 `internal/barrel-imports.js`.
 // * `uf:asset`  — an imported image is decoded, resized to the widths the
 //                 project declares and re-encoded by `uf assets`, and an
 //                 imported font is self-hosted with the `@font-face` and the
@@ -35,18 +44,31 @@
 // `uniflowed(options)` returns the array; a project that wants to add a plugin
 // declares it in `uf.config.js` and the driver appends it after these.
 
-import { readdirSync } from "node:fs";
+import { instrumentationFile } from "./internal/instrumentation.js";
+
+import { readFileSync } from "node:fs";
 import path from "node:path";
+import { nativeWebPlugin } from "./internal/native-web.js";
 
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
+import { relayConfig, relayDependencies, transformRelay } from "./internal/relay.js";
 
+import {
+  AUDIT_PUBLIC_PATH,
+  AUDIT_RESOLVED_ID,
+  auditAvailable,
+  auditRuntimeSource,
+  auditTag,
+} from "./internal/a11y.js";
 import { assetPlugin } from "./internal/assets.js";
-import { emit, reportRenderError } from "./internal/events.js";
+import { barrelImportsPlugin, namespaceViewOf } from "./internal/barrel-imports.js";
+import { emit, reportRenderError, errorEvent } from "./internal/events.js";
+import remarkFrontmatterExport from "./internal/frontmatter.js";
 import { highlightPlugin } from "./internal/highlight.js";
+import { moduleId } from "./internal/module-graph.js";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
-import remarkMdxFrontmatter from "remark-mdx-frontmatter";
 
 import {
   RUNTIME_PUBLIC_PATH,
@@ -55,22 +77,93 @@ import {
   preambleCode,
   refreshRuntimeSource,
 } from "./internal/refresh.js";
-import { RSC_MANIFEST_ENV, clientRouteFilter, readRscManifest } from "./internal/rsc.js";
+import {
+  RSC_MANIFEST_ENV,
+  actionReferenceSource,
+  declaresDefaultExport,
+  serverActionSource,
+  actionsModuleSource,
+  clientRouteFilter,
+  readRscManifest,
+  rscManifestKey,
+  serverActionModules,
+  serverActionTable,
+} from "./internal/rsc.js";
 import {
   RESERVED,
   VIRTUAL,
   clientModuleSource,
+  resolveRouteTarget,
   routesModuleSource,
+  routingRulesOf,
   scanRoutes,
   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";
+import {
+  TransformService,
+  isCompiledOutput,
+  isFlowModule,
+  uniflowedPackages,
+} from "@uniflowed/host/transform";
+import {
+  DEV_RSC_HOOK,
+  FLIGHT_BROWSER_DEPENDENCIES,
+  FLIGHT_VIRTUAL,
+  INTERCEPTED_FROM_HEADER,
+  RSC_ENVIRONMENT,
+  builtBridgeSource,
+  builtReferencesSource,
+  clientManifestSource,
+  clientModuleUrlPlugin,
+  clientReferencePlugin,
+  compilerRuntimeSource,
+  createFlightState,
+  devBridgeSource,
+  devReferencesSource,
+  devStylesheets,
+  flightClientSource,
+  flightDocumentPath,
+  flightServerSource,
+  linkStylesheets,
+  rendersFlight,
+  rscEntrySource,
+  rscEnvironment,
+} from "./internal/flight.js";
+import { createChannelMiddleware } from "./internal/diagnostics.js";
+import { startDevState } from "./internal/dev-state.js";
+import { devtoolsPreamble } from "./internal/devtools.js";
+import { send, toAddressRequest, toRequest } from "./internal/http.js";
+import {
+  answerRouting,
+  answersInFrontOfFiles,
+  beginRequest,
+  forViteBase,
+  rewriteRouting,
+} from "./internal/serve.js";
+import { serverComponentsProblem } from "./internal/server-components.js";
 
 /** A resolved virtual id: Vite's convention is a leading NUL byte. */
 const resolved = (id) => `\0${id}`;
-const VIRTUAL_IDS = new Set(Object.values(VIRTUAL));
+const VIRTUAL_IDS = new Set([...Object.values(VIRTUAL), ...Object.values(FLIGHT_VIRTUAL)]);
+
+/**
+ * CommonJS packages the browser can reach only through an installed
+ * `@uniflowed/*` package.
+ *
+ * uf excludes its own packages from Vite's dependency optimizer because they
+ * ship Flow, so Vite will not discover a CommonJS peer through them once they
+ * live under a project's `node_modules`. React Testing's `happy-dom` edge is
+ * ESM and browser-mapped to a local stub, and the optional `axe-core` edge is
+ * named separately below only when the project actually installed it.
+ */
+const CLIENT_COMMONJS_DEPENDENCIES = Object.freeze([
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react/compiler-runtime",
+  "react-dom",
+  "react-dom/client",
+]);
 
 /**
  * Prefix of the virtual module that carries one source module's StyleX rules.
@@ -93,7 +186,14 @@ export function devUrlFor(id) {
  * @typedef {object} UniflowedOptions
  * @property {string} [root] absolute project root; Vite's root by default
  * @property {object} [config] the loaded `uf.config.js` object
+ * @property {"web" | "native" | "ios" | "android"} [target] app target
  * @property {string} [command] the `uf` binary to transform through
+ * @property {boolean} [shareTransformAcrossBuilds] keep one `uf transform` for
+ *   every build these plugins run, rather than closing it when each ends. For a
+ *   caller that runs several builds with the same plugins and owns the process
+ *   they run in — `driver.js` — which is what makes an idle service left open
+ *   at the end nobody's problem. Off by default: a process that builds many
+ *   projects in turn would otherwise keep one idle `uf` per project.
  */
 
 /**
@@ -104,25 +204,114 @@ export function devUrlFor(id) {
 export default function uniflowed(options = {}) {
   const ufConfig = options.config ?? {};
   const app = ufConfig.app ?? {};
+  const routeTarget = resolveRouteTarget(ufConfig, options.target);
   const routerRoot = app.router?.root ?? "app";
   const appEntry = app.router?.entry ?? ufConfig.build?.entries?.[0] ?? "app.js";
   const markdown = app.builtins?.markdown ?? {};
   const builtins = app.builtins ?? {};
+  // On unless the project says otherwise, and read as `!== false` rather than
+  // `=== true` because that is what "on by default" means for a field almost
+  // no `uf.config.js` will mention. It only ever reaches the *development*
+  // client entry; see `flowPlugin`'s `load`. ubugeeei-prod/uf#516.
+  const strictMode = app.react?.strictMode !== false;
+  // What the browser does with a link, read here for the reason Strict Mode is
+  // and honoured in every command rather than in the build alone: it is the
+  // one setting whose whole effect is what happens on a click, so a dev server
+  // that disagreed with the deployment would be the wrong application to look
+  // at. Anything but `"document"` is the client router, which is what every
+  // project that has not heard of the key has.
+  const navigation = app.rendering?.navigation === "document" ? "document" : "client";
+  // How long, in seconds, the client router shows a route it already fetched
+  // without asking the server again, written into the client entry beside
+  // `navigation` and honoured by every command for the same reason. Anything
+  // but a positive number is `0`, which keeps nothing.
+  const staleTime =
+    typeof app.rendering?.staleTime === "number" &&
+    Number.isFinite(app.rendering.staleTime) &&
+    app.rendering.staleTime > 0
+      ? app.rendering.staleTime
+      : 0;
+  // Whether this application starts by attaching to markup or by rendering
+  // into an empty root. `["csr"]` is the only list that means the second, and
+  // `uf` refuses that value beside any other while the config is read — so the
+  // question here is "is it in the list", not "is it the only thing in it",
+  // and a driver started by hand on a config `uf` never validated gets the same
+  // answer for the same reason a project would want.
+  const mount = (app.rendering?.modes ?? []).includes("csr") ? "render" : "hydrate";
+  // Whether routes render as React Server Components, which is the default: a
+  // second module graph resolved under `react-server`, a document carrying the
+  // Flight payload it was rendered from, and a browser that hydrates that
+  // payload rather than importing routes. `app.rsc: false` is the application
+  // rendered from its modules, as every uf application was before
+  // ubugeeei-prod/uf#519. See `./internal/flight.js`.
+  const flightState = rendersFlight(app, { mount, routeTarget })
+    ? createFlightState({ root: options.root ?? process.cwd() })
+    : null;
+
+  const accessibility = ufConfig.accessibility ?? {};
+  // `app.router.redirects`, `rewrites` and `headers`: written into the server
+  // bundle for every host that serves a build, and asked by `uf dev` itself
+  // from the same object. See `@uniflowed/server`'s `internal/routing.js`.
+  const routing = routingRulesOf(app.router);
 
   return [
-    flowPlugin({ routerRoot, appEntry, command: options.command }),
+    flowPlugin({
+      routerRoot,
+      appEntry,
+      routeTarget,
+      strictMode,
+      navigation,
+      staleTime,
+      mount,
+      flightState,
+      routing,
+      command: options.command,
+      shareTransformAcrossBuilds: options.shareTransformAcrossBuilds === true,
+      accessibility,
+      relayEnabled: builtins.relay !== false,
+    }),
+    ...(flightState == null ? [] : [clientReferencePlugin(flightState), clientModuleUrlPlugin()]),
+    // After the references, so a client module the rsc graph has already
+    // replaced is not read for imports it no longer has; see the file.
+    barrelImportsPlugin(),
     mdxPlugin(markdown),
     assetPlugin({
       images: builtins.images ?? {},
       fonts: builtins.fonts ?? {},
+      icons: builtins.icons ?? {},
+      og: builtins.og ?? {},
       command: options.command,
     }),
+    nativeWebPlugin(routeTarget),
   ];
 }
 
-function flowPlugin({ routerRoot, appEntry, command }) {
+function flowPlugin({
+  routerRoot,
+  appEntry,
+  routeTarget,
+  strictMode,
+  navigation,
+  staleTime,
+  mount,
+  flightState,
+  routing,
+  command,
+  shareTransformAcrossBuilds,
+  accessibility,
+  relayEnabled,
+}) {
   let root = process.cwd();
   let isProduction = false;
+  /**
+   * Whether this project has axe-core, so the audit has an engine.
+   *
+   * Answered once in `configResolved` rather than per document: it is a
+   * question about `node_modules`, the answer cannot change while the server
+   * runs without a restart anyway, and asking it per render would put a module
+   * resolution on the path of every page.
+   */
+  let auditsPage = false;
   let base = "/";
   let appRoot = "";
   let entryPath = "";
@@ -130,6 +319,7 @@ function flowPlugin({ routerRoot, appEntry, command }) {
   let server = null;
   /** @type {TransformService | null} */
   let service = null;
+  let relayOptions = null;
   /**
    * Each module's compiled stylesheet, keyed by the virtual id serving it.
    *
@@ -157,8 +347,11 @@ function flowPlugin({ routerRoot, appEntry, command }) {
   /** Findings held back as a dependency's, waiting to be counted out loud. */
   let suppressed = [];
 
+  // A service that has lost its process is replaced rather than kept: under
+  // `shareTransformAcrossBuilds` one outlives a build, and a `uf transform`
+  // that died in one pass must not fail every pass after it.
   const ensureService = () => {
-    service ??= new TransformService({ command, root });
+    if (service == null || !service.alive) service = new TransformService({ command, root });
     return service;
   };
 
@@ -185,30 +378,107 @@ function flowPlugin({ routerRoot, appEntry, command }) {
     if (server == null) {
       emit("rsc-split", { pages: kept.size, routes: table.routes.length });
     }
-    return routesModuleSource(table, { shipsPage: (route) => kept.has(route) });
+    // `relativeTo` only here, and never for the server's copy below. Every
+    // `import()` in this table becomes a chunk URL, but `file` is a string and
+    // survives the build — so the browser's table was shipping the absolute
+    // path of every page on the machine that built the site, to every visitor.
+    // The server's table is read where those files are and keeps them.
+    // HTTP handlers are exclusively server capabilities. Even an unused
+    // dynamic import makes Vite traverse the handler's database/auth imports.
+    return routesModuleSource(
+      { ...table, handlers: [] },
+      {
+        shipsPage: (route) => kept.has(route),
+        relativeTo: root,
+      },
+    );
+  };
+
+  /**
+   * The manifest's two action tables, re-read only when the file changes.
+   *
+   * `load` runs for every module in the graph and has to ask "is this a
+   * `"use server"` module?" about each one, so parsing the manifest per call
+   * would put a JSON parse of the whole graph between Vite and every file it
+   * opens. Size and modification time are the identity — the same pair
+   * `.uf/cache/transform` keys on — and `uf dev` drops the memo outright when
+   * its watcher sees the file change, so a rewrite inside one millisecond is
+   * still seen.
+   */
+  let actionMemo = null;
+  const forgetActions = () => {
+    actionMemo = null;
+  };
+  const invalidateActionModules = (moduleGraph, modules) => {
+    for (const id of modules.keys()) {
+      const module = moduleGraph.getModuleById(id);
+      if (module) moduleGraph.invalidateModule(module);
+    }
+  };
+  const actionTables = () => {
+    const file = process.env[RSC_MANIFEST_ENV];
+    const key = rscManifestKey(file);
+    if (actionMemo == null || actionMemo.key !== key) {
+      const manifest = readRscManifest(file);
+      actionMemo = {
+        key,
+        modules: serverActionModules(manifest, root),
+        table: serverActionTable(manifest, root),
+      };
+    }
+    return actionMemo;
   };
 
   return {
     name: "uf:flow",
     enforce: "pre",
+    // What `driver.js` runs the three builds with; `null` for an application
+    // rendered from its modules. See `./internal/flight.js`.
+    api: { flight: flightState },
 
     config(userConfig, env) {
       const projectRoot = path.resolve(userConfig.root ?? process.cwd());
+      // Before anything is resolved. Routes that render as React Server
+      // Components need `react-server-dom-parcel` and React 19.3, and the router
+      // installs without either (ubugeeei-prod/uf#992). Said here, once, rather
+      // than as an unresolved import deep in a build or a failure inside a render.
+      if (flightState != null) {
+        const problem = serverComponentsProblem(projectRoot);
+        if (problem != null) {
+          throw new Error(problem);
+        }
+      }
       isProduction = env.mode === "production" || env.command === "build";
+      // A reference names the client manifest only in a build, where a client
+      // build writes the chunks it names; a dev server names the URL it serves.
+      if (flightState != null) flightState.production = env.command === "build";
+      // Decided here rather than in `configResolved`, because the answer has to
+      // reach `optimizeDeps.include` below and that is written in this hook.
+      auditsPage =
+        !isProduction && (accessibility?.devAudit ?? true) && auditAvailable(projectRoot);
       return {
         // uf serves HTML itself; there is no index.html to fall back to.
         appType: "custom",
         resolve: {
-          dedupe: ["react", "react-dom"],
+          dedupe: ["react", "react-dom", "react-relay", "relay-runtime"],
         },
         optimizeDeps: {
           include: [
-            "react",
-            "react/jsx-runtime",
-            "react/jsx-dev-runtime",
-            "react/compiler-runtime",
-            "react-dom",
-            "react-dom/client",
+            ...CLIENT_COMMONJS_DEPENDENCIES,
+            ...relayDependencies(projectRoot),
+            // React's Flight client, for an application whose routes render as
+            // Server Components; `FLIGHT_BROWSER_DEPENDENCIES` says why.
+            ...(flightState == null ? [] : FLIGHT_BROWSER_DEPENDENCIES),
+            // The accessibility audit's engine, when this project has one.
+            //
+            // Named up front rather than left to be discovered. axe-core is
+            // CommonJS, and the only thing that imports it is a *virtual*
+            // module reached from the document — so Vite would meet it for the
+            // first time after a page had already loaded, optimise it then, and
+            // reload the page it had just served. A full reload in the middle
+            // of the first render of every `uf dev` session is a high price for
+            // a feature whose whole manner is to be quiet.
+            ...(auditsPage ? ["axe-core"] : []),
           ],
           // uf's packages ship Flow. The dependency optimiser pre-bundles
           // with a JavaScript parser and would reject every one of them.
@@ -220,12 +490,30 @@ function flowPlugin({ routerRoot, appEntry, command }) {
           // externalised.
           noExternal: [/^@uniflowed\//],
         },
+        // The graph React Server Components render in, beside the two Vite
+        // always has — declared only for an application that renders them, so
+        // `app.rsc: false` is a Vite configuration with nothing added.
+        ...(flightState == null
+          ? {}
+          : {
+              environments: {
+                [RSC_ENVIRONMENT]: rscEnvironment({
+                  root: projectRoot,
+                  production: env.command === "build",
+                  exclude: uniflowedPackages(projectRoot),
+                }),
+              },
+            }),
       };
     },
 
     configResolved(config) {
       root = config.root;
       base = config.base;
+      if (flightState != null) {
+        flightState.root = config.root;
+        flightState.base = config.base;
+      }
       appRoot = path.resolve(root, routerRoot);
       entryPath = path.resolve(root, appEntry);
     },
@@ -234,8 +522,43 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       ensureService();
     },
 
-    resolveId(id) {
+    resolveId(id, importer, resolveOptions) {
+      // The client's graph, and the rsc graph too. `@uniflowed/react` is
+      // `export * from "react"`, and the rsc graph pre-bundles React's CommonJS
+      // under `react-server`: a star re-export of that namespace names nothing
+      // Vite's module runner can forward, so under `uf dev` every hook a server
+      // component imported from `@uniflowed/react` was `undefined` — `use` first.
+      // Importing `react` itself is the module those names are on. The ssr graph
+      // keeps its own resolution, because React is external there and Node's
+      // interop forwards the names.
+      if (
+        id === "@uniflowed/react" &&
+        (this.environment?.name === RSC_ENVIRONMENT || !isSsr(this, resolveOptions))
+      ) {
+        return this.resolve("react", importer, { ...resolveOptions, skipSelf: true });
+      }
       if (id === RUNTIME_PUBLIC_PATH) return RUNTIME_RESOLVED_ID;
+      if (id === AUDIT_PUBLIC_PATH) return AUDIT_RESOLVED_ID;
+      // The rsc build cannot know a client chunk's URL, because the client
+      // build that writes the chunks runs after it. It leaves the manifest as an
+      // import, and the ssr build — which bundles the rsc output in — resolves it.
+      if (
+        id === FLIGHT_VIRTUAL.manifest &&
+        flightState?.production === true &&
+        this.environment?.name === RSC_ENVIRONMENT
+      ) {
+        return { id, external: true };
+      }
+      // The React Compiler's runtime, which reads the client's internals and so
+      // cannot run where `react` resolved under `react-server`; see
+      // `compilerRuntimeSource`.
+      if (
+        id === "react/compiler-runtime" &&
+        flightState != null &&
+        this.environment?.name === RSC_ENVIRONMENT
+      ) {
+        return resolved(FLIGHT_VIRTUAL.compilerRuntime);
+      }
       if (VIRTUAL_IDS.has(id)) return resolved(id);
       // A module's own stylesheet, which `transform` below asked for by
       // importing this id. Returning it unchanged marks it resolved without
@@ -246,23 +569,153 @@ function flowPlugin({ routerRoot, appEntry, command }) {
 
     load(id, loadOptions) {
       if (id === RUNTIME_RESOLVED_ID) return refreshRuntimeSource();
+      if (id === AUDIT_RESOLVED_ID) return auditRuntimeSource(accessibility?.axe);
       if (id === resolved(VIRTUAL.routes)) {
-        const table = scanRoutes(appRoot);
+        const table = scanRoutes(appRoot, { target: routeTarget });
+        // Under React Server Components the table is split by graph rather than
+        // filtered. The rsc graph renders routes, so it gets every route and
+        // boundary and no handler or middleware: those answer a request, and
+        // importing one here would resolve its dependencies under
+        // `react-server` for nothing. The ssr graph gets exactly those two,
+        // because every route it renders reaches it as a payload.
+        if (flightState != null && this.environment?.name === RSC_ENVIRONMENT) {
+          return routesModuleSource({ ...table, handlers: [], middleware: [] });
+        }
+        if (flightState != null && isSsr(this, loadOptions)) {
+          return routesModuleSource({ ...table, routes: [], notFound: [], errors: [] });
+        }
         // 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);
+      // Strict Mode belongs to the client entry and to development only: a
+      // build passes `false`, so the generated module is the one that existed
+      // before #516 and a visitor's browser renders once.
+      //
+      // `navigation` is in the same entry and has no `isProduction` beside it,
+      // deliberately: it is what a link does, and a dev server whose links
+      // behave differently from the deployment is the wrong thing to be
+      // looking at. See `clientModuleSource`.
+      if (id === resolved(VIRTUAL.client) && flightState != null) {
+        return flightClientSource(entryPath, {
+          instrumentation: instrumentationFile(appRoot, true),
+          strictMode: strictMode && !isProduction,
+          navigation,
+          staleTime,
+          routing,
+        });
+      }
+      if (id === resolved(VIRTUAL.client)) {
+        return clientModuleSource(entryPath, {
+          instrumentation: instrumentationFile(appRoot, true),
+          strictMode: strictMode && !isProduction,
+          navigation,
+          staleTime,
+          mount,
+          routing,
+        });
+      }
+      if (id === resolved(VIRTUAL.server)) {
+        return flightState == null
+          ? serverModuleSource(entryPath, routing, instrumentationFile(appRoot))
+          : flightServerSource(
+              entryPath,
+              VIRTUAL.routes,
+              VIRTUAL.actions,
+              routing,
+              instrumentationFile(appRoot),
+            );
+      }
+      if (flightState != null) {
+        if (id === resolved(FLIGHT_VIRTUAL.entry))
+          return rscEntrySource(VIRTUAL.routes, routing, flightState.deployment);
+        if (id === resolved(FLIGHT_VIRTUAL.compilerRuntime)) return compilerRuntimeSource();
+        if (id === resolved(FLIGHT_VIRTUAL.bridge)) {
+          if (server != null) return devBridgeSource();
+          if (flightState.rscOutput == null) {
+            throw new Error(
+              "uf: the server bundle was asked to bundle the rsc graph before it was built. " +
+                "`uf build` builds `virtual:uf/rsc` first; a build started some other way has to as well.",
+            );
+          }
+          return builtBridgeSource(flightState.rscOutput);
+        }
+        if (id === resolved(FLIGHT_VIRTUAL.manifest)) {
+          return clientManifestSource(flightState.chunkUrls);
+        }
+        if (id === resolved(FLIGHT_VIRTUAL.references)) {
+          return server != null
+            ? devReferencesSource(root, base)
+            : builtReferencesSource(flightState.chunkUrls);
+        }
+      }
+      // Only `virtual:uf/server` imports this, so it is only ever asked for in
+      // the server environment — but the table it carries is every callable
+      // endpoint of the build, so it is worth saying that a browser asking for
+      // it gets nothing rather than getting the list.
+      if (id === resolved(VIRTUAL.actions)) {
+        if (!isSsr(this, loadOptions))
+          return "export const actions = [];\nexport default actions;\n";
+        return actionsModuleSource(actionTables().table);
+      }
       if (id.startsWith(STYLE_PREFIX)) return styles.get(id) ?? "";
+
+      // A `"use server"` module, in the browser's graph only: what the client
+      // gets is one `createServerReference` per callable export, and never the
+      // file. This is where the second half of the RSC split actually happens
+      // — the route filter above decides which *pages* the browser is given,
+      // and this decides that an action module's body, its imports and
+      // everything only they reached are not the browser's business at all.
+      //
+      // Substituting the source rather than rewriting it: a transform that
+      // stripped the body would have to be right about every way a module can
+      // name something, and being wrong once means shipping a database handle.
+      // The exports the reference module declares come from the manifest, so
+      // they are exactly the exports `uf_rsc` decided are callable endpoints
+      // and an import of anything else is a build error rather than a silent
+      // `undefined`. `crates/uf_rsc/src/graph/build.rs` colours these modules
+      // server for the same reason, so the analysis and the bundle agree.
+      //
+      // Nor in the rsc graph: a server component that calls an action is calling
+      // a function on the server, and it gets the function.
+      if (!isSsr(this, loadOptions) && this.environment?.name !== RSC_ENVIRONMENT) {
+        const references = actionTables().modules.get(cleanId(id));
+        if (references != null) return actionReferenceSource(references);
+        return null;
+      }
+      // And in the server graphs, the file itself behind a module that gives
+      // each callable export what React reads to write a form that posts before
+      // hydration. The file is imported under a query, so it is still one
+      // module; only the plain id is the wrapper. See `serverActionSource`.
+      if (!id.includes("?")) {
+        const exported = actionTables().modules.get(id);
+        if (exported != null) {
+          let source = "";
+          try {
+            source = readFileSync(id, "utf8");
+          } catch {
+            return null;
+          }
+          return serverActionSource(id, exported, declaresDefaultExport(source));
+        }
+      }
       return null;
     },
 
     async transform(code, id, transformOptions) {
-      if (!isFlowModule(id)) return null;
-      const ssr = transformOptions?.ssr === true || this.environment?.name === "ssr";
+      // A view of a barrel's namespace has the barrel's path and none of its
+      // source: `uf:barrel-imports` generates it as JavaScript.
+      if (!isFlowModule(id) || namespaceViewOf(id) != null) return null;
+      // What an earlier pass of this build wrote under `.uf/build/` — the ssr
+      // pass imports the rsc graph's bundle — is already this transform's
+      // output. See `isCompiledOutput`.
+      if (isCompiledOutput(id)) return null;
+      // Both server graphs: neither gets a refresh wrapper, and the rsc graph's
+      // findings are reported as that graph's.
+      const rsc = this.environment?.name === RSC_ENVIRONMENT;
+      const ssr = transformOptions?.ssr === true || this.environment?.name === "ssr" || rsc;
       const refresh = !isProduction && !ssr && server != null;
       const out = await ensureService().transform(cleanId(id), code, {
         development: !isProduction,
@@ -274,11 +727,20 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         id: cleanId(id),
         root,
         diagnostics: out.diagnostics,
-        environment: ssr ? "ssr" : "client",
+        environment: rsc ? RSC_ENVIRONMENT : ssr ? "ssr" : "client",
         reported,
         suppressed,
       });
-      const map = out.map == null ? null : JSON.parse(out.map);
+      let map = out.map == null ? null : JSON.parse(out.map);
+      let output = out.code;
+      if (relayEnabled && output.includes("graphql")) {
+        relayOptions ??= relayConfig(root);
+        const transformed = await transformRelay(output, cleanId(id), map, await relayOptions);
+        if (transformed != null) {
+          output = transformed.code;
+          map = transformed.map;
+        }
+      }
       // StyleX. `uf transform` compiled the module's `stylex.create` calls into
       // class names and handed back the rules they declared; the rules become a
       // module of their own that this one imports.
@@ -288,10 +750,16 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       // business: Vite already injects a stylesheet in dev, extracts it in a
       // build, code-splits it per chunk, and replaces it over HMR. A module
       // whose styles are gone stops importing it, and Vite notices.
+      //
+      // The stylesheet is named by the module's path from the project root, the
+      // spelling `moduleId` gives the module graph report, and not by its
+      // absolute path. In a client chunk the stylesheet is one of the chunk's
+      // sources, so its name is written into the source map a site publishes,
+      // and an absolute name would publish where the machine that built it
+      // keeps its files. A module outside the root climbs out with `../`.
       const styled = out.css != null && out.css !== "";
-      let output = out.code;
       if (styled) {
-        const styleId = `${STYLE_PREFIX}${cleanId(id)}.css`;
+        const styleId = `${STYLE_PREFIX}${moduleId(root, cleanId(id))}.css`;
         styles.set(styleId, out.css);
         output = `import ${JSON.stringify(styleId)};\n${output}`;
       }
@@ -316,33 +784,129 @@ function flowPlugin({ routerRoot, appEntry, command }) {
     buildEnd() {
       summariseSuppressed(this, suppressed);
       suppressed = [];
-      // A dev server keeps its service for the whole session; a build is
-      // done with it here.
-      if (server == null) {
+      // A dev server keeps its service for the whole session. A build is done
+      // with it here, unless the caller runs more builds with these plugins:
+      // `uf build`'s passes — the rsc graph, the client, the server — go over
+      // largely the same modules with the same options, and `uf transform`
+      // answers a request it has already answered from memory. A service per
+      // pass compiled `@uniflowed/router` and every shared module three times.
+      // An idle service does not hold the host open (see `TransformService`),
+      // and its child sees stdin close when the host exits.
+      if (server == null && !shareTransformAcrossBuilds) {
         service?.close();
         service = null;
       }
     },
 
+    // The two scripts a development document loads before its own, and
+    // nothing at all in a build — which is the whole of "the hook is out of a
+    // production build" (ubugeeei-prod/uf#503) and of "production does not run
+    // under Strict Mode" (#516, whose flag is generated into
+    // `virtual:uf/client` rather than injected here).
+    //
+    // DevTools first, and as a *classic* script rather than a module: React
+    // registers itself with `__REACT_DEVTOOLS_GLOBAL_HOOK__` while `react-dom`
+    // is evaluated and never again, so the hook has to exist before any module
+    // runs. A classic inline script runs while the parser is on it; a module
+    // waits for the document. `internal/devtools.js` has the rest of the
+    // argument, and the three conditions DevTools needs.
     transformIndexHtml() {
       if (isProduction) return [];
-      return [
+      const tags = [
         {
           tag: "script",
-          attrs: { type: "module" },
+          attrs: { "data-uf-dev-head-preamble": "react-devtools" },
+          children: devtoolsPreamble(),
+          injectTo: "head-prepend",
+        },
+        {
+          tag: "script",
+          attrs: { type: "module", "data-uf-dev-head-preamble": "react-refresh" },
           children: preambleCode(base),
           injectTo: "head-prepend",
         },
       ];
+      // Only when the project has the engine. A tag pointing at a module that
+      // cannot resolve `axe-core` would be a red console on every page of a
+      // project that never asked for an audit, which is a worse default than
+      // no audit.
+      const audit = auditTag(base, auditsPage);
+      if (audit != null) tags.push(audit);
+      return tags;
+    },
+
+    // An edit to a server component changes what the rsc graph renders and no
+    // module the browser holds, so Vite has nothing to tell the browser. It is
+    // reloaded, which renders the edit; an edit to a client module — which the
+    // rsc graph only holds references to — is left to Fast Refresh.
+    hotUpdate({ modules }) {
+      if (flightState == null || server == null) return;
+      if (this.environment?.name !== RSC_ENVIRONMENT) return;
+      const serverSide = modules.some((module) => {
+        const file = module.file ?? cleanId(module.id ?? "");
+        return file !== "" && !flightState.clientModules.has(file);
+      });
+      if (serverSide) server.environments.client.hot.send({ type: "full-reload", path: "*" });
     },
 
     configureServer(devServer) {
       server = devServer;
+      const diagnostics = startDevState(root, () => ({
+        routes: scanRoutes(appRoot, { target: routeTarget }).routes.map((route) => ({
+          path: route.path,
+          page: route.page,
+          layouts: route.layouts,
+        })),
+        actions: actionTables().table,
+      }));
+      devServer.middlewares.use(diagnostics.middleware);
+      devServer.httpServer?.once("close", diagnostics.close);
+      // The ssr graph's way into the rsc graph; see `devBridgeSource`.
+      if (flightState != null) {
+        globalThis[Symbol.for(DEV_RSC_HOOK)] = () =>
+          devServer.environments[RSC_ENVIRONMENT].runner.import(FLIGHT_VIRTUAL.entry);
+      }
       devServer.httpServer?.once("close", () => {
         service?.close();
         service = null;
       });
 
+      // `app.router.headers` and `redirects`, in front of Vite's own middleware
+      // — the hook's body runs before those are installed — so a redirect
+      // answers before `public/` is looked in and a header reaches a file Vite
+      // serves, as both do in front of the static half of every other door.
+      // Vite's module server is left alone: `/@vite/client` and `/@fs/…` are
+      // development plumbing no deployment has, and `/__uf/` is the browser's
+      // channel back. Not mounted at all for a project with neither list.
+      if (answersInFrontOfFiles(routing)) {
+        devServer.middlewares.use((request, response, next) => {
+          const url = request.url ?? "/";
+          // Vite serves its own paths under the base path too, so they are
+          // recognised once it is taken off.
+          const under =
+            routing.basePath !== "" && url.startsWith(`${routing.basePath}/`)
+              ? url.slice(routing.basePath.length)
+              : url;
+          if (
+            under.startsWith("/@") ||
+            under.startsWith("/node_modules/") ||
+            under.startsWith("/__uf/")
+          ) {
+            next();
+            return;
+          }
+          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 reserved file appearing or disappearing changes the route table,
       // which lives in a virtual module the watcher knows nothing about.
       //
@@ -352,14 +916,15 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       // missing `route` — so adding a route handler to a running dev server
       // did not rebuild the table and the handler stayed invisible until a
       // restart. A list that has to match another list has to be that list.
-      const stems = Object.values(RESERVED)
-        .map((stem) => stem.replaceAll(".", "\\."))
-        .join("|");
+      const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const stems = Object.values(RESERVED).map(escapeRegExp).join("|");
       const reserved = new RegExp(`/(${stems})(\\.[a-z]+)?\\.(js|jsx|mdx)$`);
       const onRouteFile = (file) => {
         if (!reserved.test(file) || !file.startsWith(appRoot)) return;
-        const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
-        if (routes) devServer.moduleGraph.invalidateModule(routes);
+        for (const id of [VIRTUAL.routes, VIRTUAL.server, VIRTUAL.client]) {
+          const module = devServer.moduleGraph.getModuleById(resolved(id));
+          if (module) devServer.moduleGraph.invalidateModule(module);
+        }
         devServer.ws.send({ type: "full-reload", path: "*" });
       };
       devServer.watcher.on("add", onRouteFile);
@@ -378,8 +943,19 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         devServer.watcher.add(manifestPath);
         const onManifest = (file) => {
           if (path.resolve(file) !== manifestPath) return;
+          const previousActions = actionTables().modules;
+          // The action tables are read from the same file and are memoised on
+          // its size and modification time, which is a pair two writes inside
+          // one millisecond can share. This is the answer that does not
+          // depend on a clock.
+          forgetActions();
+          const nextActions = actionTables().modules;
+          invalidateActionModules(devServer.moduleGraph, previousActions);
+          invalidateActionModules(devServer.moduleGraph, nextActions);
           const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
           if (routes) devServer.moduleGraph.invalidateModule(routes);
+          const actions = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.actions));
+          if (actions) devServer.moduleGraph.invalidateModule(actions);
           devServer.ws.send({ type: "full-reload", path: "*" });
         };
         devServer.watcher.on("add", onManifest);
@@ -387,75 +963,332 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       }
 
       // After Vite's own middlewares, so `/@vite/client`, `/@id/...` and
-      // static files are served first and only a document request reaches
-      // the renderer.
+      // static files are served first and only what Vite declined reaches uf.
+      //
+      // # One renderer
+      //
+      // This is the only middleware that renders a document under `uf dev`,
+      // and that is worth stating because there were two. `driver.js` added a
+      // second one after `createServer` had returned, which put it *later* in
+      // the connect stack than this one — so for every request this one
+      // claimed, this one decided, and the other was reached only for what
+      // this one declined. Route-handler dispatch was in the other. A
+      // `GET /feed` from a browser is `Accept: text/html` with no extension,
+      // so it looked like a document, so `app/feed/$route.js` was never
+      // asked and the reader got the route table's page — or the not-found
+      // page — for a path that had a handler. See ubugeeei-prod/uf#349.
+      //
+      // Two renderers is also how the two came to disagree about the render
+      // result's `headers`: this one wrote them and the driver's did not, so a
+      // loader calling `redirect()` answered a browser with a `307` carrying
+      // no `Location` and a meta-refresh body — a redirect that works when you
+      // deploy it and not while you are writing it. See
+      // ubugeeei-prod/uf#338.
+      //
+      // So the driver's middleware is gone and everything it did is here: it
+      // claims every request, runs the guard, the action endpoint and the
+      // dispatcher for every method, and hands back to Vite's chain what none
+      // of them answered.
+      //
+      // # What is still not `createFetchHandler`
+      //
+      // One middleware rather than two, and still not the function every
+      // deployment runs. It cannot be: `transformIndexHtml` takes a whole
+      // document, so the render has to be collected here rather than streamed
+      // (ubugeeei-prod/uf#374), and a request nothing claimed has to go back
+      // to Vite's chain rather than become a 404 — neither of which a handler
+      // that always answers with a `Response` can do.
+      //
+      // What that still costs, written down so the next reader does not have
+      // to find it: `createFetchHandler` renders inside a cache scope even
+      // with no cache configured, so a component calling `cacheLife` states a
+      // lifetime nobody honours; here there is no scope, so the same component
+      // throws under `uf dev` and renders under `uf start`. Closing that means
+      // the generated server entry handing the host a scope the way it already
+      // hands it `beginRequest` — see `serverModuleSource` in
+      // `./internal/routes.js` — and it is the next thing to remove from this
+      // list rather than something this middleware can decide on its own.
       return () => {
+        // The browser's own reporting channel, mounted above the application
+        // so that a report never reaches a project's `$middleware.js` or
+        // its route table. See `internal/diagnostics.js`.
+        devServer.middlewares.use(
+          createChannelMiddleware((diagnostic) => emit("diagnostic", diagnostic)),
+        );
+
         devServer.middlewares.use(async (request, response, next) => {
-          if (!wantsDocument(request)) return next();
+          // `request.url` and not `originalUrl`, which is the URL Vite's base
+          // middleware has already stripped the base from — and the route
+          // table's paths have no base in them either.
+          //
+          // `let`, because a rewrite moves it: from here on it is the address
+          // the application answers for, which is what the render, the payload
+          // and the document test below all have to agree on.
+          let url = request.url ?? "/";
+          // Declared out here so the catch below can still settle: a request
+          // that failed is a request that happened, and a middleware that
+          // logged its arrival is owed its callback either way.
+          let lifecycle = null;
           try {
-            const url = request.url ?? "/";
             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 requests that look like a document 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 anything answers: 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. `driver.js` makes the same call, for
-              // every method.
+            // At `request.url`, which Vite's base middleware has already taken
+            // `app.router.basePath` off: the application path, as every other
+            // front door hands the application once it has admitted a request.
+            const arrived = await toRequest(request, devServer.config, url);
+            // `app.router.rewrites`, where `createFetchHandler` applies them for
+            // every other door: after the files Vite already served, before the
+            // guard — so the guard that runs is the destination's.
+            let asRequest = (await rewriteRouting(entry.routing, arrived)) ?? arrived;
+            if (asRequest !== arrived) url = addressOf(asRequest);
+
+            // The request begins here and ends when the response has been
+            // written, which is what `after()` promises and what `uf preview`,
+            // `uf start` and a compiled binary all do too — a middleware that
+            // logs a response's status has to mean the same thing in
+            // development as in production. See `internal/serve.js` and
+            // ubugeeei-prod/uf#389.
+            lifecycle = await beginRequest(entry, arrived);
+            const answered = await lifecycle.run(async () => {
+              // Before anything answers: a middleware guards a subtree, so it
+              // has to run for a page, for a route handler, and for a path
+              // under it that matches neither. Running it inside the
+              // dispatcher and again inside the renderer would have left
+              // `/dashboard/typo` unguarded and run it twice for a path that
+              // is both. See ubugeeei-prod/uf#260.
+              //
+              // A `Request` back is a middleware's `rewrite()`, already past
+              // the destination's own middleware.
               const guarded = await entry.runMiddleware(asRequest);
-              if (guarded != null) {
+              if (guarded instanceof Request) {
+                asRequest = guarded;
+                url = addressOf(guarded);
+              } else if (guarded != null) {
                 await send(response, guarded);
-                return;
+                return true;
               }
 
-              // Then the route handlers, above the renderer and for the same
-              // reason `driver.js` puts them there: a path that answers a
-              // request is not a document, whatever the client said it would
-              // accept. `curl /api/thing` and a `<form action>` navigation both
-              // send `Accept: text/html`, and both want the handler's answer.
+              // Then a server action, below the guard and above the handlers.
+              // It declines every request that carries no action id, so this
+              // costs an ordinary request one `headers.get`; and it answers
+              // every request that carries one, refusals included, so an
+              // action can never fall through to a route handler that happens
+              // to sit at the URL it was posted to. The same two lines are in
+              // `@uniflowed/server`'s `fetch.js`, which is what every
+              // deployment runs.
               //
-              // This step is not a duplicate of the dispatcher in `driver.js`,
-              // it is the only one that can run: this middleware is mounted by
-              // `configureServer`, which Vite calls while it is building the
-              // server, and `uf dev` adds its own after `createServer` has
-              // returned — so for every request this one claims, it is the one
-              // that decides. Without it a route handler under `uf dev` was
-              // reachable only by a client that asked for something other than
-              // HTML, and answered the 404 page to everyone else.
+              // A form posted before its page hydrated is answered with the
+              // page, rendered with the action's result as the submitting
+              // `useActionState`'s state — the render below, given `formState`.
+              const acted = await entry.callAction(asRequest, {
+                postback: async (formState) => {
+                  const result = await entry.render(
+                    url,
+                    { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
+                    {
+                      onError: (error) => reportRenderError(devServer, url, error),
+                      transformHead: (head) =>
+                        devServer.transformIndexHtml(
+                          url,
+                          flightState == null
+                            ? head
+                            : linkStylesheets(head, devStylesheets(devServer)),
+                        ),
+                      formState,
+                    },
+                  );
+                  if (result.error != null) reportRenderError(devServer, url, result.error);
+                  return new Response(result.stream(), {
+                    status: result.status ?? 200,
+                    headers: { ...result.headers, "content-type": "text/html; charset=utf-8" },
+                  });
+                },
+              });
+              if (acted != null) {
+                await send(response, acted);
+                return true;
+              }
+
+              // Then the route handlers, above the renderer and for every
+              // method: a path that answers a request is not a document,
+              // whatever the client said it would accept. `curl /api/thing`
+              // and a `<form action>` navigation both send `Accept:
+              // text/html`, and both want the handler's answer — which is the
+              // whole of ubugeeei-prod/uf#349.
+              // A browser that is navigating, asking for the next route's
+              // payload: after the guard and before the handlers, for the
+              // reasons `@uniflowed/server`'s `internal/flight.js` gives.
+              const payloadFor =
+                entry.flight == null ? null : flightDocumentPath(url.split("?")[0]);
+              if (payloadFor != null && (request.method === "GET" || request.method === "HEAD")) {
+                const query = url.includes("?") ? url.slice(url.indexOf("?")) : "";
+                const target = payloadFor + query;
+                // Read off the request the guard handed back, never off the
+                // one Node received: the middleware runner takes this header
+                // off when the page it names is one the guards of that page
+                // would not serve, and reading the original would render it
+                // anyway. See "A payload that renders over another page" in
+                // `@uniflowed/router/middleware`.
+                const interceptedFrom = asRequest.headers.get(INTERCEPTED_FROM_HEADER) ?? undefined;
+                const answered = await entry.flight(target, {
+                  onError: (error) => reportRenderError(devServer, target, error),
+                  interceptedFrom,
+                });
+                if (answered.error != null) reportRenderError(devServer, target, answered.error);
+                if (request.method === "HEAD") await answered.stream?.cancel();
+                await send(
+                  response,
+                  new Response(request.method === "HEAD" ? null : answered.stream, {
+                    status: answered.status,
+                    headers: answered.headers,
+                  }),
+                );
+                return true;
+              }
+
               const handled = await entry.dispatch(asRequest);
               if (handled != null) {
                 await send(response, handled);
-                return;
+                return true;
+              }
+
+              // Only a navigation reaches the renderer. A page cannot answer a
+              // `POST`, and letting one try would turn a missing handler into
+              // a rendered page with a 200 rather than a 404.
+              //
+              // `notADocumentBecause` is stricter than the production handler, which
+              // renders anything a static file did not answer, and the
+              // difference is Vite's chain: `/@id/…`, `/node_modules/…` and
+              // any path with an extension belong to the module server, and a
+              // request one of those declined has to go back to it rather than
+              // become a rendered 404 page. What it costs is that
+              // `/favicon.svg` on a project that has none is a bare 404 here
+              // and the project's own not-found *page* under `uf preview` and
+              // `uf start` — a difference in the body of a 404 for a path that
+              // is an asset request in the first place.
+              const notDocument = notADocumentBecause(request, url);
+              if (notDocument === "accept") {
+                // Everything about this is a navigation except the header, and
+                // the path is one uf renders. Say so, rather than letting the
+                // chain below answer `Cannot GET /` in somebody else's words.
+                documentNeedsHtml(request, response);
+                return true;
+              }
+              if (notDocument != null) return false;
+
+              // A single-page project's deployment answers every navigation
+              // with the same empty shell, so this does too. Rendering the
+              // route here instead would have been the better-looking dev
+              // server and the wrong one: a page that only works because the
+              // server rendered it would work all through development and be
+              // blank the day it shipped. It is the same argument
+              // `app.rendering.navigation` makes about a link, one level up.
+              //
+              // The three steps above still ran — the guard, the action, the
+              // handler — and each of them is something `uf build` refuses in
+              // a `["csr"]` project by name. A dev server that skipped them
+              // would hide the very thing the build is going to stop.
+              if (mount === "render") {
+                response.statusCode = 200;
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                const shell = entry.shellDocument({
+                  scripts: [devUrlFor(VIRTUAL.client)],
+                  styles: [],
+                  preloads: [],
+                });
+                response.end(await devServer.transformIndexHtml(url, shell));
+                return true;
               }
 
               const result = await entry.render(
                 url,
                 { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
-                { onError: (error) => reportRenderError(devServer, url, error) },
+                {
+                  // A boundary that threw after the shell went out.
+                  // `result.error` cannot carry it — the caller already has the
+                  // result by then — so the terminal hears about it here or not
+                  // at all.
+                  onError: (error) => reportRenderError(devServer, url, error),
+                  // Vite sees the head and only the head. That is what lets the
+                  // development server stream like every other host — see below.
+                  //
+                  // Under React Server Components it is also where a server
+                  // component's stylesheets are linked in development: they are
+                  // in the rsc graph, which the browser never loads, and they
+                  // enter it when the route's modules are imported — after this
+                  // call and before the head is written, which is when this
+                  // runs. See `devStylesheets`.
+                  transformHead: (head) =>
+                    devServer.transformIndexHtml(
+                      url,
+                      flightState == null ? head : linkStylesheets(head, devStylesheets(devServer)),
+                    ),
+                  // And what the streaming actually did, when it changed. The
+                  // router has already decided there is something worth saying
+                  // and written the words — see its `internal/inspector.js`,
+                  // which cannot be imported from here because this file is
+                  // plain JavaScript that Vite loads before any Flow transform
+                  // exists. `info`, because a page that streamed is a
+                  // measurement and not a problem; `origin`, because a report
+                  // that does not say which page produced it is one somebody
+                  // has to reproduce before they can act on it.
+                  onStream: (diagnostic) =>
+                    emit("diagnostic", {
+                      severity: "info",
+                      origin: url,
+                      message: diagnostic.message,
+                      detail: diagnostic.detail,
+                    }),
+                },
               );
               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");
+              // Piped, like every other host. This used to collect the whole
+              // document and transform it at the end, because
+              // `transformIndexHtml` is a *whole document* hook — which made the
+              // one place a developer would notice streaming the one place it
+              // did not happen: a slow page showed nothing until it was finished
+              // and `$loading.js` looked broken.
+              //
+              // `transformHead` above is the seam. `internal/stream.js` already
+              // held the opening chunk back until the head was complete and
+              // forwarded everything after it untouched, so the hook only ever
+              // sees the head — and Vite's dev hook handles a document that ends
+              // mid-`<body>` without complaint, which was the open question on
+              // ubugeeei-prod/uf#374.
+              response.statusCode = result.status ?? 200;
+              // The render's own headers, then the content type over the top:
+              // exactly the order `@uniflowed/server`'s `fetch.js` writes them
+              // in, so a `Location` from `redirect()` survives here and a
+              // render cannot claim to be something other than a document.
               for (const [name, value] of Object.entries(result.headers ?? {})) {
                 response.setHeader(name, value);
               }
-              response.end(html);
+              response.setHeader("content-type", "text/html; charset=utf-8");
+              await result.pipe(response);
+              return true;
             });
+
+            if (!answered) {
+              // The one path where uf is not the one writing the response: a
+              // request nothing claimed goes back to Vite's chain. The guard
+              // has still run and may have deferred work, so `close` — the
+              // socket saying the response is over, however it ended — is the
+              // only honest signal left that the bytes are out.
+              response.once("close", lifecycle.settle);
+              next();
+              return;
+            }
+            await lifecycle.settle();
           } catch (error) {
-            devServer.ssrFixStacktrace(error);
+            if (lifecycle != null) await lifecycle.settle();
+            // Map the stack back onto the Flow source before it reaches the
+            // overlay.
+            if (error instanceof Error) devServer.ssrFixStacktrace(error);
+            emit("diagnostic", {
+              severity: "error",
+              kind: "runtime",
+              origin: url,
+              ...errorEvent(error),
+            });
             next(error);
           }
         });
@@ -478,11 +1311,7 @@ function mdxPlugin(markdown) {
     enforce: "pre",
     ...mdx({
       jsxImportSource: "react",
-      remarkPlugins: [
-        remarkGfm,
-        remarkFrontmatter,
-        [remarkMdxFrontmatter, { name: "frontmatter" }],
-      ],
+      remarkPlugins: [remarkGfm, remarkFrontmatter, remarkFrontmatterExport],
       rehypePlugins,
     }),
     name: "uf:mdx",
@@ -507,16 +1336,75 @@ async function importServerEntry(devServer) {
   return devServer.ssrLoadModule(VIRTUAL.server);
 }
 
-function wantsDocument(request) {
-  if (request.method !== "GET" && request.method !== "HEAD") return false;
-  const url = request.url ?? "/";
-  if (url.startsWith("/@") || url.startsWith("/node_modules/")) return false;
-  const accept = request.headers.accept ?? "";
-  if (!accept.includes("text/html")) return false;
+/**
+ * The path and query a `Request` is for, which is what the dev server's
+ * renderer and payload test are keyed on.
+ *
+ * @param {Request} request
+ */
+function addressOf(request) {
+  const url = new URL(request.url);
+  return url.pathname + url.search;
+}
+
+/**
+ * Why `request` is not a document request, or `null` when it is one.
+ *
+ * `url` is the address the application answers for, which a rewrite may have
+ * moved away from the one the request line named.
+ *
+ * A reason rather than a boolean because one of the four is worth saying out
+ * loud. Three of them mean the request belongs to somebody else — Vite's module
+ * server, a static file, or a method a page cannot answer — and handing it back
+ * is the whole point. The fourth means the client asked for a page uf would
+ * have rendered and did not say it accepts HTML, and `curl` is the client that
+ * does that. See ubugeeei-prod/uf#675.
+ *
+ * The extension test moved above the `accept` test so the two cannot be
+ * confused: `/favicon.svg` with `Accept: *\/*` is an asset, not a navigation
+ * with the wrong header, and still goes back to Vite's chain untouched.
+ */
+function notADocumentBecause(request, url = request.url ?? "/") {
+  if (request.method !== "GET" && request.method !== "HEAD") return "method";
+  if (url.startsWith("/@") || url.startsWith("/node_modules/")) return "module-server";
   const pathname = url.split("?")[0];
   // A request for a file — `/favicon.svg`, `/assets/x.js` — that no static
   // middleware answered is a 404, not a page.
-  return !/\.[a-z0-9]+$/i.test(pathname);
+  if (/\.[a-z0-9]+$/i.test(pathname)) return "asset";
+  const accept = request.headers.accept ?? "";
+  if (!accept.includes("text/html")) return "accept";
+  return null;
+}
+
+/**
+ * The 404 for a navigation that did not ask for HTML.
+ *
+ * uf's own words rather than the framework underneath saying `Cannot GET /` in
+ * its: the path is one uf would have rendered, and the only thing that stopped
+ * it is a header the reader cannot see from the terminal. Development only —
+ * this middleware is the dev server — and `uf preview` and `uf start` answer a
+ * 404 with nothing in it, as `docs/security.md` requires.
+ *
+ * The client's `Accept` is quoted back, so it is treated the way every other
+ * piece of foreign text here is treated: control characters removed and the
+ * length capped. A header is not a thing a terminal should be asked to run.
+ * See ubugeeei-prod/uf#649.
+ */
+function documentNeedsHtml(request, response) {
+  const accept = String(request.headers.accept ?? "")
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .slice(0, 80);
+  const path = String(request.url ?? "/").slice(0, 200);
+  const body =
+    `404  ${request.method} ${path}\n\n` +
+    "This path is a page, and a page is rendered for a request that accepts\n" +
+    `HTML. This request sent \`Accept: ${accept || "(none)"}\`.\n\n` +
+    `    curl -H 'Accept: text/html' http://${request.headers.host ?? "localhost"}${path}\n\n` +
+    "A browser sends it; `curl` does not. Nothing is wrong with the route.\n";
+  response.statusCode = 404;
+  response.setHeader("content-type", "text/plain; charset=utf-8");
+  response.end(body);
 }
 
 /** The name of the environment variable that turns every finding back on. */
@@ -526,14 +1414,25 @@ const ALL_DIAGNOSTICS = "UF_REACT_COMPILER_DIAGNOSTICS";
  * Report what the React Compiler said about one module.
  *
  * Every finding used to be printed as `a function: <message>` — no file, no
- * line, no column, and the fallback string doing all the work because the
- * compiler names an inner function about as often as not. The transform hook
+ * line, no column, and the fallback string doing all the work, because
+ * `diagnostic.function` was read out of a field only a *success* event carries
+ * and so was null for every finding there has ever been (#371), not because
+ * the compiler was reporting on anonymous inner functions. The transform hook
  * knows the module and the compiler gives a position for most findings, so
  * both go into the message: Vite prints a plugin warning's `message` and
  * nothing else, so a location that is not in the string is a location the
  * reader never sees. `id` and `loc` go along for anything reading the log
  * object rather than the line. See ubugeeei-prod/uf#307.
  *
+ * `(in Form)` is real now: `uf transform` recovers the name from the tree it
+ * compiled, and leaves it off the diagnostic when the function genuinely has
+ * no name to give.
+ *
+ * The position is real too, and is the expression the compiler objected to
+ * rather than the function containing it, so the two halves of the line say
+ * different things — `packages/hooks/dom.js:195:7: This value cannot be
+ * modified (in useLongPress)` locates the write and names the hook to look in.
+ *
  * A dependency's findings are held back. A React Compiler bailout inside
  * `@uniflowed/form` is not something the person running the build can fix, and
  * a channel carrying forty of them on every build is a channel people stop
@@ -556,9 +1455,20 @@ function reportDiagnostics(context, { id, root, diagnostics, environment, report
   const mine = isProjectModule(root, id) || process.env[ALL_DIAGNOSTICS] === "all";
   for (const diagnostic of diagnostics) {
     // Everything a reader would be shown, so two findings that would print as
-    // the same line collapse into one. The compiler reports "Cannot access refs
-    // during render" once per pass that noticed it — three times for one `ref`
-    // — and three identical lines are not three things to fix.
+    // the same line collapse into one.
+    //
+    // This used to collapse far more than that, and the note here used to say
+    // the compiler reports "Cannot access refs during render" once per pass
+    // that noticed it — three times for one `ref`. That was the wrong reading
+    // of the evidence. The position in a finding was the position of the
+    // *function* it was found in, so every finding in one function shared a
+    // line and a column and any two with the same message were, to this
+    // signature, the same finding. They were not: over this repository's own
+    // packages it collapsed 173 findings into 119 lines, and the five that
+    // became one line in `DatePickerInput` are five different reads of a ref
+    // on five different lines. `uf transform` now reports where the compiler
+    // actually objected, so the signature separates them, and what it still
+    // collapses is a genuine repeat of one site.
     const signature = `${diagnostic.kind}\0${diagnostic.line}\0${diagnostic.column}\0${diagnostic.message}`;
     if (ledger.signatures.has(signature)) continue;
     ledger.signatures.add(signature);
@@ -651,24 +1561,3 @@ function cleanId(id) {
   const at = id.indexOf("?");
   return at === -1 ? id : id.slice(0, at);
 }
-
-/**
- * Every `@uniflowed/*` package the project can resolve, for
- * `optimizeDeps.exclude`, which takes names rather than patterns.
- */
-function uniflowedPackages(root) {
-  const names = new Set();
-  let directory = root;
-  for (let depth = 0; depth < 16; depth += 1) {
-    const scope = path.join(directory, "node_modules", "@uniflowed");
-    try {
-      for (const entry of readdirSync(scope)) names.add(`@uniflowed/${entry}`);
-    } catch {
-      // no packages at this level
-    }
-    const parent = path.dirname(directory);
-    if (parent === directory) break;
-    directory = parent;
-  }
-  return [...names].sort();
-}