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

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,7 +40,7 @@
 // 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";
@@ -97,7 +99,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)}` });
@@ -680,6 +682,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`.
  *
@@ -887,6 +1030,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");

package/index.js

@@ -79,6 +79,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,19 +123,26 @@ 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;
 
   return [
-    flowPlugin({ routerRoot, appEntry, command: options.command }),
+    flowPlugin({ routerRoot, appEntry, strictMode, command: options.command }),
     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 }) {
   let root = process.cwd();
   let isProduction = false;
   let base = "/";
@@ -305,7 +313,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 +417,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 [
+        {
+          tag: "script",
+          children: devtoolsPreamble(),
+          injectTo: "head-prepend",
+        },
         {
           tag: "script",
           attrs: { type: "module" },

package/internal/assets.js

@@ -9,7 +9,10 @@
 // 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.
+// implementation of a plugin uf was already claiming to run — and `resolveId`
+// and `generateBundle`, declared there from the start and unimplemented until
+// icons arrived, are now real: the first resolves `uf:icon/…`, the second
+// assembles the sprite once the graph is complete.
 //
 // # What an import becomes
 //
@@ -45,6 +48,19 @@
 // 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.
 //
+// # Icons, and why they are not `.svg`
+//
+// `import Star from "uf:icon/star"` resolves against the directory
+// `app.builtins.icons.dir` names, and `import sprite from "uf:icon-sprite"` is
+// the sprite built from every icon the build reached. Neither claims an
+// extension, which is the point: `.svg` stays Vite's, so `vite-plugin-svgr`
+// and everything like it keep working, and uf adds a capability in its own
+// namespace instead of taking one away.
+//
+// The sprite is emitted in `generateBundle`, which is the first hook that runs
+// after every module has been loaded — and therefore the first moment the set
+// of icons a build reached is the whole set.
+//
 // # What this plugin deliberately does not claim
 //
 // An import with a query — `./hero.png?url`, `?raw`, `?inline` — is left to
@@ -57,7 +73,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
-import { AssetService, assetKind } from "@uniflowed/host/assets";
+import {
+  AssetService,
+  ICON_PREFIX,
+  ICON_SPRITE,
+  OG_EXTENSION,
+  assetKind,
+} from "@uniflowed/host/assets";
 
 /** Where transformed assets are kept, relative to the project root. */
 export const CACHE_DIR = ".uf/cache/assets";
@@ -71,6 +93,36 @@ export const CACHE_DIR = ".uf/cache/assets";
  */
 export const DEV_PREFIX = "@uf-asset/";
 
+/**
+ * What stands in for the sprite until `generateBundle` knows what is in it.
+ *
+ * A string no source file would contain, replaced in the generated chunk once
+ * every module has been loaded. The module graph needs *something* at `load`
+ * time and the sprite is not knowable then; see the `sprite` branch of `load`.
+ */
+const SPRITE_PLACEHOLDER = "__UF_ICON_SPRITE__";
+
+/**
+ * What a `*.og.json` import resolves to.
+ *
+ * A card cannot keep its own id, and the reason is worth writing down because
+ * nothing about `enforce: "pre"` prevents it. Vite's JSON handling is a
+ * *native* rolldown plugin, `builtin:vite-json`, and it selects modules by
+ * **id**: anything still ending in `.json` when its `transform` runs is put
+ * through a JSON parser, whatever an earlier `load` returned. Ordering the
+ * hooks does not help, because the module this plugin loads is JavaScript
+ * under a name that says JSON — and the parser's answer is
+ * `expected value at line 1 column 1`.
+ *
+ * So the id changes rather than the order. The card resolves to
+ * `\0uf-og:<absolute path>.js`: `\0` is the convention for a module that is
+ * not a file, and the trailing extension is what takes it out of every
+ * `.json` filter in the pipeline.
+ */
+const OG_PREFIX = "\0uf-og:";
+/** Appended to that id so it does not end in `.json`. See [`OG_PREFIX`]. */
+const OG_SUFFIX = ".js";
+
 /**
  * The module source for one transformed asset.
  *
@@ -146,15 +198,20 @@ export function withUrls(image, baseUrl) {
  * @param {object} options
  * @param {object} [options.images] `app.builtins.images`
  * @param {object} [options.fonts] `app.builtins.fonts`
+ * @param {object} [options.icons] `app.builtins.icons`
+ * @param {object} [options.og] `app.builtins.og`
  * @param {string} [options.command] the `uf` binary to transform through
  */
-export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
+export function assetPlugin({ images = {}, fonts = {}, icons = {}, og = {}, 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;
+  const iconsOn = icons.enabled !== false;
+  const ogOn = og.enabled !== false;
+  const iconDir = icons.dir ?? "icons";
 
   let root = process.cwd();
   let base = "/";
@@ -174,6 +231,18 @@ export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
    * redo every image, which is the whole cost this map exists to avoid.
    */
   const transformed = new Map();
+  /** Whether anything imported the sprite at all. */
+  let spriteRequested = false;
+  /**
+   * Every icon this build has reached, by symbol id.
+   *
+   * Here and not in the `uf assets` process, because this closure outlives it:
+   * a build closes the service in `buildEnd`, which runs *before*
+   * `generateBundle`, and a build with a client environment and a server one
+   * has two bundles and one set of icons between them. The plugin is what
+   * spans a build, so the plugin is what remembers.
+   */
+  const reachedIcons = new Map();
 
   const cacheDir = () => path.resolve(root, CACHE_DIR);
   /**
@@ -206,9 +275,32 @@ export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
     const kind = assetKind(id);
     if (kind === "image" && !imagesOn) return null;
     if (kind === "font" && !fontsOn) return null;
+    if (kind === "og" && !ogOn) return null;
+    if ((kind === "icon" || kind === "sprite") && !iconsOn) return null;
     return kind;
   };
 
+  /**
+   * The file one `uf:icon/<name>` names.
+   *
+   * The name is a path segment and nothing else. `..` in it would reach out of
+   * the icon directory and turn an import into a way to read the repository,
+   * so it is rejected rather than resolved — the same rule the dev middleware
+   * applies to an emitted file name.
+   */
+  const iconFile = (id) => {
+    const name = id.slice(ICON_PREFIX.length);
+    if (name === "" || name.includes("..") || path.isAbsolute(name)) return null;
+    return { name, file: path.resolve(root, iconDir, `${name}.svg`) };
+  };
+
+  /** Tell a dev server the sprite it already sent is missing an icon. */
+  const invalidateSprite = () => {
+    if (server == null || !spriteRequested) return;
+    const module = server.moduleGraph.getModuleById(ICON_SPRITE);
+    if (module != null) server.moduleGraph.invalidateModule(module);
+  };
+
   return {
     name: "uf:asset",
     // Before Vite's own asset handling, which would otherwise claim the same
@@ -222,9 +314,93 @@ export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
       isBuild = config.command === "build";
     },
 
+    // `uf:icon/…` and `uf:icon-sprite` are uf's own ids and resolve to
+    // themselves. Returning the id unchanged rather than a `\0`-prefixed one
+    // keeps it readable in a stack trace and in `vite --debug`, and nothing
+    // else in the pipeline claims the `uf:` scheme.
+    //
+    // A card is the opposite case: it has to *lose* its name, because the name
+    // is what the native JSON plugin claims it by. See `OG_PREFIX`.
+    async resolveId(id, importer, options) {
+      if (iconsOn && (id === ICON_SPRITE || id.startsWith(ICON_PREFIX))) return id;
+      if (!ogOn || !id.toLowerCase().endsWith(OG_EXTENSION)) return null;
+      // Compared against the id as written, so a query is never claimed:
+      // `./card.og.json?raw` and `?url` still reach the file, because a query
+      // is Vite's.
+      const resolved = await this.resolve(id, importer, { ...options, skipSelf: true });
+      if (resolved == null || resolved.external || !existsSync(resolved.id)) return resolved;
+      return `${OG_PREFIX}${resolved.id}${OG_SUFFIX}`;
+    },
+
     async load(id) {
+      if (id.startsWith(OG_PREFIX)) {
+        const file = id.slice(OG_PREFIX.length, -OG_SUFFIX.length);
+        // Watched by hand, because the module id is no longer the file's path
+        // and nothing else would associate the two. Without this a dev server
+        // never redraws a card whose template was edited.
+        this.addWatchFile(file);
+        return loadAsset.call(this, {
+          kind: "og",
+          file,
+          transformed,
+          service: ensureService(),
+          cacheDir: cacheDir(),
+          baseUrl: baseUrl(),
+          assetsDir,
+          isBuild,
+          images,
+          fonts,
+        });
+      }
+
       const kind = claims(id);
       if (kind == null) return null;
+
+      if (kind === "sprite") {
+        spriteRequested = true;
+        // A build cannot know the sprite here: `load` runs while the graph is
+        // still being walked, so the set of icons reached so far is not the
+        // set. It emits a placeholder that `generateBundle` — the first hook
+        // after every module has been loaded — replaces with the real markup.
+        //
+        // A dev server has no `generateBundle`, so it assembles from what has
+        // been reached and invalidates this module whenever a new icon turns
+        // up. That costs one extra reload the first time a page introduces an
+        // icon and is exactly right afterwards, which is the trade a dev
+        // server makes everywhere else too.
+        if (isBuild) return assetModuleSource({ markup: SPRITE_PLACEHOLDER });
+        const sprite = await ensureService().sprite({
+          outDir: cacheDir(),
+          icons: [...reachedIcons.values()],
+        });
+        return assetModuleSource({ markup: sprite.markup });
+      }
+
+      if (kind === "icon") {
+        const resolved = iconFile(id);
+        if (resolved == null) return null;
+        if (!existsSync(resolved.file)) {
+          this.error(
+            `${id} does not exist: uf looked for ${path.relative(root, resolved.file)}. ` +
+              "`app.builtins.icons.dir` is where `uf:icon/…` resolves against.",
+          );
+        }
+        const asset = await ensureService().icon(resolved.file, {
+          outDir: cacheDir(),
+          name: resolved.name,
+        });
+        this.addWatchFile(resolved.file);
+        reachedIcons.set(asset.id, asset);
+        invalidateSprite();
+        return assetModuleSource({
+          id: asset.id,
+          href: `#${asset.id}`,
+          viewBox: asset.viewBox,
+          width: asset.width,
+          height: asset.height,
+        });
+      }
+
       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.
@@ -244,6 +420,38 @@ export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
       });
     },
 
+    // After every module has been loaded, which is the first moment the set of
+    // icons this build reached is the whole set. A sprite assembled in `load`
+    // would hold the icons reached *so far*, which is a different sprite on
+    // every run depending on module order.
+    async generateBundle(_options, bundle) {
+      if (!iconsOn || !spriteRequested) return;
+      const sprite = await ensureService().sprite({
+        outDir: cacheDir(),
+        icons: [...reachedIcons.values()],
+      });
+      // Inlined into the chunk and *not* emitted as a file of its own. An
+      // external sprite would be the better answer if it worked — one file
+      // cached across every page — but `<use href="sprite.svg#id">` does not
+      // resolve across documents in any version of Safari and is blocked
+      // cross-origin in Chrome, so the file would be dead weight in `dist/`
+      // and in `uf_bundle`'s size report. `uf assets` still writes it into the
+      // cache directory, which is where the dev server reads it from.
+      //
+      // The placeholder is replaced rather than the module re-run: by
+      // `generateBundle` the chunk is already generated, and the sprite is one
+      // string literal in it.
+      //
+      // A function replacement, because a plain string one would interpret
+      // `$&` and `$'` — and an icon is somebody else's markup.
+      const escaped = JSON.stringify(sprite.markup).slice(1, -1);
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type === "chunk" && chunk.code.includes(SPRITE_PLACEHOLDER)) {
+          chunk.code = chunk.code.replaceAll(SPRITE_PLACEHOLDER, () => escaped);
+        }
+      }
+    },
+
     configureServer(devServer) {
       server = devServer;
       devServer.httpServer?.once("close", () => {
@@ -288,6 +496,7 @@ export function assetPlugin({ images = {}, fonts = {}, command } = {}) {
       // files and leaves the old ones for anything still holding a URL.
       transformed.delete(`image:${path.resolve(id)}`);
       transformed.delete(`font:${path.resolve(id)}`);
+      transformed.delete(`og:${path.resolve(id)}`);
     },
 
     buildEnd() {
@@ -319,24 +528,38 @@ async function loadAsset(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,
-          });
+    if (kind === "image") {
+      manifest = await service.image(file, {
+        outDir: cacheDir,
+        widths: images.widths,
+        quality: images.quality,
+        blur: images.placeholder,
+      });
+    } else if (kind === "og") {
+      manifest = await service.og(file, { outDir: cacheDir });
+    } else {
+      manifest = await service.font(file, {
+        outDir: cacheDir,
+        family: fonts.family,
+        display: fonts.display,
+        subset: fonts.subset,
+        preload: fonts.preload,
+        baseUrl,
+      });
+    }
     transformed.set(key, manifest);
   }
 
-  const files = kind === "image" ? manifest.variants.map((v) => v.file) : [manifest.file];
+  const files =
+    kind === "image"
+      ? manifest.variants.map((v) => v.file)
+      : kind === "og"
+        ? [manifest.file]
+        : // Every bucket, not just the primary: a `unicode-range` split emits
+          // one file per script and the browser fetches whichever the page
+          // needs. Emitting only the one the manifest calls primary would
+          // leave the others named in the stylesheet and absent from `dist/`.
+          manifest.faces.map((face) => face.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
@@ -356,6 +579,18 @@ async function loadAsset(context) {
   if (kind === "image") {
     return assetModuleSource(withUrls(manifest, baseUrl));
   }
+  if (kind === "og") {
+    return assetModuleSource({
+      // The shape `Metadata.openGraph.images` and `OgImage` both read. A URL,
+      // a size and the alt text, which is all a card ever is to a page.
+      url: `${baseUrl}${manifest.file}`,
+      width: manifest.width,
+      height: manifest.height,
+      type: manifest.mime,
+      alt: manifest.alt,
+      bytes: manifest.bytes,
+    });
+  }
   return assetModuleSource({
     src: `${baseUrl}${manifest.file}`,
     family: manifest.family,
@@ -373,6 +608,19 @@ async function loadAsset(context) {
     metrics: manifest.metrics,
     fallback: manifest.fallback,
     fallbackDeclined: manifest.fallbackDeclined,
+    // Every emitted file with its URL, so `Font` can preload exactly the one
+    // marked rather than all of them — which is the one thing that would undo
+    // a `unicode-range` split.
+    faces: (manifest.faces ?? []).map((face) => ({
+      ...face,
+      url: `${baseUrl}${face.file}`,
+    })),
+    subset: manifest.subset ?? null,
+    // Carried through for the same reason `declined` is on an image: a project
+    // that asked for a subset and got the whole font is entitled to the
+    // sentence saying why, without reading this plugin.
+    subsetDeclined: manifest.subsetDeclined ?? null,
+    sourceBytes: manifest.sourceBytes ?? null,
   });
 }
 

package/internal/devtools.js

@@ -0,0 +1,117 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// React DevTools, in `uf dev`, on purpose.
+//
+// DevTools does not attach to React. React attaches to *DevTools*: while
+// `react-dom` is being evaluated it looks for `__REACT_DEVTOOLS_GLOBAL_HOOK__`
+// on the global object and registers itself with whatever it finds, once. A
+// hook that arrives after that line has run is a hook no renderer ever sees, so
+// everything below is about one ordering — the hook exists first — and about
+// saying so in a file whose name a person can grep for.
+//
+// # Why this file exists at all, when it worked before it
+//
+// It did work, and by accident. The Fast Refresh preamble calls
+// `injectIntoGlobalHook` (`./refresh-runtime.js`, Meta's runtime as vendored by
+// `@vitejs/plugin-react`), and that function installs a hook when it finds
+// none, because Fast Refresh needs one to decorate. So `uf dev` had a DevTools
+// hook as a side effect of a function whose subject is hot reloading, in a file
+// uf does not own, with nothing anywhere naming DevTools and no test that would
+// notice its absence. The next upgrade of that vendored runtime, or a change to
+// how the preamble is injected, could have taken it away in a diff nobody would
+// read as being about DevTools. See ubugeeei-prod/uf#503.
+//
+// So the hook is installed here, first, deliberately, and `tests/library/
+// devtools.test.js` runs this script's own text against a fake window.
+//
+// # Three things DevTools needs, and what carries each
+//
+// Naming them together, because each is provided somewhere else and each is one
+// edit away from being lost:
+//
+//   1. **The hook, before the renderer.** This module, injected by
+//      `packages/vite/index.js`'s `transformIndexHtml` as a *classic* script at
+//      the top of the head — see [`devtoolsPreamble`] for why classic.
+//   2. **One copy of the renderer.** `resolve.dedupe: ["react", "react-dom"]`
+//      in that same file. Two copies of `react-dom` register two renderers, and
+//      DevTools shows the tree of whichever one it heard from — which is the
+//      shape of the "multiple renderers concurrently rendering" report.
+//   3. **The development build of it.** `mode` is `development`, so Vite
+//      resolves React's development export condition, and `uf transform` is
+//      called with `development: true` — which is what emits `jsxDEV` and the
+//      `_jsxFileName` beside every element. Against a production build DevTools
+//      says so and shows a tree with no props, no hooks and no source.
+//
+// # And out of a production build
+//
+// A production build injects none of this: `transformIndexHtml` returns an
+// empty list unless the plugin is serving. That is the half a person can check
+// on the artefact rather than by reading, and
+// `crates/uf_cli/tests/vite.rs`'s `a_build_ships_no_devtools_hook` does.
+//
+// What it checks for is the *assignment* below rather than the name, and the
+// distinction is worth stating here because the obvious test is wrong: React's
+// own production build mentions `__REACT_DEVTOOLS_GLOBAL_HOOK__` twice, because
+// reading that global is how a deployed React application is attachable at all.
+// React reads it; only an installer writes it. So `window.<hook> =` is what
+// must be absent, and it is absent because this function is never called
+// outside a dev server.
+
+/**
+ * The global React registers itself with.
+ *
+ * Written once, here, so that every other mention of it in uf — the injected
+ * script below, the assertion that a build has none — is this constant rather
+ * than a fourth spelling of a name whose whole value is that it matches
+ * React's exactly.
+ */
+export const DEVTOOLS_HOOK = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+
+/**
+ * The script every document loads before anything else in development.
+ *
+ * # A classic script, not a module
+ *
+ * Everything else uf injects is `type="module"`, and a module script is
+ * deferred: it runs after the document has been parsed, in document order with
+ * the other modules. That would still be early enough today, because the client
+ * entry is also a module and comes later — but "early enough as long as nobody
+ * adds a script above it" is exactly the accident this file exists to end. A
+ * classic inline script runs while the parser is on it, so no module, no
+ * import, and no `<script src>` a project's own Vite plugin injects can get
+ * between this and the renderer.
+ *
+ * # It never replaces a hook that is already there
+ *
+ * The DevTools extension installs its hook at `document_start`, which is before
+ * any script in the document, so on a machine that has DevTools the branch
+ * below is not taken and the extension's hook is what React registers with.
+ * Overwriting it would be the one way this file could break the thing it exists
+ * to support: the extension holds the connection to the panel, and a stub in
+ * its place is a page DevTools can see and never hear from.
+ *
+ * What is installed when there is nothing to leave alone is the minimum a
+ * renderer will register with — `renderers`, `supportsFiber`, `inject` and the
+ * three commit callbacks. It reports nothing to anybody: there is no panel, and
+ * the point of installing it is that `react-dom` takes the branch where a hook
+ * exists, so Fast Refresh has one to decorate and DevTools opened *later* in
+ * the same page finds a renderer already registered rather than a page that has
+ * to be reloaded. It is the same shape `injectIntoGlobalHook` installs, because
+ * it is the same contract; the difference is that this is uf saying so.
+ */
+export function devtoolsPreamble() {
+  return `(function () {
+  if (window.${DEVTOOLS_HOOK} != null) return;
+  var nextID = 0;
+  window.${DEVTOOLS_HOOK} = {
+    renderers: new Map(),
+    supportsFiber: true,
+    inject: function () { return nextID++; },
+    onScheduleFiberRoot: function () {},
+    onCommitFiberRoot: function () {},
+    onCommitFiberUnmount: function () {},
+  };
+})();`;
+}

package/internal/diagnostics.js

@@ -16,8 +16,11 @@
 //
 //   * `POST /__uf/diagnostic` — a diagnostic a browser-side runtime produced
 //     and wants a person to read. `@uniflowed/router`'s `internal/diagnostics.js`
-//     is the client half, and the hydration-mismatch report beside it is what
-//     calls it.
+//     is the client half; the hydration-mismatch report beside it is what calls
+//     it, and so is `internal/devtools.js`, which reads back after hydration
+//     whether React DevTools can attach to this page at all
+//     (ubugeeei-prod/uf#503). One channel and not one per feature is the whole
+//     point: a second endpoint would be a second thing to notice.
 //   * `POST /__uf/vitals`     — the five numbers `@uniflowed/web/vitals`
 //     measures, posted by `vitalsBeacon()`. In production a project points the
 //     beacon at an endpoint of its own; in development there was nothing at

package/internal/routes.js

@@ -790,12 +790,28 @@ export default routes;
  * The current route's modules are loaded *before* hydration so the first
  * render is synchronous and matches the server's HTML; a lazy import during
  * hydration would suspend and React would fall back to a client render.
+ *
+ * # Strict Mode is a generated constant, not a runtime check
+ *
+ * `strictMode` is written into this module as a literal, so a production build
+ * gets `hydrate({ … })` with the argument absent and Rollup has nothing to
+ * decide. It would have been shorter to have `hydrate` read `import.meta.hot`
+ * — the way `client.js` gates the hydration reporter — and that would have been
+ * one signal answering two questions: `uf.config.js` can turn Strict Mode off
+ * (ubugeeei-prod/uf#516) and `import.meta.hot` cannot be told about it. A
+ * project that sets `app.react.strictMode: false` gets a dev server that
+ * hydrates the way its deployment does, which is the whole of the escape
+ * hatch.
+ *
+ * @param {string} appEntry the project's `app.js`, as an import specifier
+ * @param {{ strictMode?: boolean }} [options]
  */
-export function clientModuleSource(appEntry) {
+export function clientModuleSource(appEntry, options = {}) {
+  const strictMode = options.strictMode === true ? ", strictMode: true" : "";
   return `import { hydrate } from "@uniflowed/router/client";
 import { routes, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-hydrate({ App, routes, notFound, errors });
+hydrate({ App, routes, notFound, errors${strictMode} });
 `;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.14",
+  "version": "0.0.0-alpha.15",
   "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.14",
-    "@uniflowed/server": "0.0.0-alpha.14",
+    "@uniflowed/host": "0.0.0-alpha.15",
+    "@uniflowed/server": "0.0.0-alpha.15",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",