@uniflowed/vite 0.0.0-alpha.14 → 0.0.0-alpha.16

package/driver.js

@@ -10,6 +10,8 @@
 //   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>]
 //                            [--prerender everything|possible|nothing]
 //                            [--static-build] [--because <sentence>]
+//   <host> driver.js library --root <dir> [--mode <m>] [--out-dir <dir>]
+//                            --entry <file>... --format <es|cjs>... [--external <name>]...
 //   <host> driver.js compile --root <dir> [--mode <m>] [--out-dir <dir>] --assets <file> --bundle <dir>
 //   <host> driver.js deploy  --root <dir> [--mode <m>] [--out-dir <dir>] --adapter <name> --work <dir> --output <dir>
 //   <host> driver.js preview --root <dir> [--mode <m>] [--out-dir <dir>] [--host <h>] [--port <n>]
@@ -38,11 +40,12 @@
 // one host that can evaluate the file evaluates it.
 
 import { createServer as createHttpServer } from "node:http";
-import { register } from "node:module";
+import { builtinModules, register } from "node:module";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { COMPILE_ASSETS_ID, compileAssetsPlugin } from "./internal/compile-assets.js";
 import { emit, errorEvent, eventLogger } from "./internal/events.js";
 import { loadUfConfig, projectConfig } from "./internal/config.js";
 import { send, toRequest } from "./internal/http.js";
@@ -50,6 +53,7 @@ import { withProjectConfig } from "./merge.js";
 import { VIRTUAL, scanRoutes } from "./internal/routes.js";
 import {
   assetsFromManifest,
+  createPrerenderGate,
   createServeHandler,
   loadBuild,
   nodeListener,
@@ -97,7 +101,7 @@ process.stdin.on("end", () => process.exit(0));
 process.stdin.on("error", () => process.exit(0));
 process.stdin.resume();
 
-const commands = { dev, build, compile, deploy, preview, start, config: printConfig };
+const commands = { dev, build, library, compile, deploy, preview, start, config: printConfig };
 const run = commands[command];
 if (run == null) {
   emit("error", { message: `unknown driver command ${JSON.stringify(command)}` });
@@ -341,6 +345,16 @@ function watchEnvFiles(server) {
  * The static middleware still runs first, and that is deliberate rather than
  * incidental; see `internal/serve.js` for why `uf start` orders itself the
  * same way.
+ *
+ * One request is the exception, and it is the only thing uf mounts in *front*
+ * of Vite here: a request carrying the draft cookie, which no front door may
+ * answer from a prerendered document. `createStaticHandler` applies that rule
+ * and cannot reach a request Vite's file middleware answered first, so under
+ * `uf preview` draft mode appeared to be off while it worked under `uf dev`
+ * and `uf start` — ubugeeei-prod/uf#620. `configurePreviewServer` is where a
+ * middleware goes ahead of Vite's own; the hook's *body* runs before they are
+ * installed and a function it returns runs after, which is why this is a body
+ * and the handler below is a `use` on the started server.
  */
 async function preview() {
   const { preview: startPreview } = await import("vite");
@@ -361,25 +375,53 @@ async function preview() {
         serverDir: path.join(".uf", "build", "server"),
       });
 
-  const server = await startPreview({ ...inline, appType: "custom" });
-  if (build != null) {
-    const handle = createServeHandler({ ...build, cache: config.app?.rendering?.cache });
-    server.middlewares.use(async (request, response, next) => {
-      try {
-        const asRequest = await toRequest(request, server.config);
-        // The same lifecycle `uf start` gets from `nodeListener`, spelled out
-        // because this door is Vite's connect chain rather than a bare
-        // `node:http` server: the whole request runs inside it, and it settles
-        // once `send` has returned. A preview whose `after()` fired at a
-        // different moment from the production server's would be a preview that
-        // is checked and believed and wrong.
-        await withRequest(build.entry, asRequest, async () => {
-          await send(response, await handle(asRequest));
-        });
-      } catch (error) {
-        next(error);
-      }
-    });
+  // One handler for both positions in the chain. A draft request meets it in
+  // front of Vite's file middleware and every other request meets it behind,
+  // and because it is the same handler the two give the same answer — which is
+  // the whole reason `uf preview` exists.
+  const handle =
+    build == null ? null : createServeHandler({ ...build, cache: config.app?.rendering?.cache });
+  const answer = (previewServer) => async (request, response, next) => {
+    try {
+      const asRequest = await toRequest(request, previewServer.config);
+      // The same lifecycle `uf start` gets from `nodeListener`, spelled out
+      // because this door is Vite's connect chain rather than a bare
+      // `node:http` server: the whole request runs inside it, and it settles
+      // once `send` has returned. A preview whose `after()` fired at a
+      // different moment from the production server's would be a preview that
+      // is checked and believed and wrong.
+      await withRequest(build.entry, asRequest, async () => {
+        await send(response, await handle(asRequest));
+      });
+    } catch (error) {
+      next(error);
+    }
+  };
+
+  const mayAnswerFromPrerender = createPrerenderGate();
+  const draftFirst = {
+    name: "uf:draft-before-files",
+    configurePreviewServer(previewServer) {
+      if (handle == null) return;
+      const run = answer(previewServer);
+      previewServer.middlewares.use((request, response, next) => {
+        // Not `await`ed by connect, which takes no promise: the gate is
+        // resolved inside and `next()` is called from there. A rejection is a
+        // `next(error)` for the same reason.
+        mayAnswerFromPrerender(request.headers.cookie ?? null)
+          .then((mayAnswer) => (mayAnswer ? next() : run(request, response, next)))
+          .catch(next);
+      });
+    },
+  };
+
+  const server = await startPreview({
+    ...inline,
+    appType: "custom",
+    plugins: [...(inline.plugins ?? []), draftFirst],
+  });
+  if (handle != null) {
+    server.middlewares.use(answer(server));
   }
 
   const urls = server.resolvedUrls ?? { local: [], network: [] };
@@ -680,6 +722,147 @@ async function build() {
   process.exit(0);
 }
 
+/**
+ * The library build, for a project whose `app.router.enabled` is false.
+ *
+ * `build` above is an application build and has no other mode: it links
+ * `virtual:uf/client`, which imports the router and the project's `app.js`.
+ * A library has neither, so `uf build` in a project `uf create lib`
+ * scaffolded failed at the first pass with `Could not resolve '<root>/app.js'`
+ * — a file a library does not have and never had. See ubugeeei-prod/uf#268.
+ *
+ * This is the fourth thing the driver does, beside `dev`, `build` and
+ * `compile`, and it is one pass per format over one input list. Which of the
+ * two builds runs is **not decided here**: `uf` resolves it from the config
+ * (`uf_config`'s `LibraryPlan`) and spawns this subcommand, the same way
+ * `--prerender` arrives as one word rather than as two settings for this file
+ * to read together.
+ *
+ * # The three ways it differs from the application build
+ *
+ *   * **Every dependency stays an import.** `--external` names them, and
+ *     `uf` computes the list from the project's own manifest —
+ *     `dependencies`, `peerDependencies`, `optionalDependencies` — so a
+ *     library ships its own modules and nobody else's. That is the opposite
+ *     of the application build, which inlines what it can because an
+ *     application is the end of the line and a library is not: a bundled copy
+ *     of React inside a library is a second React in every application that
+ *     installs it.
+ *   * **One output per entry, named after the entry.** `index.js` becomes
+ *     `dist/index.js`; `internal/parse.js` becomes `dist/internal/parse.js`.
+ *     The path rather than the basename, so two entries cannot collide at the
+ *     moment one would overwrite the other.
+ *   * **No manifest, no prerender, no server bundle.** There is no document to
+ *     write and no route table to write it from.
+ *
+ * Vite's own `build.lib` does the work. uf owns *that* a library is a
+ * different build and what goes into it; how this builder performs one is the
+ * builder's, which is the same line `build` draws around `rollupOptions`.
+ */
+async function library() {
+  const vite = await import("vite");
+  const config = await loadConfig();
+  const inline = await viteConfig(config, argument("--mode") ?? "production");
+  const outDir = path.resolve(root, inline.build.outDir);
+  const entries = argumentAll("--entry");
+  const formats = argumentAll("--format");
+  const external = argumentAll("--external");
+  if (entries.length === 0) {
+    throw new Error("uf: `driver.js library` needs at least one --entry");
+  }
+  if (formats.length === 0) {
+    throw new Error("uf: `driver.js library` needs at least one --format");
+  }
+
+  // Keyed by the entry's path without its extension, which is what Vite's lib
+  // mode turns into the output file name.
+  const input = {};
+  for (const entry of entries) {
+    input[entryName(entry)] = path.resolve(root, entry);
+  }
+
+  const isExternal = externalTest(external);
+  // One pass per format rather than one build with several outputs: Vite's
+  // lib mode writes a whole `outDir` per format, and the second pass must not
+  // empty what the first wrote. So `emptyOutDir` is true exactly once, on the
+  // first, which is also what makes a build that dropped an entry leave no
+  // stale copy of it behind.
+  let first = true;
+  for (const format of formats) {
+    emit("phase", { name: `library (${format})` });
+    await vite.build({
+      ...inline,
+      build: {
+        ...inline.build,
+        // Vite's `manifest` maps source modules to hashed browser assets. A
+        // library has neither — its file names are its API — and writing one
+        // would put a `.vite/` directory into a published tarball.
+        manifest: false,
+        outDir,
+        emptyOutDir: first,
+        lib: {
+          entry: input,
+          formats: [format],
+          fileName: (_format, name) => `${name}.${format === "cjs" ? "cjs" : "js"}`,
+        },
+        rollupOptions: { external: isExternal },
+      },
+    });
+    first = false;
+  }
+
+  emit("done", { outDir: path.relative(root, outDir), pages: 0 });
+  process.exit(0);
+}
+
+/**
+ * The output name for one entry: its path, without the extension.
+ *
+ * Not the basename. `index.js` and `internal/index.js` are two entries a
+ * library can reasonably have, and under a basename they are one file written
+ * twice — the second silently winning, which is a published package whose
+ * subpath export is somebody else's module.
+ */
+function entryName(entry) {
+  const normalised = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+  const dot = normalised.lastIndexOf(".");
+  const slash = normalised.lastIndexOf("/");
+  return dot > slash ? normalised.slice(0, dot) : normalised;
+}
+
+/**
+ * Whether an import is somebody else's module.
+ *
+ * Three checks, and only the one over `names` is a policy uf decided. `names`
+ * is what `uf` read out of the project's manifest and passed as `--external`,
+ * and a subpath of one of those names — `@scope/pkg/deep` for `@scope/pkg` —
+ * is the same package. The other two are the host's built-in modules, and they
+ * are a fact rather than a decision: `node:fs` has no bytes to inline.
+ *
+ * A bare relative or absolute id is never external, which is the rule that
+ * makes this a library build at all: what the author wrote is bundled, and
+ * what they installed is imported.
+ */
+function externalTest(names) {
+  const declared = new Set(names);
+  // The host's built-in module names, unprefixed. `node:`-prefixed ids are
+  // caught by the first check whatever the host is; this set is for the bare
+  // spellings — `fs`, `path`, `stream` — which a dependency written before the
+  // prefix existed still uses. Read from the running host rather than written
+  // down, because the list grows and a stale copy of it here would be a
+  // bundled `node:worker_threads` that cannot be bundled.
+  const builtins = new Set(builtinModules ?? []);
+  return (id) => {
+    if (id.startsWith("node:")) return true;
+    if (builtins.has(id)) return true;
+    if (declared.has(id)) return true;
+    for (const name of declared) {
+      if (id.startsWith(`${name}/`)) return true;
+    }
+    return false;
+  };
+}
+
 /**
  * Link the whole application into one JavaScript file, for `uf build --compile`.
  *
@@ -741,17 +924,19 @@ async function compile() {
   emit("phase", { name: "standalone" });
 
   // The entry is written to disk rather than served as another virtual module:
-  // it is generated per build (it names this build's asset file), and a real
+  // it is generated per build (it bakes in this build's document), and a real
   // file is the version a person can open when a compiled binary misbehaves.
   const entry = path.join(bundleDir, "entry.js");
   mkdirSync(bundleDir, { recursive: true });
-  const specifier = `./${path.relative(bundleDir, assets)}`;
-  writeFileSync(entry, entrySource(specifier, assetsFromManifest(readManifest(outDir))));
+  writeFileSync(
+    entry,
+    entrySource(path.relative(root, assets), assetsFromManifest(readManifest(outDir))),
+  );
 
   await vite.build({
     ...inline,
     customLogger: eventLogger("warn"),
-    plugins: [...inline.plugins, nativeAddonGuard()],
+    plugins: [...inline.plugins, nativeAddonGuard(), compileAssetsPlugin(assets)],
     ssr: { ...(inline.ssr ?? {}), noExternal: true },
     build: {
       ...inline.build,
@@ -887,6 +1072,16 @@ const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lam
  * copying every file in it is bulk work over the whole build, which belongs in
  * Rust rather than in the host process — the same division `--compile` makes
  * with its embedded assets.
+ *
+ * # `--adapter static` never reaches this function
+ *
+ * It is the one implemented target with no application to link: a static host
+ * returns files, and `uf build` has already written them. So `uf` copies the
+ * output directory itself and never spawns this driver for it, which is why
+ * [`ADAPTERS`] has four rows and not five. What that target does instead of
+ * linking is refuse a project whose route handlers, middleware, unprerendered
+ * routes or server actions a static host cannot answer — in Rust, because the
+ * facts it needs are the route table and what the prerender reported.
  */
 async function deploy() {
   const vite = await import("vite");
@@ -1162,8 +1357,14 @@ export const handler = createLambdaHandler({ handle, beginRequest, staticDir });
  * bytes of `dist/`. The document's script and stylesheet URLs are baked in
  * here because they come from the client manifest, which exists at this moment
  * and not inside the binary.
+ *
+ * `assetsFile` is the generated payload's path, and it appears in a comment
+ * rather than in the import: the module enters the graph under a virtual id so
+ * that uf's Flow transform never meets eight megabytes of base64. The reason
+ * that matters is `./internal/compile-assets.js`; naming the file here is what
+ * keeps a reader of the generated entry able to find the bytes it carries.
  */
-function entrySource(assetsSpecifier, document) {
+function entrySource(assetsFile, document) {
   // Not `await serve(...)` at the top level. uf parses that now
   // (ubugeeei-prod/uf#204) and this entry is a module, so it would work;
   // `.catch` is the better spelling regardless: a binary that cannot take its
@@ -1171,7 +1372,11 @@ function entrySource(assetsSpecifier, document) {
   // unhandled rejection.
   return `// Generated by \`uf build --compile\`. Not checked in, not edited.
 import { serve } from "@uniflowed/server/standalone";
-import { assets } from ${JSON.stringify(assetsSpecifier)};
+// Every file \`uf build\` wrote, base64 in one string. It is on disk at
+// ${assetsFile}, and it is imported under a virtual id so that uf's
+// Flow transform is never asked to parse it — see \`@uniflowed/vite\`'s
+// \`internal/compile-assets.js\` for why that matters.
+import { assets } from ${JSON.stringify(COMPILE_ASSETS_ID)};
 import * as app from ${JSON.stringify(VIRTUAL.server)};
 
 serve({ app, assets, document: ${JSON.stringify(document)} }).catch((error) => {

package/index.js

@@ -45,6 +45,13 @@ import path from "node:path";
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
 
+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 { highlightPlugin } from "./internal/highlight.js";
@@ -79,6 +86,7 @@ import {
 } from "./internal/routes.js";
 import { TransformService, isFlowModule } from "@uniflowed/host/transform";
 import { createChannelMiddleware } from "./internal/diagnostics.js";
+import { devtoolsPreamble } from "./internal/devtools.js";
 import { send, toRequest } from "./internal/http.js";
 import { beginRequest } from "./internal/serve.js";
 
@@ -122,21 +130,45 @@ export default function uniflowed(options = {}) {
   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;
+
+  const accessibility = ufConfig.accessibility ?? {};
 
   return [
-    flowPlugin({ routerRoot, appEntry, command: options.command }),
+    flowPlugin({
+      routerRoot,
+      appEntry,
+      strictMode,
+      command: options.command,
+      accessibility,
+    }),
     mdxPlugin(markdown),
     assetPlugin({
       images: builtins.images ?? {},
       fonts: builtins.fonts ?? {},
+      icons: builtins.icons ?? {},
+      og: builtins.og ?? {},
       command: options.command,
     }),
   ];
 }
 
-function flowPlugin({ routerRoot, appEntry, command }) {
+function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }) {
   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 = "";
@@ -246,6 +278,10 @@ function flowPlugin({ routerRoot, appEntry, command }) {
     config(userConfig, env) {
       const projectRoot = path.resolve(userConfig.root ?? process.cwd());
       isProduction = env.mode === "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",
@@ -260,6 +296,16 @@ function flowPlugin({ routerRoot, appEntry, command }) {
             "react/compiler-runtime",
             "react-dom",
             "react-dom/client",
+            // 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.
@@ -287,6 +333,7 @@ function flowPlugin({ routerRoot, appEntry, command }) {
 
     resolveId(id) {
       if (id === RUNTIME_PUBLIC_PATH) return RUNTIME_RESOLVED_ID;
+      if (id === AUDIT_PUBLIC_PATH) return AUDIT_RESOLVED_ID;
       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
@@ -297,6 +344,7 @@ 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);
         // The server renders every route, so the server's table is the whole
@@ -305,7 +353,12 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         if (isSsr(this, loadOptions)) return routesModuleSource(table);
         return clientRoutesModule(table);
       }
-      if (id === resolved(VIRTUAL.client)) return clientModuleSource(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.
+      if (id === resolved(VIRTUAL.client)) {
+        return clientModuleSource(entryPath, { strictMode: strictMode && !isProduction });
+      }
       if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
       // 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
@@ -404,9 +457,26 @@ 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",
+          children: devtoolsPreamble(),
+          injectTo: "head-prepend",
+        },
         {
           tag: "script",
           attrs: { type: "module" },
@@ -414,6 +484,13 @@ function flowPlugin({ routerRoot, appEntry, command }) {
           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;
     },
 
     configureServer(devServer) {
@@ -590,7 +667,7 @@ function flowPlugin({ routerRoot, appEntry, command }) {
               // `POST`, and letting one try would turn a missing handler into
               // a rendered page with a 200 rather than a 404.
               //
-              // `wantsDocument` is stricter than the production handler, which
+              // `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
@@ -600,7 +677,15 @@ function flowPlugin({ routerRoot, appEntry, command }) {
               // 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.
-              if (!wantsDocument(request)) return false;
+              const notDocument = notADocumentBecause(request);
+              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;
 
               const result = await entry.render(
                 url,
@@ -700,16 +785,62 @@ async function importServerEntry(devServer) {
   return devServer.ssrLoadModule(VIRTUAL.server);
 }
 
-function wantsDocument(request) {
-  if (request.method !== "GET" && request.method !== "HEAD") return false;
+/**
+ * Why `request` is not a document request, or `null` when it is one.
+ *
+ * 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) {
+  if (request.method !== "GET" && request.method !== "HEAD") return "method";
   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;
+  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. */