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

package/driver.js

@@ -5,14 +5,20 @@
 // The driver `uf dev`, `uf build`, `uf build --compile`, `uf preview` and
 // `uf start` spawn.
 //
-//   <host> driver.js dev     --root <dir> [--host <h>] [--port <n>] [--strict-port]
-//   <host> driver.js build   --root <dir> [--out-dir <dir>] [--mode <m>]
-//   <host> driver.js compile --root <dir> [--out-dir <dir>] --assets <file> --bundle <dir>
-//   <host> driver.js deploy  --root <dir> [--out-dir <dir>] --adapter <name> --work <dir> --output <dir>
-//   <host> driver.js preview --root <dir> [--out-dir <dir>] [--host <h>] [--port <n>]
+//   <host> driver.js dev     --root <dir> [--mode <m>] [--host <h>] [--port <n>] [--strict-port]
+//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>]
+//   <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>]
 //   <host> driver.js start   --root <dir> [--out-dir <dir>] [--host <h>] [--port <n>]
 //   <host> driver.js config  --root <dir>
 //
+// `--mode` is what `uf` resolved from `--mode`, `.uniflowed/profile` and
+// `env.active`; it is Vite's mode, so it is `import.meta.env.MODE`. The `.env`
+// files it selected have already been read, by `uf`, into this process's
+// environment — see `viteConfig` below and `crates/uf_config/src/env_files.rs`.
+// `start` has no Vite in it and therefore no mode.
+//
 // `uf` in Rust owns the terminal; this process owns Vite. They talk over
 // stdout, one JSON event per line (see `./internal/events.js`), and the driver
 // exits when its stdin closes so it cannot outlive the command that started
@@ -107,12 +113,23 @@ async function viteConfig(config, mode) {
   // merely passes on — `allowedHosts` gates binding a routable address, and
   // `manifest` is how the prerender finds its assets.
   //
-  // `envDir: false` rather than `envFile: false`: Vite 8 deprecated the second
-  // spelling and prints a line saying so on every dev server and every build,
-  // twice in the docs site's. A project turns the loader back on with
-  // `vite: { envDir: "." }`, which is the default directory — the project's own
-  // configuration is merged over this one, so it wins. See #259 for why uf
-  // switches it off at all.
+  // `envDir: false` turns off Vite's *file* loading, and only that. uf reads
+  // the `.env` cascade itself, in Rust, before this process starts — one
+  // parser, one precedence, one answer for `uf dev`, `uf build`, `uf start`,
+  // `uf test` and `uf run` — and sets what it read in this process's
+  // environment. Vite's `loadEnv` still runs with `envDir: false` and still
+  // picks every `envPrefix`-matching name out of `process.env`, so the client
+  // half is Vite's own, unchanged: the prefixed subset becomes
+  // `import.meta.env.*` in the browser bundle and nothing else does. See
+  // `crates/uf_config/src/env_files.rs`, `docs/app/guide/env` and #259.
+  //
+  // A project that would rather Vite read the files can still say
+  // `vite: { envDir: "." }` — its own configuration is merged over this one —
+  // and then both parsers run, uf's answer still standing. `loadEnv` takes the
+  // prefixed names out of the files it read and then copies every prefixed name
+  // in `process.env` over the top, and uf put its own there before this process
+  // started; so the second parser adds prefixed names uf did not set and
+  // changes none that it did.
   const generated = {
     root,
     configFile: false,
@@ -189,7 +206,10 @@ async function viteConfig(config, mode) {
 async function dev() {
   const { createServer } = await import("vite");
   const config = await loadConfig();
-  const inline = await viteConfig(config, "development");
+  // The mode is uf's to decide, not this file's: `uf dev` resolves `--mode`,
+  // the profile `uf env use` wrote and `env.active` before it starts anything,
+  // and always passes the answer. The fallback is for a driver started by hand.
+  const inline = await viteConfig(config, argument("--mode") ?? "development");
   const server = await createServer({ ...inline, appType: "custom" });
 
   // In dev the browser loads the client entry from Vite, not from a manifest;
@@ -354,7 +374,7 @@ function watchSources(server) {
 async function preview() {
   const { preview: startPreview } = await import("vite");
   const config = await loadConfig();
-  const inline = await viteConfig(config, "production");
+  const inline = await viteConfig(config, argument("--mode") ?? "production");
   const build = await loadBuild({
     root,
     outDir: inline.build.outDir,
@@ -707,14 +727,65 @@ async function compile() {
   process.exit(0);
 }
 
+/**
+ * What each adapter links, and what it links it against.
+ *
+ * Every entry in this table produces the same `handler.js` — the application
+ * as `Request` → `Response`, from `@uniflowed/server/fetch` — and differs only
+ * in the file wrapped around it and, for a target whose dependencies have a
+ * different build, in the export conditions that pick one. That is the whole
+ * of what an adapter is, and keeping the differences in one object is what
+ * stops a second one from quietly becoming a second application.
+ *
+ * `bun`, `deno` and `static` are deliberately absent; `uf_config`'s
+ * `DeployAdapter::is_implemented` is the other half of that fact and
+ * `docs/app/reference/cli/_uf.page.mdx` says why for each of them.
+ */
+const ADAPTERS = {
+  node: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      server: nodeEntrySource("./handler.js"),
+    }),
+  },
+  // The same two files. What `--adapter container` adds is a `Dockerfile` and
+  // a `.dockerignore`, and both are plain text that `uf` writes beside this
+  // output rather than anything the bundler produces — see `uf_cli`'s
+  // `commands::deploy`.
+  container: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      server: nodeEntrySource("./handler.js"),
+    }),
+  },
+  edge: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      worker: workerEntrySource("./handler.js"),
+    }),
+    // `workerd` first, so React resolves to the build that has
+    // `renderToReadableStream` and no `node:stream`. `browser` and `module`
+    // after it are Vite's own SSR defaults, kept so a dependency with no
+    // worker condition still resolves the way it does for every other target.
+    conditions: ["workerd", "worker", "edge-light", "browser", "module", "import", "default"],
+  },
+  serverless: {
+    entries: (document) => ({
+      handler: handlerEntrySource(document),
+      lambda: lambdaEntrySource("./handler.js"),
+    }),
+  },
+};
+
 /**
  * Link the application into a directory that can be copied, for
  * `uf build --adapter`.
  *
  * `uf start` serves a build and `uf build --compile` puts one inside an
  * executable, and between them is the shape most hosts actually want: a
- * directory you copy onto a machine that has a JavaScript runtime and nothing
- * else — no `node_modules`, no checkout, no `uf`. That is what this writes.
+ * directory that carries everything and nothing that is still in the checkout
+ * — no `node_modules`, no source, no `uf`. That is what this writes, for
+ * whichever of [`ADAPTERS`] was asked for.
  *
  * It differs from the server build in [`build`] in one way, and that one way
  * is the whole of the difference between a build artefact and a checkout:
@@ -730,16 +801,17 @@ async function compile() {
  *
  * `handler.js` is the application as a Web-standard `fetch` export: a
  * `Request` in, a `Response` out, no filesystem, no socket, no `node:` import
- * that a worker does not already have. That is the seam — every other target
- * in `app.runtime.deploy.adapters` is this file with a different thing wrapped
- * around it.
+ * that a worker does not already have. That is the seam, and it is the same
+ * file for every target in [`ADAPTERS`].
  *
- * `server.js` is the wrapper for *this* target: `node:http`, with the build's
- * files served from `static/` beside it. It is thirty lines, and that is the
- * point — the work is in the handler, and what a second adapter has to write
- * is the thirty lines, not the application.
+ * The second entry is the wrapper for *this* target — `node:http` for `node`
+ * and `container`, `export default { fetch }` for a Worker, `export const
+ * handler` for a Lambda — and each of them is a handful of lines around an
+ * import from `@uniflowed/server`. That is the point: the work is in the
+ * handler, and what a new adapter has to write is the handful of lines, not
+ * the application.
  *
- * Both are ordinary entries of one Rolldown build, so `server.js` imports the
+ * Both are ordinary entries of one Rolldown build, so the wrapper imports the
  * emitted `handler.js` rather than a second copy of the application.
  *
  * The `static/` directory is *not* written here. `uf` copies it (see
@@ -765,11 +837,12 @@ async function deploy() {
   // future `uf` that knows an adapter this copy does not, and answering "one
   // moment, here is a directory" for a target nobody wrote would be the silent
   // wrong answer the whole issue is about.
-  if (adapter !== "node") {
+  const shape = ADAPTERS[adapter];
+  if (shape == null) {
     throw new Error(
-      `uf: this driver implements the \`node\` adapter and was asked for ${JSON.stringify(
-        adapter,
-      )}`,
+      `uf: this driver implements ${Object.keys(ADAPTERS)
+        .map((name) => JSON.stringify(name))
+        .join(", ")} and was asked for ${JSON.stringify(adapter)}`,
     );
   }
   const work = path.resolve(root, workArgument);
@@ -783,14 +856,29 @@ async function deploy() {
   // misbehaves.
   mkdirSync(work, { recursive: true });
   const document = assetsFromManifest(readManifest(outDir));
-  writeFileSync(path.join(work, "handler.js"), handlerEntrySource(document));
-  writeFileSync(path.join(work, "server.js"), nodeEntrySource("./handler.js"));
+  const entries = shape.entries(document);
+  const input = {};
+  for (const name of Object.keys(entries)) {
+    writeFileSync(path.join(work, `${name}.js`), entries[name]);
+    input[name] = path.join(work, `${name}.js`);
+  }
+
+  const ssr = { ...(inline.ssr ?? {}), noExternal: true };
+  if (shape.conditions != null) {
+    // Which build of a dependency this target gets, and it is the difference
+    // between a worker that renders and one that fails to link. React ships
+    // `server.node.js` under the `node` condition and `server.edge.js` under
+    // `workerd`; the first one imports `node:stream`, and the router picks its
+    // renderer by asking whether `renderToPipeableStream` is there — so the
+    // condition list is what decides that, not a flag in the application.
+    ssr.resolve = { ...(inline.ssr?.resolve ?? {}), conditions: shape.conditions };
+  }
 
   await vite.build({
     ...inline,
     customLogger: eventLogger("warn"),
     plugins: [...inline.plugins, nativeAddonGuard()],
-    ssr: { ...(inline.ssr ?? {}), noExternal: true },
+    ssr,
     build: {
       ...inline.build,
       manifest: false,
@@ -805,10 +893,7 @@ async function deploy() {
       // that happens.
       emptyOutDir: false,
       rollupOptions: {
-        input: {
-          handler: path.join(work, "handler.js"),
-          server: path.join(work, "server.js"),
-        },
+        input,
         output: {
           entryFileNames: "[name].js",
           // Route modules are lazy `import()`s, so the server bundle splits
@@ -893,11 +978,10 @@ import { beginRequest, fetch } from ${JSON.stringify(handlerSpecifier)};
 // trap in it.
 const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
 
-// Not \`await serve(...)\` at the top level: Node runs top-level \`await\` happily
-// and the Flow parser uf vendors does not (ubugeeei-prod/uf#204), so the generated
-// entry would fail its own transform. \`.catch\` is the better spelling anyway —
-// a server that cannot take its port should say so and exit non-zero, rather
-// than die as an unhandled rejection.
+// 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 server that cannot take its port should
+// say so and exit non-zero, rather than die as an unhandled rejection.
 serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
   process.stderr.write(\`uf: \${error?.message ?? String(error)}\\n\`);
   process.exit(1);
@@ -905,6 +989,60 @@ serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
 `;
 }
 
+/**
+ * The source of `worker.js`: the Cloudflare Workers entry around that handler.
+ *
+ * `export default { fetch }`, which is the modules-format Worker Cloudflare
+ * runs, and everything host-specific is in `@uniflowed/server/edge` — the
+ * asset lookup through the `ASSETS` binding `wrangler.json` declares, and the
+ * `ctx.waitUntil` that keeps the isolate alive for `after()`.
+ *
+ * `beginRequest` comes from the handler beside this file for the reason
+ * `nodeEntrySource` gives: the request has to be established in the storage the
+ * *application* reads. See ubugeeei-prod/uf#389.
+ */
+function workerEntrySource(handlerSpecifier) {
+  return `// Generated by \`uf build --adapter edge\`. Not checked in, not edited.
+import { createWorkerFetch } from "@uniflowed/server/edge";
+
+import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+
+export default { fetch: createWorkerFetch({ handle, beginRequest }) };
+`;
+}
+
+/**
+ * The source of `lambda.js`: the AWS Lambda entry around that handler.
+ *
+ * `export const handler`, so the function's configured handler is
+ * `lambda.handler`. Everything platform-specific — the payload format 2.0
+ * event, the base64 rules, the `cookies` array — is in
+ * `@uniflowed/server/lambda`.
+ *
+ * `staticDir` points at the `static/` copied beside this file, so an uploaded
+ * package answers a prerendered document without any other infrastructure
+ * existing. That is a starting point rather than a destination, and the module
+ * it is passed to says so at length.
+ */
+function lambdaEntrySource(handlerSpecifier) {
+  return `// Generated by \`uf build --adapter serverless\`. Not checked in, not edited.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createLambdaHandler } from "@uniflowed/server/lambda";
+
+import { beginRequest, fetch as handle } from ${JSON.stringify(handlerSpecifier)};
+
+// Resolved from this file and not from the working directory: Lambda sets the
+// working directory to the task root today and is under no obligation to keep
+// doing so, and a deployment that only found its own assets by accident is a
+// deployment with a trap in it.
+const staticDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
+
+export const handler = createLambdaHandler({ handle, beginRequest, staticDir });
+`;
+}
+
 /**
  * The source of the module a runtime gets wrapped around.
  *
@@ -914,11 +1052,11 @@ serve({ handle: fetch, staticDir, beginRequest }).catch((error) => {
  * and not inside the binary.
  */
 function entrySource(assetsSpecifier, document) {
-  // Not `await serve(...)` at the top level. Node runs top-level `await`
-  // happily and the Flow parser uf vendors does not parse it (ubugeeei-prod/uf#204),
-  // so the generated entry would fail its own transform. `.catch` is the better
-  // spelling anyway: a binary that cannot take its port should say which port
-  // and exit non-zero, rather than die as an unhandled rejection.
+  // 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
+  // port should say which port and exit non-zero, rather than die as an
+  // 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)};

package/index.js

@@ -24,6 +24,13 @@
 //                 markdown, front matter, heading ids and build-time syntax
 //                 highlighting, so `.mdx` works with
 //                 no configuration.
+// * `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.
@@ -34,6 +41,7 @@ import path from "node:path";
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
 
+import { assetPlugin } from "./internal/assets.js";
 import { emit, reportRenderError } from "./internal/events.js";
 import { highlightPlugin } from "./internal/highlight.js";
 import remarkFrontmatter from "remark-frontmatter";
@@ -99,8 +107,17 @@ export default function uniflowed(options = {}) {
   const routerRoot = app.router?.root ?? "app";
   const appEntry = app.router?.entry ?? ufConfig.build?.entries?.[0] ?? "app.js";
   const markdown = app.builtins?.markdown ?? {};
-
-  return [flowPlugin({ routerRoot, appEntry, command: options.command }), mdxPlugin(markdown)];
+  const builtins = app.builtins ?? {};
+
+  return [
+    flowPlugin({ routerRoot, appEntry, command: options.command }),
+    mdxPlugin(markdown),
+    assetPlugin({
+      images: builtins.images ?? {},
+      fonts: builtins.fonts ?? {},
+      command: options.command,
+    }),
+  ];
 }
 
 function flowPlugin({ routerRoot, appEntry, command }) {
@@ -387,21 +404,40 @@ function flowPlugin({ routerRoot, appEntry, command }) {
             // `after()` runs than the same project run through `uf dev`; see
             // `internal/serve.js` and ubugeeei-prod/uf#389.
             //
-            // Only document requests reach here, so unlike `driver.js` there is
-            // no path where uf hands the response back to Vite's chain: what is
-            // below either writes it or throws.
+            // Only requests that look like a document reach here, so unlike
+            // `driver.js` there is no path where uf hands the response back to
+            // Vite's chain: what is below either writes it or throws.
             await withRequest(entry, asRequest, async () => {
-              // Before the page: a middleware guards a subtree, and a page
-              // rendered while the guard on it had not run is the whole of
-              // ubugeeei-prod/uf#260. Only document requests reach here, so this
-              // is the page half of the guarantee; `driver.js` makes the same
-              // call above the route handlers, for every method.
+              // Before anything answers: a middleware guards a subtree, and a
+              // page rendered while the guard on it had not run is the whole of
+              // ubugeeei-prod/uf#260. `driver.js` makes the same call, for
+              // every method.
               const guarded = await entry.runMiddleware(asRequest);
               if (guarded != null) {
                 await send(response, guarded);
                 return;
               }
 
+              // Then the route handlers, above the renderer and for the same
+              // reason `driver.js` puts them there: a path that answers a
+              // request is not a document, whatever the client said it would
+              // accept. `curl /api/thing` and a `<form action>` navigation both
+              // send `Accept: text/html`, and both want the handler's answer.
+              //
+              // This step is not a duplicate of the dispatcher in `driver.js`,
+              // it is the only one that can run: this middleware is mounted by
+              // `configureServer`, which Vite calls while it is building the
+              // server, and `uf dev` adds its own after `createServer` has
+              // returned — so for every request this one claims, it is the one
+              // that decides. Without it a route handler under `uf dev` was
+              // reachable only by a client that asked for something other than
+              // HTML, and answered the 404 page to everyone else.
+              const handled = await entry.dispatch(asRequest);
+              if (handled != null) {
+                await send(response, handled);
+                return;
+              }
+
               const result = await entry.render(
                 url,
                 { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },

package/internal/assets.js

@@ -0,0 +1,396 @@
+// @noflow
+//
+// Plain JavaScript: Vite imports this module directly, before any transform.
+//
+// `uf:asset` — what an imported image or font becomes.
+//
+// The name and the hook set are not new. `crates/uf_plugin/src/builtin.rs` has
+// declared `uf:asset` — "resolves, fingerprints, and emits non-JavaScript
+// imports", `resolveId` + `load` + `generateBundle` + `writeBundle` +
+// `transformIndexHtml` — since before there was anything behind it, and
+// `uf inspect` has been listing it in the resolved pipeline. This is the
+// implementation of a plugin uf was already claiming to run.
+//
+// # What an import becomes
+//
+// ```js
+// import hero from "./hero.jpg";
+// <Image src={hero} alt="…" sizes="(max-width: 640px) 100vw, 640px" />
+// ```
+//
+// `hero` is not a URL string. It is the manifest `crates/uf_assets` produced —
+// the intrinsic width and height, every emitted variant with its own width, the
+// blur placeholder — because a `srcSet` can only be written by something that
+// knows which other sizes exist, and a URL string does not.
+//
+// A font import is the same shape: the self-hosted file, the `@font-face` rules
+// that declare it, and the metric-matched fallback.
+//
+// # Where the work happens, and when
+//
+// In `uf`, over the `uf assets` protocol — one native process for the whole
+// build rather than an image codec in the dependency tree. Both schedules go
+// through the same process with the same parameters, and both write to the
+// same cache directory:
+//
+// * **`uf build`** reads each emitted variant out of the cache and hands it to
+//   Rollup with `emitFile`, so the bundler owns what lands in `dist/` and the
+//   size report counts it.
+// * **`uf dev`** serves the same files out of the same cache directory over a
+//   middleware, transformed on the first import and reused after.
+//
+// The files are named by a content hash of the source and the parameters, so
+// the second build of an unchanged image does no work in either mode and a dev
+// session warms the cache a build then reuses. That is also the whole of "the
+// two must agree": there is one pipeline and one set of bytes, and the only
+// thing that differs between them is the URL prefix they are served under.
+//
+// # What this plugin deliberately does not claim
+//
+// An import with a query — `./hero.png?url`, `?raw`, `?inline` — is left to
+// Vite. Those are Vite's own asset conventions and a project reaching for one
+// is reaching past uf on purpose; claiming them here would make a documented
+// Vite feature unreachable from a uf project, which is red line 8 in
+// `docs/red-lines.md`. `import hero from "./hero.png"` is uf's; everything
+// with a `?` after it is Vite's.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { AssetService, assetKind } from "@uniflowed/host/assets";
+
+/** Where transformed assets are kept, relative to the project root. */
+export const CACHE_DIR = ".uf/cache/assets";
+
+/**
+ * The URL prefix a dev server answers transformed assets on.
+ *
+ * `@` first, following the convention Vite uses for everything that is not a
+ * file in the project: it cannot collide with a real path, and Vite's own
+ * middlewares leave it alone.
+ */
+export const DEV_PREFIX = "@uf-asset/";
+
+/**
+ * The module source for one transformed asset.
+ *
+ * A frozen object literal rather than a JSON blob assigned to a variable: this
+ * is what the component destructures, it is small, and a build that inlines it
+ * into the one component that used it is the right outcome.
+ */
+export function assetModuleSource(manifest) {
+  return `export default Object.freeze(${JSON.stringify(manifest)});\n`;
+}
+
+/**
+ * The `srcSet` for one format, and the URLs that go in it.
+ *
+ * Written here rather than in the component so that a build and a dev server
+ * cannot produce different strings from the same manifest: the only input that
+ * differs between them is `baseUrl`, and it is an argument.
+ */
+export function withUrls(image, baseUrl) {
+  const variants = image.variants.map((variant) => ({
+    ...variant,
+    url: `${baseUrl}${variant.file}`,
+  }));
+  // Widest last within a format, which is the order a `srcset` reads best in
+  // and the order `sizes` is evaluated against.
+  variants.sort((left, right) => left.width - right.width);
+
+  const formats = [];
+  for (const variant of variants) {
+    if (variant.format === image.format) continue;
+    if (!formats.includes(variant.format)) formats.push(variant.format);
+  }
+
+  const srcSetFor = (format) =>
+    variants
+      .filter((variant) => variant.format === format)
+      // `640w` and not `2x`: a density descriptor describes one layout width,
+      // and the whole point of the ladder is that the layout width is not
+      // known here. With `w`, the browser combines it with `sizes` and picks.
+      .map((variant) => `${variant.url} ${variant.width}w`)
+      .join(", ");
+
+  const fallbacks = variants.filter((variant) => variant.format === image.format);
+  const widest = fallbacks[fallbacks.length - 1] ?? variants[variants.length - 1];
+
+  return {
+    src: widest?.url ?? null,
+    width: image.width,
+    height: image.height,
+    srcSet: srcSetFor(image.format),
+    // Alternatives first: a browser takes the first `<source>` it understands,
+    // so the format every browser understands must not be offered before the
+    // ones that are smaller.
+    sources: formats.map((format) => ({
+      type: variants.find((variant) => variant.format === format).mime,
+      srcSet: srcSetFor(format),
+    })),
+    blurDataURL: image.blur,
+    // Carried through so a project can see what the pipeline decided and why,
+    // rather than having to infer it from what is missing: `hero.declined` is
+    // the widths where the alternative format was encoded and came out larger,
+    // with both byte counts. Nothing prints them — a line on every build about
+    // a format that was correctly not emitted is noise — and `uf explain build`
+    // is where the limit itself is stated.
+    declined: image.declined,
+    note: image.note,
+  };
+}
+
+/**
+ * uf's asset pipeline, as a Vite plugin.
+ *
+ * @param {object} options
+ * @param {object} [options.images] `app.builtins.images`
+ * @param {object} [options.fonts] `app.builtins.fonts`
+ * @param {string} [options.command] the `uf` binary to transform through
+ */
+export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
+  // Both halves can be turned off independently, and a plugin that is off is
+  // still in the array: `uf inspect` lists the resolved pipeline, and a
+  // pipeline that changes shape when a feature is disabled is a pipeline whose
+  // listing cannot be compared between two projects.
+  const imagesOn = images.enabled !== false;
+  const fontsOn = fonts.enabled !== false;
+
+  let root = process.cwd();
+  let base = "/";
+  let assetsDir = "assets";
+  let isBuild = false;
+  /** @type {import("vite").ViteDevServer | null} */
+  let server = null;
+  /** @type {AssetService | null} */
+  let service = null;
+  /**
+   * The manifest for each source path, so one image is transformed once.
+   *
+   * `uf build` runs Vite twice over the same modules — once for the browser
+   * bundle and once for the server one — from a single plugin array, so both
+   * passes share this map and the second decodes nothing. It survives
+   * `buildEnd` deliberately: clearing it there is what made the server pass
+   * redo every image, which is the whole cost this map exists to avoid.
+   */
+  const transformed = new Map();
+
+  const cacheDir = () => path.resolve(root, CACHE_DIR);
+  /**
+   * The `uf assets` process, started on the first asset and not before.
+   *
+   * Lazily rather than in `buildStart`, which is where `uf:flow` starts its
+   * transform service: that one is going to be asked about every module in the
+   * project, and this one is asked about nothing at all in a project that
+   * imports no images or fonts. A build that has no use for an image codec
+   * should not spawn one.
+   */
+  const ensureService = () => {
+    service ??= new AssetService({ command, root });
+    return service;
+  };
+
+  /**
+   * Where a transformed file is served from.
+   *
+   * A build's URL is the bundler's output directory; a dev server's is this
+   * plugin's own middleware. This is the *only* thing that differs between the
+   * two schedules, and it is one string.
+   */
+  const baseUrl = () => (isBuild ? `${base}${assetsDir}/` : `${base}${DEV_PREFIX}`);
+
+  const claims = (id) => {
+    // A query is Vite's, not uf's. See the header.
+    if (id.includes("?")) return null;
+    if (id.startsWith("\0")) return null;
+    const kind = assetKind(id);
+    if (kind === "image" && !imagesOn) return null;
+    if (kind === "font" && !fontsOn) return null;
+    return kind;
+  };
+
+  return {
+    name: "uf:asset",
+    // Before Vite's own asset handling, which would otherwise claim the same
+    // extensions and return a URL string.
+    enforce: "pre",
+
+    configResolved(config) {
+      root = config.root;
+      base = config.base;
+      assetsDir = config.build?.assetsDir ?? "assets";
+      isBuild = config.command === "build";
+    },
+
+    async load(id) {
+      const kind = claims(id);
+      if (kind == null) return null;
+      const file = path.resolve(id);
+      // Not this plugin's to fail on: an id with one of these extensions that
+      // is not a file on disk is a virtual module somebody else owns.
+      if (!existsSync(file)) return null;
+
+      return loadAsset.call(this, {
+        kind,
+        file,
+        transformed,
+        service: ensureService(),
+        cacheDir: cacheDir(),
+        baseUrl: baseUrl(),
+        assetsDir,
+        isBuild,
+        images,
+        fonts,
+      });
+    },
+
+    configureServer(devServer) {
+      server = devServer;
+      devServer.httpServer?.once("close", () => {
+        service?.close();
+        service = null;
+      });
+
+      // Before Vite's own middlewares: nothing else knows this prefix, and the
+      // files are outside the module graph, so there is nothing to wait for.
+      const directory = cacheDir();
+      devServer.middlewares.use((request, response, next) => {
+        const url = request.url ?? "";
+        const at = url.indexOf(DEV_PREFIX);
+        if (at === -1) return next();
+        const name = decodeURIComponent(url.slice(at + DEV_PREFIX.length).split("?")[0]);
+        // The name is a file name and nothing else. Every emitted name is one
+        // path segment by construction, so a request carrying a separator is
+        // not a name this plugin ever minted — refusing it rather than
+        // resolving it is what keeps the cache directory from being a way to
+        // read the rest of the disk.
+        if (name === "" || name.includes("/") || name.includes("\\") || name.includes("..")) {
+          response.statusCode = 400;
+          response.end("bad asset name");
+          return;
+        }
+        const target = path.join(directory, name);
+        if (!existsSync(target)) return next();
+        response.setHeader("Content-Type", contentTypeOf(name));
+        // The name is a content hash, so the bytes under it never change.
+        response.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+        response.end(readFileSync(target));
+      });
+    },
+
+    watchChange(id) {
+      // The memo below is what stops `uf build` decoding every image twice,
+      // once per bundle. In a dev server it would also stop uf ever noticing
+      // that an image was edited: Vite invalidates the module and calls `load`
+      // again, and `load` would hand back the manifest it made before the
+      // change. Dropping both keys is cheap and the next `load` redoes the
+      // work — which, because the emitted names are content hashes, writes new
+      // files and leaves the old ones for anything still holding a URL.
+      transformed.delete(`image:${path.resolve(id)}`);
+      transformed.delete(`font:${path.resolve(id)}`);
+    },
+
+    buildEnd() {
+      // A dev server keeps its service for the whole session; a build is done
+      // with it here. The same rule `uf:flow` follows next door.
+      //
+      // `transformed` is *not* cleared. A build's second pass over the same
+      // modules then needs no process at all — every answer is already in the
+      // map, and `ensureService` is never reached.
+      if (server == null) {
+        service?.close();
+        service = null;
+      }
+    },
+  };
+}
+
+/**
+ * Transform one asset and return the module that stands for it.
+ *
+ * Split out of the hook so the hook stays readable and so the memoisation is
+ * visible: `uf build` runs Vite twice over the same modules, once for the
+ * browser bundle and once for the server one, and an image transformed on both
+ * passes would be decoded twice for one build.
+ */
+async function loadAsset(context) {
+  const { kind, file, transformed, service, cacheDir, baseUrl, assetsDir, isBuild, images, fonts } =
+    context;
+  const key = `${kind}:${file}`;
+  let manifest = transformed.get(key);
+  if (manifest == null) {
+    manifest =
+      kind === "image"
+        ? await service.image(file, {
+            outDir: cacheDir,
+            widths: images.widths,
+            quality: images.quality,
+            blur: images.placeholder,
+          })
+        : await service.font(file, {
+            outDir: cacheDir,
+            family: fonts.family,
+            display: fonts.display,
+            baseUrl,
+          });
+    transformed.set(key, manifest);
+  }
+
+  const files = kind === "image" ? manifest.variants.map((v) => v.file) : [manifest.file];
+  if (isBuild) {
+    // Handed to Rollup rather than copied by hand, so the bundler owns what
+    // lands in the output directory and `uf_bundle`'s size report — which
+    // walks that directory — counts every one of them.
+    for (const name of files) {
+      this.emitFile({
+        type: "asset",
+        // `fileName` rather than `name`: the name is already a content hash of
+        // the source and the parameters, and letting Rollup hash it again
+        // would move it on every encoder change while saying nothing new.
+        fileName: `${assetsDir}/${name}`,
+        source: readFileSync(path.join(cacheDir, name)),
+      });
+    }
+  }
+
+  if (kind === "image") {
+    return assetModuleSource(withUrls(manifest, baseUrl));
+  }
+  return assetModuleSource({
+    src: `${baseUrl}${manifest.file}`,
+    family: manifest.family,
+    fallbackFamily: manifest.fallbackFamily,
+    // The stack a page should set `font-family` to: the real face, then the
+    // metric-matched fallback, then the local face it was scaled from. Written
+    // here so no page has to remember that the fallback only ever applies when
+    // it is named after the real face.
+    fontFamily: [manifest.family, manifest.fallbackFamily, manifest.fallback?.local]
+      .filter((name) => name != null)
+      .map((name) => JSON.stringify(name))
+      .join(", "),
+    type: manifest.mime,
+    css: manifest.css,
+    metrics: manifest.metrics,
+    fallback: manifest.fallback,
+    fallbackDeclined: manifest.fallbackDeclined,
+  });
+}
+
+/** The media type for one emitted file name. */
+function contentTypeOf(name) {
+  const extension = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
+  const types = {
+    avif: "image/avif",
+    gif: "image/gif",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    otf: "font/otf",
+    png: "image/png",
+    svg: "image/svg+xml",
+    ttf: "font/ttf",
+    webp: "image/webp",
+    woff: "font/woff",
+    woff2: "font/woff2",
+  };
+  return types[extension] ?? "application/octet-stream";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.8",
+  "version": "0.0.0-alpha.9",
   "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",
@@ -25,8 +25,8 @@
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.8",
-    "@uniflowed/server": "0.0.0-alpha.8",
+    "@uniflowed/host": "0.0.0-alpha.9",
+    "@uniflowed/server": "0.0.0-alpha.9",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",