@uniflowed/vite 0.0.0-alpha.45 → 0.0.0-alpha.47

package/driver.js

@@ -49,6 +49,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { COMPILE_ASSETS_ID, compileAssetsPlugin } from "./internal/compile-assets.js";
+import { servesRemoteImages } from "./internal/image-endpoint.js";
 import {
   survivingImports,
   unavailableOnWorkers,
@@ -65,6 +66,7 @@ import { VIRTUAL, resolveRouteTarget, routingRulesOf, scanRoutes } from "./inter
 import {
   BUILD_ID_FILE,
   DOCUMENT_ASSETS_FILE,
+  PARTIAL_PRERENDER_FILE,
   REGENERATED_DIRECTORY,
   REGENERATION_FILE,
   answerRouting,
@@ -73,11 +75,13 @@ import {
   buildIdentity,
   createPrerenderGate,
   createServeHandler,
+  deploymentIdFor,
   documentAssetsFor,
   forViteBase,
   loadBuild,
   nodeListener,
   providerSpecifier,
+  readPartialPrerenders,
   readRegeneration,
   withRequest,
 } from "./internal/serve.js";
@@ -474,7 +478,13 @@ async function preview() {
   // 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 });
+    build == null
+      ? null
+      : createServeHandler({
+          ...build,
+          cache: config.app?.rendering?.cache,
+          images: config.app?.builtins?.images,
+        });
   const answer = (previewServer) => async (request, response, next) => {
     try {
       const asRequest = await toRequest(request, previewServer.config);
@@ -634,7 +644,11 @@ async function start() {
   const port = Number(argument("--port") ?? process.env.PORT ?? 3000);
   const server = createHttpServer(
     nodeListener(
-      createServeHandler({ ...build, cache: config.app?.rendering?.cache }),
+      createServeHandler({
+        ...build,
+        cache: config.app?.rendering?.cache,
+        images: config.app?.builtins?.images,
+      }),
       build.entry,
     ),
   );
@@ -699,8 +713,14 @@ async function build() {
   if (graph != null) {
     inline.plugins = [...(inline.plugins ?? []), graph.plugin];
   }
+  // What this build is called, minted before anything is bundled: the rsc
+  // graph bakes the public half into every payload it renders, and the
+  // documents below carry it in their head. See `deploymentIdFor`.
+  const buildId = mintBuildId();
+  const deployment = deploymentIdFor(buildId);
   const rscDir = path.join(root, ".uf", "build", "rsc");
   if (flight != null) {
+    flight.deployment = deployment;
     emit("phase", { name: "rsc" });
     await buildRscGraph(vite, inline, flight, { outDir: rscDir, conditions: null });
   }
@@ -761,7 +781,7 @@ async function build() {
   // build's URLs with the previous build's documents. See
   // `packages/server/internal/cache-key.js`, which argues the whole of it, and
   // `internal/serve.js`'s `buildIdentity`, which is what reads this.
-  writeFileSync(path.join(serverDir, BUILD_ID_FILE), `${mintBuildId()}\n`);
+  writeFileSync(path.join(serverDir, BUILD_ID_FILE), `${buildId}\n`);
 
   // Every bundle is built by here, and the prerender below builds none.
   graph?.write(path.join(root, ".uf", "build", "meta", MODULE_GRAPH_FILE));
@@ -774,10 +794,15 @@ async function build() {
   //    arrives here as one word, and this is where it meets the route table.
   emit("phase", { name: "prerender" });
   const server = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
-  const assets =
-    flight == null
+  const assets = {
+    ...(flight == null
       ? assetsFromManifest(manifest, basePathOf(config))
-      : flightAssets(manifest, references, rscDir, outDir, basePathOf(config));
+      : flightAssets(manifest, references, rscDir, outDir, basePathOf(config))),
+    // Which build these URLs are. Every document names it, a browser sends it
+    // back, and a server on another build refuses rather than answering with
+    // ids and chunks the page does not have. See `deploymentIdFor`.
+    deployment,
+  };
   // Recorded beside the server bundle, because whatever serves this build
   // later cannot recompute them from the client manifest alone; see
   // `documentAssetsFor`.
@@ -849,14 +874,30 @@ async function build() {
   // A tag without a lifetime is not enough, for the route cache's own reason:
   // an entry with no end is one another process could serve from its memory
   // for ever after `revalidateTag` took it out of the shared store.
+  //
+  // A page is written as a static shell when `uf` passed `--partial` — `ppr`
+  // allowed in `app.rendering.modes` and a server deployed to fill it — and the
+  // page read `cookies()`, `headers()` or `draftMode()` inside a `<Suspense>`
+  // boundary. The prerender then answers with a `shell` instead of a document:
+  // the markup React could render without a request, and React's record of the
+  // holes. Nothing is written under `dist/` for it, neither a document nor a
+  // payload, because a shell on its own is a page whose holes never fill and
+  // the browser hydrates from the request's payload. The shell goes into
+  // `PARTIAL_PRERENDER_FILE` beside the server bundle, and every server that
+  // serves this build answers the page from there. A page that read the
+  // request outside every boundary still fails, naming what it read.
   const { collectCacheDeclarations } = await import("@uniflowed/server/cache");
   const regenerate = flag("--regenerate");
+  const partialPrerender = flag("--partial");
   const regenerated = {};
+  const partial = {};
   for (const url of pages) {
     let declared;
     const renderedAt = Date.now();
     try {
-      declared = await collectCacheDeclarations(() => server.prerender(url, assets));
+      declared = await collectCacheDeclarations(() =>
+        server.prerender(url, assets, partialPrerender ? { partial: true } : undefined),
+      );
     } catch (error) {
       failed(url, error);
       continue;
@@ -866,6 +907,18 @@ async function build() {
       failed(url, result.error);
       continue;
     }
+    if (result.shell != null) {
+      partial[url] = result.shell;
+      emit("page", {
+        url,
+        file: path.relative(root, path.join(serverDir, PARTIAL_PRERENDER_FILE)),
+        status: result.status,
+        bytes: Buffer.byteLength(result.shell.html),
+        regenerates: false,
+        partial: true,
+      });
+      continue;
+    }
     const lifetime = declared.lifetime;
     const regenerates =
       regenerate && result.status === 200 && declared.denied == null && lifetime != null;
@@ -912,6 +965,12 @@ async function build() {
       `${JSON.stringify({ pages: regenerated }, null, 2)}\n`,
     );
   }
+  if (Object.keys(partial).length > 0) {
+    writeFileSync(
+      path.join(serverDir, PARTIAL_PRERENDER_FILE),
+      `${JSON.stringify({ pages: partial })}\n`,
+    );
+  }
   // One `404.html`, from the boundary at the router root: a static host serves
   // a single error document for the whole site, so the nested boundaries a
   // project declares are the server's and the client's to render, not
@@ -1233,6 +1292,18 @@ async function compile() {
   }
   const assets = path.resolve(root, assetsArgument);
   const bundleDir = path.resolve(root, bundleArgument);
+  // The compiled binary answers from `@uniflowed/server/standalone`, which has
+  // no `/__uf/image` — and it would still carry pages whose `Image` writes the
+  // endpoint's URLs. Refused by name rather than compiled into a binary whose
+  // remote images are all 404s. See docs/app/guide/assets.
+  if (servesRemoteImages(config.app?.builtins?.images)) {
+    throw new Error(
+      "uf: app.builtins.images.remotePatterns lists remote hosts, and a `--compile` binary " +
+        "has no /__uf/image to answer them: it carries neither the `uf` encoder nor a place " +
+        "to name one. Serve the build with `uf start` or an `--adapter`, or remove the remote " +
+        "patterns. See docs/app/guide/assets.",
+    );
+  }
 
   emit("phase", { name: "standalone" });
 
@@ -1299,11 +1370,24 @@ async function compile() {
  * invocations and is refused by name instead. A regenerated page kept only in
  * memory would go back to the build's copy on every restart, which is a page
  * that travels back in time. See [`deploy`].
+ *
+ * `streams: false` marks the one target whose responses are buffered whole.
+ * A page the build prerendered partially is worth nothing there — its shell is
+ * the part that was meant to arrive first — so such a build is refused by name
+ * rather than deployed as a page that waits for its slowest hole.
  */
 const ADAPTERS = {
   node: {
-    entries: (document, cache, build, schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        NODE_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       server: nodeEntrySource("./handler.js", schedules),
     }),
     regenerationStore: "filesystem",
@@ -1323,15 +1407,31 @@ const ADAPTERS = {
   // nobody here. `edge` pays that price because it must: there is no
   // `node:stream` in a Worker.
   bun: {
-    entries: (document, cache, build, schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, BUN_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        BUN_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       server: bunEntrySource("./handler.js", schedules),
     }),
     regenerationStore: "filesystem",
   },
   deno: {
-    entries: (document, cache, build, schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, DENO_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        DENO_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       server: denoEntrySource("./handler.js", schedules),
     }),
     regenerationStore: "filesystem",
@@ -1341,15 +1441,31 @@ const ADAPTERS = {
   // output rather than anything the bundler produces — see `uf_cli`'s
   // `commands::deploy`.
   container: {
-    entries: (document, cache, build, schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        NODE_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       server: nodeEntrySource("./handler.js", schedules),
     }),
     regenerationStore: "filesystem",
   },
   edge: {
-    entries: (document, cache, build, schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        EDGE_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       worker: workerEntrySource("./handler.js", schedules),
     }),
     // Workers KV, through the same module seam a project's own provider goes
@@ -1373,14 +1489,27 @@ const ADAPTERS = {
     workerBuiltins: true,
   },
   serverless: {
-    entries: (document, cache, build, _schedules, regeneration) => ({
-      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES, build, regeneration),
+    entries: (document, cache, build, _schedules, regeneration, images, partial) => ({
+      handler: handlerEntrySource(
+        document,
+        cache,
+        SERVERLESS_CAPABILITIES,
+        build,
+        regeneration,
+        images,
+        partial,
+      ),
       lambda: lambdaEntrySource("./handler.js"),
     }),
     // A Lambda's memory lasts one instance and its disk is that instance's
     // `/tmp`, so neither is somewhere a regenerated page survives. A build that
     // regenerates pages has to name a provider module; see [`deploy`].
     regenerationStore: null,
+    // And `@uniflowed/server/lambda` buffers every response into the one
+    // result an invocation returns, so a page's static shell would reach the
+    // browser with its holes, not before them. A build that prerendered a page
+    // partially is refused by name; see [`deploy`].
+    streams: false,
   },
 };
 
@@ -1541,7 +1670,33 @@ async function deploy() {
     }
     cacheConfig = { ...declaredCache, store: shape.regenerationStore };
   }
-  const entries = shape.entries(document, cacheConfig, buildId, schedules, regeneration);
+  // The pages this build prerendered partially. Their static shells are baked
+  // into `handler.js`, and a target that cannot send a shell before its holes
+  // refuses them by name: a partial prerender answered by a buffered response
+  // is a page that waits for its slowest hole, which is exactly the page it
+  // was prerendered not to be.
+  const partial = await readPartialPrerenders(path.join(root, ".uf", "build", "server"));
+  if (partial != null && shape.streams === false) {
+    const pages = Object.keys(partial.pages);
+    throw new Error(
+      `uf: this build prerendered ${pages.length} ${plural(pages.length, "page")} partially ` +
+        `(${pages.join(", ")}), and \`--adapter ${adapter}\` buffers every response, so the ` +
+        "static shell would arrive with its holes rather than before them. Deploy with an " +
+        "adapter that streams — node, bun, deno, container or edge — or export " +
+        '`dynamic = "force-dynamic"` from those pages to render each of them whole per ' +
+        "request. See docs/app/guide/rendering.",
+    );
+  }
+  const images = await imageEndpointFor(adapter, config.app?.builtins?.images);
+  const entries = shape.entries(
+    document,
+    cacheConfig,
+    buildId,
+    schedules,
+    regeneration,
+    images,
+    partial,
+  );
   const input = {};
   for (const name of Object.keys(entries)) {
     writeFileSync(path.join(work, `${name}.js`), entries[name]);
@@ -1555,6 +1710,9 @@ async function deploy() {
   const flight = flightStateOf(inline);
   if (flight != null) {
     loadFlightBuild(flight, path.join(root, ".uf", "build", "rsc"));
+    // The id `build` recorded, and not a new one: a Worker's payloads have to
+    // name the same build its documents do.
+    flight.deployment = document.deployment ?? null;
     if (shape.conditions != null) {
       await buildRscGraph(vite, inline, flight, {
         outDir: path.join(work, "rsc"),
@@ -1687,7 +1845,7 @@ async function deploy() {
  * `buildIdentity` is where it came from and
  * `packages/server/internal/cache-key.js` is why it exists.
  */
-function handlerEntrySource(document, cache, capabilities, build, regeneration) {
+function handlerEntrySource(document, cache, capabilities, build, regeneration, images, partial) {
   const route = cache?.route === true;
   const fetchCache = cache?.fetch === true;
   const dataCache = cache?.data === true;
@@ -1706,15 +1864,29 @@ function handlerEntrySource(document, cache, capabilities, build, regeneration)
     // the same reason: the manifest exists on the machine doing the build, and
     // the deployed directory has only what this file carries.
     ...(store && regeneration != null ? [`regeneration: ${JSON.stringify(regeneration)}`] : []),
+    ...(images == null ? [] : ["images"]),
+    // The static shells of the pages it prerendered partially, for the same
+    // reason. Absent for a build with none, so its `handler.js` is unchanged.
+    ...(partial != null ? [`partial: ${JSON.stringify(partial)}`] : []),
   ].join(", ");
-  const cacheImport = store ? 'import { createCacheStore } from "@uniflowed/server/cache";\n' : "";
-  const providerImport = durable == null ? "" : `${durable.import}\n`;
+  // The image endpoint keeps its variants over the same durable provider when
+  // there is one, so it needs the store constructor even for a build whose
+  // route cache is off; `imageEndpointSource` argues the rest.
+  const imageDurable =
+    images == null || store ? null : durableStoreSource(root, cache, build, { required: false });
+  const linkedDurable = durable ?? imageDurable;
+  const cacheImport =
+    store || imageDurable != null
+      ? 'import { createCacheStore } from "@uniflowed/server/cache";\n'
+      : "";
+  const providerImport = linkedDurable == null ? "" : `${linkedDurable.import}\n`;
+  const imageSource = images == null ? null : imageEndpointSource(images, linkedDurable, build);
   const from = JSON.stringify(capabilities.module);
   const capabilityImport = `import { ${capabilities.name} } from ${from};`;
   return `// Generated by \`uf build --adapter\`. Not checked in, not edited.
 import { createFetchHandler } from "@uniflowed/server/fetch";
 ${cacheImport}${providerImport}${capabilityImport}
-import * as app from ${JSON.stringify(VIRTUAL.server)};
+${imageSource == null ? "" : imageSource.imports}import * as app from ${JSON.stringify(VIRTUAL.server)};
 
 ${
   store
@@ -1741,7 +1913,7 @@ const cache = { store: createCacheStore(${
 // passed for the upgrade or the queue — uf defines both and implements
 // neither. See \`@uniflowed/server/socket\` and \`@uniflowed/server/queue\`.
 const capabilities = ${capabilities.name}();
-
+${imageSource == null ? "" : `\n${imageSource.declaration}`}
 export const fetch = createFetchHandler({ ${options} });
 export const beginRequest = app.beginRequest;
 // \`app.router\`'s redirects and headers, for the entry beside this file to put
@@ -1776,10 +1948,14 @@ export default { fetch, beginRequest, routing };
  * @param {{store?: string, storeDir?: string}} cache
  * @param {string | null} build
  */
-function durableStoreSource(root, cache, build) {
+function durableStoreSource(root, cache, build, { required = true } = {}) {
   const named = cache?.store ?? "memory";
   if (named === "memory") return null;
   if (build == null) {
+    // Only the image endpoint asks without requiring one: its variants are a
+    // cache of somebody else's images rather than of this build's documents,
+    // and memory is a correct, colder, answer for them.
+    if (!required) return null;
     throw new Error(
       `uf: rendering.cache.store is ${JSON.stringify(named)}, which keeps entries between ` +
         "restarts, and this build has no identity to key them by. Run `uf build` so one is " +
@@ -1803,6 +1979,103 @@ function durableStoreSource(root, cache, build) {
   };
 }
 
+/**
+ * What `--adapter` links for `/__uf/image`, or `null` for a project with no
+ * remote images.
+ *
+ * A deployed directory has no `uf` in it, so the encoder `uf start` uses is
+ * not there to link, and each target gets the one it has:
+ *
+ * * **`edge`**: Cloudflare's Images binding, through
+ *   `@uniflowed/server/image/edge` — the platform's own image service, handed
+ *   bytes uf fetched and checked rather than a URL it would fetch itself.
+ *   `uf` declares the binding in `wrangler.json` when it finds this linked.
+ * * **Every other target**: the module `app.builtins.images.transformer`
+ *   names, exporting `createImageTransformer`. `node`, `bun`, `deno`,
+ *   `container` and `serverless` have no image service to delegate to, and a
+ *   project that deploys to one names the encoder it has — `sharp`, a WASM
+ *   codec, a call to a service it runs — behind the same seam `uf` sits behind.
+ *
+ * A target with neither is refused here, by name, rather than linked with an
+ * endpoint that fetches every image and then fails to encode it.
+ *
+ * @param {string} adapter
+ * @param {object | undefined} images `app.builtins.images`
+ */
+async function imageEndpointFor(adapter, images) {
+  if (!servesRemoteImages(images)) return null;
+  const defaults = await import("@uniflowed/server/image");
+  const settings = {
+    remotePatterns: images.remotePatterns,
+    widths: images.widths ?? defaults.DEFAULT_WIDTHS,
+    quality: images.quality ?? defaults.DEFAULT_QUALITY,
+    qualities: images.qualities ?? [],
+  };
+  if (adapter === "edge") {
+    return { kind: "edge", settings };
+  }
+  const named = images.transformer;
+  if (typeof named !== "string" || named === "") {
+    throw new Error(
+      `uf: app.builtins.images.remotePatterns lists remote hosts, and \`--adapter ${adapter}\` ` +
+        "has no image encoder to link: uf encodes with the `uf` binary under `uf start` and " +
+        "`uf preview`, and a deployed directory does not carry it. Name a module exporting " +
+        "`createImageTransformer` in app.builtins.images.transformer, deploy with " +
+        "`--adapter edge` to use Cloudflare's image binding, or remove the remote patterns. " +
+        "See docs/app/guide/assets.",
+    );
+  }
+  return {
+    kind: "module",
+    settings,
+    specifier: providerSpecifier(root, named),
+    // Never on a deployment: a switch for a test that serves its own images.
+    allowPrivateAddresses: images.dangerouslyAllowPrivateAddresses === true,
+  };
+}
+
+/**
+ * The lines `handler.js` needs for the endpoint [`imageEndpointFor`] chose.
+ *
+ * `durable` is the provider the route cache links, when it links one, so the
+ * variants live where the project already said entries survive a restart; a
+ * Worker with none keeps them in the isolate's memory.
+ *
+ * @param {{kind: "edge" | "module", settings: object, specifier?: string, allowPrivateAddresses?: boolean}} images
+ * @param {{provider: string} | null} durable
+ * @param {string | null} build
+ */
+function imageEndpointSource(images, durable, build) {
+  const imports =
+    images.kind === "edge"
+      ? 'import { createImageEndpoint, MAX_MEMORY_VARIANTS } from "@uniflowed/server/image";\n' +
+        'import { cloudflareImageTransform, edgeImageFetch } from "@uniflowed/server/image/edge";\n'
+      : 'import { createImageEndpoint, MAX_MEMORY_VARIANTS } from "@uniflowed/server/image";\n' +
+        'import { nodeImageFetch } from "@uniflowed/server/image/node";\n' +
+        `import { createImageTransformer } from ${JSON.stringify(images.specifier)};\n`;
+  const fetch =
+    images.kind === "edge"
+      ? "edgeImageFetch()"
+      : `nodeImageFetch(${images.allowPrivateAddresses ? "{ allowPrivateAddresses: true }" : ""})`;
+  const transform =
+    images.kind === "edge" ? "cloudflareImageTransform()" : "createImageTransformer()";
+  const store =
+    durable == null
+      ? ""
+      : `\n  store: createCacheStore({ provider: ${durable.provider}, build: ${JSON.stringify(
+          build,
+        )}, maxEntries: MAX_MEMORY_VARIANTS }),`;
+  const declaration = `// \`/__uf/image\`, for the remote hosts app.builtins.images.remotePatterns
+// lists. See \`@uniflowed/server/image\` and ubugeeei-prod/uf#958.
+const images = createImageEndpoint({
+  ...${JSON.stringify(images.settings)},
+  fetch: ${fetch},
+  transform: ${transform},${store}
+});
+`;
+  return { imports, declaration };
+}
+
 /**
  * The lines a process entry needs to run what the project declared.
  *

package/index.js

@@ -610,7 +610,8 @@ function flowPlugin({
             );
       }
       if (flightState != null) {
-        if (id === resolved(FLIGHT_VIRTUAL.entry)) return rscEntrySource(VIRTUAL.routes, routing);
+        if (id === resolved(FLIGHT_VIRTUAL.entry))
+          return rscEntrySource(VIRTUAL.routes, routing, flightState.deployment);
         if (id === resolved(FLIGHT_VIRTUAL.compilerRuntime)) return compilerRuntimeSource();
         if (id === resolved(FLIGHT_VIRTUAL.bridge)) {
           if (server != null) return devBridgeSource();

package/internal/assets.js

@@ -81,6 +81,63 @@ import {
   assetKind,
 } from "@uniflowed/host/assets";
 
+import { endpointSettings, localImageEndpoint, servesRemoteImages } from "./image-endpoint.js";
+
+/**
+ * Whether `id` is `@uniflowed/web`'s `internal/image-endpoint.js`.
+ *
+ * By path *and* by the package it is in, because the suffix alone is a name
+ * any package could have; the manifest two directories up has to say
+ * `@uniflowed/web`. The answer is remembered per directory, so the manifest is
+ * read once rather than once per module id.
+ */
+const webPackageDirectories = new Map();
+function isWebImageEndpoint(id) {
+  const file = id.split("?")[0];
+  if (
+    !file.endsWith(`${path.sep}internal${path.sep}image-endpoint.js`) &&
+    !file.endsWith("/internal/image-endpoint.js")
+  ) {
+    return false;
+  }
+  const directory = path.dirname(path.dirname(file));
+  if (!webPackageDirectories.has(directory)) {
+    let name = null;
+    try {
+      name = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8")).name;
+    } catch {
+      name = null;
+    }
+    webPackageDirectories.set(directory, name === "@uniflowed/web");
+  }
+  return webPackageDirectories.get(directory);
+}
+
+/**
+ * The source `@uniflowed/web/internal/image-endpoint.js` is answered with.
+ *
+ * The same shape as the file, with the project's values: the endpoint's path
+ * under Vite's `base` when `remotePatterns` lists anything, and `null`
+ * otherwise, which is the file's own answer — so a project with no remote
+ * images renders exactly what it rendered before the endpoint existed. The
+ * widths and quality are the ones the endpoint will accept, defaulted the way
+ * `@uniflowed/server/image` defaults them, so the `srcset` `Image` writes
+ * names no width the endpoint refuses.
+ *
+ * @param {object} images `app.builtins.images`
+ * @param {string} base Vite's resolved `base`
+ */
+export async function imageEndpointSource(images, base) {
+  const defaults = await import("@uniflowed/server/image");
+  const { widths, quality } = endpointSettings(images, defaults);
+  const endpoint = servesRemoteImages(images) ? `${base}__uf/image` : null;
+  return (
+    "// Generated by uf:asset from app.builtins.images. See @uniflowed/web's\n" +
+    "// internal/image-endpoint.js for the file this stands in for.\n" +
+    `export const IMAGE_ENDPOINT = ${JSON.stringify({ path: endpoint, widths, quality })};\n`
+  );
+}
+
 /** Where transformed assets are kept, relative to the project root. */
 export const CACHE_DIR = ".uf/cache/assets";
 
@@ -333,6 +390,11 @@ export function assetPlugin({ images = {}, fonts = {}, icons = {}, og = {}, comm
     },
 
     async load(id) {
+      // `@uniflowed/web`'s idea of the image endpoint, answered with the
+      // project's. See `imageEndpointSource`.
+      if (isWebImageEndpoint(id)) {
+        return imageEndpointSource(imagesOn ? images : { enabled: false }, base);
+      }
       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
@@ -484,6 +546,44 @@ export function assetPlugin({ images = {}, fonts = {}, icons = {}, og = {}, comm
         response.setHeader("Cache-Control", "public, max-age=31536000, immutable");
         response.end(readFileSync(target));
       });
+
+      // `/__uf/image`, so an `Image` with a remote `src` renders under
+      // `uf dev` exactly as it will under `uf start`: the same endpoint, the
+      // same allow-list, the same encoder. Mounted only for a project that
+      // listed remote hosts, and built on the first request for it rather
+      // than with the server. See `./image-endpoint.js`.
+      if (imagesOn && servesRemoteImages(images)) {
+        const endpointPath = `${base}__uf/image`;
+        let ready = null;
+        devServer.middlewares.use((request, response, next) => {
+          const url = request.url ?? "";
+          const queryAt = url.indexOf("?");
+          if ((queryAt === -1 ? url : url.slice(0, queryAt)) !== endpointPath) return next();
+          ready ??= Promise.all([
+            localImageEndpoint({ images, root, command }),
+            import("@uniflowed/server/node"),
+          ]);
+          ready
+            .then(async ([endpoint, { send }]) => {
+              // The endpoint reads the query and `Accept` and nothing else, so
+              // that is all the request it is handed carries.
+              const accept = request.headers.accept;
+              const asked = new Request(
+                `http://localhost/__uf/image${queryAt === -1 ? "" : url.slice(queryAt)}`,
+                {
+                  method: request.method,
+                  headers: typeof accept === "string" ? { accept } : {},
+                },
+              );
+              const answered = await endpoint(asked);
+              if (answered == null) return next();
+              await send(response, answered);
+              return undefined;
+            })
+            .catch(next);
+          return undefined;
+        });
+      }
     },
 
     watchChange(id) {

package/internal/flight.js

@@ -247,6 +247,8 @@ export function createFlightState({ root }) {
     clientModules: new Set(),
     chunkUrls: new Map(),
     rscOutput: null,
+    // The build's public id, set by the driver before it builds the rsc graph.
+    deployment: null,
   };
 }
 
@@ -500,8 +502,14 @@ export function fsFileOf(pathname) {
   return /^[A-Za-z]:\//.test(rest) ? rest : `/${rest}`;
 }
 
-/** `virtual:uf/rsc`: the Flight renderer over the rsc graph's route table. */
-export function rscEntrySource(routesId, routing = {}) {
+/**
+ * `virtual:uf/rsc`: the Flight renderer over the rsc graph's route table.
+ *
+ * `deployment` is the build's public id, baked in so every payload says which
+ * build rendered it — a prerendered payload is a file, and nothing that serves
+ * a file can say so for it. `null` under `uf dev`.
+ */
+export function rscEntrySource(routesId, routing = {}, deployment = null) {
   const settings = {
     basePath: routing.basePath ?? "",
     trailingSlash: routing.trailingSlash ?? "ignore",
@@ -510,7 +518,9 @@ export function rscEntrySource(routesId, routing = {}) {
 import { routes, notFound, errors } from ${JSON.stringify(routesId)};
 installRouting(${JSON.stringify(settings)});
 export { routes, notFound, errors };
-export const renderFlight = createFlightRenderer({ routes, notFound, errors });
+export const renderFlight = createFlightRenderer({ routes, notFound, errors, deployment: ${JSON.stringify(
+    deployment ?? null,
+  )} });
 `;
 }
 
@@ -716,6 +726,9 @@ export const render = (url, assets, options = {}) => instrumentRender(
   (onError) => renderer.render(url, assets, { ...options, onError }), options.onError,
 );
 export const prerender = renderer.prerender;
+export const resume = (url, assets, shell, options = {}) => instrumentRender(
+  (onError) => renderer.resume(url, assets, shell, { ...options, onError }), options.onError,
+);
 export const flight = (url, options = {}) => instrumentRender(
   (onError) => renderer.flight(url, { ...options, onError }), options.onError,
 );

package/internal/image-endpoint.js

@@ -0,0 +1,118 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that serves a build, and by `uf dev`.
+//
+// `/__uf/image` on the three doors `uf` itself runs — `uf dev`, `uf preview`
+// and `uf start` — with `uf` as the encoder.
+//
+// The endpoint is `@uniflowed/server/image`'s, the fetch is
+// `@uniflowed/server/image/node`'s, and this is the one piece those two
+// cannot have: a transformer that reaches the `uf` binary. It writes the
+// bounded source to a private temporary directory, asks `uf assets` for one
+// variant of it (`crates/uf_cli/src/commands/assets.rs`'s `variant` request,
+// which is `uf_assets::variant`), and reads the one file that comes back.
+// Both files are removed before the answer is returned: the cache is the
+// endpoint's `CacheStore`, not this directory.
+//
+// A deployed directory has no `uf` in it, which is why this is not in
+// `@uniflowed/server`. What `--adapter` links instead is argued in
+// `driver.js`'s `imageEndpointSource`.
+
+import { randomUUID } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { AssetService } from "@uniflowed/host/assets";
+
+/**
+ * Whether the project asked for an endpoint at all.
+ *
+ * `app.builtins.images.remotePatterns` with something in it, and images not
+ * turned off. Nothing else constructs one: a project that listed no host has
+ * no `/__uf/image`, and the path is an ordinary 404.
+ *
+ * @param {{enabled?: boolean, remotePatterns?: unknown[]} | undefined} images
+ */
+export function servesRemoteImages(images) {
+  return (
+    images?.enabled !== false &&
+    Array.isArray(images?.remotePatterns) &&
+    images.remotePatterns.length > 0
+  );
+}
+
+/**
+ * The endpoint's options from `app.builtins.images`, with uf's defaults where
+ * the project said nothing — the same defaults `uf_assets::ImagesConfig`
+ * applies, from `@uniflowed/server/image` where both sides can read them.
+ *
+ * @param {object} images `app.builtins.images`
+ * @param {{DEFAULT_WIDTHS: number[], DEFAULT_QUALITY: number}} defaults
+ */
+export function endpointSettings(images, defaults) {
+  return {
+    remotePatterns: images.remotePatterns,
+    widths: images.widths ?? defaults.DEFAULT_WIDTHS,
+    quality: images.quality ?? defaults.DEFAULT_QUALITY,
+    qualities: images.qualities ?? [],
+  };
+}
+
+/**
+ * An encoder that is `uf` itself.
+ *
+ * One `uf assets` process for the life of the server, started on the first
+ * miss and not before, and one temporary directory beside it.
+ *
+ * @param {{root: string, command?: string}} options
+ */
+export function ufImageTransform({ root, command }) {
+  let service = null;
+  let directory = null;
+  return async function transform({ bytes, width, quality, avif }) {
+    service ??= new AssetService({ command, root });
+    directory ??= mkdtemp(path.join(os.tmpdir(), "uf-image-"));
+    const base = path.join(await directory, randomUUID());
+    const source = `${base}.source`;
+    const out = `${base}.out`;
+    await writeFile(source, bytes);
+    try {
+      const variant = await service.variant(source, { outDir: out, width, quality, avif });
+      const encoded = await readFile(path.join(out, variant.file));
+      return {
+        bytes: new Uint8Array(encoded.buffer, encoded.byteOffset, encoded.byteLength),
+        type: variant.mime,
+      };
+    } finally {
+      await rm(source, { force: true });
+      await rm(out, { recursive: true, force: true });
+    }
+  };
+}
+
+/**
+ * `/__uf/image` for a door `uf` runs, or `undefined` for a project with no
+ * remote images.
+ *
+ * `store` is the `CacheStore` a durable `rendering.cache.store` gave the route
+ * cache's provider to, when there is one; without it the endpoint keeps its
+ * variants in memory.
+ *
+ * @param {{images?: object, root: string, command?: string, store?: object}} options
+ */
+export async function localImageEndpoint({ images, root, command, store }) {
+  if (!servesRemoteImages(images)) return undefined;
+  const [endpoint, node] = await Promise.all([
+    import("@uniflowed/server/image"),
+    import("@uniflowed/server/image/node"),
+  ]);
+  return endpoint.createImageEndpoint({
+    ...endpointSettings(images, endpoint),
+    fetch: node.nodeImageFetch({
+      allowPrivateAddresses: images.dangerouslyAllowPrivateAddresses === true,
+    }),
+    transform: ufImageTransform({ root, command }),
+    ...(store == null ? {} : { store }),
+  });
+}

package/internal/serve.js

@@ -71,10 +71,13 @@
 // guard would run, the page would render, and every `cookies()` in it would
 // throw as though no host had run at all. See ubugeeei-prod/uf#389.
 
+import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { localImageEndpoint, servesRemoteImages } from "./image-endpoint.js";
+
 /**
  * `@uniflowed/server`'s two halves, loaded once.
  *
@@ -127,6 +130,29 @@ async function cacheFor(declared, createCacheStore, where) {
   return { store, route, fetch: fetchCache, data };
 }
 
+/**
+ * Where `/__uf/image` keeps its variants: over the provider
+ * `rendering.cache.store` names, or `undefined` for the endpoint's own memory.
+ *
+ * The same provider as the route cache, because it is the one a project
+ * already said survives a restart and is shared between processes — a second
+ * setting for "where do image variants go" would be a second answer to a
+ * question the project answered once. Asked only when a store is named, so a
+ * project that names none needs no build identity for its images.
+ *
+ * @param {{store?: string, storeDir?: string} | undefined} declared
+ * @param {(options?: object) => object} createCacheStore
+ * @param {{root: string, build: string | null}} where
+ */
+async function imageStoreFor(declared, createCacheStore, where) {
+  const named = declared?.store ?? "memory";
+  if (named === "memory") return undefined;
+  const provider = await providerFor(declared, where);
+  if (provider == null) return undefined;
+  const { MAX_MEMORY_VARIANTS } = await import("@uniflowed/server/image");
+  return createCacheStore({ provider, build: where.build, maxEntries: MAX_MEMORY_VARIANTS });
+}
+
 /**
  * The durable provider `rendering.cache.store` names, or `null` for memory.
  *
@@ -220,6 +246,7 @@ export async function loadBuild({ root, outDir, serverDir }) {
   await deployment();
   const build = await buildIdentity(root, serverDir);
   const regeneration = await readRegeneration(path.resolve(root, serverDir));
+  const partial = await readPartialPrerenders(path.resolve(root, serverDir));
   return {
     entry,
     assets: await documentAssetsFor(path.resolve(root, serverDir), manifest),
@@ -227,6 +254,7 @@ export async function loadBuild({ root, outDir, serverDir }) {
     root,
     build,
     regeneration,
+    partial,
   };
 }
 
@@ -296,6 +324,33 @@ export async function readRegeneration(serverDir) {
   return JSON.parse(text);
 }
 
+/**
+ * The file beside the server bundle that holds the static shells of the pages a
+ * build prerendered partially.
+ *
+ * Beside the server bundle rather than under the output directory, because a
+ * shell is not a document anybody should be sent on its own: its holes are
+ * filled by the server that reads this file, and a file server would send it
+ * with every hole showing its fallback forever.
+ */
+export const PARTIAL_PRERENDER_FILE = "partial-prerender.json";
+
+/**
+ * The pages this build prerendered partially, or `undefined` for a build with
+ * none — which then serves exactly as every build did before partial
+ * prerendering existed.
+ */
+export async function readPartialPrerenders(serverDir) {
+  let text;
+  try {
+    text = await readFile(path.join(serverDir, PARTIAL_PRERENDER_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return JSON.parse(text);
+}
+
 /**
  * What `import()` should be given for a provider a project named.
  *
@@ -351,6 +406,24 @@ export async function buildIdentity(root, serverDir) {
   }
 }
 
+/**
+ * The id a build's documents publish, derived from the build id.
+ *
+ * A browser names it on every action call and payload request, and a front
+ * door on another build refuses rather than answering; see
+ * `@uniflowed/server`'s `internal/deployment.js`. It has to be public — it is
+ * in every document — and the build id must not be: it is the key the action
+ * ids are an HMAC under whenever `UF_BUILD_ID` names both. So this is a
+ * digest of it, under a label of its own, and sixteen hex characters of that:
+ * the same for two artefacts that are one build, different for any two that
+ * are not, and no help to anybody guessing the key.
+ *
+ * @param {string} buildId
+ */
+export function deploymentIdFor(buildId) {
+  return createHash("sha256").update("uf:deployment\0").update(buildId).digest("hex").slice(0, 16);
+}
+
 async function readable(file, message) {
   try {
     await stat(file);
@@ -524,9 +597,21 @@ export async function beginRequest(entry, request) {
  * keyed by. Both are `undefined` for a caller that constructs a handler by
  * hand, which is the memory-only store and needs neither.
  *
- * @param {{entry: object, assets: object, cache?: object, root?: string, build?: string | null}} build
+ * `images` is `app.builtins.images`, and it adds `/__uf/image` to what the
+ * handler answers when it lists remote hosts; see `./image-endpoint.js`.
+ *
+ * @param {{entry: object, assets: object, cache?: object, root?: string, build?: string | null, regeneration?: object, images?: object, partial?: object}} build
  */
-export function createApplicationHandler({ entry, assets, cache, root, build, regeneration }) {
+export function createApplicationHandler({
+  entry,
+  assets,
+  cache,
+  root,
+  build,
+  regeneration,
+  images,
+  partial,
+}) {
   const ready = deployment().then(
     async ({ createFetchHandler, createCacheStore, nodeCapabilities }) =>
       createFetchHandler({
@@ -537,10 +622,27 @@ export function createApplicationHandler({ entry, assets, cache, root, build, re
           build: build ?? null,
           regenerates: regeneration != null,
         }),
+        // `/__uf/image`, for a project that listed remote hosts. See
+        // `./image-endpoint.js`.
+        ...(servesRemoteImages(images)
+          ? {
+              images: await localImageEndpoint({
+                images,
+                root: root ?? process.cwd(),
+                store: await imageStoreFor(cache, createCacheStore, {
+                  root: root ?? process.cwd(),
+                  build: build ?? null,
+                }),
+              }),
+            }
+          : {}),
         // The pages this build regenerates, from the manifest beside the server
         // bundle. Absent for a build with none, which then serves exactly as it
         // did before regeneration existed.
         ...(regeneration == null ? {} : { regeneration }),
+        // And the static shells of the pages it prerendered partially, from the
+        // file beside the server bundle, for the same reason.
+        ...(partial == null ? {} : { partial }),
         // `uf preview` and `uf start` are a Node process with a socket, which is
         // what a deployed `--adapter node` build is too — so a route handler
         // that streams events answers the same way in the preview it is checked
@@ -589,10 +691,29 @@ export function createStaticHandler({ root }) {
  * a deployment. `uf preview` puts the same two in front of Vite's file
  * middleware as well; see [`answerRouting`].
  *
- * @param {{entry: object, assets: object, distDir: string, cache?: object, root?: string, build?: string | null, regeneration?: object}} build
+ * @param {{entry: object, assets: object, distDir: string, cache?: object, root?: string, build?: string | null, regeneration?: object, partial?: object}} build
  */
-export function createServeHandler({ entry, assets, distDir, cache, root, build, regeneration }) {
-  const application = createApplicationHandler({ entry, assets, cache, root, build, regeneration });
+export function createServeHandler({
+  entry,
+  assets,
+  distDir,
+  cache,
+  root,
+  build,
+  regeneration,
+  images,
+  partial,
+}) {
+  const application = createApplicationHandler({
+    entry,
+    assets,
+    cache,
+    root,
+    build,
+    regeneration,
+    images,
+    partial,
+  });
   const ready = deployment().then(({ createServeHandler: create }) =>
     create({ staticDir: distDir, handle: application, routing: entry.routing }),
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.45",
+  "version": "0.0.0-alpha.47",
   "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",
@@ -35,10 +35,10 @@
     "@babel/core": "^7.29.7",
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.45",
-    "@uniflowed/router": "0.0.0-alpha.45",
-    "@uniflowed/server": "0.0.0-alpha.45",
-    "@uniflowed/validator": "0.0.0-alpha.45",
+    "@uniflowed/host": "0.0.0-alpha.47",
+    "@uniflowed/router": "0.0.0-alpha.47",
+    "@uniflowed/server": "0.0.0-alpha.47",
+    "@uniflowed/validator": "0.0.0-alpha.47",
     "babel-plugin-relay": "^21.0.1",
     "estree-util-value-to-estree": "^3.5.0",
     "rehype-slug": "^6.0.0",