@ultimat3/cli 22.14.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.14.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.14.0",
-    "@ultimat3/admin": "22.14.0",
-    "@ultimat3/ai": "22.14.0",
-    "@ultimat3/auth": "22.14.0",
-    "@ultimat3/cache": "22.14.0",
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/db": "22.14.0",
-    "@ultimat3/entity": "22.14.0",
-    "@ultimat3/flags": "22.14.0",
-    "@ultimat3/http": "22.14.0",
-    "@ultimat3/i18n": "22.14.0",
-    "@ultimat3/jobs": "22.14.0",
-    "@ultimat3/mail": "22.14.0",
-    "@ultimat3/manifest": "22.14.0",
-    "@ultimat3/mcp": "22.14.0",
-    "@ultimat3/money": "22.14.0",
-    "@ultimat3/notify": "22.14.0",
-    "@ultimat3/policy": "22.14.0",
-    "@ultimat3/pwa": "22.14.0",
-    "@ultimat3/query": "22.14.0",
-    "@ultimat3/realtime": "22.14.0",
-    "@ultimat3/render": "22.14.0",
-    "@ultimat3/schema": "22.14.0",
-    "@ultimat3/seo": "22.14.0",
-    "@ultimat3/storage": "22.14.0",
-    "@ultimat3/testing": "22.14.0",
-    "@ultimat3/time": "22.14.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/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

@@ -242,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, mcpPaths } = await devRouteTable({
+  const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
     env: options.env,
@@ -278,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[] =>

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,6 +58,8 @@ 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 default MCP endpoint was mounted, or `null`. */
@@ -75,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.
@@ -151,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
         ? {}
@@ -158,5 +166,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
   ];
 
-  return { routes, theme, errorStyles, mcpPath: mcpMount.path, mcpPaths: mcpMount.paths };
+  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 });
+}