@uniflowed/vite 0.0.0-alpha.15 → 0.0.0-alpha.17

package/driver.js

@@ -45,6 +45,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 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";
@@ -52,6 +53,7 @@ import { withProjectConfig } from "./merge.js";
 import { VIRTUAL, scanRoutes } from "./internal/routes.js";
 import {
   assetsFromManifest,
+  createPrerenderGate,
   createServeHandler,
   loadBuild,
   nodeListener,
@@ -343,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");
@@ -363,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: [] };
@@ -884,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,
@@ -1315,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
@@ -1324,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";
@@ -129,8 +136,16 @@ export default function uniflowed(options = {}) {
   // client entry; see `flowPlugin`'s `load`. ubugeeei-prod/uf#516.
   const strictMode = app.react?.strictMode !== false;
 
+  const accessibility = ufConfig.accessibility ?? {};
+
   return [
-    flowPlugin({ routerRoot, appEntry, strictMode, command: options.command }),
+    flowPlugin({
+      routerRoot,
+      appEntry,
+      strictMode,
+      command: options.command,
+      accessibility,
+    }),
     mdxPlugin(markdown),
     assetPlugin({
       images: builtins.images ?? {},
@@ -142,9 +157,18 @@ export default function uniflowed(options = {}) {
   ];
 }
 
-function flowPlugin({ routerRoot, appEntry, strictMode, 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 = "";
@@ -254,6 +278,10 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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",
@@ -268,6 +296,16 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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.
@@ -295,6 +333,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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
@@ -305,6 +344,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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
@@ -431,7 +471,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command }) {
     // argument, and the three conditions DevTools needs.
     transformIndexHtml() {
       if (isProduction) return [];
-      return [
+      const tags = [
         {
           tag: "script",
           children: devtoolsPreamble(),
@@ -444,6 +484,13 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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) {
@@ -620,7 +667,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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
@@ -630,7 +677,15 @@ function flowPlugin({ routerRoot, appEntry, strictMode, 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,
@@ -730,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. */

package/internal/a11y-runtime.js

@@ -0,0 +1,234 @@
+// @noflow
+//
+// Plain JavaScript: this module is served to the browser as text, by
+// `./a11y.js`'s virtual module, before any transform has run on it.
+//
+// The accessibility audit `uf dev` runs against the page on screen.
+//
+// The second half of ubugeeei-prod/uf#511, and the half that is worth more: a
+// violation found while the component is being written is a violation somebody
+// can fix in the same minute, and one found in CI is a pull request that goes
+// red an hour later. Same engine and same rule set as
+// `expect(el).toHaveNoAxeViolations()` — `uf.config.js`'s `accessibility.axe`
+// is read once and given to both — so the two cannot disagree about what
+// "accessible" means.
+//
+// # It reports to the terminal rather than drawing an overlay
+//
+// `internal/diagnostics.js` records the decision and the reason, from #583: an
+// overlay is a rectangle drawn over the page, and a rectangle drawn over the
+// page is the last thing an *accessibility* report should be. It would cover
+// the markup it is complaining about, it would change the layout the audit
+// just measured, and it would need to be accessible itself. So a finding goes
+// down the channel that already exists, `POST /__uf/diagnostic`, and comes out
+// in the terminal beside every other thing `uf dev` has to say.
+//
+// # When it runs
+//
+// Once when the page has settled, and again after the DOM stops changing.
+// Not on every mutation: a React render is hundreds of them, and axe walks the
+// whole subtree each time. The debounce is what makes it a background job
+// rather than a stutter, and the audit is skipped outright while the tab is
+// hidden — a page nobody is looking at has nothing to report about.
+//
+// Development only. `./a11y.js` injects this module from `transformIndexHtml`,
+// which is guarded on `isProduction`, and the module is not reachable from any
+// entry a build follows.
+
+import axe from "axe-core";
+
+/**
+ * Whether the engine is mid-run, for every audit in the process.
+ *
+ * Module scope because `axe` is a singleton and holds a single-run lock of its
+ * own: asking it for a second run while one is going answers "Axe is already
+ * running" rather than a result, and a per-page flag would not see the other
+ * page's run. One engine, one lock.
+ */
+let engineBusy = false;
+
+/** Most violations one report names; the rest are counted. */
+const MAX_VIOLATIONS_REPORTED = 8;
+
+/** Longest excerpt of an element's markup a line quotes. */
+const MAX_NODE_CHARS = 100;
+
+/**
+ * Start auditing.
+ *
+ * `options` is generated by `./a11y.js` and carries the project's rule set,
+ * the endpoint to report to, and nothing a page could have chosen: everything
+ * here is decided by `uf.config.js` on the server before the module exists.
+ */
+export function start(options) {
+  const endpoint = options.endpoint;
+  // How long the DOM has to stop moving before an audit runs. Decided by
+  // `./a11y.js` and written into this module's last line rather than kept here
+  // as a constant, so there is one number rather than two — and so a test can
+  // drive the loop without waiting three quarters of a second per assertion.
+  const settleMs = options.settleMs;
+  const runOptions = axeOptions(options.axe ?? {});
+  const floor = options.axe?.minImpact ?? null;
+  let timer = null;
+  // Whether `stop` has been called. A run already in flight cannot be
+  // cancelled, but nothing after it should act as though the page is still
+  // being watched.
+  let stopped = false;
+  // What the last report said, so a re-render that changes nothing the audit
+  // cares about does not print the same block again. A page under active
+  // editing re-renders constantly; a terminal that repeats itself every time
+  // is a terminal nobody reads.
+  let reported = "";
+
+  const audit = async () => {
+    if (stopped || document.hidden) return;
+    if (engineBusy) {
+      // Not a run to skip — a run to come back for. The timer that brought us
+      // here cleared itself before calling, so returning without scheduling
+      // again loses the mutation for good: nothing is left pending, and the
+      // DOM it settled into never gets audited. Rescheduling rather than
+      // queueing a flag also means the wait is another settle, which is right
+      // — the tree may still be moving — and it is the same answer whether the
+      // engine is busy for this page or for another one.
+      schedule();
+      return;
+    }
+    engineBusy = true;
+    try {
+      const results = await axe.run(document, runOptions);
+      // The engine takes as long as it takes, and `stop` can land in the
+      // middle of it. A caller that has said it is done is not expecting one
+      // more report a second later.
+      if (stopped) return;
+      const violations = (results?.violations ?? []).filter((violation) =>
+        atOrAbove(violation.impact, floor),
+      );
+      const summary = violations.map((violation) => violation.id).join(",");
+      if (summary === reported) return;
+      reported = summary;
+      if (violations.length > 0) report(endpoint, violations);
+    } catch (error) {
+      // An audit that throws is a bug in this file or in the engine, and it
+      // must not take the page with it: `uf dev` is for developing the
+      // application, not this. Reported once, at `info`, and then the run is
+      // over — `reported` is left as it was so the next settle tries again.
+      report(endpoint, null, error);
+    } finally {
+      engineBusy = false;
+    }
+  };
+
+  const schedule = () => {
+    if (timer != null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void audit();
+    }, settleMs);
+  };
+
+  const observer = new MutationObserver(schedule);
+  observer.observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+  });
+  document.addEventListener("visibilitychange", () => {
+    if (!document.hidden) schedule();
+  });
+  schedule();
+
+  // Returned so a caller that owns the page's lifetime can end the loop. The
+  // generated call in `./a11y.js` ignores it: a dev server's page is over when
+  // the document is, and nothing outlives that.
+  return () => {
+    stopped = true;
+    if (timer != null) clearTimeout(timer);
+    observer.disconnect();
+  };
+}
+
+/** The project's rule set in axe's own vocabulary. */
+function axeOptions(settings) {
+  const options = {};
+  const tags = settings.tags ?? [];
+  if (tags.length > 0) options.runOnly = { type: "tag", values: [...tags] };
+  const disabled = settings.disabledRules ?? [];
+  if (disabled.length > 0) {
+    const rules = {};
+    for (const rule of disabled) rules[rule] = { enabled: false };
+    options.rules = rules;
+  }
+  return options;
+}
+
+/** Impacts weakest first, so a floor is a comparison rather than a match. */
+const IMPACTS = ["minor", "moderate", "serious", "critical"];
+
+/**
+ * Whether a violation clears the configured floor.
+ *
+ * A violation axe could not rate clears every floor: "we do not know how bad
+ * this is" is not a reason to hide it.
+ */
+function atOrAbove(impact, floor) {
+  if (floor == null || impact == null) return true;
+  const at = IMPACTS.indexOf(impact);
+  return at === -1 || at >= IMPACTS.indexOf(floor);
+}
+
+/** One element, short enough to be one line of a terminal. */
+function excerpt(html) {
+  const line = String(html ?? "")
+    .split("\n")[0]
+    .trim();
+  return line.length > MAX_NODE_CHARS ? `${line.slice(0, MAX_NODE_CHARS)}…` : line;
+}
+
+/**
+ * Send one report down the diagnostic channel.
+ *
+ * `keepalive` and a swallowed failure, because this is telemetry about the
+ * page rather than part of it: a dev server that has gone away must not turn
+ * into an unhandled rejection in the application being developed.
+ */
+function report(endpoint, violations, error) {
+  const body =
+    violations == null
+      ? {
+          severity: "info",
+          message: `the accessibility audit could not run: ${String(error)}`,
+        }
+      : {
+          severity: "warn",
+          message: `${violations.length} accessibility ${
+            violations.length === 1 ? "violation" : "violations"
+          } on this page`,
+          detail: detailLines(violations),
+        };
+  void fetch(endpoint, {
+    method: "POST",
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ ...body, url: window.location.href }),
+  }).then(
+    () => {},
+    () => {},
+  );
+}
+
+/** One line per rule, then the elements that broke it. */
+function detailLines(violations) {
+  const lines = [];
+  for (const violation of violations.slice(0, MAX_VIOLATIONS_REPORTED)) {
+    const impact = violation.impact == null ? "" : ` (${violation.impact})`;
+    lines.push(`${violation.id}${impact} — ${violation.help}`);
+    for (const node of (violation.nodes ?? []).slice(0, 2)) {
+      lines.push(`  ${excerpt(node.html)}`);
+    }
+    if (violation.helpUrl) lines.push(`  ${violation.helpUrl}`);
+  }
+  if (violations.length > MAX_VIOLATIONS_REPORTED) {
+    lines.push(`…and ${violations.length - MAX_VIOLATIONS_REPORTED} more rules`);
+  }
+  return lines;
+}

package/internal/a11y.js

@@ -0,0 +1,100 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// Serving `./a11y-runtime.js` to the page `uf dev` renders.
+//
+// The same shape as `./refresh.js`, and deliberately so: a virtual module
+// whose source is a file read from disk, and a tag added to every development
+// document that imports it. Two mechanisms for "a module uf injects into the
+// page" would be two things to keep working.
+//
+// What is different is the gate. Fast Refresh is always there; this is not.
+// axe-core is an *optional* dependency — uf does not make a project that never
+// audits carry a megabyte of rule definitions — so the injection is decided by
+// asking the project's own `node_modules` whether the engine is installed. The
+// question is answered on the server, once, before anything is injected, which
+// is why a project without the engine gets no script, no failed import and no
+// error in a console it did not open.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { DIAGNOSTIC_ENDPOINT } from "./diagnostics.js";
+
+/** Public URL the audit runtime is served from. */
+export const AUDIT_PUBLIC_PATH = "/@uf-a11y";
+
+/** The resolved id Vite hands back for it. */
+export const AUDIT_RESOLVED_ID = "\0uf:a11y-audit";
+
+const RUNTIME_SOURCE_PATH = fileURLToPath(new URL("./a11y-runtime.js", import.meta.url));
+
+/**
+ * How long the DOM has to stop moving before an audit runs, in milliseconds.
+ *
+ * A React render is hundreds of mutations and axe walks the whole subtree, so
+ * without a window this would be a stutter rather than a background job. Long
+ * enough to sit out a render and short enough that somebody who has just saved
+ * a file hears about it while they are still looking at the page.
+ */
+export const SETTLE_MS = 750;
+
+/**
+ * Whether the project has axe-core.
+ *
+ * Resolved from the project root rather than from this package, because the
+ * dependency is the *project's* — `@uniflowed/vite` declares it as an optional
+ * peer, so it is installed beside the application and not beside the plugin.
+ *
+ * A failure to resolve is the ordinary answer, not an error: "no engine" is
+ * what most projects will say, and it is the reason this function exists.
+ */
+export function auditAvailable(root) {
+  try {
+    createRequire(path.join(root, "package.json")).resolve("axe-core");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The audit module's source, with the project's settings written into its
+ * last line.
+ *
+ * Generated rather than passed at runtime because the module is a *module*:
+ * there is nowhere for a caller to hand it arguments, and a global would be a
+ * second name to agree on. `JSON.stringify` of a value uf built from its own
+ * config — never from anything a page said — is what goes in.
+ */
+export function auditRuntimeSource(settings) {
+  const options = {
+    endpoint: DIAGNOSTIC_ENDPOINT,
+    settleMs: SETTLE_MS,
+    axe: {
+      tags: settings?.tags ?? [],
+      disabledRules: settings?.disabledRules ?? [],
+      minImpact: settings?.minImpact ?? null,
+    },
+  };
+  return `${readFileSync(RUNTIME_SOURCE_PATH, "utf8")}\nstart(${JSON.stringify(options)});\n`;
+}
+
+/**
+ * The tag that loads it, or `null` when this project has no engine.
+ *
+ * `injectTo: "body"` rather than the head: the audit reads the rendered tree,
+ * so there is nothing for it to do until there is one, and a script in the
+ * head would only sit through the same wait with the parser stopped behind it.
+ */
+export function auditTag(base, available) {
+  if (!available) return null;
+  return {
+    tag: "script",
+    attrs: { type: "module", src: `${base}${AUDIT_PUBLIC_PATH.slice(1)}` },
+    injectTo: "body",
+  };
+}

package/internal/compile-assets.js

@@ -0,0 +1,67 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// The embedded copy of `dist/`, handed to the bundler as a virtual module.
+//
+// `uf build --compile` puts everything `uf build` wrote inside the binary, and
+// the way it travels there is one generated module: `uf_bundle::embed` writes
+// `export const assets = JSON.parse("…")` into `.uf/build/compile/assets.js`,
+// where the string is base64 of every file in the output directory. For the
+// docs site that is eight megabytes; for a project with images it is tens.
+//
+// # Why it does not enter the graph as the file it is
+//
+// Because it is uf's own data, and the module graph is where uf's *source*
+// transform is. `crates/uf_transform` refuses a source over
+// `MAX_SOURCE_BYTES` — 8 MiB, a ceiling that bounds the parser against a file
+// nobody meant to compile — and `.uf/build/compile/assets.js` is a file
+// nobody wrote at all: its size is the size of the *build output*, which has
+// no relationship to the size of any source file and grows every time a page
+// is added. A site that crossed the line failed with
+//
+//     TransformError: source is 8442536 bytes, over the 8388608 byte ceiling
+//       [plugin uf:flow] docs/.uf/build/compile/assets.js
+//
+// which names a file the project does not own, for a limit it did not break,
+// at the end of a build that had already succeeded.
+//
+// So the payload enters the graph the way a build tool's own modules do,
+// under a NUL-prefixed id. `@uniflowed/host/transform`'s `isFlowModule`
+// declines those by name — "a build tool synthesises modules of its own", the
+// first sentence of its contract — so the bytes go from disk to the bundler
+// without being parsed as Flow on the way. Raising the ceiling instead would
+// have weakened the one thing it is for, on every real source file, to make
+// room for a file that is not source.
+//
+// The file on disk is still written and still what is served, so a person
+// debugging a compiled binary can open the thing that went into it. What
+// changed is only which name the bundler reaches it by.
+
+import { readFileSync } from "node:fs";
+
+/** What the generated entry imports. */
+export const COMPILE_ASSETS_ID = "virtual:uf/compile-assets";
+
+/** The resolved id Vite hands back for it. */
+export const COMPILE_ASSETS_RESOLVED_ID = `\0${COMPILE_ASSETS_ID}`;
+
+/**
+ * Serve `file` — `uf_bundle::embed`'s output — as [`COMPILE_ASSETS_ID`].
+ *
+ * Read at `load` rather than when the plugin is made, so a build that fails
+ * before it reaches the entry never pays for eight megabytes of string, and
+ * so the bytes are the ones on disk at the moment the bundler asked for them
+ * rather than at the moment the plugin list was assembled.
+ */
+export function compileAssetsPlugin(file) {
+  return {
+    name: "uf:compile-assets",
+    resolveId(id) {
+      return id === COMPILE_ASSETS_ID ? COMPILE_ASSETS_RESOLVED_ID : null;
+    },
+    load(id) {
+      return id === COMPILE_ASSETS_RESOLVED_ID ? readFileSync(file, "utf8") : null;
+    },
+  };
+}

package/internal/serve.js

@@ -362,6 +362,36 @@ export function createServeHandler({ entry, assets, distDir, cache }) {
   };
 }
 
+/**
+ * Whether a file server may answer this request, or uf has to go first.
+ *
+ * `@uniflowed/server`'s `prerenderedMayAnswer`, reached the same way
+ * `createStaticHandler` is. It exists out here because of the one request
+ * `uf preview` may not leave to Vite: `createServeHandler` above is mounted
+ * *behind* Vite's static middleware, which is fine for everything except a
+ * request carrying the draft cookie. `createStaticHandler` declines a
+ * prerendered document for such a request and, under `uf preview`, never sees
+ * it — so draft mode appeared to be off there while it worked under `uf dev`
+ * and `uf start`. That is ubugeeei-prod/uf#620.
+ *
+ * `driver.js` asks this in a middleware mounted in *front* of Vite's, and
+ * mounts `createServeHandler` behind it for the answer, so a draft request
+ * goes through the same handler `uf start` uses and gets the same answer —
+ * including its stylesheets and chunks, which that handler still serves off
+ * disk. Every other request is untouched and Vite's file middleware runs as
+ * before.
+ *
+ * A gate rather than a second handler, because the caller has a request
+ * lifecycle to open and must not open one for a request it is about to hand
+ * on.
+ */
+export function createPrerenderGate() {
+  const ready = deployment().then(({ prerenderedMayAnswer }) => prerenderedMayAnswer);
+  return async function prerenderedMayAnswer(cookieHeader) {
+    return (await ready)(cookieHeader ?? null);
+  };
+}
+
 /**
  * A `Request`/`Response` handler as a Node request listener.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.15",
+  "version": "0.0.0-alpha.17",
   "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
   "type": "module",
   "license": "MIT",
@@ -33,8 +33,8 @@
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.15",
-    "@uniflowed/server": "0.0.0-alpha.15",
+    "@uniflowed/host": "0.0.0-alpha.17",
+    "@uniflowed/server": "0.0.0-alpha.17",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
@@ -44,6 +44,12 @@
   },
   "peerDependencies": {
     "react": ">=19",
-    "react-dom": ">=19"
+    "react-dom": ">=19",
+    "axe-core": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "axe-core": {
+      "optional": true
+    }
   }
 }