@uniflowed/vite 0.0.0-alpha.4 → 0.0.0-alpha.41

package/index.js

@@ -14,26 +14,58 @@
 //                 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
+//                 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
 //                 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
+//                 metric-matched fallback that stop the swap moving the page.
+//                 The import evaluates to what `Image` and `Font` need — the
+//                 intrinsic size, every emitted variant, the placeholder —
+//                 rather than to a URL string. See `internal/assets.js`.
 //
 // `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 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 { 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,
@@ -43,17 +75,85 @@ import {
   refreshRuntimeSource,
 } from "./internal/refresh.js";
 import {
+  RSC_MANIFEST_ENV,
+  actionReferenceSource,
+  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 { TransformService, 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.
@@ -76,6 +176,7 @@ 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
  */
 
@@ -87,16 +188,112 @@ 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 }), mdxPlugin(markdown)];
+  return [
+    flowPlugin({
+      routerRoot,
+      appEntry,
+      routeTarget,
+      strictMode,
+      navigation,
+      staleTime,
+      mount,
+      flightState,
+      routing,
+      command: options.command,
+      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,
+  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 = "";
@@ -104,6 +301,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.
    *
@@ -113,33 +311,153 @@ function flowPlugin({ routerRoot, appEntry, command }) {
    * hand, which is the part that goes wrong.
    */
   const styles = new Map();
+  /**
+   * The React Compiler findings already reported, so each is said once.
+   *
+   * `uf build` runs Vite twice — once for the browser bundle and once for the
+   * server one — over the same modules, so every finding was made twice and
+   * printed twice. An entry records which environment reported a module's
+   * findings first: a re-transform in *that* environment (a dev server, after
+   * an edit) clears it and reports again, and the other environment's pass over
+   * the same module stays quiet. Keying on the environment rather than on a
+   * flag is what keeps the second half true without making the first half
+   * false.
+   *
+   * @type {Map<string, { environment: string, signatures: Set<string> }>}
+   */
+  const reported = new Map();
+  /** Findings held back as a dependency's, waiting to be counted out loud. */
+  let suppressed = [];
 
   const ensureService = () => {
     service ??= new TransformService({ command, root });
     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 });
+    }
+    // `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.
@@ -151,12 +469,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);
     },
@@ -165,8 +501,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
@@ -175,18 +546,125 @@ 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.client)) return clientModuleSource(entryPath);
-      if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
+      if (id === AUDIT_RESOLVED_ID) return auditRuntimeSource(accessibility?.axe);
+      if (id === resolved(VIRTUAL.routes)) {
+        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);
+      }
+      // 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, {
+          strictMode: strictMode && !isProduction,
+          navigation,
+          staleTime,
+          routing,
+        });
+      }
+      if (id === resolved(VIRTUAL.client)) {
+        return clientModuleSource(entryPath, {
+          strictMode: strictMode && !isProduction,
+          navigation,
+          staleTime,
+          mount,
+          routing,
+        });
+      }
+      if (id === resolved(VIRTUAL.server)) {
+        return flightState == null
+          ? serverModuleSource(entryPath, routing)
+          : flightServerSource(entryPath, VIRTUAL.routes, VIRTUAL.actions, routing);
+      }
+      if (flightState != null) {
+        if (id === resolved(FLIGHT_VIRTUAL.entry)) return rscEntrySource(VIRTUAL.routes, routing);
+        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;
     },
 
     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;
+      // 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,
@@ -194,10 +672,24 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         sourceMap: true,
       });
       if (out == null) return null;
-      for (const diagnostic of out.diagnostics) {
-        this.warn?.(`${diagnostic.function ?? "a function"}: ${diagnostic.message}`);
+      reportDiagnostics(this, {
+        id: cleanId(id),
+        root,
+        diagnostics: out.diagnostics,
+        environment: rsc ? RSC_ENVIRONMENT : ssr ? "ssr" : "client",
+        reported,
+        suppressed,
+      });
+      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;
+        }
       }
-      const map = out.map == null ? null : JSON.parse(out.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.
@@ -207,18 +699,40 @@ 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.
-      let output = out.code;
-      if (out.css != null && out.css !== "") {
-        const styleId = `${STYLE_PREFIX}${cleanId(id)}.css`;
+      //
+      // 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 !== "";
+      if (styled) {
+        const styleId = `${STYLE_PREFIX}${moduleId(root, cleanId(id))}.css`;
         styles.set(styleId, out.css);
         output = `import ${JSON.stringify(styleId)};\n${output}`;
       }
-      if (!refresh) return { code: output, map };
+      // A module that compiled a stylesheet has a side effect, whatever its
+      // package says. `@uniflowed/stylex` declares `sideEffects: false` and is
+      // right about its source: `tokens.stylex.js` only exports a token set.
+      // What it exports after this transform is a token set *and* a `:root`
+      // block, and the page that imports `ufTokens` no longer names it at
+      // runtime — the compiler turned every read into the `var(--…)` it minted.
+      // So the import was unused, a side-effect-free module with no used
+      // exports was dropped, and the custom properties every one of those
+      // `var()`s resolves against went with it: rules that referred to nothing.
+      // Declaring the side effect here rather than editing the package is
+      // deliberate — the side effect is one this plugin added, so it is this
+      // plugin's to admit to. See ubugeeei-prod/uf#306.
+      const moduleSideEffects = styled ? true : undefined;
+      if (!refresh) return { code: output, map, moduleSideEffects };
       const relative = path.relative(root, cleanId(id)).split(path.sep).join("/");
-      return addRefreshWrapper(output, map, relative);
+      return { ...addRefreshWrapper(output, map, relative), moduleSideEffects };
     },
 
     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) {
@@ -227,28 +741,127 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       }
     },
 
+    // 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: { "data-uf-dev-head-preamble": "react-devtools" },
+          children: devtoolsPreamble(),
+          injectTo: "head-prepend",
+        },
         {
           tag: "script",
-          attrs: { type: "module" },
+          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;
       });
 
-      // A page or layout appearing or disappearing changes the route table,
+      // `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.
-      const reserved = /\/_uf\.(page|layout|middleware|not-found)(\.[a-z]+)?\.(js|jsx|mdx)$/;
+      //
+      // Built from `RESERVED` rather than written out. It used to be the
+      // literal `(page|layout|middleware|not-found)`, which is a fourth
+      // spelling of a grammar that already has three, and it was already
+      // 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 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));
@@ -258,29 +871,332 @@ 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 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);
+        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.
+      // 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 { render } = await importServerEntry(devServer);
-            const result = await render(url, {
-              scripts: [devUrlFor(VIRTUAL.client)],
-              styles: [],
-              preloads: [],
+            const entry = await importServerEntry(devServer);
+            // 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 instanceof Request) {
+                asRequest = guarded;
+                url = addressOf(guarded);
+              } else if (guarded != null) {
+                await send(response, guarded);
+                return true;
+              }
+
+              // 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.
+              const acted = await entry.callAction(asRequest);
+              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;
+                const fromHeader = request.headers[INTERCEPTED_FROM_HEADER];
+                const answered = await entry.flight(target, {
+                  onError: (error) => reportRenderError(devServer, target, error),
+                  interceptedFrom: Array.isArray(fromHeader) ? fromHeader[0] : fromHeader,
+                });
+                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 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: [] },
+                {
+                  // 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);
+              // 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.setHeader("content-type", "text/html; charset=utf-8");
+              await result.pipe(response);
+              return true;
             });
-            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);
+
+            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;
             }
-            response.end(html);
+            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);
           }
         });
@@ -303,11 +1219,7 @@ function mdxPlugin(markdown) {
     enforce: "pre",
     ...mdx({
       jsxImportSource: "react",
-      remarkPlugins: [
-        remarkGfm,
-        remarkFrontmatter,
-        [remarkMdxFrontmatter, { name: "frontmatter" }],
-      ],
+      remarkPlugins: [remarkGfm, remarkFrontmatter, remarkFrontmatterExport],
       rehypePlugins,
     }),
     name: "uf:mdx",
@@ -332,40 +1244,228 @@ 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;
 }
 
-function cleanId(id) {
-  const at = id.indexOf("?");
-  return at === -1 ? id : id.slice(0, at);
+/**
+ * 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. */
+const ALL_DIAGNOSTICS = "UF_REACT_COMPILER_DIAGNOSTICS";
+
 /**
- * Every `@uniflowed/*` package the project can resolve, for
- * `optimizeDeps.exclude`, which takes names rather than patterns.
+ * 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
+ * `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
+ * reading — which costs them the one finding that was theirs. They are counted
+ * and said once instead, and `UF_REACT_COMPILER_DIAGNOSTICS=all` prints every
+ * one for whoever is fixing the dependency.
  */
-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
+function reportDiagnostics(context, { id, root, diagnostics, environment, reported, suppressed }) {
+  if (diagnostics.length === 0) return;
+  // A module transformed again by the environment that first reported it has
+  // been edited; anything else is the second bundle passing over the same file.
+  const previous = reported.get(id);
+  const ledger =
+    previous != null && previous.environment !== environment
+      ? previous
+      : { environment, signatures: new Set() };
+  reported.set(id, ledger);
+
+  const file = relativeId(root, id);
+  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.
+    //
+    // 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);
+    if (!mine) {
+      suppressed.push(file);
+      continue;
     }
-    const parent = path.dirname(directory);
-    if (parent === directory) break;
-    directory = parent;
+    // Two conventions, both honoured. uf's own frames count columns from one
+    // (`uf_term::diagnostic`) and so does every editor a reader will paste
+    // `file:line:column` into; Rollup's `loc.column` counts from zero, which is
+    // what the compiler already gave us. The string gets the reader's number
+    // and the log object gets Rollup's.
+    const at = diagnostic.line == null ? "" : `:${diagnostic.line}:${(diagnostic.column ?? 0) + 1}`;
+    const who = diagnostic.function == null ? "" : ` (in ${diagnostic.function})`;
+    context.warn?.({
+      message: `${file}${at}: ${diagnostic.message}${who}`,
+      id,
+      loc:
+        diagnostic.line == null
+          ? undefined
+          : { file: id, line: diagnostic.line, column: diagnostic.column ?? 0 },
+    });
   }
-  return [...names].sort();
+}
+
+/**
+ * Say how many findings were a dependency's, and whose.
+ *
+ * Held back is not the same as hidden: a build that quietly drops forty
+ * findings is a build that has decided for the reader that uf has no bugs. One
+ * line names the packages and how to see the rest.
+ */
+function summariseSuppressed(context, suppressed) {
+  if (suppressed.length === 0) return;
+  const packages = [...new Set(suppressed.map(packageOf))].sort();
+  const count = suppressed.length;
+  context.warn?.(
+    `${count} React Compiler ${count === 1 ? "finding" : "findings"} in ` +
+      `${packages.join(", ")} — not this application's to fix; ` +
+      `set ${ALL_DIAGNOSTICS}=all to see them`,
+  );
+}
+
+/**
+ * Whether a finding about this module is the application author's to act on.
+ *
+ * Inside the project root *and* outside `node_modules`, rather than
+ * `node_modules` alone: uf's own packages reach an application through a
+ * workspace link in this repository and through `node_modules` everywhere
+ * else, and they are no more the reader's code in one case than the other.
+ */
+function isProjectModule(root, id) {
+  const relative = path.relative(root, id);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
+  return !relative.split(path.sep).includes("node_modules");
+}
+
+/** A module's path as a reader would write it: relative, with forward slashes. */
+function relativeId(root, id) {
+  const relative = path.relative(root, id);
+  return relative === "" ? id : relative.split(path.sep).join("/");
+}
+
+/** The package a module belongs to, for the one line that names them. */
+function packageOf(file) {
+  const parts = file.split("/");
+  const at = parts.lastIndexOf("node_modules");
+  if (at !== -1) {
+    const scoped = parts[at + 1]?.startsWith("@");
+    return parts.slice(at + 1, at + (scoped ? 3 : 2)).join("/");
+  }
+  // No `node_modules` in the path: a workspace link, resolved to a checkout.
+  // The directory the module hangs off is the closest thing to a package name
+  // that is true without reading its `package.json` from a warning path.
+  const up = parts.lastIndexOf("packages");
+  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);
 }