@ultimat3/cli 29.3.2 → 30.0.0

package/src/site-llms.ts

@@ -0,0 +1,64 @@
+// `/llms.txt`'s pages, off the route table: every public `site/` page in the default locale by the
+// title and description its own `meta` gives it. A dynamic route (or one with a `load`) is expanded
+// through `prerender()` and its `load`, page by page, exactly as the static export renders it — or
+// read off what the export already collected inside its API scope (`site-llms-pages.ts`).
+
+import type { Environment } from '@ultimat3/core';
+import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { unlocalizedPath } from '@ultimat3/i18n';
+import type { RouteRecord } from '@ultimat3/seo';
+import { buildLlmsTxt, disallowMatcher, isDynamic, isIndexable } from '@ultimat3/seo';
+import type { Enumerate, LlmsPages } from './site-llms-pages';
+import { llmsRoutes, pageRecords } from './site-llms-pages';
+
+export interface SiteLlmsOptions {
+  readonly baseUrl: string;
+  readonly environment?: Environment | undefined;
+  /** `seo.llms`; `false` answers an empty document. */
+  readonly enabled?: boolean | undefined;
+  readonly disallow?: readonly string[] | undefined;
+  /** The static export's emitted pages per route, as the sitemap reads them (`SiteSeoOptions`). */
+  readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
+  /** The app's default locale: every `meta` runs in it, and its paths are unprefixed. */
+  readonly defaultLocale: string;
+  /** `siteSeo`'s one enumeration per route, so the sitemap and this file never call `prerender()` twice. */
+  readonly enumerate?: Enumerate | undefined;
+  /**
+   * What the static export read inside its API scope (`collectLlmsPages`), by declared route path.
+   * A route listed here never runs its `load` again: by the time `llms.txt` is written the build's
+   * scope is gone, and a `load` reading the app's own query failed the export
+   * (`X_CLIENT_TRANSPORT_FAILED`).
+   */
+  readonly pages?: LlmsPages | undefined;
+}
+
+/**
+ * Empty outside production and under `seo.llms: false` BEFORE any `prerender()` or `load` runs: a
+ * staging web role must not read every post to answer a document it then throws away.
+ */
+export async function siteLlms(options: SiteLlmsOptions): Promise<string> {
+  const environment = options.environment ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
+  if (options.enabled === false || !isIndexable(environment)) return '';
+  const disallowed = disallowMatcher(options.disallow ?? []);
+  const { resolved, loaded } = await llmsRoutes(options.defaultLocale);
+  const expanded: RouteRecord[] = [];
+  for (const entry of loaded) {
+    const records = options.pages?.get(entry.path) ?? (await pageRecords(entry, options));
+    expanded.push(...emittedOnly(entry.path, records, options));
+  }
+  return buildLlmsTxt(
+    [...resolved, ...expanded].filter((record) => !disallowed(record.path)),
+    { baseUrl: options.baseUrl, environment },
+  );
+}
+
+/** A dynamic route's pages, less those the export did not emit — the sitemap's own rule. */
+function emittedOnly(
+  routePath: string,
+  records: readonly RouteRecord[],
+  options: SiteLlmsOptions,
+): readonly RouteRecord[] {
+  if (options.pagesFor === undefined || !isDynamic(routePath)) return records;
+  const emitted = new Set(options.pagesFor(routePath).map((path) => unlocalizedPath(path)));
+  return records.filter((record) => emitted.has(record.path));
+}

package/src/site-seo-write.ts

@@ -1,8 +1,9 @@
 // Single responsibility: `siteSeo()`'s answer as files in a static export — `/sitemap.xml`, every
-// part an index names, and `robots.txt` — so a CDN serves the bytes a running web role answers.
+// part an index names, `robots.txt` and `llms.txt` — so a CDN serves the bytes a running web role answers.
 
 // why: Bun exposes no path-join primitive, and every file path is relative to the output root.
 import { join } from 'node:path';
+import { LLMS_PATH } from '@ultimat3/seo';
 import { ROBOTS_PATH, type SiteSeo } from './site-seo';
 
 /**
@@ -12,5 +13,6 @@ import { ROBOTS_PATH, type SiteSeo } from './site-seo';
 export async function writeSiteSeo(out: string, seo: SiteSeo): Promise<readonly string[]> {
   for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
   await Bun.write(join(out, ROBOTS_PATH), seo.robots);
-  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH];
+  await Bun.write(join(out, LLMS_PATH), seo.llms);
+  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH, LLMS_PATH];
 }

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 });
 }