@ultimat3/cli 29.4.0 → 30.1.0

package/src/runtime-isr-outcome.ts

@@ -4,11 +4,11 @@
 
 import { logger } from '@ultimat3/core';
 import type { RedirectIntent, RequestContext, RouteParams } from '@ultimat3/http';
-import { asCtx, requestAddress, takeRedirect } from '@ultimat3/http';
+import { asCtx, requestAddress, takeRedirect, withAnonymousRequest } from '@ultimat3/http';
 import type { RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
 import { describePages, routeDataFor, routeNoStoreOf, routeStatusOf } from '@ultimat3/render';
 import type { IsrController, IsrEntry } from '@ultimat3/render/server';
-import { isrKey, isrRequestUrl, isrRouteFor, undeclaredQuery } from '@ultimat3/render/server';
+import { isrKey, isrRequestUrl, isrRouteFor } from '@ultimat3/render/server';
 
 export type IsrOutcome =
   | { readonly kind: 'page'; readonly result: RenderResult }
@@ -23,47 +23,83 @@ export interface IsrRequest {
   readonly data: IsrData;
   readonly ctx: RequestContext;
   readonly isr: IsrController;
+  /** The app's declared public origin (`publicOrigin()`), or nothing: then the request's is keyed. */
+  readonly origin: string | undefined;
   /**
-   * The route's whole document for what `load` returned (`runtime-render.ts`'s `documentFrom`),
+   * The route's whole document for what `load` returned (`runtime-render-document.ts`'s `documentFrom`),
    * rendered AT the data this file hands it — the narrowed URL, never the request's own.
    */
   readonly document: (loaded: RouteData, at: IsrData) => Promise<string>;
 }
 
-/** Route files already told, once, about a request whose query they never declared. */
-const toldUndeclared = new Set<string>();
-
-/** Names are the visitor's: a few, cut short, is all a log line needs to name the edit. */
-const NAMED_PARAMS = 5;
-const NAMED_PARAM_CHARS = 40;
-
 /**
  * The request narrowed to what the route declared it varies on (`revalidate.query`), AT the one
  * spelling of its address (`pathname`). ONE narrowing feeds the store key, `load`, `meta` and the
  * page, so neither a parameter outside the key nor the way a visitor happened to spell the path
  * (`/blog//a/`, `/blog/%61`) can reach the document stored under it.
  *
- * A route that declared NOTHING still keys on the whole query, and is told so once, the first time
- * a visitor uses that: every distinct query string is then a render and a stored page of its own.
+ * The origin is the same narrowing: a declared one replaces the request's before the key, so `load`
+ * and the page are handed the address the document's own canonical names, whatever `Host` arrived.
  */
-function keyedData(entry: RouteEntry, data: IsrData, pathname: string | undefined): IsrData {
+function keyedData(
+  entry: RouteEntry,
+  data: IsrData,
+  pathname: string | undefined,
+  origin: URL | undefined,
+): IsrData {
   const url = new URL(data.url);
   if (pathname !== undefined) url.pathname = pathname;
-  const declared = entry.config.revalidate?.query ?? null;
-  if (declared === null && !toldUndeclared.has(entry.file)) {
-    const minted = undeclaredQuery(url, declared);
-    if (minted.length > 0) {
-      toldUndeclared.add(entry.file);
-      logger.warn('isr.query.undeclared', {
-        route: entry.file,
-        params: minted.slice(0, NAMED_PARAMS).map((name) => name.slice(0, NAMED_PARAM_CHARS)),
-        cause:
-          'the route declares no revalidate.query, so every distinct query string is rendered and stored as its own page',
-        fix: `revalidate: { query: [] }   // in ${entry.file}; or query: ['<name>'] for each parameter the page varies on`,
-      });
-    }
+  if (origin !== undefined) {
+    url.protocol = origin.protocol;
+    url.hostname = origin.hostname;
+    // `port` and not `host`: a `host` with no port leaves the request's, so `evil.test:8443` named
+    // itself in the document after all.
+    url.port = origin.port;
   }
-  return { ...data, url: isrRequestUrl(url, declared).href };
+  return { ...data, url: isrRequestUrl(url, entry.config.revalidate?.query ?? null).href };
+}
+
+/**
+ * The declared origin, when it is one: http or https. `APP_URL` is an operator's string and nothing
+ * has read it as a URL by here. One that does not parse would be a 500 on every `isr` page, and
+ * `localhost:3000` parses with `localhost:` as its scheme, where URL setters do nothing and every
+ * host would share one key. Both are keyed as undeclared: against the request, as the head falls back.
+ */
+function declaredOrigin(origin: string | undefined): URL | undefined {
+  if (origin === undefined || !URL.canParse(origin)) return undefined;
+  const parsed = new URL(origin);
+  return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed : undefined;
+}
+
+/**
+ * How many request origins one controller stores pages for when the app declares none. A `Host` is
+ * the visitor's to choose, so each new one would be a render and an entry pushing a real page out
+ * of the bounded store. Past the cap a NEW origin is refused rather than anything evicted, as
+ * `static-document.ts`'s memo does: answered, its own canonical, never stored.
+ */
+export const ISR_MAX_REQUEST_ORIGINS = 16;
+
+/** Per controller, so a `stop` that drops the store drops what it had admitted. */
+const admittedOrigins = new WeakMap<IsrController, Set<string>>();
+
+function admitsOrigin(isr: IsrController, origin: string, route: string): boolean {
+  const admitted = admittedOrigins.get(isr) ?? new Set<string>();
+  admittedOrigins.set(isr, admitted);
+  if (admitted.has(origin)) return true;
+  if (admitted.size < ISR_MAX_REQUEST_ORIGINS) {
+    admitted.add(origin);
+    return true;
+  }
+  if (admitted.size === ISR_MAX_REQUEST_ORIGINS) {
+    // Told once: a sentinel past the cap, which nothing else ever reads as an origin.
+    admitted.add('');
+    logger.warn('isr.origin.over_cap', {
+      route,
+      cause: `this process has stored pages for ${ISR_MAX_REQUEST_ORIGINS} request origins and the app declares none, so a page for any other Host is answered uncached`,
+      fix: 'APP_URL=https://your.domain   # or site: { origin } in app.config.ts',
+    });
+  }
+  return false;
 }
 
 /**
@@ -94,50 +130,61 @@ function dropPage(isr: IsrController, key: string): void {
  * inside the producer, which runs on a miss and on a stale page's regeneration.
  *
  * Concurrent misses on one key share ONE producer run, and only a PAGE may be shared. A redirect is
- * the request's own (its `load` may have read a cookie), so a request that joined a run whose load
+ * never stored, so it stays the decision of the render that made it: a request that joined a run whose load
  * redirected decides for itself, exactly as the static single-flight in `appRoutes` does.
+ *
+ * `load` and the document run as nobody, on every path (`withAnonymousRequest`): what is stored is
+ * answered to every later visitor, so it may not hold what this one's identity could read.
  */
 export async function isrOutcome(arrived: IsrRequest): Promise<IsrOutcome> {
   // Where the router MATCHED this request, never where the visitor wrote it: the router answers
   // many spellings with one page, and a key built from the raw pathname stored each of them.
   const address = requestAddress(arrived.ctx);
+  const origin = declaredOrigin(arrived.origin);
   const request: IsrRequest = {
     ...arrived,
-    data: keyedData(arrived.entry, arrived.data, address?.pathname),
+    data: keyedData(arrived.entry, arrived.data, address?.pathname, origin),
   };
   const { entry, data, ctx, isr } = request;
-  // `isrKey(url, locale)`, never `url.pathname`: the DECLARED query is part of what was rendered —
+  // `isrKey(url, locale, origin)`, never `url.pathname`: the DECLARED query is part of what was rendered —
   // `meta` reads `data.url` — so two URLs differing in it are two documents (#171). The locale is
   // `ctx.locale`, the one the `locale` stage negotiated for THIS request. The key's path carries
   // NO base path: the route table has never heard of the mount, so a key that kept it matched no
   // route — and every `isr` page of an app under a `basePath` was stored with no ttl and no tags.
   const keyed = new URL(data.url);
   if (address !== undefined) keyed.pathname = address.path;
-  const key = isrKey(keyed, asCtx(ctx).locale);
+  // No origin declared: the document's canonical is absolute against the request's, so a foreign
+  // `Host` is its own entry and never names itself in the page the next visitor gets.
+  const key = isrKey(keyed, asCtx(ctx).locale, origin === undefined ? keyed.origin : undefined);
   // The key has to read back as THIS route, or its ttl, its tags and what a bust does to it are
   // another route's or nobody's. It always does for an address the framework's URL scheme can
   // spell; what is left is a path the router matched that another reading claims (`//en/x` is the
   // `/:lang/x` route with no locale, and `/en/x` is the `/x` route in English). Answered, uncached.
   if (isrRouteFor(describePages(), key)?.file !== entry.file) return ownOutcome(request);
+  if (origin === undefined && !admitsOrigin(isr, keyed.origin, entry.file)) {
+    return ownOutcome(request);
+  }
   let decided: RedirectIntent | undefined;
   // `{ html, status }`, never the bare string: the entry stores the status beside the HTML and
   // serves it on every hit, so a 404 under `isr` is a 404 for its whole TTL.
-  const served = await isr.serve(key, async () => {
-    const loaded = await routeDataFor(entry.config, data);
-    const to = takeRedirect(ctx);
-    if (to === undefined) {
-      return {
-        html: await request.document(loaded, data),
-        status: routeStatusOf(loaded),
-        noStore: routeNoStoreOf(loaded),
-      };
-    }
-    // Set by THIS request's producer only. On a stale page it runs behind the answer, and when it
-    // has already decided by the time `serve` returns, the redirect is still this request's own.
-    decided = to;
-    dropPage(isr, key);
-    return { html: '', status: to.status };
-  });
+  const served = await isr.serve(key, () =>
+    withAnonymousRequest(ctx, new URL(data.url), async (scope) => {
+      const loaded = await routeDataFor(entry.config, data);
+      const to = takeRedirect(scope);
+      if (to === undefined) {
+        return {
+          html: await request.document(loaded, data),
+          status: routeStatusOf(loaded),
+          noStore: routeNoStoreOf(loaded),
+        };
+      }
+      // Set by THIS request's producer only. On a stale page it runs behind the answer, and when it
+      // has already decided by the time `serve` returns, the redirect is still this request's own.
+      decided = to;
+      dropPage(isr, key);
+      return { html: '', status: to.status };
+    }),
+  );
   if (decided !== undefined) return { kind: 'redirect', to: decided };
   if (!isRedirectMarker(served.entry)) return { kind: 'page', result: served.result };
   return ownOutcome(request);
@@ -146,19 +193,26 @@ export async function isrOutcome(arrived: IsrRequest): Promise<IsrOutcome> {
 /**
  * A request answered for itself alone: a joiner whose leader's load redirected, or one whose key
  * is not its own route's. Its own `load`; a page here is NOT stored — the store was just told the
- * key has none, or the key is another page's — so it is `private, no-store`.
+ * key has none, or the key is another page's — so it is `private, no-store`. Still as nobody: not
+ * to protect the store, but because one route renders one way, whichever path a request took.
  */
-async function ownOutcome(request: IsrRequest): Promise<IsrOutcome> {
-  const loaded = await routeDataFor(request.entry.config, request.data);
-  const to = takeRedirect(request.ctx);
-  if (to !== undefined) return { kind: 'redirect', to };
-  const body = await request.document(loaded, request.data);
-  return {
-    kind: 'page',
-    result: {
-      status: routeStatusOf(loaded),
-      headers: { 'cache-control': 'private, no-store' },
-      body,
+function ownOutcome(request: IsrRequest): Promise<IsrOutcome> {
+  return withAnonymousRequest(
+    request.ctx,
+    new URL(request.data.url),
+    async (scope): Promise<IsrOutcome> => {
+      const loaded = await routeDataFor(request.entry.config, request.data);
+      const to = takeRedirect(scope);
+      if (to !== undefined) return { kind: 'redirect', to };
+      const body = await request.document(loaded, request.data);
+      return {
+        kind: 'page',
+        result: {
+          status: routeStatusOf(loaded),
+          headers: { 'cache-control': 'private, no-store' },
+          body,
+        },
+      };
     },
-  };
+  );
 }

package/src/runtime-purge.ts

@@ -1,8 +1,8 @@
 // The retention sweep this boot owns: the framework tables that grow with traffic, the `purge()`
 // job that empties them and the `task` that fires it hourly.
 //
-// NINE TARGETS, `As of 2026-10-17` — `x_idempotency`, `x_rate_limit`, the `x_auth` limiter's
-// table, `x_notify_deliveries`, `x_notify_inbox`, `x_notify_digests`, `x_job_events`, `x_outbox`
+// TEN TARGETS, `As of 2026-11-02` — `x_idempotency`, `x_rate_limit`, the `x_auth` limiter's
+// table, `x_totp_steps`, `x_notify_deliveries`, `x_notify_inbox`, `x_notify_digests`, `x_job_events`, `x_outbox`
 // (published rows) and `x_jobs` (finished rows, with their `x_job_steps`). Counted nowhere in prose but here: this header said
 // "three" for two releases after the notify tables joined the boot's DDL, which is how
 // `x_notify_inbox` became the one framework table nothing swept — and `x_jobs` was the next one.
@@ -19,6 +19,7 @@
 // per source address forever.
 
 import type { PostgresIdempotencyStore } from '@ultimat3/action';
+import type { PostgresTotpReplayGuard } from '@ultimat3/auth';
 import { purgeAuthLimits } from '@ultimat3/auth';
 import type { PostgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
@@ -52,6 +53,12 @@ export const PURGE_TASK_NAME = 'x.purge.hourly';
 export interface RetentionStores {
   readonly idempotency: PostgresIdempotencyStore;
   readonly rateLimit: PostgresRateLimitStore;
+  /**
+   * The guard this boot installed through `configureTotpReplay`. Unlike the limiter it takes
+   * nothing from the app, so it exists here. REQUIRED, or `x_totp_steps` keeps a row per second
+   * factor for the life of the deployment.
+   */
+  readonly totpReplay: PostgresTotpReplayGuard;
   /**
    * The bus this boot installed for `step.waitForEvent`. REQUIRED: `x_job_events` takes a row per
    * publish and `find` only filters an expired one, so a boot that left it out is the table
@@ -149,6 +156,11 @@ function retentionTargets(stores: RetentionStores): readonly PurgeTarget[] {
       purgeExpired: (nowMs: number): Promise<number> => stores.rateLimit.purgeExpired(nowMs),
     },
     authTarget,
+    {
+      name: 'x_totp_steps',
+      // The job's clock: `verifyTotp` derived every step in that table from a process's clock.
+      purgeExpired: (nowMs: number): Promise<number> => stores.totpReplay.purgeExpired(nowMs),
+    },
     ...notifyTargets(stores.inboxRetention ?? NO_INBOX_RETENTION),
     // Its own clock, and so no `nowMs`: every instant in that table is the database's.
     eventsPurgeTarget(stores.events),

package/src/runtime-queue.ts

@@ -7,9 +7,12 @@
 import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
+  postgresMeterStore,
   requestDeadlineMs,
   resetIdempotency,
+  resetMeterStore,
   setIdempotencyStore,
+  setMeterStore,
 } from '@ultimat3/action';
 import type { PgliteClient, PostgresClient } from '@ultimat3/db';
 import {
@@ -18,6 +21,8 @@ import {
   dbExecutor,
   pgliteClient,
   pgliteDataDir,
+  poolerFromEnv,
+  poolerSessionRequired,
   poolMaxFromEnv,
   postgresClient,
   setDbClient,
@@ -111,7 +116,7 @@ export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
           dataDir: pgliteDataDir(binding.url),
           extensions: () => appExtensions(services.root),
         })
-      : postgresClient({ url: binding.url, profile });
+      : postgresClient({ url: binding.url, profile, env });
   const attached = attachReplica(client, replicaUrlFor(binding, env), profile);
   setDbClient(attached.client);
   return { client, replica: attached.replica };
@@ -182,8 +187,8 @@ async function startJobs(
   schema: SchemaMode,
 ): Promise<RunningQueue> {
   await applySchema(client, schema);
-  // Bound to `client`, never the ambient `db()`: the queue, the event bus and the idempotency
-  // reservations stay on the boot's pool whatever transaction is open.
+  // Bound to `client`, never the ambient `db()`: the queue and the idempotency reservations stay
+  // on the boot's pool whatever transaction is open.
   const executor = dbExecutor(() => client);
   const driver = overrides?.jobs ?? postgresJobDriver({ executor });
   setJobDriver(driver);
@@ -195,7 +200,16 @@ async function startJobs(
   setJobsFacade(
     outboxJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
   );
-  const events = postgresEventBus({ executor });
+  // The open transaction's connection, as the outbox beside it: an answer belongs to the unit of
+  // work that gave it, so a refusal that rolls back never resumes the run waiting on it.
+  //
+  // `wakes` only when the queue in hand is the boot's own `postgresJobDriver`: the wake is an update
+  // of `x_jobs` on this database, and an override driver (Redis) keeps no rows here — its waiters
+  // keep the 30 s poll. Waking, a parked wait's backstop is 15 min instead.
+  const events = postgresEventBus({
+    executor: dbExecutor(() => currentTx() ?? client),
+    wakes: overrides?.jobs === undefined,
+  });
   setEventBus(events);
   const idempotency = postgresIdempotencyStore({
     executor,
@@ -206,6 +220,9 @@ async function startJobs(
     reclaimAfterMs: requestDeadlineMs,
   });
   setIdempotencyStore(idempotency);
+  // `meter:` counters on the boot's pool, never the open transaction: a draw is the caller's
+  // whether or not the business write commits, and one tenant's day is one row on every replica.
+  setMeterStore(postgresMeterStore({ executor }));
   return {
     db: client,
     jobs: driver,
@@ -234,6 +251,7 @@ async function releaseQueue(
   // The idempotency store goes back to the memory default for the same reason the facade does: it
   // holds this client, and the next command in this process would reserve keys over a closed one.
   resetIdempotency();
+  resetMeterStore();
   resetJobsFacade();
   resetEventBus();
   resetJobDriver();
@@ -266,6 +284,15 @@ export async function startQueue(
    */
   schema: SchemaMode = 'ensure',
 ): Promise<RunningQueue> {
+  // `x db migrate` runs as whatever ROLE the shell has, so `postgresClient`'s role check cannot see
+  // it: what needs the session is the step that takes the migration lock, whichever role asked.
+  if (
+    schema === 'apply' &&
+    services.db.mode !== 'embedded' &&
+    poolerFromEnv(env) === 'transaction'
+  ) {
+    throw poolerSessionRequired('a step that applies migrations');
+  }
   const { client: db, replica } = startDb(services, env);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database

package/src/runtime-render-document.ts

@@ -0,0 +1,204 @@
+// One route's document: the head a route and the app decide together, the body inside the
+// hydration root, and the assembly of the two. Split from `runtime-render.ts`, which owns picking a
+// mode and answering with what it rendered; every mode's document is built here, once.
+
+import { actionPathStyle } from '@ultimat3/action';
+import { escapeHtml } from '@ultimat3/core';
+import type { RouteParams } from '@ultimat3/http';
+import { currentLocale } from '@ultimat3/i18n';
+import type { IslandCollector, RouteData, RouteEntry } from '@ultimat3/render';
+import {
+  clientPathStyleTags,
+  clientPersistTags,
+  clientPinTags,
+  clientScopeTag,
+  clientSyncTags,
+  headFromMeta,
+  hydrateRuntime,
+  metaContextFor,
+  renderHead,
+  seoRenderers,
+} from '@ultimat3/render';
+import type { HoleSink } from '@ultimat3/render/server';
+import { ROOT_ELEMENT_ID, renderComponent } from '@ultimat3/render/server';
+import { loadAppConfig } from './app-config-load';
+import type { DocumentOptions } from './document-options';
+import { routeQuery } from './isr-query-guard';
+import { navigationTagsOf } from './page-navigation';
+import { servedPins } from './page-pins';
+import { bootScript, collectorFor } from './route-islands';
+import { siteAssetTable } from './site-assets';
+import { styleBundle } from './style-bundle';
+
+/**
+ * The app-wide favicon head, from `site.favicon`: the content-hashed URL `asset('assets/….svg')`
+ * returns and `/assets/*` serves, never the raw path. Per render, never frozen at boot.
+ */
+export async function appFaviconHead(root: string): Promise<string | undefined> {
+  const favicon = (await loadAppConfig(root))?.site.favicon;
+  if (favicon === undefined) return undefined;
+  const url = siteAssetTable(root).resolve(favicon).url;
+  return `<link rel="icon" type="image/svg+xml" href="${escapeHtml(url)}">`;
+}
+
+/** `DocumentOptions`, plus the app root the app's own favicon is resolved against per render. */
+export type RenderOptions = DocumentOptions & { readonly root?: string };
+
+/** What a route's `meta(data)` is given. `url` is a string because that is what `ld.*` embeds. */
+export interface DevRouteData extends Record<string, unknown> {
+  readonly url: string;
+  readonly params: RouteParams;
+}
+/**
+ * `<html lang>` is the request's own locale, never a constant: the `locale` stage negotiated it
+ * one stage before this handler and published it on the context, so a hardcoded `'en'` shipped
+ * every document mislabelled — wrong for a screen reader, wrong for `hreflang`. Outside a request
+ * (`x build`'s prerender) it is the app's own configured fallback.
+ */
+export const lang = (): string => currentLocale();
+
+/**
+ * `scope` is present only on a PRIVATE document (a gated `ssr` page, every `stream`): the page's
+ * client scope (`@ultimat3/auth`'s `clientScopeOf`), which core's `pageClient()` reads to fence its
+ * one store per principal. A shareable document carries NO scope tag — absent means "not rendered
+ * for anyone", a different answer from `''`, the anonymous page.
+ */
+export const headFor = async (
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: RenderOptions,
+  scope?: string,
+): Promise<string> => {
+  const meta = metaContextFor(ctx, data);
+  const url = new URL(ctx.url);
+  const router = navigationTagsOf(options.navigation, entry, meta.t);
+  return (
+    renderHead(
+      headFromMeta(
+        await entry.config.meta(meta),
+        seoRenderers({
+          path: url.pathname,
+          baseUrl: options.origin ?? url.origin,
+          // The default is the cluster's own head (`alternates` is default-first by contract), so
+          // `x-default` comes from the list the hreflang tags do — never a second locale read.
+          localization: {
+            locale: meta.locale,
+            defaultLocale: meta.alternates[0]?.locale ?? meta.locale,
+            alternates: meta.alternates,
+          },
+        }),
+        [
+          ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
+          // Every document, shareable ones included: the style is the app's, not a visitor's, and
+          // it is the only way an island's `rpc()` learns it. Read per render — `defineApi` may run
+          // after these routes are built. `'resource'`, the default, is no tag.
+          ...clientPathStyleTags(actionPathStyle()),
+          // Same reason, same read: a pinned action or query is reached by NAME from the browser
+          // (`rpc`, `useQuery`, `useMutation`) only through this. Nothing pinned is no tag.
+          ...clientPinTags(servedPins()),
+          ...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.
+          ...(scope === undefined
+            ? []
+            : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
+        ],
+      ),
+    ) +
+    (options.themeHead ?? '') +
+    // One mechanism per document: the router prefetches for itself, the browser for the rest.
+    (router.length === 0 ? (options.speculationHead ?? '') : '') +
+    // The app's own favicon: one link, every document, the URL the table resolves NOW.
+    ((options.root === undefined ? options.faviconHead : await appFaviconHead(options.root)) ??
+      '') +
+    // Per locale: each links its own locale's manifest (`PwaArtifacts.headFor`).
+    (typeof options.pwaHead === 'function'
+      ? options.pwaHead(meta.locale)
+      : (options.pwaHead ?? '')) +
+    (entry.surface === 'app' ? (options.appHead ?? '') : (options.siteHead ?? ''))
+  );
+};
+
+/**
+ * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
+ * imports none.
+ *
+ * In `<head>`, which is what keeps this a swap and not a regression: a `<link rel="stylesheet">`
+ * there is render-blocking in every browser, exactly as the inline block was, so there is no window
+ * in which the document paints unstyled. Moving it to the body, or deferring it, would introduce a
+ * flash — never do that here.
+ *
+ * Read through `styleBundle()` rather than passed in through `DocumentOptions`: the registry it
+ * derives from is process-global (importing the app IS what fills it), so a caller that forgot to
+ * thread a resolver would serve a document with no CSS at all. One reader, and it is the same one
+ * `styleRoutes` serves from.
+ */
+const styleTag = (entry: RouteEntry): string => {
+  const href = styleBundle().hrefFor(entry.surface);
+  return href === undefined ? '' : `<link rel="stylesheet" href="${href}">`;
+};
+
+/** The surface stylesheet, then the app's brand — the order that lets the brand win the cascade. */
+export const stylesFor = (entry: RouteEntry, options: DocumentOptions): string =>
+  styleTag(entry) + (options.brandHead ?? '');
+
+/**
+ * The route's rendered body, inside the hydration root. Every mode goes through here — an empty
+ * root is what a module exporting no component renders, and nothing else: `spa` was the one mode
+ * that never reached this function, so every `spa` route ever declared served an empty root.
+ */
+export async function routeBody(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  islands: IslandCollector,
+  // Only the `stream` branch passes one. Absent, a `<Hole>` is its children, inline.
+  holes?: HoleSink,
+): Promise<string> {
+  if (entry.component === undefined) return `<div id="${ROOT_ELEMENT_ID}"></div>`;
+  const url = new URL(ctx.url);
+  const html = await renderComponent(
+    entry.component,
+    // `data` is the route's own `load` result and is what `meta` was just given — the same object,
+    // never a second resolution. `query` is supplied because a page that reads `props.query.x`
+    // otherwise dereferences undefined and takes the whole render down.
+    {
+      data,
+      params: ctx.params,
+      url: ctx.url,
+      query: routeQuery(entry, url),
+    },
+    entry.file,
+    holes === undefined ? { islands } : { islands, holes },
+  );
+  return `<div id="${ROOT_ELEMENT_ID}">${html}</div>`;
+}
+
+/**
+ * The document from data ALREADY resolved. Split from `routeDocument` so one request resolves
+ * `load` exactly once: `stream` renders head and body separately, and resolving in each would let
+ * a `<title>` describe content the body does not contain.
+ *
+ * The hydration runtime is appended after the body and only after it: what strategies a page needs
+ * is a fact about the islands the walk just recorded, so emitting it earlier would guess or ship
+ * the whole runtime to a page with no island.
+ */
+export async function documentFrom(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: RenderOptions,
+  scope?: string,
+): Promise<string> {
+  const islands = collectorFor(entry, options, scope);
+  const [head, body] = await Promise.all([
+    headFor(entry, ctx, data, options, scope),
+    routeBody(entry, ctx, data, islands),
+  ]);
+  return (
+    `<!doctype html><html lang="${lang()}"><head>${head}${stylesFor(entry, options)}</head>` +
+    `<body>${body}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}</body></html>`
+  );
+}