@ultimat3/cli 22.13.0 → 22.15.0

package/CLAUDE.md

@@ -84,6 +84,8 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `app-openapi.ts` | `openapi.json` (complete when `defineApi({ openapi })` is declared) and each bearer mount's own document; staleness for all of them |
 | `script-csp.ts` / `style-csp.ts` / `style-bundle.ts` / `page-sync.ts` / `worker-bundle.ts` | CSP hashes, the CSS file, the page's sync target and worker |
 | `page-navigation.ts` | the client router for `navigation.client` surfaces — built, routed and named ONCE for `x dev`, the container and the static export; none opted in builds nothing |
+| `page-speculation.ts` | Speculation Rules for documents WITHOUT the router (`navigation.speculation`): the allow-list of pure-read pages, the one tag, and its `script-src` hash — composed once for all three writers. An allow-list, never "every link but": a prefetch is a real GET with cookies |
+| `static-document.ts` | a served `static` page: `304` on a matching `If-None-Match`, and (container only, `memoStatic`) the document kept after its first render. Never `x dev` — a save moves the stylesheet URL the kept document names |
 | `island-bundle.ts` / `island-store.ts` / `island-realtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; `x build --target docker` writes a verified store the container loads |
 | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.13.0",
+  "version": "22.15.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.13.0",
-    "@ultimat3/admin": "22.13.0",
-    "@ultimat3/ai": "22.13.0",
-    "@ultimat3/auth": "22.13.0",
-    "@ultimat3/cache": "22.13.0",
-    "@ultimat3/core": "22.13.0",
-    "@ultimat3/db": "22.13.0",
-    "@ultimat3/entity": "22.13.0",
-    "@ultimat3/flags": "22.13.0",
-    "@ultimat3/http": "22.13.0",
-    "@ultimat3/i18n": "22.13.0",
-    "@ultimat3/jobs": "22.13.0",
-    "@ultimat3/mail": "22.13.0",
-    "@ultimat3/manifest": "22.13.0",
-    "@ultimat3/mcp": "22.13.0",
-    "@ultimat3/money": "22.13.0",
-    "@ultimat3/notify": "22.13.0",
-    "@ultimat3/policy": "22.13.0",
-    "@ultimat3/pwa": "22.13.0",
-    "@ultimat3/query": "22.13.0",
-    "@ultimat3/realtime": "22.13.0",
-    "@ultimat3/render": "22.13.0",
-    "@ultimat3/schema": "22.13.0",
-    "@ultimat3/seo": "22.13.0",
-    "@ultimat3/storage": "22.13.0",
-    "@ultimat3/testing": "22.13.0",
-    "@ultimat3/time": "22.13.0",
+    "@ultimat3/action": "22.15.0",
+    "@ultimat3/admin": "22.15.0",
+    "@ultimat3/ai": "22.15.0",
+    "@ultimat3/auth": "22.15.0",
+    "@ultimat3/cache": "22.15.0",
+    "@ultimat3/core": "22.15.0",
+    "@ultimat3/db": "22.15.0",
+    "@ultimat3/entity": "22.15.0",
+    "@ultimat3/flags": "22.15.0",
+    "@ultimat3/http": "22.15.0",
+    "@ultimat3/i18n": "22.15.0",
+    "@ultimat3/jobs": "22.15.0",
+    "@ultimat3/mail": "22.15.0",
+    "@ultimat3/manifest": "22.15.0",
+    "@ultimat3/mcp": "22.15.0",
+    "@ultimat3/money": "22.15.0",
+    "@ultimat3/notify": "22.15.0",
+    "@ultimat3/policy": "22.15.0",
+    "@ultimat3/pwa": "22.15.0",
+    "@ultimat3/query": "22.15.0",
+    "@ultimat3/realtime": "22.15.0",
+    "@ultimat3/render": "22.15.0",
+    "@ultimat3/schema": "22.15.0",
+    "@ultimat3/seo": "22.15.0",
+    "@ultimat3/storage": "22.15.0",
+    "@ultimat3/testing": "22.15.0",
+    "@ultimat3/time": "22.15.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-mcp.ts

@@ -3,7 +3,9 @@
 // `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
 // neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
-// exports `mcp`, an `AppMcp`; this module finds it, and both boots mount what it carries.
+// exports `mcp` — one `AppMcp`, or an array of them, one per population (customers, staff,
+// affiliates) — this module finds it, and both boots mount what it carries: endpoint #0 at
+// `ai.mcp.path`, every other at its own `defineAppMcp({ path })`.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
@@ -12,23 +14,38 @@ import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { json, selfOrigin } from '@ultimat3/http';
-import { type AppMcp, McpAppUnmountedError } from '@ultimat3/mcp';
+import {
+  type AppMcp,
+  McpAppUnmountedError,
+  McpPathDuplicateError,
+  PROTECTED_RESOURCE_WELL_KNOWN,
+} from '@ultimat3/mcp';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
-/** The export that file makes — an `AppMcp`, the value `defineAppMcp` returns. */
+/**
+ * The export that file makes — an `AppMcp`, the value `defineAppMcp` returns, or a non-empty array
+ * of them. ONE export name either way: a second named export per endpoint would be a second way
+ * to say the same thing, and the array's order is the one fact the mount needs (#0 is the default).
+ */
 export const APP_MCP_EXPORT = 'mcp';
-/** What the boot line and `/_x` call the route. */
+/** What the boot line and `/_x` call endpoint #0's route; endpoint #n is `mcp:<its path>`. */
 export const APP_MCP_ROUTE_NAME = 'mcp';
 
 export interface AppMcpMount {
-  /** `[]` when `expose` is false, when nothing exports `mcp`, or when the export has no route. */
+  /** `[]` when `expose` is false, when nothing exports `mcp`, or when no endpoint has a route. */
   readonly routes: readonly Route[];
-  /** `POST <path>` when mounted, else `null` — the boot line prints it. */
+  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default, at `ai.mcp.path`. */
   readonly path: string | null;
-  /** Set exactly when `expose` is true and `routes` is empty: the reason, as an instruction. */
+  /** Every mounted endpoint's `POST <path>`, in export order — the boot line prints one each. */
+  readonly paths: readonly string[];
+  /**
+   * Set when `expose` is true and an endpoint could not be mounted — nothing exports `mcp`, or the
+   * first endpoint built without `resolveToken`: the reason, as an instruction. The endpoints that
+   * could be mounted still are.
+   */
   readonly warning: McpAppUnmountedError | undefined;
 }
 
@@ -65,6 +82,13 @@ async function exposeDeclaration(root: string): Promise<ExposeDeclaration | unde
 const isAppMcp = (value: unknown): value is AppMcp =>
   isRecord(value) && 'server' in value && 'tools' in value && 'route' in value;
 
+/** The export as a list of endpoints, or `undefined` when it is not one (the "missing" case). */
+function endpointsOf(exported: unknown): readonly AppMcp[] | undefined {
+  if (isAppMcp(exported)) return [exported];
+  if (!Array.isArray(exported) || exported.length === 0) return undefined;
+  return exported.every(isAppMcp) ? (exported as readonly AppMcp[]) : undefined;
+}
+
 /** Every `apps/<app>/mcp.ts`, app-root-relative and sorted, so two apps answer in one order. */
 async function candidates(root: string): Promise<readonly string[]> {
   // A root with no `apps/` is an app with no MCP file, never a boot failure — the scan's ENOENT
@@ -75,8 +99,10 @@ async function candidates(root: string): Promise<readonly string[]> {
   return files.sort();
 }
 
+const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undefined };
+
 /**
- * The route to mount, or the reason there is none. Pure over the filesystem it is pointed at;
+ * The routes to mount, or the reason there are none. Pure over the filesystem it is pointed at;
  * `mountAppMcp` below is the one place the warning becomes a log line.
  *
  * `meta.auth: 'public'` and `enforcedBy: 'handler'` — the http pipeline must not pre-judge:
@@ -87,72 +113,17 @@ async function candidates(root: string): Promise<readonly string[]> {
  */
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
   const declared = await exposeDeclaration(root);
-  if (declared === undefined || !declared.expose)
-    return { routes: [], path: null, warning: undefined };
+  if (declared === undefined || !declared.expose) return NOTHING;
   const files = await candidates(root);
   const fallbackFile = 'apps/web/mcp.ts';
-  if (files.length === 0) {
-    return {
-      routes: [],
-      path: null,
-      warning: new McpAppUnmountedError({
-        reason: 'missing',
-        path: declared.path,
-        file: fallbackFile,
-      }),
-    };
-  }
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
-    const exported = module[APP_MCP_EXPORT];
-    if (!isAppMcp(exported)) continue;
-    const route = exported.route;
-    if (route === undefined) {
-      return {
-        routes: [],
-        path: null,
-        warning: new McpAppUnmountedError({ reason: 'no-route', path: declared.path, file }),
-      };
-    }
-    // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
-    // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://` on
-    // an internal host, and a `resource_metadata` naming that is a URL no client can reach.
-    const resource = route.protectedResource;
-    return {
-      routes: [
-        {
-          method: 'POST',
-          path: declared.path,
-          handler: (request, ctx) =>
-            route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
-          meta: { name: APP_MCP_ROUTE_NAME, auth: 'public', enforcedBy: 'handler' },
-        },
-        // RFC 9728 protected-resource metadata, when the app declared `oauth`: path-inserted and
-        // at the root, so a client probing either finds the authorization server.
-        ...(resource === undefined
-          ? []
-          : resource.paths.map(
-              (path): Route => ({
-                method: 'GET',
-                path,
-                handler: (_request, ctx) => {
-                  const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
-                  // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
-                  response.headers.set('access-control-allow-origin', '*');
-                  response.headers.set('cache-control', 'public, max-age=3600');
-                  return response;
-                },
-                meta: { name: `${APP_MCP_ROUTE_NAME}.oauth-protected-resource`, auth: 'public' },
-              }),
-            )),
-      ],
-      path: declared.path,
-      warning: undefined,
-    };
+    const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
+    if (endpoints === undefined) continue;
+    return mountEndpoints(endpoints, declared.path, file);
   }
   return {
-    routes: [],
-    path: null,
+    ...NOTHING,
     warning: new McpAppUnmountedError({
       reason: 'missing',
       path: declared.path,
@@ -161,6 +132,95 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
   };
 }
 
+/**
+ * One file's endpoints onto one route table. An endpoint built without `resolveToken` has no
+ * route: it is skipped and the FIRST such is the warning, so one unfinished population never takes
+ * the others down with it. Two endpoints on one route is thrown — see `McpPathDuplicateError`.
+ */
+function mountEndpoints(
+  endpoints: readonly AppMcp[],
+  defaultPath: string,
+  file: string,
+): AppMcpMount {
+  const routes: Route[] = [];
+  const paths: string[] = [];
+  const claimed = new Map<string, number>();
+  let warning: McpAppUnmountedError | undefined;
+  endpoints.forEach((endpoint, index) => {
+    const route = endpoint.route;
+    if (route === undefined) {
+      warning ??= new McpAppUnmountedError({
+        reason: 'no-route',
+        path: defaultPath,
+        file,
+        ...(index === 0 ? {} : { endpoint: index }),
+      });
+      return;
+    }
+    const path = index === 0 ? defaultPath : route.path;
+    for (const mounted of endpointRoutes(route, path, index)) {
+      const key = `${mounted.method} ${mounted.path}`;
+      const first = claimed.get(key);
+      if (first !== undefined) {
+        throw new McpPathDuplicateError({
+          method: mounted.method,
+          path: mounted.path,
+          endpoints: [first, index],
+          file,
+        });
+      }
+      claimed.set(key, index);
+      routes.push(mounted);
+    }
+    paths.push(path);
+  });
+  const path = endpoints[0]?.route === undefined ? null : defaultPath;
+  return { routes, path, paths, warning };
+}
+
+type Descriptor = NonNullable<AppMcp['route']>;
+
+/** One endpoint's `POST` and, when it declared `oauth`, its RFC 9728 metadata `GET`s. */
+function endpointRoutes(route: Descriptor, path: string, index: number): readonly Route[] {
+  const name = index === 0 ? APP_MCP_ROUTE_NAME : `${APP_MCP_ROUTE_NAME}:${path}`;
+  const resource = route.protectedResource;
+  // The ROOT document belongs to endpoint #0 alone: a client that probes the bare well-known URL
+  // is asking about the default resource, and a second endpoint answering there would collide.
+  // Every endpoint keeps its path-inserted document (RFC 9728 §3.1), which its own 401 names.
+  const metadata: readonly Route[] =
+    resource === undefined
+      ? []
+      : resource.paths
+          .filter((metadataPath) => index === 0 || metadataPath !== PROTECTED_RESOURCE_WELL_KNOWN)
+          .map(
+            (metadataPath): Route => ({
+              method: 'GET',
+              path: metadataPath,
+              handler: (_request, ctx) => {
+                const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
+                // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
+                response.headers.set('access-control-allow-origin', '*');
+                response.headers.set('cache-control', 'public, max-age=3600');
+                return response;
+              },
+              meta: { name: `${name}.oauth-protected-resource`, auth: 'public' },
+            }),
+          );
+  return [
+    {
+      method: 'POST',
+      path,
+      // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
+      // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
+      // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      handler: (request, ctx) =>
+        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+      meta: { name, auth: 'public', enforcedBy: 'handler' },
+    },
+    ...metadata,
+  ];
+}
+
 /**
  * The boot's call: the routes to spread into the table, with the warning already logged ONCE and
  * the mount announced. Both `x dev` and `runRole` go through here, so a developer's terminal and a
@@ -171,6 +231,6 @@ export async function mountAppMcp(root: string): Promise<AppMcpMount> {
   if (mount.warning !== undefined) {
     logger.warn(`${mount.warning.code}: ${mount.warning.cause} — fix: ${mount.warning.fix}`);
   }
-  if (mount.path !== null) logger.info('app mcp mounted', { method: 'POST', path: mount.path });
+  for (const path of mount.paths) logger.info('app mcp mounted', { method: 'POST', path });
   return mount;
 }

package/src/budgets.ts

@@ -10,7 +10,12 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
-import { formatBytes, parseByteBudget, themeScriptBody } from '@ultimat3/render';
+import {
+  formatBytes,
+  parseByteBudget,
+  SPECULATION_RULES_TYPE,
+  themeScriptBody,
+} from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
 import { SW_REGISTER_PATH } from './sw-artifacts';
@@ -242,7 +247,10 @@ const carriesJson = (attrs: string): boolean => {
   // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
   // test alone charged an SEO structured-data block as executable JavaScript all over again.
   const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
-  return type.trim().toLowerCase().endsWith('json');
+  const declared = type.trim().toLowerCase();
+  // Speculation rules are JSON under a type that does not say so: read by the browser's
+  // prefetcher, never executed — the one script a 0kb page may carry for free.
+  return declared.endsWith('json') || declared === SPECULATION_RULES_TYPE;
 };
 
 /**

package/src/cmd-dev.ts

@@ -79,8 +79,10 @@ export interface DevServer {
   readonly runtime: RunningServices;
   /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
   readonly panels: readonly string[];
-  /** `POST <path>` of the app's own MCP endpoint, or `null` when nothing was mounted. */
+  /** `POST <path>` of the app's default MCP endpoint, or `null` when nothing was mounted. */
   readonly mcp: string | null;
+  /** `POST <path>` of every mounted MCP endpoint, default first — `[]` when none was. */
+  readonly mcpPaths: readonly string[];
   stop(): Promise<void>;
 }
 
@@ -240,7 +242,7 @@ async function bootDev(
   // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
   // its whole ttl after every save, whatever the modules behind it now said.
   const isr = createIsrController({ buildId });
-  const { routes, theme, errorStyles, mcpPath } = await devRouteTable({
+  const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
     env: options.env,
@@ -276,7 +278,7 @@ async function bootDev(
     // The `/_x` shell, the harness's frame, and the app's own error pages — the inline bodies this
     // process serves; the app's surfaces are content-hashed files `'self'` admits.
     inlineStyles: [await devShellStyle(), FRAME_STYLE, ...errorStyles],
-    inlineScripts: [theme.cspSource],
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
     // The overlay renders this request's own loops under the error it is already showing.
     // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
@@ -328,6 +330,7 @@ async function bootDev(
     services,
     roles: running.roles,
     mcp: mcpPath,
+    mcpPaths,
     get buildId(): string {
       return stamped ?? state.manifest.buildId;
     },
@@ -447,6 +450,7 @@ export const devCommand: CliCommand = {
         introspect: `${server.url}/_x`,
         panels: [...server.panels],
         mcp: server.mcp,
+        mcpPaths: [...server.mcpPaths],
       },
       lines: [
         // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
@@ -458,7 +462,8 @@ export const devCommand: CliCommand = {
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
         // Only when something was mounted: the unmounted case has already said why, once, as a
         // warning with a fix, and a summary line reading `mcp none` would be a second copy of it.
-        ...(server.mcp === null ? [] : [msg('cli.dev.mcp', { path: server.mcp })]),
+        // One line per endpoint, so an app serving customers, staff and affiliates sees all three.
+        ...server.mcpPaths.map((path) => msg('cli.dev.mcp', { path })),
       ],
     };
     await writeLock(services.stateDir, {

package/src/dev-route-table.ts

@@ -17,6 +17,8 @@ import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
 import { loadNavigation, pageNavigation } from './page-navigation';
+import type { PageSpeculation } from './page-speculation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { assetRoutes } from './runtime-assets';
@@ -56,10 +58,14 @@ export interface DevRouteTable {
   readonly routes: readonly Route[];
   /** The theme boot, whose `cspSource` the web role admits. */
   readonly theme: ThemeBoot;
+  /** The speculation rules, admitted the same way — `undefined` when no document carries any. */
+  readonly speculation: PageSpeculation | undefined;
   /** The app's own error pages' inline styles, admitted the same way. */
   readonly errorStyles: readonly string[];
-  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  /** Where the app's default MCP endpoint was mounted, or `null`. */
   readonly mcpPath: string | null;
+  /** Every mounted MCP endpoint's path, default first — one per population the app serves. */
+  readonly mcpPaths: readonly string[];
 }
 
 export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
@@ -73,11 +79,14 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
   const sync = await pageSync(input.root, input.env, input.buildId, input.realtime);
   // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
-  const navigation = await pageNavigation(
-    input.root,
-    await loadNavigation(input.root),
-    input.buildId,
-  );
+  const declared = await loadNavigation(input.root);
+  const navigation = await pageNavigation(input.root, declared, input.buildId);
+  // The browser's own prefetch, from the table as it stands at boot: a page added by a later save
+  // joins the rules on the next `x dev` — its links are a full load until then, never a wrong one.
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(input.root),
+    client: declared.surfaces,
+  });
   const errorStyles = await errorPageStyleSources(input.root);
   // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
   // changes under a page it controls is the update path, and one per keystroke exercises it per save.
@@ -149,6 +158,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined
         ? {}
@@ -156,5 +166,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
   ];
 
-  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+  return {
+    routes,
+    theme,
+    speculation,
+    errorStyles,
+    mcpPath: mcpMount.path,
+    mcpPaths: mcpMount.paths,
+  };
 }

package/src/document-options.ts

@@ -0,0 +1,64 @@
+// What a document renderer is handed by the boot that knows it: the island resolver and every
+// document-level head the route itself cannot decide. Split out of `runtime-render.ts` at its
+// 500-line ceiling; one declaration for `x dev`, the container and the static export.
+
+import type { ClientSyncHead } from '@ultimat3/render';
+import type { NavigationDocumentHead } from './page-navigation';
+
+/**
+ * Specifier → built chunk URL, bound to the route file the specifier is written relative to.
+ * Supplied by whoever built the islands (`x dev`, the container, the static build); absent means
+ * no island was built, and a page that renders one then fails by name rather than emitting a
+ * `data-x-entry` nothing can import.
+ */
+export type IslandResolver = (routeFile: string) => (src: string) => string;
+
+export interface DocumentOptions {
+  readonly resolveIsland?: IslandResolver;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
+   * from `pwa-artifacts.ts`, or absent when the app is not installable.
+   *
+   * A document-level string rather than something a route's `meta()` returns: it is the same three
+   * elements on every page of the app, an installable app is one whose EVERY page carries them
+   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
+   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
+   * boot knows it, the renderer cannot ask.
+   */
+  readonly pwaHead?: string | ((locale: string) => string);
+  /**
+   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
+   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
+   * decided by `app.config.ts`, which the boot read and the renderer cannot.
+   */
+  readonly themeHead?: string;
+  /**
+   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
+   * document this process serves. Principal-free, so a shareable document carries it too; absent
+   * for a caller that serves no socket at all (the static export).
+   */
+  readonly sync?: ClientSyncHead;
+  /**
+   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
+   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
+   * with no scope carries none.
+   */
+  readonly persisted?: () => readonly string[];
+  /**
+   * The public origin canonical, `og:url` and hreflang are absolute against — `publicOrigin()`
+   * from `site-config.ts`. Absent, the request's own origin: a relative canonical is one a crawler
+   * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
+   */
+  readonly origin?: string;
+  /**
+   * The client router — `pageNavigation(…).head`. A document of a surface listed in
+   * `navigation.client` names it; every other document carries none of it.
+   */
+  readonly navigation?: NavigationDocumentHead;
+  /**
+   * `<script type="speculationrules">` — `pageSpeculation(…).head` — on every document that names
+   * NO client router: the browser prefetches the next page instead. A document with the router
+   * carries none, because the router prefetches by its own rules.
+   */
+  readonly speculationHead?: string;
+}

package/src/page-speculation.ts

@@ -0,0 +1,124 @@
+// Speculation Rules for the documents that carry NO client router, composed ONCE for `x dev`, the
+// container and the static export: `navigation.speculation` from `app.config.ts`, the pages the
+// route table knows to be a pure read, the one `<script type="speculationrules">` every such
+// document carries, and the `script-src` source that admits exactly that body. A browser fetches
+// the next page's document on pointer rest, so a full-page navigation between prerendered pages
+// paints from memory — and the page still ships 0kb of JavaScript (axiom 6).
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
+// necessity `theme-boot.ts` records.
+import { join } from 'node:path';
+import type { NavigationSurface, SpeculationConfig } from '@ultimat3/core';
+import { DEFAULT_SPECULATION, localeSegment, resolveSpeculation } from '@ultimat3/core';
+import { cspHashSource } from '@ultimat3/http';
+import { localeConfig, routedLocales } from '@ultimat3/i18n';
+import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
+import {
+  describeRoutes,
+  renderHead,
+  routeEntries,
+  speculationPattern,
+  speculationRulesBody,
+  speculationRulesTag,
+} from '@ultimat3/render';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * `navigation.speculation` — the default (on, `'moderate'`) when the app says nothing or has no
+ * config file. Structural, for `loadThemeMode`'s reason, and so possibly NOT what `defineConfig`
+ * validated: what it finds goes through core's `resolveSpeculation`, the one validator, which
+ * REFUSES (`X_CONFIG_INVALID`) a value `defineConfig` would refuse. Never coerced: an `'eager'`
+ * quietly served as `'moderate'` is a rule the app did not write.
+ */
+export async function loadSpeculation(root: string): Promise<SpeculationConfig> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return DEFAULT_SPECULATION;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const navigation = isRecord(config) ? config['navigation'] : undefined;
+  return resolveSpeculation(isRecord(navigation) ? navigation['speculation'] : undefined);
+}
+
+/**
+ * Whether a browser may fetch this page before anyone asked for it. An ALLOW-list, never "every
+ * link but these": a prefetch is a real GET with the visitor's cookies, so the only safe candidates
+ * are pages the table itself says are a pure read.
+ *
+ * - On a surface WITHOUT the client router: a prerendered, shareable document — `static` or `isr`,
+ *   no policy, no `no-store`. Such a page ran its `load` at build time, for nobody. An `ssr` page
+ *   there has no way to declare that its GET records something (`navigation` is refused on a
+ *   surface that did not opt in), so it is never a candidate.
+ * - On a client-routed surface: only a page that declared `navigation: 'prefetch'` — the app's own
+ *   statement that its GET is a pure read, the same one the router's prefetch obeys.
+ * - Never an `api/` route, a `navigation: 'document'` page, or an `offline: 'network-only'` one.
+ */
+export function speculationCandidate(
+  entry: Pick<RouteEntry, 'surface' | 'config'>,
+  described: Pick<RouteDescriptor, 'mode' | 'offline' | 'personal'>,
+  client: ReadonlySet<string>,
+): boolean {
+  if (entry.surface !== 'site' && entry.surface !== 'app') return false;
+  if (entry.config.navigation === 'document' || described.offline === 'network-only') return false;
+  if (client.has(entry.surface)) return entry.config.navigation === 'prefetch';
+  return (described.mode === 'static' || described.mode === 'isr') && !described.personal;
+}
+
+export interface PageSpeculation {
+  /** The rendered `<script type="speculationrules">`, for `DocumentOptions.speculationHead`. */
+  readonly head: string;
+  /** The text between its tags — what a browser hashes. */
+  readonly body: string;
+  /** The `script-src` source that admits exactly that body. */
+  readonly cspSource: string;
+}
+
+export interface PageSpeculationInput {
+  readonly config: SpeculationConfig;
+  /** `navigation.client`: the surfaces whose documents carry the router instead. */
+  readonly client: readonly NavigationSurface[];
+  readonly entries?: readonly RouteEntry[];
+  readonly described?: readonly RouteDescriptor[];
+  /** The NON-default routed locales' URL segments. Read from `@ultimat3/i18n` when absent. */
+  readonly localeSegments?: readonly string[];
+}
+
+const otherLocaleSegments = (): readonly string[] => {
+  const fallback = localeSegment(localeConfig().fallback);
+  return routedLocales()
+    .map(localeSegment)
+    .filter((segment) => segment !== fallback);
+};
+
+/**
+ * Tag and hash from ONE body, as `themeBoot` does. `undefined` when the app turned it off or no
+ * page is a candidate — then no document carries a tag and the policy admits nothing new. Called
+ * after the app is loaded: the route table and the routed locales are what it reads.
+ */
+export function pageSpeculation(input: PageSpeculationInput): PageSpeculation | undefined {
+  if (input.config.prefetch === false) return undefined;
+  const entries = input.entries ?? routeEntries();
+  const described = new Map((input.described ?? describeRoutes()).map((one) => [one.file, one]));
+  const client = new Set<string>(input.client);
+  const segments = input.localeSegments ?? otherLocaleSegments();
+  const include = entries
+    .filter((entry) => {
+      const facts = described.get(entry.file);
+      return facts !== undefined && speculationCandidate(entry, facts, client);
+    })
+    .map((entry) => speculationPattern(entry.path, segments));
+  const body = speculationRulesBody({
+    eagerness: input.config.prefetch,
+    include,
+    exclude: input.config.exclude,
+  });
+  if (body === undefined) return undefined;
+  return {
+    head: renderHead([speculationRulesTag(body)]),
+    body,
+    cspSource: cspHashSource(body),
+  };
+}

package/src/prerender.ts

@@ -28,6 +28,7 @@ import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
 import { measureScope, withAppUrl } from './measure-scope';
 import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
 import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
@@ -237,11 +238,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // The client router, for the surfaces that opted in: written BEFORE any document names it, for
   // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
   // the route (the interactivity the app asked for), so it must be there to be weighed.
-  const navigation = await pageNavigation(
-    options.root,
-    await loadNavigation(options.root),
-    buildId,
-  );
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The same rules the served process writes, so the exported file and the served document agree.
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
   if (navigation.script !== undefined) {
     await Bun.write(join(options.out, navigation.script.url.slice(1)), navigation.script.code);
   }
@@ -305,6 +308,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     routeDocument(entry, data, {
       resolveIsland: (file: string) => islands.resolverFor(file),
       themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       origin,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       ...(pwa === undefined

package/src/runtime-render.ts

@@ -27,13 +27,7 @@ import type {
 } from '@ultimat3/http';
 import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
 import { currentLocale, localeConfig } from '@ultimat3/i18n';
-import type {
-  ClientSyncHead,
-  IslandCollector,
-  RenderResult,
-  RouteData,
-  RouteEntry,
-} from '@ultimat3/render';
+import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
 import {
   clientBootTags,
   clientPersistTags,
@@ -65,6 +59,7 @@ import {
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import type { DocumentOptions } from './document-options';
 import { realtimeIslandFiles } from './island-realtime';
 import {
   type NavigationDocumentHead,
@@ -72,64 +67,21 @@ import {
   navigationTagsOf,
   principalRelocation,
 } from './page-navigation';
+import type { StaticResult } from './static-document';
+import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
 
-/**
- * Specifier → built chunk URL, bound to the route file the specifier is written relative to.
- * Supplied by whoever built the islands (`x dev`, the container, the static build); absent means
- * no island was built, and a page that renders one then fails by name rather than emitting a
- * `data-x-entry` nothing can import.
- */
-export type IslandResolver = (routeFile: string) => (src: string) => string;
-
-export interface DocumentOptions {
-  readonly resolveIsland?: IslandResolver;
-  /**
-   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
-   * from `pwa-artifacts.ts`, or absent when the app is not installable.
-   *
-   * A document-level string rather than something a route's `meta()` returns: it is the same three
-   * elements on every page of the app, an installable app is one whose EVERY page carries them
-   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
-   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
-   * boot knows it, the renderer cannot ask.
-   */
-  readonly pwaHead?: string | ((locale: string) => string);
-  /**
-   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
-   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
-   * decided by `app.config.ts`, which the boot read and the renderer cannot.
-   */
-  readonly themeHead?: string;
-  /**
-   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
-   * document this process serves. Principal-free, so a shareable document carries it too; absent
-   * for a caller that serves no socket at all (the static export).
-   */
-  readonly sync?: ClientSyncHead;
-  /**
-   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
-   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
-   * with no scope carries none.
-   */
-  readonly persisted?: () => readonly string[];
-  /**
-   * The public origin canonical, `og:url` and hreflang are absolute against — `publicOrigin()`
-   * from `site-config.ts`. Absent, the request's own origin: a relative canonical is one a crawler
-   * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
-   */
-  readonly origin?: string;
-  /**
-   * The client router — `pageNavigation(…).head`. A document of a surface listed in
-   * `navigation.client` names it; every other document carries none of it.
-   */
-  readonly navigation?: NavigationDocumentHead;
-}
+export type { DocumentOptions, IslandResolver } from './document-options';
 
 export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
   /** Injected so a test can drive the ISR store without a timer. */
   readonly isr?: IsrController;
+  /**
+   * Keep each `static` document after its first render (`static-document.ts`). The container sets
+   * it; `x dev` never does — a save changes the page, its stylesheet's URL and its islands'.
+   */
+  readonly memoStatic?: boolean;
 }
 
 /** What a route's `meta(data)` is given. `url` is a string because that is what `ld.*` embeds. */
@@ -162,6 +114,7 @@ const headFor = async (
 ): Promise<string> => {
   const meta = metaContextFor(ctx, data);
   const url = new URL(ctx.url);
+  const router = navigationTagsOf(options.navigation, entry);
   return (
     renderHead(
       headFromMeta(
@@ -177,7 +130,7 @@ const headFor = async (
         }),
         [
           ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
-          ...navigationTagsOf(options.navigation, entry),
+          ...router,
           // The page boot rides the scope tag: its whole job — restoring a principal's persisted
           // records and replaying its queued writes — is per principal, and a shareable document
           // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
@@ -188,6 +141,8 @@ const headFor = async (
       ),
     ) +
     (options.themeHead ?? '') +
+    // One mechanism per document: the router prefetches for itself, the browser for the rest.
+    (router.length === 0 ? (options.speculationHead ?? '') : '') +
     // Per locale: each links its own locale's manifest (`PwaArtifacts.headFor`).
     (typeof options.pwaHead === 'function' ? options.pwaHead(meta.locale) : (options.pwaHead ?? ''))
   );
@@ -469,6 +424,7 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? createIsrController({ buildId: options.buildId });
+  const memo = createStaticMemo();
   return routeEntries().map((registered) => ({
     method: 'GET' as const,
     path: registered.path,
@@ -481,6 +437,13 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
       // A soft visit onto another principal's document is a real load — answered before `load`.
       const moved = principalRelocation(entry, request, asCtx(ctx), options.buildId);
       if (moved !== undefined) return moved;
+      // A static page already rendered by this process is answered without `load` or a render.
+      const key =
+        options.memoStatic === true
+          ? staticMemoKey(entry, request.url, asCtx(ctx).locale)
+          : undefined;
+      const kept = key === undefined ? undefined : memo.get(key);
+      if (kept !== undefined) return staticResponse(request, kept);
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
       // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
       // object, so a route's `load` runs exactly once however its mode splits head from body.
@@ -490,7 +453,14 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
       // 3xx because a rendered document has no `Location`; this is the path that has one.
       const to = takeRedirect(ctx);
       if (to !== undefined) return loadRedirect(entry, to);
-      return responseOf(await resultFor(entry, data, loaded, options, isr, asCtx(ctx)));
+      const result = await resultFor(entry, data, loaded, options, isr, asCtx(ctx));
+      if (entry.config.render !== 'static' || typeof result.body !== 'string') {
+        return responseOf(result);
+      }
+      const document: StaticResult = { ...result, body: result.body };
+      if (key !== undefined) memo.set(key, document);
+      // The ETag was only ever a header: a matching `If-None-Match` is a 304, not the page again.
+      return staticResponse(request, document);
     },
   }));
 }

package/src/serve-boot.ts

@@ -19,6 +19,7 @@ import { loadOrBuildIslands } from './island-store';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
 import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { startRoles } from './role-start';
@@ -98,7 +99,7 @@ export async function bootRoles(boot: {
     // The enforced policy this process sends must admit the app's own error pages' `<style>` and
     // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
     inlineStyles: web === undefined ? [] : await errorPageStyleSources(options.root),
-    inlineScripts: web === undefined ? [] : [web.themeCsp],
+    inlineScripts: web === undefined ? [] : web.inlineScripts,
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,
@@ -134,7 +135,7 @@ async function webSurface(
   options: ServeOptions,
   runtime: RunningServices,
   buildId: string,
-): Promise<{ readonly routes: readonly Route[]; readonly themeCsp: string }> {
+): Promise<{ readonly routes: readonly Route[]; readonly inlineScripts: readonly string[] }> {
   // Read from the store `x build --target docker` wrote and VERIFIED against this app and this
   // runtime (`island-store.ts`); built here only when there is no store to trust, which is correct
   // and slower, and logged with its reason.
@@ -151,11 +152,13 @@ async function webSurface(
   // Before the service worker, which precaches those scripts.
   const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
   // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
-  const navigation = await pageNavigation(
-    options.root,
-    await loadNavigation(options.root),
-    buildId,
-  );
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The browser's own prefetch, for the documents that carry no router (`navigation.speculation`).
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
   // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
@@ -211,6 +214,9 @@ async function webSurface(
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
+      // A `static` page is the same bytes for every request of this process: rendered once.
+      memoStatic: true,
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined
         ? {}
@@ -223,5 +229,9 @@ async function webSurface(
         : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
     }),
   ];
-  return { routes, themeCsp: theme.cspSource };
+  return {
+    routes,
+    // The theme boot and the speculation rules: the two inline bodies every document may carry.
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+  };
 }

package/src/static-document.ts

@@ -0,0 +1,108 @@
+// How a served process answers a `render: 'static'` page: a 304 when the browser already holds
+// these bytes, and — in the container — the document it rendered the first time, from memory.
+// A static page is one file in the export; the served process answering it must not cost a render
+// 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 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 };
+
+/**
+ * The entries one process keeps. A static route has no params here and no query, so the real count
+ * is routes × locales; the cap is what a forged `Host` (part of the key when the app declares no
+ * origin) can cost — past it a page is rendered per request, as before, never refused.
+ */
+export const STATIC_MEMO_LIMIT = 1024;
+
+/**
+ * The BYTES one process keeps, the cache tiers' `maxBytes` idea: a count alone lets 1,024 rotated
+ * `Host` headers retain 1,024 whole documents, whatever each weighs. Past it, as past the count, a
+ * page is rendered per request.
+ */
+export const STATIC_MEMO_MAX_BYTES = 32 * 1024 * 1024;
+
+export interface StaticMemo {
+  get(key: string): StaticResult | undefined;
+  set(key: string, result: StaticResult): void;
+  readonly size: number;
+  /** UTF-8 bytes of the kept keys and bodies. */
+  readonly bytes: number;
+}
+
+const encoder = new TextEncoder();
+const weigh = (key: string, result: StaticResult): number =>
+  encoder.encode(key).byteLength + encoder.encode(result.body).byteLength;
+
+export function createStaticMemo(
+  limit: number = STATIC_MEMO_LIMIT,
+  maxBytes: number = STATIC_MEMO_MAX_BYTES,
+): StaticMemo {
+  const kept = new Map<string, { readonly result: StaticResult; readonly weight: number }>();
+  let bytes = 0;
+  return {
+    get: (key) => kept.get(key)?.result,
+    set(key, result) {
+      // Only a 200 is the page: a loader's 404 or 500 is an answer about one moment.
+      if (result.status !== 200) return;
+      const held = kept.get(key);
+      if (held === undefined && kept.size >= limit) return;
+      const weight = weigh(key, result);
+      // A replacement gives its old weight back first; one that no longer fits is not kept, and
+      // neither is the stale document it would have replaced.
+      const after = bytes - (held?.weight ?? 0) + weight;
+      if (after > maxBytes) {
+        if (held !== undefined) {
+          kept.delete(key);
+          bytes -= held.weight;
+        }
+        return;
+      }
+      kept.set(key, { result, weight });
+      bytes = after;
+    },
+    get size() {
+      return kept.size;
+    },
+    get bytes() {
+      return bytes;
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function staticMemoKey(
+  entry: Pick<RouteEntry, 'config' | 'pattern'>,
+  url: URL,
+  locale: 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}`;
+}
+
+/**
+ * The document, or a bodiless 304 when `If-None-Match` names its ETag. The 304 repeats the
+ * validators and the cache posture (RFC 9110 §15.4.5) and drops `content-type`: it has no content.
+ * Only a 200 revalidates — a 404 rendered under `static` is sent whole.
+ */
+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)
+  ) {
+    const { 'content-type': _dropped, ...headers } = result.headers;
+    return new Response(null, { status: 304, headers });
+  }
+  return html(result.body, { status: result.status, headers: result.headers });
+}