@ultimat3/cli 29.4.0 → 30.1.0

package/src/site-seo.ts

@@ -1,4 +1,4 @@
-// `robots.txt` and `sitemap.xml`, off the route table: ONE answer for the static export
+// `robots.txt`, `sitemap.xml` and `llms.txt`, off the route table: ONE answer for the static export
 // (`apps/web/prerender.ts` writes it into the artifact) and the running web role (`seo-routes.ts`
 // serves it), so a crawler reads the same two files from a CDN and from a container.
 
@@ -6,12 +6,15 @@ import type { Environment, SeoRobotsGroup, SeoSitemapConfig } from '@ultimat3/co
 import { UltimateError } from '@ultimat3/core';
 import { localizedPath, unlocalizedPath } from '@ultimat3/i18n';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
-import type { RouteEntry } from '@ultimat3/render';
+import type { PrerenderEntry, RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { enumeratePrerenderEntries, fillPath } from '@ultimat3/render/server';
 import type { RouteRecord, SitemapFile, SitemapPage } from '@ultimat3/seo';
 import { buildRobots, buildSitemap, isDynamic } from '@ultimat3/seo';
+import type { RouteEntries } from './prerender-entries';
 import { readSiteMeta } from './seo-meta';
+import { siteLlms } from './site-llms';
+import type { LlmsPages } from './site-llms-pages';
 import { lastmodOf } from './sitemap-lastmod';
 
 export const ROBOTS_PATH = '/robots.txt';
@@ -47,6 +50,20 @@ export interface SiteSeoOptions {
   readonly sitemap?: SiteSeoSitemap | undefined;
   /** The app root the route files are relative to — read for `lastmod: 'git' | 'mtime'`. */
   readonly root?: string | undefined;
+  /** `seo.llms` from `app.config.ts`. Omitted: on, like the sitemap. */
+  readonly llms?: boolean | undefined;
+  /**
+   * What the static export's `prerender()` calls already answered, by declared route path
+   * (`PrerenderReport.entries`). A route listed here is never asked again: the build enumerated
+   * it inside its API scope, which is gone by the time the sitemap is written, so a `prerender()`
+   * reading the app's own query would fail the export (`X_CLIENT_TRANSPORT_FAILED`).
+   */
+  readonly entries?: RouteEntries | undefined;
+  /**
+   * `llms.txt`'s page records the static export read inside its API scope
+   * (`PrerenderReport.llmsPages`). A route listed here never runs its `load` again.
+   */
+  readonly llmsPages?: LlmsPages | undefined;
 }
 
 /**
@@ -72,6 +89,8 @@ export class SitemapExtraInvalidError extends UltimateError {
 
 export interface SiteSeo {
   readonly robots: string;
+  /** `/llms.txt`: empty outside production and under `seo.llms: false`. */
+  readonly llms: string;
   /** Every sitemap file: `/sitemap.xml` alone, or the index at that path first and its parts after. */
   readonly sitemaps: readonly SitemapFile[];
 }
@@ -89,8 +108,9 @@ const isPublicSite = (entry: RouteEntry): boolean =>
 const pagesOf = async (
   entry: RouteEntry,
   options: SiteSeoOptions,
+  enumerate: Enumerate,
 ): Promise<readonly SitemapPage[]> => {
-  const said = (await enumeratePrerenderEntries(entry)).map(
+  const said = (await enumerate(entry)).map(
     (page): SitemapPage => ({
       path: fillPath(entry.pattern.source, page.params),
       ...(page.lastmod === undefined ? {} : { lastmod: page.lastmod }),
@@ -147,6 +167,7 @@ async function publicSiteRoutes(
   options: SiteSeoOptions,
   stamp: Stamp,
   locales: readonly string[],
+  enumerate: Enumerate,
 ): Promise<readonly RouteRecord[]> {
   const indexed = await indexability(locales);
   return routeEntries()
@@ -158,7 +179,7 @@ async function publicSiteRoutes(
       render: entry.config.render,
       ...indexed(entry.path),
       ...(isDynamic(entry.path) || entry.config.prerender !== undefined
-        ? { prerender: () => pagesOf(entry, options) }
+        ? { prerender: () => pagesOf(entry, options, enumerate) }
         : {}),
       ...stamp(entry.file),
     }));
@@ -166,6 +187,22 @@ async function publicSiteRoutes(
 
 type Stamp = (file: string) => { readonly lastmod?: string };
 
+/** `enumeratePrerenderEntries`, asked once per route per answer: the sitemap and `llms.txt` share it. */
+type Enumerate = (entry: RouteEntry) => Promise<readonly PrerenderEntry[]>;
+
+const enumerateOnce = (given: RouteEntries | undefined): Enumerate => {
+  const asked = new Map<RouteEntry, Promise<readonly PrerenderEntry[]>>();
+  return (entry) => {
+    const enumerated = given?.get(entry.path);
+    if (enumerated !== undefined) return Promise.resolve(enumerated);
+    const known = asked.get(entry);
+    if (known !== undefined) return known;
+    const answer = enumeratePrerenderEntries(entry);
+    asked.set(entry, answer);
+    return answer;
+  };
+};
+
 /**
  * The app's `seo.sitemap.extra` paths as records, each resolved to the route that answers it — the
  * most specific match, the router's own tie-break. REFUSED, never skipped, when it names no route,
@@ -216,8 +253,9 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
     const lastmod = lastmodOf(file, settings.lastmod, root);
     return lastmod === undefined ? {} : { lastmod };
   };
+  const enumerate = enumerateOnce(options.entries);
   const routes = [
-    ...(await publicSiteRoutes(options, stamp, locales)),
+    ...(await publicSiteRoutes(options, stamp, locales, enumerate)),
     ...extraRoutes(settings.extra, stamp),
   ];
   const sitemap = await buildSitemap(routes, {
@@ -245,5 +283,16 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
     ...(options.robotsGroups === undefined ? {} : { groups: options.robotsGroups }),
     ...(options.environment === undefined ? {} : { environment: options.environment }),
   });
-  return { robots, sitemaps };
+  // The same pages, default locale, less what `robots.txt` keeps crawlers out of (`site-llms.ts`).
+  const llms = await siteLlms({
+    baseUrl: options.baseUrl,
+    environment: options.environment,
+    enabled: options.llms,
+    disallow: options.disallow,
+    pagesFor: options.pagesFor,
+    defaultLocale,
+    enumerate,
+    pages: options.llmsPages,
+  });
+  return { robots, sitemaps, llms };
 }

package/src/source-mtime.ts

@@ -0,0 +1,50 @@
+// The newest mtime over what a static build reads, for `budgets`' freshness: the app's source files
+// (tests and declarations ship no bytes), the config and the lockfile, and every directory those
+// files sit in — a deleted page changes no remaining file's mtime, only its directory's.
+
+// why: Bun exposes no path-join or dirname primitive.
+import { dirname, join } from 'node:path';
+import { APP_CONFIG_FILE } from '@ultimat3/core';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+
+/**
+ * Files outside `SOURCE_GLOBS` that still move a route's bytes: the config (pwa, theme, surfaces)
+ * and the lockfile, whose change is a framework or dependency upgrade.
+ */
+const BYTE_INPUTS = [APP_CONFIG_FILE, 'bun.lock'] as const;
+
+/** `0` for a path that vanished between the glob and the stat: it cannot be newer than anything. */
+const mtimeOf = async (path: string): Promise<number> => {
+  const file = Bun.file(path);
+  try {
+    return (await file.stat()).mtimeMs;
+  } catch {
+    return 0;
+  }
+};
+
+/** Every directory between `path` and the root, the root itself excluded (`.x/` lives there). */
+const ancestorsOf = (path: string): readonly string[] => {
+  const out: string[] = [];
+  for (let dir = dirname(path); dir !== '.' && dir !== '' && dir !== '/'; dir = dirname(dir)) {
+    out.push(dir);
+  }
+  return out;
+};
+
+/** The newest mtime, in ms, or `undefined` for an app with no source at all. */
+export async function newestSourceMtime(root: string): Promise<number | undefined> {
+  let newest: number | undefined;
+  const consider = (ms: number): void => {
+    if (ms > 0 && (newest === undefined || ms > newest)) newest = ms;
+  };
+  const dirs = new Set<string>();
+  for await (const path of eachSourceFile(root)) {
+    if (isTest(path) || isGenerated(path)) continue;
+    consider(await mtimeOf(join(root, path)));
+    for (const dir of ancestorsOf(path)) dirs.add(dir);
+  }
+  for (const dir of dirs) consider(await mtimeOf(join(root, dir)));
+  for (const path of BYTE_INPUTS) consider(await mtimeOf(join(root, path)));
+  return newest;
+}

package/src/static-capture-errors.ts

@@ -0,0 +1,41 @@
+// The three ways a static export's FILES — image variants and social cards — cannot be made: a
+// `src` the export does not hold, a card path no exported page answers, and no browser to take the
+// card with. Codes and titles are `error-codes.ts`'s; these are the constructors.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+
+const listed = (values: readonly string[]): string =>
+  values.map((value) => renderCauseValue(value)).join(', ');
+
+export class ImageSourceUnreadableError extends UltimateError {
+  constructor(srcs: readonly string[]) {
+    super({
+      code: 'X_IMAGE_SOURCE_UNREADABLE',
+      cause: `responsiveImage() on an exported page named ${listed(srcs)}, and the static export holds no such file, so no variant of it can be written — a CDN would answer every <source> with a 404`,
+      fix: "x build --target static --json   # lists the export; put the file under apps/web/site/assets/ and pass asset('assets/<file>') as src, or give an absolute https:// URL",
+      meta: { srcs: [...srcs] },
+    });
+  }
+}
+
+export class CardRouteUnknownError extends UltimateError {
+  constructor(paths: readonly string[], declaredIn?: string) {
+    super({
+      code: 'X_SEO_CARD_ROUTE_UNKNOWN',
+      cause: `og.capture names ${listed(paths)}${declaredIn === undefined ? '' : ` (in ${declaredIn})`}, and no exported site/ page answers that path, so there is no page to photograph`,
+      fix: 'x routes --json   # list the site/ routes; add apps/web/site/<the capture path>/page.tsx at 1200 x 630 with robots: { index: false }, or correct the og.capture path',
+      meta: { paths: [...paths] },
+    });
+  }
+}
+
+export class CardBrowserMissingError extends UltimateError {
+  constructor(paths: readonly string[]) {
+    super({
+      code: 'X_SEO_CARD_BROWSER_MISSING',
+      cause: `x build --target static photographs ${listed(paths)} as social cards, and no browser was named or found — no CHROME_PATH, PUPPETEER_EXECUTABLE_PATH or SCRAPE_CDP_URL is set and no probed path holds one`,
+      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome, Chromium or Edge binary; or drop og.capture from the route; the gate build passes --no-capture and needs none',
+      meta: { paths: [...paths] },
+    });
+  }
+}

package/src/static-capture.ts

@@ -0,0 +1,56 @@
+// Single responsibility: install `@ultimat3/seo`'s static seam for one export, and after the render
+// loop write the files the exported documents promised — image variants (`static-images.ts`) and
+// social cards (`static-cards.ts`). The prerenderer's one touch point for both.
+
+// why: Bun exposes no path-join primitive, and every page file is relative to the export root.
+import { join } from 'node:path';
+import { setStaticExport } from '@ultimat3/seo';
+import type { ShotDriver } from './browser-launcher-port';
+import { BUILD_CAPTURE_ENV } from './build-capture-env';
+import { CARD_SIZE, staticCards } from './static-cards';
+import { staticImages } from './static-images';
+
+export interface StaticCaptureFiles {
+  readonly images: readonly string[];
+  readonly cards: readonly string[];
+}
+
+export interface StaticCapture {
+  /** Uninstalls the seam. Idempotent; runs in the render loop's `finally`. */
+  close(): void;
+  write(
+    pages: readonly { readonly path: string; readonly file: string }[],
+  ): Promise<StaticCaptureFiles>;
+}
+
+/** The CLI's own CDP driver, or `undefined` when nothing can be launched or attached to. */
+async function cardBrowser(): Promise<ShotDriver | undefined> {
+  const { appBrowser, cdpUrlFrom, executablePathFrom } = await import('./browser-launcher');
+  const cdpUrl = cdpUrlFrom(undefined, Bun.env);
+  const executablePath = executablePathFrom(undefined, Bun.env);
+  if (cdpUrl === undefined && executablePath === undefined) return undefined;
+  return appBrowser({ cdpUrl, executablePath, viewport: CARD_SIZE });
+}
+
+export async function staticCapture(
+  out: string,
+  capture: boolean = Bun.env[BUILD_CAPTURE_ENV] !== 'off',
+  browser: () => Promise<ShotDriver | undefined> = cardBrowser,
+): Promise<StaticCapture> {
+  const images = await staticImages(out);
+  const cards = staticCards();
+  setStaticExport({ imageUrl: images.imageUrl, cardImage: cards.cardImage });
+  return {
+    close: () => setStaticExport(undefined),
+    async write(pages) {
+      const documents = await Promise.all(
+        pages.map((page) => Bun.file(join(out, page.file)).text()),
+      );
+      const exported = new Set(pages.map((page) => page.path));
+      return {
+        images: await images.write(documents),
+        cards: await cards.write(out, documents, exported, { capture, browser }),
+      };
+    },
+  };
+}

package/src/static-cards-serve.ts

@@ -0,0 +1,39 @@
+// Single responsibility: the export, served on loopback for the length of a card capture — the
+// dumb file server a CDN is, so a card page is photographed with exactly the stylesheet, fonts and
+// assets the published page links. Never the app: a static export has no process behind it.
+
+// why: Bun exposes no path-join primitive, and every file served is relative to the export root.
+import { join, normalize, sep } from 'node:path';
+
+export interface ServedExport {
+  readonly origin: string;
+  stop(): void;
+}
+
+/** `/og/home` → `og/home/index.html`, then the bare file — the two shapes an export holds. */
+function fileFor(out: string, pathname: string): readonly string[] {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return [];
+  }
+  const relative = normalize(decoded).replace(/^[/\\]+/, '');
+  if (relative.split(sep).includes('..')) return [];
+  return [join(out, relative, 'index.html'), join(out, relative)];
+}
+
+export function serveExport(out: string): ServedExport {
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    async fetch(request) {
+      for (const file of fileFor(out, new URL(request.url).pathname)) {
+        const body = Bun.file(file);
+        if (await body.exists()) return new Response(body);
+      }
+      return new Response(null, { status: 404 });
+    },
+  });
+  return { origin: `http://127.0.0.1:${String(server.port)}`, stop: () => void server.stop(true) };
+}

package/src/static-cards.ts

@@ -0,0 +1,93 @@
+// Single responsibility: social cards as FILES in a static export. While it renders, `og.capture`
+// is answered as `/_og/<path>.png` at 1200 x 630 and recorded; after it, each card an exported
+// document names is photographed from its exported page over the CLI's own CDP driver. Under
+// `--no-capture` (the gate's build) the tags are stamped and no PNG is written.
+
+// why: Bun exposes no path-join primitive, and every card path is relative to the export root.
+import { join } from 'node:path';
+import { probeImage, transformImageBytes } from '@ultimat3/core';
+import type { OpenGraphImage } from '@ultimat3/seo';
+import type { ShotDriver } from './browser-launcher-port';
+import { DEFAULT_PAGE_TIMEOUT_MS, systemShotClock } from './cdp-shot-clock';
+import { CardBrowserMissingError, CardRouteUnknownError } from './static-capture-errors';
+import { serveExport } from './static-cards-serve';
+
+/** The size every platform crops a link preview from. */
+export const CARD_SIZE = Object.freeze({ width: 1200, height: 630 });
+
+export const STATIC_CARD_DIR = '_og';
+
+/** `/og/post/hello` → `/_og/og/post/hello.png`; `/` → `/_og/index.png`. */
+export function cardUrl(capturePath: string): string {
+  const trimmed = capturePath.replace(/\/+$/, '');
+  return `/${STATIC_CARD_DIR}${trimmed === '' ? '/index' : trimmed}.png`;
+}
+
+export interface CardCaptureOptions {
+  /** `false` under `--no-capture`: the tags are stamped, no browser is asked, no PNG is written. */
+  readonly capture: boolean;
+  /** The browser, asked only when a card has to be taken. `undefined` means none is available. */
+  readonly browser: () => Promise<ShotDriver | undefined>;
+}
+
+export interface StaticCards {
+  /** The `og:image` the seo seam stamps for one `og.capture`. Never throws. */
+  cardImage(capturePath: string): OpenGraphImage;
+  /**
+   * The cards exported documents name: each capture path must be an exported page
+   * (`X_SEO_CARD_ROUTE_UNKNOWN`), then each is photographed unless capture is off. Answers the
+   * PNG site paths written.
+   */
+  write(
+    out: string,
+    documents: readonly string[],
+    exportedPaths: ReadonlySet<string>,
+    options: CardCaptureOptions,
+  ): Promise<readonly string[]>;
+}
+
+/** Exactly 1200 x 630 on disk, whatever the device pixel ratio did: the stamped size is a promise. */
+async function sized(png: Uint8Array): Promise<Uint8Array> {
+  const info = probeImage(png);
+  if (info.width === CARD_SIZE.width && info.height === CARD_SIZE.height) return png;
+  return transformImageBytes(png, { ...CARD_SIZE, fit: 'cover', format: 'png' });
+}
+
+export function staticCards(): StaticCards {
+  const captures = new Map<string, string>();
+  return {
+    cardImage(capturePath) {
+      const url = cardUrl(capturePath);
+      captures.set(url, capturePath);
+      return { url, ...CARD_SIZE, type: 'image/png' };
+    },
+    async write(out, documents, exportedPaths, options) {
+      const named = [...captures].filter(([url]) => documents.some((html) => html.includes(url)));
+      const unknown = named.map(([, path]) => path).filter((path) => !exportedPaths.has(path));
+      if (unknown.length > 0) throw new CardRouteUnknownError(unknown);
+      if (!options.capture || named.length === 0) return [];
+      const driver = await options.browser();
+      if (driver === undefined) throw new CardBrowserMissingError(named.map(([, path]) => path));
+      const served = serveExport(out);
+      const session = await driver.open({
+        name: 'x build cards',
+        rules: { allowHosts: ['127.0.0.1'] },
+        clock: systemShotClock,
+        timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+        viewport: CARD_SIZE,
+      });
+      try {
+        const written: string[] = [];
+        for (const [url, path] of named) {
+          await session.page.goto(new URL(path, served.origin).href);
+          await Bun.write(join(out, url.slice(1)), await sized(await session.page.screenshot({})));
+          written.push(url);
+        }
+        return written;
+      } finally {
+        await session.close();
+        served.stop();
+      }
+    },
+  };
+}

package/src/static-document.ts

@@ -4,9 +4,8 @@
 // per request, nor a body per revalidation. No other mode comes through here.
 
 import type { UltimateRequest } from '@ultimat3/http';
-import { html } from '@ultimat3/http';
+import { html, notModified } from '@ultimat3/http';
 import type { RenderResult, RouteEntry } from '@ultimat3/render';
-import { etagMatches } from './runtime-storage';
 
 /** A rendered static document: always a string body, never a stream. */
 export type StaticResult = RenderResult & { readonly body: string };
@@ -78,19 +77,24 @@ export function createStaticMemo(
 /**
  * The key a request's document is kept under, or `undefined` when it must be rendered: a query
  * string is part of what `meta` reads (`data.url`), and a dynamic segment is an unbounded set an
- * anonymous visitor chooses. The origin is in the key because canonical and `og:url` are absolute
- * against the request's own when the app declares none. `url` is `addressedUrl`'s: keyed on the
- * pathname as written, any visitor filled the memo with spellings of one page (`/about//`, …) and
- * every page that arrived after the cap was rendered per request for the life of the process.
+ * anonymous visitor chooses. The request's origin is in the key only when the app declares none,
+ * because canonical and `og:url` are then absolute against it; declared, they are absolute against
+ * `origin` (`runtime-render-document.ts`'s `baseUrl`), the document is one whatever the `Host`, and
+ * keying on the request's let rotated `Host` headers fill the memo. `url` is `addressedUrl`'s:
+ * keyed on the pathname as written, any visitor filled the memo with spellings of one page
+ * (`/about//`, …) and every page that arrived after the cap was rendered per request for the life
+ * of the process.
  */
 export function staticMemoKey(
   entry: Pick<RouteEntry, 'config' | 'pattern'>,
   url: URL,
   locale: string,
+  /** The app's declared origin — the same value the document's head is built against. */
+  origin?: string,
 ): string | undefined {
   if (entry.config.render !== 'static') return undefined;
   if (entry.pattern.keys.length > 0 || url.search !== '') return undefined;
-  return `${locale}\n${url.origin}${url.pathname}`;
+  return `${locale}\n${origin ?? url.origin}${url.pathname}`;
 }
 
 /**
@@ -100,13 +104,10 @@ export function staticMemoKey(
  */
 export function staticResponse(request: UltimateRequest, result: StaticResult): Response {
   const etag = result.headers['etag'];
-  if (
-    result.status === 200 &&
-    etag !== undefined &&
-    etagMatches(request.header('if-none-match'), etag)
-  ) {
+  if (result.status === 200 && etag !== undefined) {
     const { 'content-type': _dropped, ...headers } = result.headers;
-    return new Response(null, { status: 304, headers });
+    const fresh = notModified(request, etag, headers);
+    if (fresh !== undefined) return fresh;
   }
   return html(result.body, { status: result.status, headers: result.headers });
 }

package/src/static-images.ts

@@ -0,0 +1,115 @@
+// Single responsibility: the image variants a static export's documents promise, as FILES. While
+// the export renders, `responsiveImage` asks this module for each variant's URL — `/_img/<source
+// hash>-<width>.<ext>` — and after it, every URL an exported document names is decoded, resized
+// and written through core's pipeline. A dumb file server then answers `image/webp` for a webp.
+
+// why: Bun exposes no path-join primitive, and every variant path is relative to the export root.
+import { join } from 'node:path';
+import { canEncode, imageUnsupported, sniffImageFormat, transformImageBytes } from '@ultimat3/core';
+import { contentHash } from '@ultimat3/render/server';
+import type { StaticImageRequest } from '@ultimat3/seo';
+import { ImageSourceUnreadableError } from './static-capture-errors';
+
+/** Where every variant lands, and the prefix a document names it by. */
+export const STATIC_IMAGE_DIR = '_img';
+
+/** The source encodings an export can read and resize — core's decoders, minus SVG markup. */
+const SOURCE_GLOB = new Bun.Glob('**/*.{png,jpg,jpeg,webp,gif}');
+
+interface Source {
+  readonly file: string;
+  readonly hash: string;
+  /** What the variant is written as when the document named no format. */
+  readonly ownFormat: 'png' | 'jpeg' | 'webp';
+}
+
+interface Variant {
+  readonly src: string;
+  readonly width: number;
+  /** `undefined` for a source the export does not hold: the URL is recorded, never written. */
+  readonly source: Source | undefined;
+  readonly format: string;
+}
+
+export interface StaticImages {
+  /** The URL builder `@ultimat3/seo`'s static seam calls. Never throws: refusals wait for `write`. */
+  imageUrl(request: StaticImageRequest): string;
+  /**
+   * Writes every recorded variant an exported document names, and answers their site paths. A
+   * named variant of a `src` the export does not hold is `X_IMAGE_SOURCE_UNREADABLE`; one in a
+   * format the pipeline cannot encode (`avif`) is core's `X_IMAGE_UNSUPPORTED` — a build error,
+   * never a dead `<source>`. URLs only weighed documents named are never written.
+   */
+  write(documents: readonly string[]): Promise<readonly string[]>;
+}
+
+const EXTENSION: ReadonlyMap<string, string> = new Map([
+  ['png', 'png'],
+  ['jpeg', 'jpg'],
+  ['webp', 'webp'],
+  ['avif', 'avif'],
+]);
+
+/** The site path a `src` names, without a query or fragment — the file it is in the export. */
+const pathOf = (src: string): string => src.replace(/[?#].*$/, '');
+
+/** Index the images the export already holds (`asset()` copies, icons), by their site path. */
+async function indexSources(out: string): Promise<ReadonlyMap<string, Source>> {
+  const sources = new Map<string, Source>();
+  for await (const relative of SOURCE_GLOB.scan({ cwd: out, onlyFiles: true })) {
+    const site = `/${relative.split('\\').join('/')}`;
+    if (site.startsWith(`/${STATIC_IMAGE_DIR}/`)) continue;
+    const file = join(out, relative);
+    const bytes = await Bun.file(file).bytes();
+    const format = sniffImageFormat(bytes);
+    if (format === null) continue;
+    sources.set(site, {
+      file,
+      hash: contentHash(bytes),
+      ownFormat: format === 'jpeg' || format === 'webp' ? format : 'png',
+    });
+  }
+  return sources;
+}
+
+export async function staticImages(out: string): Promise<StaticImages> {
+  const sources = await indexSources(out);
+  const variants = new Map<string, Variant>();
+  return {
+    imageUrl({ src, width, format }) {
+      const source = sources.get(pathOf(src));
+      const resolved = format ?? source?.ownFormat ?? 'png';
+      // A src the export lacks still gets a stable URL, so `write` can tell which document named it.
+      const stem = source === undefined ? `missing-${contentHash(src)}` : source.hash;
+      const url = `/${STATIC_IMAGE_DIR}/${stem}-${String(width)}.${EXTENSION.get(resolved) ?? resolved}`;
+      variants.set(url, { src, width, source, format: resolved });
+      return url;
+    },
+    async write(documents) {
+      const named = [...variants].filter(([url]) => documents.some((html) => html.includes(url)));
+      const missing = [
+        ...new Set(named.filter(([, one]) => one.source === undefined).map(([, one]) => one.src)),
+      ];
+      if (missing.length > 0) throw new ImageSourceUnreadableError(missing);
+      const refused = named.find(([, one]) => !canEncode(one.format));
+      if (refused !== undefined) {
+        throw imageUnsupported(
+          `a static page asked responsiveImage() for ${refused[1].format}, which the build pipeline cannot encode, so its <source> would name a file no build writes`,
+          "responsiveImage(input, { formats: ['webp'] })   # drop avif from a static route; a CDN driver serves it at runtime",
+          { format: refused[1].format, src: refused[1].src },
+        );
+      }
+      const written: string[] = [];
+      for (const [url, one] of named) {
+        if (one.source === undefined || !canEncode(one.format)) continue;
+        const bytes = await transformImageBytes(await Bun.file(one.source.file).bytes(), {
+          width: one.width,
+          format: one.format,
+        });
+        await Bun.write(join(out, url.slice(1)), bytes);
+        written.push(url);
+      }
+      return written;
+    },
+  };
+}

package/src/stream-hole-scope.ts

@@ -0,0 +1,55 @@
+// What is ambient inside a `<Hole>` of a `stream` page: the request's context, with the hole's own
+// signal (its deadline, the client's disconnect, the document's close) in place of the request's,
+// and the response headers sealed — they left with the first flush, so a write there was a cookie
+// or a `Location` nobody would ever receive.
+
+import { runWithContext, tryUseContext, UltimateError } from '@ultimat3/core';
+import type { HoleEnter } from '@ultimat3/render/server';
+
+const FIX =
+  'load: async () => { setCookie(name, value); return data; },   // in defineRoute, never inside a Hole';
+
+/** A response header or redirect written under a hole, after the status and headers were sent. */
+export class StreamAlreadyFlushedError extends UltimateError {
+  constructor(what: string) {
+    super({
+      code: 'X_STREAM_ALREADY_FLUSHED',
+      cause: `${what} ran inside a <Hole> on a render: 'stream' page, after the status and headers were sent with the first flush, so the browser would never receive it`,
+      fix: FIX,
+    });
+  }
+}
+
+/** Every write to the response headers refuses; every read answers what was sent. */
+const sealedHeaders = (headers: Headers): Headers =>
+  new Proxy(headers, {
+    get(target, key) {
+      if (key === 'append' || key === 'set' || key === 'delete') {
+        return (name: string) => {
+          throw new StreamAlreadyFlushedError(`writing the ${name} response header (setCookie)`);
+        };
+      }
+      const value: unknown = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+
+/**
+ * The scope a hole's children run in. Forwarded rather than rebuilt, as `runToCompletion` forwards a
+ * request's context: a rebuilt `ctxOf` drops the http fields, and `useRequestHeader()` inside a hole
+ * would then refuse. Services the request built keep the request's signal; the ambient one is the hole's.
+ */
+export const enterHole: HoleEnter = (signal, run) => {
+  const parent = tryUseContext();
+  if (parent === undefined) return run();
+  const sealed = sealedHeaders((parent as { readonly headers?: Headers }).headers ?? new Headers());
+  const scope = new Proxy(parent, {
+    get: (target, key) =>
+      key === 'signal' ? signal : key === 'headers' ? sealed : Reflect.get(target, key),
+    set: (target, key, value) => {
+      if (key === 'redirect') throw new StreamAlreadyFlushedError('setRedirect()');
+      return Reflect.set(target, key, value);
+    },
+  });
+  return runWithContext(scope, run);
+};

package/src/style-bundle.ts

@@ -3,7 +3,7 @@
 // asset over (`island-bundle.ts`), because the two answer the same question — "what does this
 // document make the browser fetch, and can it keep it?" — and one mechanism is the whole point.
 //
-// Why it stopped being an inline `<style>`: measured against ai-maxxing on 2026-09-06, every
+// Why it stopped being an inline `<style>`: measured against one adopter's app on 2026-09-06, every
 // `app/` document carried one 156,738-byte block — 1,336 rules from 406 module sources, byte
 // identical across `/`, `/fleet`, `/fleet/[host]` and the session page — inside a response the
 // pipeline sends `Cache-Control: private, no-store`. 92% of the dashboard document and 89% of the