@ultimat3/render 1.0.0

package/src/registry.ts

@@ -0,0 +1,313 @@
+/**
+ * The route table — the single source of route truth. File path → URL conventions for
+ * `site/`, `app/` and `api/`, plus `describeRoutes()`, the serializable projection that
+ * `x.manifest.json`, the `/_x` routes panel, the sitemap and `sw.js` are all generated
+ * from. Nothing downstream may keep its own list of routes.
+ */
+
+import {
+  RouteDuplicateError,
+  RouteFileInvalidError,
+  RouteUnnormalizedError,
+  SurfaceBoundaryError,
+} from './errors';
+import { assertModeInvariants } from './modes';
+import type {
+  HydrateStrategy,
+  OfflineStrategy,
+  RenderMode,
+  RouteConfig,
+  RouteData,
+  RouteParams,
+} from './route';
+import { isRouteConfig, tagKeys } from './route';
+import type { Surface } from './surfaces';
+import { surfaceOf } from './surfaces';
+
+/**
+ * The one filename a route may carry, per surface. `shared/` is absent on purpose: it is a leaf
+ * of helpers with no URL, so a route file there has nowhere to resolve to.
+ */
+export const ROUTE_FILENAME: Readonly<Partial<Record<Surface, string>>> = Object.freeze({
+  site: 'page.tsx',
+  app: 'page.tsx',
+  api: 'route.ts',
+});
+
+/** Stems that already meant "this directory", so the repair is a rename in place, not a new folder. */
+const DIRECTORY_STEMS = new Set(['index', 'page', 'route']);
+
+const API_PREFIX = '/api';
+
+export interface RouteEntry<TData = RouteData> {
+  readonly file: string;
+  readonly path: string;
+  readonly surface: Surface;
+  readonly config: RouteConfig<TData>;
+  readonly suspenseBoundaries: number;
+  readonly islands: readonly string[];
+  readonly pattern: CompiledPattern;
+}
+
+export interface RouteDescriptor {
+  readonly path: string;
+  readonly file: string;
+  readonly surface: Surface;
+  readonly mode: RenderMode;
+  readonly offline: OfflineStrategy;
+  readonly hydrate: HydrateStrategy;
+  readonly revalidateTags: readonly string[];
+  readonly revalidateTtl: string | number | null;
+  readonly prerenderable: boolean;
+  readonly dynamic: boolean;
+  readonly hasPolicy: boolean;
+  readonly islands: readonly string[];
+  readonly budgetJs: string | null;
+  readonly budgetLcp: number | null;
+}
+
+export interface CompiledPattern {
+  readonly source: string;
+  readonly regex: RegExp;
+  readonly keys: readonly string[];
+  /** Higher wins when two patterns match the same pathname. */
+  readonly specificity: number;
+}
+
+/**
+ * `apps/web/site/blog/[slug]/page.tsx` → `{ surface: 'site', path: '/blog/:slug' }`.
+ *
+ * The URL is the **directory** path under the surface; the filename names the kind of file, never
+ * a URL segment. Anything else is `X_ROUTE_FILE_INVALID` — one spelling per surface, so an agent
+ * reading a folder knows which file is the route without opening any of them.
+ *
+ * | file | path |
+ * |---|---|
+ * | `site/page.tsx` | `/` |
+ * | `site/pricing/page.tsx` | `/pricing` |
+ * | `site/(marketing)/about/page.tsx` | `/about` |
+ * | `site/blog/[slug]/page.tsx` | `/blog/:slug` |
+ * | `site/docs/[...path]/page.tsx` | `/docs/*path` |
+ * | `app/dashboard/page.tsx` | `/dashboard` |
+ * | `api/posts/route.ts` | `/api/posts` |
+ */
+export function routePathFromFile(file: string): { surface: Surface; path: string } {
+  const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
+  const surface = surfaceOf(normalized);
+  if (surface === null) {
+    throw new SurfaceBoundaryError(
+      `${file} is not inside a surface directory, so it has no URL and no bundle graph`,
+      `move ${file} under site/, app/ or api/`,
+    );
+  }
+
+  const afterSurface = normalized.slice(normalized.indexOf(`${surface}/`) + surface.length + 1);
+  const rawSegments = afterSurface.split('/').filter((s) => s.length > 0);
+  assertRouteFilename(normalized, surface, rawSegments[rawSegments.length - 1]);
+
+  const urlSegments = rawSegments
+    .slice(0, -1)
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')))
+    .map(toUrlSegment);
+
+  const base = surface === 'api' ? API_PREFIX : '';
+  const path = `${base}/${urlSegments.join('/')}`.replace(/\/+$/, '') || '/';
+  return { surface, path };
+}
+
+/**
+ * POSIX single-quotes a filesystem-derived operand for a `fix:` command: close the quote, escape
+ * an embedded quote as `'\''`, reopen it. A `fix:` is copied and run verbatim (axiom 4), so a route
+ * filename carrying a space, an apostrophe or a shell metacharacter must not change what runs.
+ */
+const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
+
+/**
+ * Enforced rather than documented (axiom 3): a convention that is not a build error is not a
+ * convention. The fix is the move that makes the file a route, spelled out — the directory the
+ * author already meant, plus the one filename that surface accepts.
+ */
+function assertRouteFilename(file: string, surface: Surface, basename: string | undefined): void {
+  const expected = ROUTE_FILENAME[surface];
+  if (expected === undefined) {
+    throw new RouteFileInvalidError(
+      `${file} is under shared/, which is a leaf of helpers with no URL — a route cannot live there`,
+      `move ${file} under site/, app/ or api/, named page.tsx (site/, app/) or route.ts (api/)`,
+    );
+  }
+  if (basename === expected) return;
+
+  // The directory the author meant is the file's own path minus its extension: `site/pricing.tsx`
+  // was always trying to be `/pricing`, so `site/pricing/page.tsx` is the move, not a guess.
+  // `index`, `page` and `route` are the exception — each already means "this directory", so the
+  // rename happens in place and no directory is created.
+  const stem = file.replace(/\.(tsx|ts|jsx|js)$/, '');
+  const dir = stem.slice(0, stem.lastIndexOf('/'));
+  const inPlace = DIRECTORY_STEMS.has(stem.slice(dir.length + 1));
+  const target = inPlace ? `${dir}/${expected}` : `${stem}/${expected}`;
+  throw new RouteFileInvalidError(
+    `${file} is a route on the ${surface} surface, so it must be named ${expected}: the URL is the ` +
+      'directory path and the filename names the kind of file',
+    inPlace
+      ? `git mv -- ${shellQuote(file)} ${shellQuote(target)}`
+      : `mkdir -p -- ${shellQuote(stem)} && git mv -- ${shellQuote(file)} ${shellQuote(target)}`,
+  );
+}
+
+function toUrlSegment(segment: string): string {
+  const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+  if (catchAll?.[1] !== undefined) return `*${catchAll[1]}`;
+  const dynamic = /^\[(.+)\]$/.exec(segment);
+  if (dynamic?.[1] !== undefined) return `:${dynamic[1]}`;
+  return segment;
+}
+
+export function compilePattern(path: string): CompiledPattern {
+  const keys: string[] = [];
+  let specificity = 0;
+  const segments = path.split('/').filter((s) => s.length > 0);
+
+  const parts = segments.map((segment) => {
+    if (segment.startsWith('*')) {
+      keys.push(segment.slice(1));
+      specificity += 1;
+      return '(.*)';
+    }
+    if (segment.startsWith(':')) {
+      keys.push(segment.slice(1));
+      specificity += 10;
+      return '([^/]+)';
+    }
+    specificity += 100;
+    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  });
+
+  return {
+    source: path,
+    regex: new RegExp(`^/${parts.join('/')}/?$`),
+    keys,
+    specificity,
+  };
+}
+
+const routes = new Map<string, RouteEntry>();
+
+export interface RegisterRouteInput<TData = RouteData> {
+  readonly file: string;
+  readonly config: RouteConfig<TData>;
+  /** Counted from the module's JSX by the build; `stream` requires >= 1. */
+  readonly suspenseBoundaries?: number;
+  readonly islands?: readonly string[];
+  /** Override the convention (locale roots, rewrites). Rarely needed. */
+  readonly path?: string;
+}
+
+/** Register a route and enforce every invariant that needs the surrounding module. */
+export function registerRoute<TData = RouteData>(
+  input: RegisterRouteInput<TData>,
+): RouteEntry<TData> {
+  // The type already refuses a declaration; this catches the JS caller and the cast. Without it a
+  // raw declaration registers, and `describeRoutes()` is where it surfaces — as a bare TypeError
+  // on `config.budget.js`, one build step away from the file that caused it.
+  if (!isRouteConfig(input.config)) {
+    throw new RouteUnnormalizedError(
+      `${input.file} registered a route declaration, not a descriptor: defineRoute normalizes ` +
+        '`meta` and `budget`, and the route table has no other normalizer',
+      `wrap the declaration in ${input.file}: registerRoute({ file, config: defineRoute({ … }) })`,
+    );
+  }
+
+  const derived = routePathFromFile(input.file);
+  const path = input.path ?? derived.path;
+  const suspenseBoundaries = input.suspenseBoundaries ?? 0;
+
+  assertModeInvariants(input.config, {
+    file: input.file,
+    path,
+    surface: derived.surface,
+    suspenseBoundaries,
+  });
+
+  const existing = routes.get(path);
+  if (existing !== undefined && existing.file !== input.file) {
+    throw new RouteDuplicateError(
+      `${path} is claimed by both ${existing.file} and ${input.file}`,
+      `rename or delete one of them — the route table is keyed by URL`,
+    );
+  }
+
+  const entry: RouteEntry<TData> = {
+    file: input.file,
+    path,
+    surface: derived.surface,
+    config: input.config,
+    suspenseBoundaries,
+    islands: input.islands ?? [],
+    pattern: compilePattern(path),
+  };
+  routes.set(path, entry as RouteEntry);
+  return entry;
+}
+
+export function clearRoutes(): void {
+  routes.clear();
+}
+
+export function routeCount(): number {
+  return routes.size;
+}
+
+export function routeEntries(): readonly RouteEntry[] {
+  return [...routes.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function routeFor(path: string): RouteEntry | undefined {
+  return routes.get(path);
+}
+
+/**
+ * The manifest projection: JSON-safe, sorted by path, identical for identical input.
+ * Determinism matters because `sw.js` and the sitemap are diffed across deploys.
+ */
+export function describeRoutes(): readonly RouteDescriptor[] {
+  return routeEntries().map((entry) => ({
+    path: entry.path,
+    file: entry.file,
+    surface: entry.surface,
+    mode: entry.config.render,
+    offline: entry.config.offline,
+    hydrate: entry.config.hydrate,
+    revalidateTags: tagKeys(entry.config.revalidate?.tags),
+    revalidateTtl: entry.config.revalidate?.ttl ?? null,
+    prerenderable: entry.config.prerender !== undefined,
+    dynamic: entry.pattern.keys.length > 0,
+    hasPolicy: entry.config.policy !== undefined,
+    islands: entry.islands,
+    budgetJs: entry.config.budget.js ?? null,
+    budgetLcp: entry.config.budget.lcp ?? null,
+  }));
+}
+
+export interface RouteMatch {
+  readonly entry: RouteEntry;
+  readonly params: RouteParams;
+}
+
+/** Most specific pattern wins: static segments > dynamic > catch-all. */
+export function matchRoute(pathname: string): RouteMatch | null {
+  const candidates = routeEntries()
+    .slice()
+    .sort((a, b) => b.pattern.specificity - a.pattern.specificity);
+
+  for (const entry of candidates) {
+    const match = entry.pattern.regex.exec(pathname);
+    if (match === null) continue;
+    const params: Record<string, string> = {};
+    entry.pattern.keys.forEach((key, index) => {
+      const value = match[index + 1];
+      if (value !== undefined) params[key] = decodeURIComponent(value);
+    });
+    return { entry, params };
+  }
+  return null;
+}

package/src/render-isr.ts

@@ -0,0 +1,290 @@
+/**
+ * `isr` — static output plus background regeneration. Three things make it safe:
+ * stale-while-revalidate (a stale page is served instantly, never a spinner),
+ * single-flight regeneration (a traffic burst on a stale page renders once, not N times),
+ * and tag-driven staleness (an action's `invalidates` marks exactly the dependent routes).
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import {
+  dependentsOfKind,
+  invalidateTags,
+  registerDependent,
+  registerRevalidator,
+  unregisterDependent,
+} from '@ultimat3/cache';
+import { logger } from '@ultimat3/core';
+import type { RouteDescriptor } from './registry';
+import { describeRoutes } from './registry';
+import { contentHash, staticHeaders } from './render-static';
+import type { RenderResult } from './route';
+
+export type IsrState = 'miss' | 'hit' | 'stale';
+
+export interface IsrEntry {
+  readonly path: string;
+  readonly html: string;
+  readonly hash: string;
+  readonly generatedAt: number;
+  readonly ttlMs: number | null;
+  /** Set by a tag invalidation; independent of the TTL clock. */
+  readonly stale: boolean;
+}
+
+export interface IsrStore {
+  get(path: string): IsrEntry | undefined;
+  set(entry: IsrEntry): void;
+  delete(path: string): void;
+  paths(): readonly string[];
+}
+
+export function memoryIsrStore(): IsrStore {
+  const map = new Map<string, IsrEntry>();
+  return {
+    get: (path) => map.get(path),
+    set: (entry) => {
+      map.set(entry.path, entry);
+    },
+    delete: (path) => {
+      map.delete(path);
+    },
+    paths: () => [...map.keys()].sort(),
+  };
+}
+
+const DURATION_UNITS: Readonly<Record<string, number>> = {
+  ms: 1,
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** `'5m'` → 300000. Numbers pass through as milliseconds. */
+export function parseTtlMs(ttl: string | number | null | undefined): number | null {
+  if (ttl === null || ttl === undefined) return null;
+  if (typeof ttl === 'number') return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(ttl.trim());
+  const amount = match?.[1];
+  const unit = match?.[2];
+  if (amount === undefined || unit === undefined) return null;
+  const factor = DURATION_UNITS[unit];
+  return factor === undefined ? null : Number(amount) * factor;
+}
+
+export type IsrRenderFn = (path: string) => string | Promise<string>;
+
+export interface IsrServeResult {
+  readonly state: IsrState;
+  readonly entry: IsrEntry;
+  readonly result: RenderResult;
+  /** True when this request started a background regeneration. */
+  readonly regenerating: boolean;
+}
+
+export interface IsrControllerOptions {
+  readonly store?: IsrStore;
+  readonly buildId?: string;
+  readonly now?: () => number;
+  /** Route table provider — defaults to the real registry. */
+  readonly routes?: () => readonly RouteDescriptor[];
+  /** ISR-route dependents for a tag set; defaults to `@ultimat3/cache`'s graph. */
+  readonly isrDependents?: (tags: readonly CacheTag[]) => readonly string[];
+}
+
+export interface IsrController {
+  serve(path: string, render: IsrRenderFn): Promise<IsrServeResult>;
+  /** Single-flight: concurrent callers for the same path share one render. */
+  regenerate(path: string, render: IsrRenderFn): Promise<IsrEntry>;
+  markStale(path: string): boolean;
+  /** Mark every ISR page the cache graph says depends on these tags. */
+  revalidateByTags(tags: readonly CacheTag[]): readonly string[];
+  inflight(): number;
+  store(): IsrStore;
+  /**
+   * Register this controller as the framework's revalidator, so
+   * `action({ cache: { invalidates: [tag.post] } })` reaches ISR in the same hop as
+   * memo, LRU, Redis and the CDN. Returns a detach function for tests and reloads.
+   */
+  attach(): () => void;
+}
+
+export function createIsrController(options: IsrControllerOptions = {}): IsrController {
+  const store = options.store ?? memoryIsrStore();
+  const now = options.now ?? (() => Date.now());
+  const routes = options.routes ?? describeRoutes;
+  const isrDependents =
+    options.isrDependents ?? ((tags: readonly CacheTag[]) => dependentsOfKind(tags, 'isr-route'));
+  const buildId = options.buildId ?? 'dev';
+  const pending = new Map<string, Promise<IsrEntry>>();
+  const registered = new Set<string>();
+
+  function descriptorFor(path: string): RouteDescriptor | undefined {
+    const table = routes();
+    return table.find((r) => r.path === path) ?? table.find((r) => matchesRoute(path, r.path));
+  }
+
+  /**
+   * A rendered page joins the invalidation graph under its route's tags, so `/blog/a` and
+   * `/blog/b` are separately addressable and a `tag.post` bust does not touch `/team`.
+   */
+  function registerPath(path: string, descriptor: RouteDescriptor | undefined): void {
+    if (descriptor === undefined || registered.has(path)) return;
+    if (descriptor.revalidateTags.length === 0) return;
+    registerDependent(descriptor.revalidateTags.map(parseWireTag), { kind: 'isr-route', id: path });
+    registered.add(path);
+  }
+
+  function isFresh(entry: IsrEntry): boolean {
+    if (entry.stale) return false;
+    if (entry.ttlMs === null) return true; // tag-only revalidation: fresh until invalidated
+    return now() - entry.generatedAt < entry.ttlMs;
+  }
+
+  function regenerate(path: string, render: IsrRenderFn): Promise<IsrEntry> {
+    const existing = pending.get(path);
+    if (existing !== undefined) return existing;
+
+    const descriptor = descriptorFor(path);
+    const work = (async (): Promise<IsrEntry> => {
+      const html = await render(path);
+      const entry: IsrEntry = {
+        path,
+        html,
+        hash: contentHash(html),
+        generatedAt: now(),
+        ttlMs: parseTtlMs(descriptor?.revalidateTtl),
+        stale: false,
+      };
+      store.set(entry);
+      registerPath(path, descriptor);
+      return entry;
+    })();
+
+    pending.set(path, work);
+    void work.catch(() => undefined).finally(() => pending.delete(path));
+    return work;
+  }
+
+  function markStale(path: string): boolean {
+    const entry = store.get(path);
+    if (entry === undefined) return false;
+    store.set({ ...entry, stale: true });
+    return true;
+  }
+
+  return {
+    store: () => store,
+    inflight: () => pending.size,
+    regenerate,
+    markStale,
+
+    async serve(path, render) {
+      const cached = store.get(path);
+
+      if (cached === undefined) {
+        const entry = await regenerate(path, render);
+        return { state: 'miss', entry, result: toResult(entry, buildId), regenerating: false };
+      }
+
+      if (isFresh(cached)) {
+        return {
+          state: 'hit',
+          entry: cached,
+          result: toResult(cached, buildId),
+          regenerating: false,
+        };
+      }
+
+      // stale-while-revalidate: answer from the stale copy now, refresh behind the request.
+      const already = pending.has(path);
+      void regenerate(path, render).catch((error: unknown) => {
+        logger.warn('isr.regenerate.failed', {
+          path,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+      return {
+        state: 'stale',
+        entry: cached,
+        result: toResult(cached, buildId, true),
+        regenerating: !already,
+      };
+    },
+
+    revalidateByTags(tags) {
+      const affected = new Set<string>();
+      for (const path of isrDependents(tags)) {
+        markStale(path);
+        affected.add(path);
+      }
+      return [...affected].sort();
+    },
+
+    attach() {
+      // The cache fanout owns the trigger; render owns only "what does stale mean here".
+      registerRevalidator((path) => {
+        markStale(path);
+      });
+      return () => {
+        for (const path of registered) unregisterDependent({ kind: 'isr-route', id: path });
+        registered.clear();
+      };
+    },
+  };
+}
+
+/**
+ * The whole loop, in one call: `action({ cache: { invalidates: [tag.post] } })` fans out
+ * across memo, LRU, Redis and the CDN, and the same hop returns the ISR pages that were
+ * marked stale — because the controller registered them in the same graph. Nobody lists
+ * pages by hand, so nobody forgets one.
+ */
+export async function invalidateAndRevalidate(
+  tags: readonly CacheTag[],
+): Promise<readonly string[]> {
+  const report = await invalidateTags(tags);
+  return report.isr;
+}
+
+/** `post` / `post:123` → `{ entity, id? }`. Mirrors `@ultimat3/cache`'s wire form. */
+function parseWireTag(wire: string): CacheTag {
+  const split = wire.indexOf(':');
+  if (split === -1) return { entity: wire };
+  return { entity: wire.slice(0, split), id: wire.slice(split + 1) };
+}
+
+/** A stored path belongs to a route when the route's pattern matches it. */
+function matchesRoute(storedPath: string, routePath: string): boolean {
+  if (!routePath.includes(':') && !routePath.includes('*')) return storedPath === routePath;
+  const parts = routePath.split('/').map(segmentPattern);
+  return new RegExp(`^${parts.join('/')}/?$`).test(storedPath);
+}
+
+function segmentPattern(segment: string): string {
+  if (segment.startsWith(':')) return '([^/]+)';
+  if (segment.startsWith('*')) return '(.*)';
+  return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Tag-only routes have no clock of their own; a tag bust reaches the CDN through the fanout. */
+const TAG_ONLY_S_MAX_AGE_SECONDS = 60;
+
+/**
+ * The declared TTL is the route's own contract with the CDN: a shared cache must not hold the
+ * page longer than the app said it stays true. A flat `s-maxage=60` made `revalidate: { ttl:
+ * '5m' }` a lie in one direction and `ttl: '30s'` a lie in the other.
+ */
+function cacheControl(ttlMs: number | null): string {
+  const sMaxAge = ttlMs === null ? TAG_ONLY_S_MAX_AGE_SECONDS : Math.round(ttlMs / 1_000);
+  return `public, max-age=0, s-maxage=${sMaxAge}, stale-while-revalidate=86400`;
+}
+
+function toResult(entry: IsrEntry, buildId: string, servedStale = false): RenderResult {
+  const headers: Record<string, string> = {
+    ...staticHeaders(entry.hash, buildId),
+    'cache-control': cacheControl(entry.ttlMs),
+  };
+  if (servedStale) headers['x-ultimate-isr'] = 'stale';
+  return { status: 200, headers, body: entry.html };
+}

package/src/render-spa.ts

@@ -0,0 +1,74 @@
+/**
+ * `spa` — shell only, client fetches everything. For dashboards behind auth, where the
+ * shell is identical for every actor and therefore cacheable, and the data is not.
+ * `modes.ts` requires a `policy` on this mode: nothing is server-rendered, so the route
+ * itself is the only place authz can live.
+ */
+
+import { RouteModeInvalidError } from './errors';
+import type { RouteEntry } from './registry';
+import { contentHash } from './render-static';
+import type { RenderResult } from './route';
+
+export const SPA_ROOT_ID = 'x-root';
+
+export interface SpaShellInput {
+  readonly entry: RouteEntry;
+  readonly buildId: string;
+  /** Everything inside `<head>`, already merged by `head.ts`. */
+  readonly head: string;
+  /** Build-id-immutable chunk URLs to preload; order is preserved for determinism. */
+  readonly chunks: readonly string[];
+  readonly rootId?: string;
+  readonly lang: string;
+  readonly dir?: 'ltr' | 'rtl';
+}
+
+export interface SpaShell {
+  readonly html: string;
+  readonly hash: string;
+}
+
+export function renderSpaShell(input: SpaShellInput): SpaShell {
+  if (input.entry.config.policy === undefined) {
+    throw new RouteModeInvalidError(
+      `${input.entry.file} declares render: 'spa' with no policy, so the shell would be public`,
+      `add policy: can('…') to ${input.entry.file}`,
+    );
+  }
+
+  const rootId = input.rootId ?? SPA_ROOT_ID;
+  const preloads = input.chunks
+    .map((chunk) => `<link rel="modulepreload" href="${chunk}">`)
+    .join('');
+  const scripts = input.chunks
+    .map((chunk) => `<script type="module" src="${chunk}"></script>`)
+    .join('');
+
+  const html =
+    `<!doctype html><html lang="${input.lang}" dir="${input.dir ?? 'ltr'}">` +
+    `<head>${input.head}${preloads}` +
+    `<meta name="x-ultimate-build" content="${input.buildId}">` +
+    `</head><body><div id="${rootId}"></div>${scripts}</body></html>`;
+
+  return { html, hash: contentHash(html) };
+}
+
+/**
+ * The shell is identical for every actor, so it is cache-first in `sw.js` and
+ * revalidate-on-navigation over HTTP. The build id in the document is what
+ * `@ultimat3/pwa`'s skew detection compares against the server's.
+ */
+export function renderSpa(input: SpaShellInput): RenderResult {
+  const shell = renderSpaShell(input);
+  return {
+    status: 200,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'private, max-age=0, must-revalidate',
+      etag: `"${shell.hash}"`,
+      'x-ultimate-build': input.buildId,
+    },
+    body: shell.html,
+  };
+}